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_ */