1 /**
2 * @file drivers/entropy.h
3 *
4 * @brief Public APIs for the entropy driver.
5 */
6
7 /*
8 * Copyright (c) 2016 ARM Ltd.
9 * Copyright (c) 2017 Intel Corporation
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 */
13 #ifndef ZEPHYR_INCLUDE_DRIVERS_ENTROPY_H_
14 #define ZEPHYR_INCLUDE_DRIVERS_ENTROPY_H_
15
16 /**
17 * @brief Entropy Interface
18 * @defgroup entropy_interface Entropy Interface
19 * @since 1.10
20 * @version 1.0.0
21 * @ingroup io_interfaces
22 * @{
23 */
24
25 #include <errno.h>
26
27 #include <zephyr/types.h>
28 #include <zephyr/device.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 /** @brief Driver is allowed to busy-wait for random data to be ready */
35 #define ENTROPY_BUSYWAIT BIT(0)
36
37 /**
38 * @typedef entropy_get_entropy_t
39 * @brief Callback API to get entropy.
40 *
41 * @note This call has to be thread safe to satisfy requirements
42 * of the random subsystem.
43 *
44 * See entropy_get_entropy() for argument description
45 */
46 typedef int (*entropy_get_entropy_t)(const struct device *dev,
47 uint8_t *buffer,
48 uint16_t length);
49 /**
50 * @typedef entropy_get_entropy_isr_t
51 * @brief Callback API to get entropy from an ISR.
52 *
53 * See entropy_get_entropy_isr() for argument description
54 */
55 typedef int (*entropy_get_entropy_isr_t)(const struct device *dev,
56 uint8_t *buffer,
57 uint16_t length,
58 uint32_t flags);
59
60 /**
61 * @brief Entropy driver API structure.
62 *
63 * This is the mandatory API any Entropy driver needs to expose.
64 */
65 __subsystem struct entropy_driver_api {
66 entropy_get_entropy_t get_entropy;
67 entropy_get_entropy_isr_t get_entropy_isr;
68 };
69
70 /**
71 * @brief Fills a buffer with entropy. Blocks if required in order to
72 * generate the necessary random data.
73 *
74 * @param dev Pointer to the entropy device.
75 * @param buffer Buffer to fill with entropy.
76 * @param length Buffer length.
77 * @retval 0 on success.
78 * @retval -ERRNO errno code on error.
79 */
80 __syscall int entropy_get_entropy(const struct device *dev,
81 uint8_t *buffer,
82 uint16_t length);
83
z_impl_entropy_get_entropy(const struct device * dev,uint8_t * buffer,uint16_t length)84 static inline int z_impl_entropy_get_entropy(const struct device *dev,
85 uint8_t *buffer,
86 uint16_t length)
87 {
88 const struct entropy_driver_api *api =
89 (const struct entropy_driver_api *)dev->api;
90
91 __ASSERT(api->get_entropy != NULL,
92 "Callback pointer should not be NULL");
93 return api->get_entropy(dev, buffer, length);
94 }
95
96 /**
97 * @brief Fills a buffer with entropy in a non-blocking or busy-wait manner.
98 * Callable from ISRs.
99 *
100 * @param dev Pointer to the device structure.
101 * @param buffer Buffer to fill with entropy.
102 * @param length Buffer length.
103 * @param flags Flags to modify the behavior of the call.
104 * @retval number of bytes filled with entropy or -error.
105 */
entropy_get_entropy_isr(const struct device * dev,uint8_t * buffer,uint16_t length,uint32_t flags)106 static inline int entropy_get_entropy_isr(const struct device *dev,
107 uint8_t *buffer,
108 uint16_t length,
109 uint32_t flags)
110 {
111 const struct entropy_driver_api *api =
112 (const struct entropy_driver_api *)dev->api;
113
114 if (unlikely(!api->get_entropy_isr)) {
115 return -ENOTSUP;
116 }
117
118 return api->get_entropy_isr(dev, buffer, length, flags);
119 }
120
121
122 #ifdef __cplusplus
123 }
124 #endif
125
126 /**
127 * @}
128 */
129
130 #include <zephyr/syscalls/entropy.h>
131
132 #endif /* ZEPHYR_INCLUDE_DRIVERS_ENTROPY_H_ */
133
