Line data    Source code

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