1 /** 2 ****************************************************************************** 3 * @file bleplat.h 4 * @author GPM WBL Application team 5 * @brief This file contains the interface of the Bluetooth LE platform layer 6 * (lower interface of the Bluetooth LE stack library). 7 ****************************************************************************** 8 * @attention 9 * 10 * Copyright (c) 2024 STMicroelectronics. 11 * All rights reserved. 12 * 13 * This software is licensed under terms that can be found in the LICENSE file 14 * in the root directory of this software component. 15 * If no LICENSE file comes with this software, it is provided AS-IS. 16 * 17 ****************************************************************************** 18 */ 19 20 #ifndef BLEPLAT_H__ 21 #define BLEPLAT_H__ 22 23 #include <stdint.h> 24 #include "bleplat_cntr.h" 25 26 #define RSSI_INVALID 127 27 28 /* Enumerated values used for the return of the functions: */ 29 30 typedef enum 31 { 32 BLEPLAT_OK = 0, 33 BLEPLAT_FULL = -1, 34 BLEPLAT_BUSY = -2, 35 BLEPLAT_EOF = -3 36 } BLEPLAT_NvmStatusTypeDef; 37 38 39 /* Enumerated values used for the 'type' of NVM functions: */ 40 41 typedef enum 42 { 43 BLEPLAT_NVM_REC_SEC = 0, 44 BLEPLAT_NVM_REC_GATT = 1, 45 BLEPLAT_NVM_REC_DEVICE_ID = 2, 46 } BLEPLAT_NvmRecordTypeDef; 47 48 49 /* Enumerated values used for the 'mode' of NVM functions: */ 50 51 typedef enum 52 { 53 BLEPLAT_NVM_FIRST = 0, 54 BLEPLAT_NVM_NEXT = 1, 55 BLEPLAT_NVM_CURRENT = 2, 56 BLEPLAT_NVM_ALL = 3 57 } BLEPLAT_NvmSeekModeTypeDef; 58 59 typedef enum 60 { 61 BLEPLAT_PKA_SUCCESS = 0, 62 BLEPLAT_PKA_ERROR = -1, 63 BLEPLAT_PKA_ERR_BUSY = -2, 64 BLEPLAT_PKA_ERR_PARAM = -3, 65 BLEPLAT_PKA_ERR_PROCESS = -4 66 } BLEPLAT_PkaStatusTypeDef; 67 68 typedef void (*BLEPLAT_PkaFuncCb)(BLEPLAT_PkaStatusTypeDef errorCode, void *args); 69 70 typedef enum { 71 BLEPLAT_AES_FLAGS_DEFAULT = (uint32_t) (0x00000000), /*!< User Flag: No flag specified. This is the default value that should be set to this flag */ 72 BLEPLAT_AES_FLAGS_DONT_PERFORM_KEY_SCHEDULE = (uint32_t) (0x00000001), /*!< User Flag: Used to force the init to not reperform key schedule.\n 73 The classic example is where the same key is used on a new message, in this case to redo key scheduling is 74 a useless waste of computation, could be particularly useful on GCM, where key schedule is very complicated. */ 75 BLEPLAT_AES_FLAGS_FINAL_APPEND = (uint32_t) (0x00000020), /*!< User Flag: Must be set in CMAC mode before the final Append call occurs. */ 76 BLEPLAT_AES_FLAGS_OPERATION_COMPLETED = (uint32_t) (0x00000002), /*!< Internal Flag (not to be set/read by user): used to check that the Finish function has been already called */ 77 BLEPLAT_AES_FLAGS_NO_MORE_APPEND_ALLOWED = (uint32_t) (0x00000004), /*!< Internal Flag (not to be set/read by user): it is set when the last append has been called. Used where the append is called with an InputSize not 78 multiple of the block size, which means that is the last input.*/ 79 BLEPLAT_AES_FLAGS_NO_MORE_HEADER_APPEND_ALLOWED = (uint32_t) (0x00000010), /*!< Internal Flag (not to be set/read by user): only for authenticated encryption modes. \n 80 It is set when the last header append has been called. Used where the header append is called with an InputSize not 81 multiple of the block size, which means that is the last input.*/ 82 BLEPLAT_AES_FLAGS_APPEND_DONE = (uint32_t) (0x00000040), /*!< Internal Flag (not to be set/read by user): only for CMAC.It is set when the first append has been called */ 83 BLEPLAT_AES_FLAGS_SET_COUNTER = (uint32_t)(0x00000080), /*!< User Flag: With ChaCha20 this is used to indicate a value for the counter, used to process non contiguous blocks (i.e. jump ahead)*/ 84 85 } AESflagsTypeDef; /*!< Type definitation for Symmetric Key Flags */ 86 87 #define BLEPLAT_AES_MAX_EXPKEY_SIZE 44 /*!< The max size of the AES expanded key (in uint32_t) */ 88 #define BLEPLAT_AES128_KEY_SIZE 16 /*!< Number of bytes (uint8_t) necessary to store an AES key of 128 bits. */ 89 90 91 typedef struct 92 { 93 uint32_t mContextId; /*!< Unique ID of this context. \b Not \b used in current implementation. */ 94 AESflagsTypeDef mFlags; /*!< 32 bit mFlags, used to perform keyschedule and future use */ 95 const uint8_t *pmKey; /*!< Pointer to original Key buffer */ 96 const uint8_t *pmIv; /*!< Pointer to original Initialization Vector buffer */ 97 int32_t mIvSize; /*!< Size of the Initialization Vector in bytes */ 98 uint32_t amIv[4]; /*!< Temporary result/IV */ 99 int32_t mKeySize; /*!< Key length in bytes */ 100 uint32_t amExpKey[BLEPLAT_AES_MAX_EXPKEY_SIZE]; /*!< Expanded AES key */ 101 const uint8_t *pmTag; /*!< Pointer to Authentication TAG. This value must be set in decryption, and this TAG will be verified */ 102 int32_t mTagSize; /*!< Size of the Tag to return. This must be set by the caller prior to calling Init */ 103 } BLEPLAT_AESCMACctxTypeDef; /*<! AES context structure for CMAC mode */ 104 105 typedef struct BLEPLAT_TimerHandleS { 106 uint64_t ExpiryTime; /*!< Managed internally when the timer is started */ 107 void (*Callback)(void *); /*!< Pointer to the user callback */ 108 uint8_t active; /*!< Managed internally when the timer is started */ 109 struct BLEPLAT_TimerHandleS *next; /*!< Managed internally when the timer is started */ 110 void *userData; /*!< Pointer to user data */ 111 } BLEPLAT_TimerHandleTypeDef; 112 113 114 void BLEPLAT_MemCpy(void *Dest, const void *Src, unsigned int Size); 115 void BLEPLAT_MemSet(void *Ptr, int Value, unsigned int Size); 116 int BLEPLAT_MemCmp(void *S1, void *S2, unsigned int Size); 117 118 119 /** 120 * @brief Get Device ID, Version and Revision numbers 121 * 122 * This function returns the device ID, version and revision numbers. 123 * To be called by the BLE Stack for ensuring platform independence. 124 * 125 * @param[out] device_id Device ID (6 = STM32WB09) 126 * @param[out] major_cut Device cut version/major number 127 * @param[out] minor_cut Device cut revision/minor number 128 * 129 * @retval None 130 */ 131 void BLEPLAT_GetPartInfo(uint8_t *pDeviceId, uint8_t *pMajorCut, uint8_t *pMinorCut); 132 133 134 /* Non Volatile Memory (NVM) interface: 135 * 136 * This interface is only called from BLE stack Tick/Commands context 137 */ 138 139 BLEPLAT_NvmStatusTypeDef BLEPLAT_NvmAdd(BLEPLAT_NvmRecordTypeDef Type, 140 const uint8_t* pData, 141 uint16_t Size, 142 const uint8_t* pExtraData, 143 uint16_t ExtraSize); 144 145 BLEPLAT_NvmStatusTypeDef BLEPLAT_NvmGet(BLEPLAT_NvmSeekModeTypeDef Mode, 146 BLEPLAT_NvmRecordTypeDef Type, 147 uint16_t Offset, 148 uint8_t* pData, 149 uint16_t Size); 150 151 int BLEPLAT_NvmCompare(uint16_t Offset, const uint8_t* pData, uint16_t Size); 152 153 void BLEPLAT_NvmDiscard(BLEPLAT_NvmSeekModeTypeDef Mode); 154 155 156 /* Public Key Algorithms (PKA) interface: 157 * 158 * This interface is only called from BLE stack Tick/Commands context 159 */ 160 161 BLEPLAT_PkaStatusTypeDef BLEPLAT_PkaStartP256Key(const uint32_t *PrivateKey, BLEPLAT_PkaFuncCb FuncCb); 162 163 BLEPLAT_PkaStatusTypeDef BLEPLAT_PkaStartDHkey(uint32_t* PrivateKey, 164 uint32_t* PublicKey, 165 BLEPLAT_PkaFuncCb FuncCb); 166 167 /* Advanced Encryption Standard (AES) interface: 168 * 169 * This interface is only called from BLE stack Tick/Commands context 170 */ 171 172 void BLEPLAT_AesEcbEncrypt(const uint32_t *plainTextData, 173 const uint32_t *key, 174 uint32_t *encryptedData); 175 176 int32_t BLEPLAT_AesCMACEncryptInit(BLEPLAT_AESCMACctxTypeDef *pAESCMACctx); 177 178 int32_t BLEPLAT_AesCMACEncryptAppend(BLEPLAT_AESCMACctxTypeDef *pAESCMACctx, 179 const uint8_t *pInputBuffer, 180 int32_t InputSize); 181 182 int32_t BLEPLAT_AesCMACEncryptFinish(BLEPLAT_AESCMACctxTypeDef *pAESCMACctx, 183 uint8_t *pOutputBuffer, 184 int32_t *pOutputSize); 185 186 /* Random Number Generation (RNG) interface: 187 * 188 * This interface is called from both BLE stack contexts: ISR and Tick/Commands 189 */ 190 191 void BLEPLAT_RngGetRandom16(uint16_t* Num); 192 193 void BLEPLAT_RngGetRandom32(uint32_t* Num); 194 195 /** 196 * @brief Convert TX output power in dBm to the related Power Amplifier level 197 * @param TX_dBm Desired TX output power. 198 * 199 * @retval PA level that has to be set in the radio register to have a TX 200 * output power lower than or equal to the desired output power 201 */ 202 uint8_t BLEPLAT_DBmToPALevel(int8_t TxDBm); 203 204 /** 205 * @brief Convert TX output power in dBm to the related Power Amplifier level 206 * @param TX_dBm Desired TX output power. 207 * 208 * @retval PA level that has to be set in the radio register to have a TX 209 * output power greater than or equal to the desired output power 210 */ 211 uint8_t BLEPLAT_DBmToPALevelGe(int8_t TxDBm); 212 213 /** 214 * @brief Convert Power Amplifier level to TX output power in dBm 215 * @param PA_Level Level setting for the Power Amplifier 216 * 217 * @retval Output power in dBm, corresponding to the given PA level. If PA 218 * level is invalid, returned value is 127. 219 */ 220 int8_t BLEPLAT_PALevelToDBm(uint8_t PaLevel); 221 222 /** 223 * @brief Return minimum and maximum supported TX power. 224 * @param[out] Min_Tx_Power Minimum supported TX power in dBm. 225 * @param[out] Max_Tx_Power Maximum supported TX power in dBm. 226 * 227 * @retval None 228 */ 229 void BLEPLAT_ReadTransmitPower(int8_t *MinTxPower, int8_t *MaxTxPower); 230 231 /** 232 * @brief Configure the radio in order to increase output power level. 233 * @note This function should be called only by the BLE stack. 234 * @param enable Enable or disable the ability to reach maximum TX power. 235 * Set to 1 to enable high power mode. Set ot 0 to disable. 236 * @retval None 237 */ 238 void BLEPLAT_SetHighPower(uint8_t Enable); 239 240 /** 241 * @brief Return the current RSSI measured for the last received packet 242 as a signed value in dBm. 243 * @retval Current RSSI value 244 */ 245 int8_t BLEPLAT_CalculateRSSI(void); 246 247 /** 248 * @brief Return the next value of the average of RSSI values 249 * given the current RSSI average value and the next RSSI value. 250 * All values are signed and expressed in dBm. 251 * An Exponential Moving Average algorithm is applied. 252 * @param avg_rssi Current RSSI average value. 253 * Set to 127 to return the 'rssi' value. 254 * @param rssi Next RSSI value 255 * @param rssi_filter_coeff Coefficient used for the filtering of 256 * the RSSI samples and the calculation of 257 * the average RSSI. 258 * @retval Next RSSI average value 259 */ 260 int8_t BLEPLAT_UpdateAvgRSSI(int8_t AvgRssi, int8_t Rssi, uint8_t RssiFilterCoeff); 261 262 /** 263 * @brief Return the Coding Indicator field of the received packet (valid for 264 * Coded PHY only) 265 * @retval 0: Coded S8; 1: Coded S2. 266 */ 267 uint8_t BLEPLAT_GetDemodCI(void); 268 269 270 /** 271 * @brief Return the maximum Power Amplifier level available for the device. 272 * @return Maximum PA level 273 */ 274 uint8_t BLEPLAT_GetMaxPALevel(void); 275 276 /** 277 * @brief Return the default level to be set for the Power Amplifier. 278 * @return Default PA level 279 */ 280 uint8_t BLEPLAT_GetDefaultPALevel(void); 281 282 void BLEPLAT_InitCTE(uint8_t smNo); 283 284 void BLEPLAT_DeinitCTE(void); 285 286 void BLEPLAT_CalibrateCTE(uint8_t smNo); 287 288 void BLEPLAT_AntIdxRemap(uint8_t antPattLen, uint8_t *pAntRamTable, const uint8_t* pAntPatt); 289 290 uint64_t BLEPLAT_GetCurrentSysTime(void); 291 292 uint64_t BLEPLAT_GetFutureSysTime64(uint32_t SysTime); 293 294 int BLEPLAT_StartTimer(BLEPLAT_TimerHandleTypeDef *TimerHandle, uint64_t Time); 295 296 void BLEPLAT_StopTimer(BLEPLAT_TimerHandleTypeDef *TimerHandle); 297 298 uint8_t BLEPLAT_SetRadioTimerValue(uint32_t Time, uint8_t EventType, uint8_t CalReq); 299 300 uint8_t BLEPLAT_ClearRadioTimerValue(void); 301 302 uint64_t BLEPLAT_GetAnchorPoint(uint64_t *current_system_time); 303 304 void BLEPLAT_SetRadioCloseTimeout(void); 305 306 uint8_t BLEPLAT_SetRadioTimerRelativeUsValue(uint32_t RelTimeoutUs, uint8_t Tx, uint8_t PLLCal); 307 308 #endif /* ! BLEPLAT_H__ */ 309