1// -*- Mode: C++ -*-
2/* SPDX-License-Identifier: ((GPL-2.0-only WITH mif-exception) OR LicenseRef-kk-custom) */
3/*
4 * Copyright (C) 2019-2020 Kernkonzept GmbH.
5 * Author(s): Sarah Hoffmann <sarah.hoffmann@kernkonzept.com>
6 *
7 */
8#pragma once
9
10#include <l4/sys/capability>
11#include <l4/sys/cxx/ipc_types>
12#include <l4/sys/cxx/ipc_iface>
13#include <l4/sys/icu>
14
15namespace L4Re
16{
17
18/**
19 * Low-bandwidth interface for random number generators.
20 *
21 * The interface offers an ICU interface where a client can register an
22 * interrupt to get notified when entropy is available. Support for
23 * notifications is optional. If a service does not implement notification,
24 * it must return 0 for the number of interrupts in the info() call.
25 * The notification interrupt must have index 0.
26 *
27 * \includefile{l4/re/random}
28 */
29struct L4_EXPORT Random
30: public L4::Kobject_t<Random, L4::Icu>
31{
32  /**
33   * Get a random number.
34   *
35   * \param size         Number of bytes of entropy requested.
36   * \param[out] buffer  Buffer containing the random number. Each byte in the
37   *                     buffer contains 8 bits of randomness.
38   *
39   * \retval >=0  Actual size of the returned random number in bytes. This may
40   *              be less than the requested size. The return value may also
41   *              be 0 if temporarily no entropy is available.
42   * \retval -L4_EIO  Source of randomness permanently unavailable.
43   * \retval <0       IPC error.
44   *
45   * This function should never block. It should immediately return as much
46   * entropy as is available. If the call returns less than the requested
47   * bytes and a notification interrupt was installed, then the service triggers
48   * an interrupt as soon as the remaining entropy is available. That means
49   * that when an interrupt is triggered, the service must guarantee that the
50   * next call to get_random() returns at least the number of missing bytes
51   * for the call that initially triggered the notification.
52   *
53   * If get_random() is called while a notification is pending, then the
54   * behaviour is implementation-defined.
55   */
56  L4_INLINE_RPC(long, get_random, (l4_size_t size,
57                                   L4::Ipc::Array<char, unsigned long> *buffer));
58
59  typedef L4::Typeid::Rpcs<get_random_t> Rpcs;
60};
61
62} // namespace
63