Branch data Line data Source code
1 : : /* 2 : : * Copyright (c) 2019 Nordic Semiconductor ASA 3 : : * 4 : : * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause 5 : : */ 6 : : /**@file 7 : : * @defgroup nrf_cc3xx_platform_mutex nrf_cc3xx_platform mutex APIs 8 : : * @ingroup nrf_cc3xx_platform 9 : : * @{ 10 : : * @brief The nrf_cc3xx_platform_mutex APIs provides RTOS integration for mutex 11 : : * usage in nrf_cc3xx_platform and dependent libraries. 12 : : */ 13 : : #ifndef NRF_CC3XX_PLATFORM_MUTEX_H__ 14 : : #define NRF_CC3XX_PLATFORM_MUTEX_H__ 15 : : 16 : : #include <stdint.h> 17 : : #include <stddef.h> 18 : : 19 : : #include "nrf_cc3xx_platform_abort.h" 20 : : 21 : : #ifdef __cplusplus 22 : : extern "C" 23 : : { 24 : : #endif 25 : : 26 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_INVALID (0) /*!< Mask indicating that the mutex is invalid (not initialized or allocated). */ 27 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_VALID (1<<0) /*!< Mask value indicating that the mutex is valid for use. */ 28 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_ALLOCATED (1<<1) /*!< Mask value indicating that the mutex is allocated and requires deallocation once freed. */ 29 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_ATOMIC (1<<2) /*!< Mask value indicating that the mutex is atomic type. */ 30 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_HW_MUTEX (1<<3) /*!< Mask value indicating that the mutex is hardware mutex type. */ 31 : : #define NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_INTERNAL_MUTEX (1<<4) /*!< Mask value indicating that the mutex is an internal CryptoCell mutex. */ 32 : : 33 : : /** @brief Type definition of architecture neutral mutex type */ 34 : : typedef struct nrf_cc3xx_platform_mutex 35 : : { 36 : : void * mutex; 37 : : uint32_t flags; 38 : : 39 : : } nrf_cc3xx_platform_mutex_t; 40 : : 41 : : /** @brief Type definition of function pointer to initialize a mutex 42 : : * 43 : : * Calling this function pointer should initialize a previously uninitialized 44 : : * mutex or do nothing if the mutex is already initialized. 45 : : * 46 : : * @note Initialization may not imply memory allocation, as this can be done 47 : : * using static allocation through other APIs in the RTOS. 48 : : * 49 : : * @param[in] mutex Pointer to a mutex to initialize. 50 : : */ 51 : : typedef void (*nrf_cc3xx_platform_mutex_init_fn_t)(nrf_cc3xx_platform_mutex_t *mutex); 52 : : 53 : : 54 : : /** @brief Type definition of function pointer to free a mutex 55 : : * 56 : : * Calling this function pointer should free a mutex. 57 : : * 58 : : * @note If the RTOS does not provide an API to free the mutex it is advised 59 : : * to reset the mutex to an initialized state with no owner. 60 : : * 61 : : * @param[in] mutex Pointer to a mutex to free. 62 : : */ 63 : : typedef void (*nrf_cc3xx_platform_mutex_free_fn_t)(nrf_cc3xx_platform_mutex_t *mutex); 64 : : 65 : : 66 : : /** @brief Type definition of function pointer to lock a mutex 67 : : * 68 : : * Calling this function pointer should lock a mutex. 69 : : * 70 : : * @param[in] mutex Pointer to a mutex to lock. 71 : : */ 72 : : typedef int (*nrf_cc3xx_platform_mutex_lock_fn_t)(nrf_cc3xx_platform_mutex_t *mutex); 73 : : 74 : : 75 : : /** @brief Type definition of function pointer to unlock a mutex 76 : : * 77 : : * Calling this function pointer should unlock a mutex. 78 : : * 79 : : * @param[in] mutex Pointer to a mutex to unlock. 80 : : */ 81 : : typedef int (*nrf_cc3xx_platform_mutex_unlock_fn_t)(nrf_cc3xx_platform_mutex_t *mutex); 82 : : 83 : : 84 : : /**@brief Type definition of structure holding platform mutex APIs 85 : : */ 86 : : typedef struct nrf_cc3xx_platform_mutex_apis_t 87 : : { 88 : : /* The platform mutex init function */ 89 : : nrf_cc3xx_platform_mutex_init_fn_t mutex_init_fn; 90 : : 91 : : /* The platform mutex free function */ 92 : : nrf_cc3xx_platform_mutex_free_fn_t mutex_free_fn; 93 : : 94 : : /* The platform lock function */ 95 : : nrf_cc3xx_platform_mutex_lock_fn_t mutex_lock_fn; 96 : : 97 : : /* The platform unlock function */ 98 : : nrf_cc3xx_platform_mutex_unlock_fn_t mutex_unlock_fn; 99 : : } nrf_cc3xx_platform_mutex_apis_t; 100 : : 101 : : 102 : : /** @brief Type definition of structure to platform hw mutexes 103 : : */ 104 : : typedef struct nrf_cc3xx_platform_mutexes_t 105 : : { 106 : : /* Mutex for symmetric operations. */ 107 : : void * sym_mutex; 108 : : 109 : : /* Mutex for asymetric operations. */ 110 : : void * asym_mutex; 111 : : 112 : : /* Mutex for rng operations. */ 113 : : void * rng_mutex; 114 : : 115 : : /* Mutex reserved for future use. */ 116 : : void * reserved; 117 : : 118 : : /* Mutex for power mode changes */ 119 : : void * power_mutex; 120 : : } nrf_cc3xx_platform_mutexes_t; 121 : : 122 : : 123 : : /**@brief External reference to structure holding the currently set platform 124 : : * mutexe APIs. 125 : : */ 126 : : extern nrf_cc3xx_platform_mutex_apis_t platform_mutex_apis; 127 : : 128 : : 129 : : /**@brief External reference to currently set platform hw mutexes */ 130 : : extern nrf_cc3xx_platform_mutexes_t platform_mutexes; 131 : : 132 : : 133 : : /** @brief Function to set platform mutex APIs and mutexes 134 : : * 135 : : * @param[in] apis Structure holding the mutex APIs. 136 : : * @param[in] mutexes Structure holding the mutexes. 137 : : */ 138 : : void nrf_cc3xx_platform_set_mutexes( 139 : : nrf_cc3xx_platform_mutex_apis_t const * const apis, 140 : : nrf_cc3xx_platform_mutexes_t const * const mutexes); 141 : : 142 : : 143 : : /** @brief Function to initialize RTOS thread-safe mutexes 144 : : * 145 : : * This function must be implemented to set the platform mutex APIS, 146 : : * and platform mutexes. 147 : : * 148 : : * @note This function must be called once before calling 149 : : * @ref nrf_cc3xx_platform_init or @ref nrf_cc3xx_platform_init_no_rng. 150 : : * 151 : : * @note This function is not expected to be thread-safe. 152 : : */ 153 : 1 : void nrf_cc3xx_platform_mutex_init(void); 154 : : 155 : : #ifdef __cplusplus 156 : : } 157 : : #endif 158 : : 159 : : #endif /* NRF_CC3XX_PLATFORM_MUTEX_H__ */ 160 : : /** @} */