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