Line data    Source code

       1           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           1 : #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           1 : 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           1 : 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           1 : __subsystem struct entropy_driver_api {
      66           0 :         entropy_get_entropy_t     get_entropy;
      67           0 :         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           1 : __syscall int entropy_get_entropy(const struct device *dev,
      81             :                                   uint8_t *buffer,
      82             :                                   uint16_t length);
      83             : 
      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             :  */
     106           1 : 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_ */