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