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