1 /* 2 * Copyright (c) 2022-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 #ifndef ti_drivers_RCL_commands_ble_cs_h__include 34 #define ti_drivers_RCL_commands_ble_cs_h__include 35 36 #include <ti/drivers/rcl/RCL_Command.h> 37 #include <ti/drivers/rcl/RCL_Buffer.h> 38 #include <ti/drivers/rcl/handlers/ble_cs.h> 39 40 #include <ti/drivers/utils/List.h> 41 42 /* Forward declaration of types */ 43 typedef struct RCL_CMD_BLE_CS_t RCL_CmdBleCs; 44 typedef struct RCL_CMD_BLE_CS_STEP_INTERNAL_t RCL_CmdBleCs_Step_Internal; 45 typedef struct RCL_CMD_BLE_CS_STEP_RESULT_INTERNAL_t RCL_CmdBleCs_StepResult_Internal; 46 typedef struct RCL_CMD_BLE_CS_STEP_t RCL_CmdBleCs_Step; 47 typedef struct RCL_CMD_BLE_CS_SUBEVENT_RESULTS_t RCL_CmdBleCs_SubeventResults; 48 typedef struct RCL_CMD_BLE_CS_SUBEVENT_RESULTS_CONTINUE_t RCL_CmdBleCs_SubeventResultsContinue; 49 typedef struct RCL_CMD_BLE_CS_S2R_t RCL_CmdBleCs_S2r; 50 typedef struct RCL_CMD_BLE_CS_STATS_t RCL_CmdBleCs_Stats; 51 typedef struct RCL_CMD_BLE_CS_IQ_SAMPLE_t RCL_CmdBleCs_IQSample; 52 typedef struct RCL_CMD_BLE_CS_PRECAL_t RCL_CmdBleCs_Precal; 53 typedef struct RCL_CMD_BLE_CS_PRECAL_TABLE_t RCL_CmdBleCs_PrecalTable; 54 typedef struct RCL_CMD_BLE_CS_PRECAL_ENTRY_t RCL_CmdBleCs_PrecalEntry; 55 56 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_TONE_t RCL_CmdBleCs_Tone; 57 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_I0_t RCL_CmdBleCs_ResultI0; 58 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_R0_t RCL_CmdBleCs_ResultR0; 59 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_IR1_t RCL_CmdBleCs_ResultIR1; 60 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_IR2_t RCL_CmdBleCs_ResultIR2; 61 typedef struct RCL_CMD_BLE_CS_STEP_RESULTS_IR3_t RCL_CmdBleCs_ResultIR3; 62 63 typedef enum RCL_CMD_BLE_CS_Phy_e RCL_CmdBleCs_Phy; 64 typedef enum RCL_CMD_BLE_CS_Role_e RCL_CmdBleCs_Role; 65 typedef enum RCL_CMD_BLE_CS_StepMode_e RCL_CmdBleCs_StepMode; 66 typedef enum RCL_CMD_BLE_CS_PacketResult_e RCL_CmdBleCs_PacketResult; 67 typedef enum RCL_CMD_BLE_CS_Tfcs_e RCL_CmdBleCs_Tfcs; 68 typedef enum RCL_CMD_BLE_CS_Tpm_e RCL_CmdBleCs_Tpm; 69 typedef enum RCL_CMD_BLE_CS_Tip_e RCL_CmdBleCs_Tip; 70 typedef enum RCL_CMD_BLE_CS_Tsw_e RCL_CmdBleCs_Tsw; 71 typedef enum RCL_CMD_BLE_CS_AntennaConfig_e RCL_CmdBleCs_AntennaConfig; 72 typedef enum RCL_CMD_BLE_CS_Payload_e RCL_CmdBleCs_Payload; 73 typedef enum RCL_CMD_BLE_CS_RxGain_e RCL_CmdBleCs_RxGain; 74 typedef enum RCL_CMD_BLE_CS_ToneQuality_e RCL_CmdBleCs_ToneQuality; 75 typedef enum RCL_CMD_BLE_CS_ToneExtensionSlot_e RCL_CmdBleCs_ToneExtensionSlot; 76 77 /* Command IDs for generic commands */ 78 #define RCL_CMDID_BLE_CS 0x1101U 79 #define RCL_CMDID_BLE_CS_PRECAL 0x1102U 80 81 /* Helper macros to convert between time units */ 82 #define RCL_BLE_CS_US_TO_MCE_TIMER(x) ((x)*48) 83 #define RCL_BLE_CS_US_TO_PBE_TIMER(x) ((x)*4) 84 #define RCL_BLE_CS_MCE_TIMER_TO_US(x) ((x)/48) 85 #define RCL_BLE_CS_PBE_TIMER_TO_US(x) ((x)/4) 86 #define RCL_BLE_CS_MCE_TIMER_TO_PBE_TIMER(x) ((x)/12) 87 88 /* Helper macros for constants */ 89 #define RCL_BLE_CS_MAX_NUM_ANT 4 90 #define RCL_BLE_CS_MAX_NUM_ANT_PATH 5 91 #define RCL_BLE_CS_MAX_PAYLOAD_SIZE 4 92 #define RCL_BLE_CS_NUM_CORR 3 93 #define RCL_BLE_CS_NUM_STIM 2 94 #define RCL_BLE_CS_MAX_S2R_LEN 1024 95 #define RCL_BLE_CS_NUM_RX_GAIN_LEVEL 2 96 #define RCL_BLE_CS_NUM_PRECAL_CHANNELS 4 97 98 /** 99 * @brief BLE Channel Sounding IQ Sample 100 * 101 * Container to store complex vectors 102 */ 103 struct RCL_CMD_BLE_CS_IQ_SAMPLE_t { 104 int16_t i; /*!< Sample I-branch */ 105 int16_t q; /*!< Sample Q-branch */ 106 }; 107 108 /** 109 * @brief BLE Channel Sounding 110 * 111 * Command to execute a BLE Channel Sounding event 112 */ 113 struct RCL_CMD_BLE_CS_t { 114 RCL_Command common; 115 struct { 116 uint16_t role:1; /*!< Role of the device @ref RCL_CmdBleCs_Role */ 117 uint16_t phy:1; /*!< Phy used for packet exchange @ref RCL_CmdBleCs_Phy */ 118 uint16_t repeatSteps:1; /*!< Enable continuous repetition of step list */ 119 uint16_t chFilterEnable:1; /*!< Enable filtering of restricted channels at (2402, 2403, 2425, 2426, 2427, 2479, 2480 MHz) */ 120 uint16_t reserved:4; 121 uint16_t nSteps:8; /*!< Total number of steps within the BLE CS Sub-Event */ 122 } mode; 123 124 struct { 125 uint8_t select; /*!< Antenna pattern selection by index @ref RCL_CmdBleCs_AntennaConfig */ 126 uint8_t gpoMask; /*!< Mask of GPOs on the LRF controlling the antennas */ 127 uint8_t gpoVal[RCL_BLE_CS_MAX_NUM_ANT]; /*!< GPOCTRL word for antenna path 0..3 */ 128 } antennaConfig; 129 130 struct { 131 uint16_t tFcs; /*!< Config of time of Frequency Change period @ref RCL_CmdBleCs_Tfcs */ 132 uint16_t tFm; /*!< Config of time of Frequency Measurement period */ 133 uint16_t tPm; /*!< Config of time of Phase Measurement Duration @ref RCL_CmdBleCs_Tpm */ 134 uint16_t tIp1; /*!< Config of time of Interlude Period 1 @ref RCL_CmdBleCs_Tip */ 135 uint16_t tIp2; /*!< Config of time of Interlude Period 2 @ref RCL_CmdBleCs_Tip */ 136 uint16_t tRxWideningR0; /*!< Config of additional time of RX timeout of mode-0 steps on reflector. */ 137 uint16_t tSw; /*!< Config of time of Antenna Switching duration @ref RCL_CmdBleCs_Tsw */ 138 uint16_t tSwAdjustA; /*!< Time adjustment of first set of antenna switching within a step (Pkt-Tn / ...) */ 139 uint16_t tSwAdjustB; /*!< Time adjustment of second set of antenna switching within a step (... / Tn-Pkt) */ 140 } timing; 141 142 struct { 143 RCL_Command_TxPower txPower; /*!< Transmit power */ 144 uint8_t rxGain; /*!< 0: Automatic Gain Control enabled, 1...15: Index value of manual RX gain @ref RCL_CmdBleCs_RxGain */ 145 int16_t foffOverride; /*!< Frequency offset compensation override value in [4xFOFF = 4x (FRF/2^21)] units. */ 146 uint16_t foffOverrideEnable:1; /*!< Disables automatic frequency offset estimation and enforces the use of the provided override value */ 147 uint16_t reserved:15; 148 } frontend; 149 150 RCL_CmdBleCs_PrecalTable *precalTable; /*!< Pointer to a table contains DC values from precalibration */ 151 RCL_CmdBleCs_StepResult_Internal *results; /*!< Pointer to result list */ 152 RCL_CmdBleCs_Stats *stats; /*!< Pointer to statistics structure */ 153 List_List stepBuffers; /*!< Linked list of steps to be executed */ 154 List_List stepBuffersDone; /*!< Linked list of steps have been executed */ 155 List_List resultBuffers; /*!< Linked list of empty result buffers */ 156 List_List resultBuffersDone; /*!< Linked list of result buffers containing data */ 157 List_List s2rBuffers; /*!< Linked list of empty s2r containers */ 158 List_List s2rBuffersDone; /*!< Linked list of s2r containers with data */ 159 }; 160 161 /* Default configuration of command */ 162 #define RCL_CmdBleCs_Default() \ 163 { \ 164 .common = RCL_Command_Default(RCL_CMDID_BLE_CS, \ 165 RCL_Handler_BLE_CS), \ 166 } 167 #define RCL_CmdBleCs_DefaultRuntime() (RCL_CmdBleCs) RCL_CmdBleCs_Default() 168 169 /** 170 * @brief BLE Channel Sounding Step 171 * 172 * Descriptor to configure a single step within the BLE Channel Sounding Event 173 */ 174 struct RCL_CMD_BLE_CS_STEP_INTERNAL_t { 175 uint16_t channelIdx; /*!< Integer index of channel information (0: 2402MHz) */ 176 uint16_t mode; /*!< Step mode @ref RCL_CmdBleCs_StepMode */ 177 uint16_t toneExtension; /*!< Configuration of tone extension */ 178 uint16_t payloadLen; /*!< Length of payload in units of 32bit words @ref RCL_CmdBleCs_Payload */ 179 uint16_t foffErr; /*!< Internal! Used for frequency offset compensation */ 180 uint16_t tAdjustA; /*!< Internal! Used for timegrid adjustment */ 181 uint16_t tAdjustB; /*!< Internal! Used for timegrid adjustment */ 182 uint16_t reserved0; 183 RCL_CmdBleCs_IQSample dcComp[RCL_BLE_CS_NUM_RX_GAIN_LEVEL]; /*!< Internal! Used for DC compensation with precalibrated values */ 184 uint32_t payloadTx[RCL_BLE_CS_MAX_PAYLOAD_SIZE]; /*!< Payload to transmit containing random bit sequence (TX) */ 185 uint32_t payloadRx[RCL_BLE_CS_MAX_PAYLOAD_SIZE]; /*!< Expected payload to receive containing random bit sequence (RX) */ 186 uint32_t aaTx; /*!< Access Address to be transmitted */ 187 uint32_t aaRx; /*!< Access Address to be received */ 188 uint16_t antennaPermIdx; /*!< Index of entry to be used from the antenna permutation table @ref RCL_CmdBleCs_AntennaConfig */ 189 uint16_t antennaSequence; /*!< Internal! Decoded antenna control sequence based on permutation table */ 190 uint16_t tStep; /*!< Internal! The total duration of step dynamically calculated */ 191 uint16_t tAntennaA; /*!< Internal! Antenna timing adjustment */ 192 uint16_t tAntennaB; /*!< Internal! Antenna timing adjustment */ 193 uint16_t reserved1; 194 }; 195 196 /** 197 * @brief BLE Channel Sounding QQ data 198 * 199 * Container to store RSSI data for postprocess of the quality of tone 200 */ 201 typedef struct { 202 int16_t magnMin; /*!< Minimum of signal magnitude during TPM */ 203 int16_t magnMax; /*!< Maximum of signal magnitude during TPM */ 204 int16_t magnAvg; /*!< Average of signal magnitude during TPM */ 205 int16_t magnAvgdB; /*!< Average of signal magnitude during TPM in dB */ 206 } MagnData; 207 208 /** 209 * @brief BLE Channel Sounding Step Result 210 * 211 * Container to store the results of a single step within the BLE Channel Sounding Event 212 */ 213 struct RCL_CMD_BLE_CS_STEP_RESULT_INTERNAL_t { 214 uint16_t channelIdx; /*!< Integer index of channel information (0: 2402MHz) */ 215 uint16_t mode; /*!< Step mode @ref RCL_CmdBleCs_StepMode */ 216 uint16_t toneExtension; /*!< Configuration of tone extension */ 217 uint16_t payloadLen; /*!< Length of payload in units of 32bit words @ref RCL_CmdBleCs_Payload */ 218 uint16_t reserved; 219 int16_t foffMeasured; /*!< Frequency offset between devices (only set on Initiator Mode 0) */ 220 uint16_t pktResult; /*!< Result of packet reception @ref RCL_CmdBleCs_PacketResult */ 221 uint8_t gain; /*!< LNA gain used (Low/High)*/ 222 int8_t pktRssi; /*!< Receiver Signal Strength Indicator [dBm] captured during packet reception */ 223 uint16_t rtt; /*!< RTT timestamp */ 224 uint16_t corr[RCL_BLE_CS_NUM_CORR]; /*!< Correlator before-peak-after values for fractional time estimation */ 225 RCL_CmdBleCs_IQSample dc; /*!< DC offset measured on packet */ 226 RCL_CmdBleCs_IQSample pct[RCL_BLE_CS_MAX_NUM_ANT_PATH]; /*!< Phase Correction Terms per antenna path (incl. extension) */ 227 uint32_t payload[RCL_BLE_CS_MAX_PAYLOAD_SIZE]; /*!< Payload containing random bit sequence (RX) */ 228 MagnData magn[RCL_BLE_CS_MAX_NUM_ANT_PATH]; /*!< Received magnitude data of tone per antenna path for quality estimation (incl. extension) */ 229 230 /* Echoed by PBE */ 231 uint16_t antennaPermIdx; /*!< Index of entry to be used from the antenna permutation table @ref RCL_CmdBleCs_AntennaConfig */ 232 uint16_t antennaPkt; /*!< Antenna used for packet exchange. No selection supported. */ 233 }; 234 235 /** 236 * @brief BLE Channel Sounding S2R Sample type definition 237 * 238 * One S2R sample can be interpreted multiple ways, depending of the signal source 239 */ 240 typedef union { 241 uint32_t word; /*!< Sample format for copying data */ 242 uint8_t byte[4]; /*!< Sample format of the Decoding Stage */ 243 RCL_CmdBleCs_IQSample iq; /*!< Sample format of the Front End Stage */ 244 } S2RSample; 245 246 /** 247 * @brief BLE Channel Sounding S2R IQ Data 248 * 249 * Container to store raw S2R samples of a BLE Channel Sounding Step 250 */ 251 struct RCL_CMD_BLE_CS_S2R_t { 252 uint8_t idx; /*!< The index of entry in the step list which the data belongs to */ 253 uint8_t phy; /*!< Phy the samples captured on */ 254 uint8_t channel; /*!< Frequency channel */ 255 uint8_t payloadLen; /*!< Payload length in bits */ 256 uint32_t payload0; /*!< Payload bits [00:31] */ 257 uint32_t payload1; /*!< Payload bits [32:63] */ 258 uint32_t payload2; /*!< Payload bits [64:95] */ 259 uint32_t payload3; /*!< Payload bits [96:127] */ 260 uint16_t iqLength; /*!< Number of valid iq samples in data[] */ 261 uint16_t reserved; 262 S2RSample data[]; /*!< Raw samples captured */ 263 }; 264 265 /** 266 * @brief BLE Channel Sounding Statistics 267 * 268 * Container to store the statistical outputs of the BLE Channel Sounding Event 269 */ 270 struct RCL_CMD_BLE_CS_STATS_t { 271 uint16_t nStepsWritten; /*!< Number of steps sent to the PBE through the FIFO */ 272 uint16_t nResultsRead; /*!< Number of results read from the PBE through the FIFO */ 273 uint16_t nStepsDone; /*!< Number of steps have been executed by the PBE */ 274 uint16_t nRxOk; /*!< Number of steps where pktResult == OK, filled by the CM0 */ 275 uint16_t nRxNok; /*!< Number of steps where pktResult != OK, filled by the CM0 */ 276 uint8_t nS2RDone; /*!< Number of Samples-To-Ram containers filled by the CM0 */ 277 int8_t lastRssi; /*!< Last valid RSSI received by the PBE */ 278 int16_t lastFoff; /*!< Last valid frequency offset received by the PBE */ 279 int16_t foffComp; /*!< Frequency offset compensation value */ 280 uint8_t numAntennaPath; /*!< Number of true antenna paths (1...4) */ 281 uint8_t reserved0; 282 uint16_t reserved1; 283 }; 284 285 /** 286 * @brief Enumerator of phy types 287 * 288 * Describes the phy packets shall be transmitted 289 */ 290 enum RCL_CMD_BLE_CS_Phy_e { 291 RCL_CmdBleCs_Phy_1M, 292 RCL_CmdBleCs_Phy_2M, 293 RCL_CmdBleCs_Phy_Length 294 }; 295 296 /** 297 * @brief Enumerator of role types 298 * 299 * Describes the role of the device during a BLE channel sounding event 300 */ 301 enum RCL_CMD_BLE_CS_Role_e { 302 RCL_CmdBleCs_Role_Initiator, 303 RCL_CmdBleCs_Role_Reflector, 304 RCL_CmdBleCs_Role_Length 305 }; 306 307 /** 308 * @brief Enumerator of step types 309 * 310 * Describes the available modes of a BLE CS step 311 */ 312 enum RCL_CMD_BLE_CS_StepMode_e { 313 RCL_CmdBleCs_StepMode_0, /*!< (M) Pkt-Pkt-Tn */ 314 RCL_CmdBleCs_StepMode_1, /*!< (M) Pkt-Pkt */ 315 RCL_CmdBleCs_StepMode_2, /*!< (M) Tn-Tn */ 316 RCL_CmdBleCs_StepMode_3, /*!< (O) Pkt-Tn-Tn-Pkt */ 317 RCL_CmdBleCs_StepMode_Length 318 }; 319 320 /** 321 * @brief Enumerator of packet status options 322 * 323 * Describes the available packet status words 324 */ 325 enum RCL_CMD_BLE_CS_PacketResult_e { 326 RCL_CmdBleCs_PacketResult_Error = -1, /*!< NA for mode-2 steps, otherwise command execution error. */ 327 RCL_CmdBleCs_PacketResult_Ok = 0, /*!< The packet reception was succesfull */ 328 RCL_CmdBleCs_PacketResult_BitError = 1, /*!< The packet was received with one or more bit errors */ 329 RCL_CmdBleCs_PacketResult_Lost = 2, /*!< The packet reception was terminated by timeout */ 330 RCL_CmdBleCs_PacketResult_Length 331 }; 332 333 /** 334 * @brief Enumerator of tFcs duration options 335 * 336 * Describes the available durations for frequency change 337 */ 338 enum RCL_CMD_BLE_CS_Tfcs_e { 339 RCL_CmdBleCs_Tfcs_80us, /*!< (C.1) */ 340 RCL_CmdBleCs_Tfcs_100us, 341 RCL_CmdBleCs_Tfcs_120us, 342 RCL_CmdBleCs_Tfcs_150us, /*!< (M) */ 343 RCL_CmdBleCs_Tfcs_Length, 344 }; 345 346 /** 347 * @brief Enumerator of tPm duration options 348 * 349 * Describes the available durations for phase measurement 350 */ 351 enum RCL_CMD_BLE_CS_Tpm_e { 352 RCL_CmdBleCs_Tpm_10us, 353 RCL_CmdBleCs_Tpm_20us, 354 RCL_CmdBleCs_Tpm_40us, /*!< (M) */ 355 RCL_CmdBleCs_Tpm_Length, 356 }; 357 358 /** 359 * @brief Enumerator of tIp duration 360 * 361 * Describes the available durations for interlude period 362 */ 363 enum RCL_CMD_BLE_CS_Tip_e { 364 RCL_CmdBleCs_Tip_40us, /*!< (C.1) */ 365 RCL_CmdBleCs_Tip_50us, 366 RCL_CmdBleCs_Tip_60us, 367 RCL_CmdBleCs_Tip_80us, /*!< (C.1) */ 368 RCL_CmdBleCs_Tip_145us, /*!< (M) */ 369 RCL_CmdBleCs_Tip_Length, 370 }; 371 372 /** 373 * @brief Enumerator of antenna switch duration 374 * 375 * Describes the available durations for antenna switching transient 376 */ 377 enum RCL_CMD_BLE_CS_Tsw_e { 378 RCL_CmdBleCs_Tsw_0us, /*!< (M) for 1x1 */ 379 RCL_CmdBleCs_Tsw_1us, 380 RCL_CmdBleCs_Tsw_2us, 381 RCL_CmdBleCs_Tsw_4us, 382 RCL_CmdBleCs_Tsw_10us, /*!< (M) */ 383 RCL_CmdBleCs_Tsw_Length 384 }; 385 386 /** 387 * @brief Enumerator of antenna configuration 388 * 389 * Describes the available values for configuration of 390 * antenna control for PCT measurement. 391 */ 392 enum RCL_CMD_BLE_CS_AntennaConfig_e { 393 RCL_CmdBleCs_AntennaConfig_1x1, /*!< (M) */ 394 RCL_CmdBleCs_AntennaConfig_2x1, 395 RCL_CmdBleCs_AntennaConfig_3x1, 396 RCL_CmdBleCs_AntennaConfig_4x1, 397 RCL_CmdBleCs_AntennaConfig_1x2, 398 RCL_CmdBleCs_AntennaConfig_1x3, 399 RCL_CmdBleCs_AntennaConfig_1x4, 400 RCL_CmdBleCs_AntennaConfig_2x2, 401 RCL_CmdBleCs_AntennaConfig_Length, 402 }; 403 404 /** 405 * @brief Enumerator of payload length 406 * 407 * Describes the available payload lengths 408 */ 409 enum RCL_CMD_BLE_CS_Payload_e { 410 RCL_CmdBleCs_Payload_None, 411 RCL_CmdBleCs_Payload_32bit, 412 RCL_CmdBleCs_Payload_64bit, 413 RCL_CmdBleCs_Payload_96bit, 414 RCL_CmdBleCs_Payload_128bit, 415 RCL_CmdBleCs_Payload_Length 416 }; 417 418 /** 419 * @brief Enumerator of RX gain 420 * 421 * Describes the available RX gain settings 422 */ 423 enum RCL_CMD_BLE_CS_RxGain_e { 424 RCL_CmdBleCs_RxGain_Auto = 0, 425 RCL_CmdBleCs_RxGain_MaxMinus21dB = 8, 426 RCL_CmdBleCs_RxGain_MaxMinus18dB = 9, 427 RCL_CmdBleCs_RxGain_MaxMinus15dB = 10, 428 RCL_CmdBleCs_RxGain_MaxMinus12dB = 11, 429 RCL_CmdBleCs_RxGain_MaxMinus9dB = 12, 430 RCL_CmdBleCs_RxGain_MaxMinus6dB = 13, 431 RCL_CmdBleCs_RxGain_MaxMinus3dB = 14, 432 RCL_CmdBleCs_RxGain_Max = 15, 433 }; 434 435 /** 436 * @brief Enumerator of tone quality 437 * 438 * Describes the classification of tone quality 439 */ 440 enum RCL_CMD_BLE_CS_ToneQuality_e { 441 RCL_CmdBleCs_ToneQuality_Good, 442 RCL_CmdBleCs_ToneQuality_Medium, 443 RCL_CmdBleCs_ToneQuality_Low, 444 RCL_CmdBleCs_ToneQuality_Unavailable, 445 RCL_CmdBleCs_ToneQuality_Length 446 }; 447 448 /** 449 * @brief Enumerator of tone extension slot 450 * 451 * Describes the classification of tone extension slot 452 */ 453 enum RCL_CMD_BLE_CS_ToneExtensionSlot_e { 454 RCL_CmdBleCs_ToneExtensionSlot_Disabled, 455 RCL_CmdBleCs_ToneExtensionSlot_Enabled_NoToneExpected, 456 RCL_CmdBleCs_ToneExtensionSlot_Enabled_ToneExpected, 457 RCL_CmdBleCs_ToneExtensionSlot_Length 458 }; 459 460 /***************************************************** 461 DC precalibration 462 *****************************************************/ 463 464 /** 465 * @brief Callback function for DC precalibration feature 466 * 467 * Describes the method that can select the right compensation value from the available precalibration table. 468 */ 469 typedef void (*RCL_CmdBleCs_PrecalCallback)(RCL_CmdBleCs_PrecalTable *table, uint8_t channel, uint32_t *hdc, uint32_t *ldc); 470 471 /** 472 * @brief DC precalibration entry 473 * 474 * Data structure to store a single DC precalibration entry. 475 */ 476 struct RCL_CMD_BLE_CS_PRECAL_ENTRY_t { 477 uint8_t channel; 478 uint8_t valid; 479 RCL_CmdBleCs_IQSample hdc; 480 RCL_CmdBleCs_IQSample ldc; 481 }; 482 483 /** 484 * @brief DC precalibration table 485 * 486 * Data structure to store and use the DC precalibration table. 487 */ 488 struct RCL_CMD_BLE_CS_PRECAL_TABLE_t { 489 RCL_CmdBleCs_PrecalCallback callback; 490 uint32_t timestamp; 491 uint16_t rxGain; 492 int8_t temperature; 493 uint8_t numEntries : 7; 494 uint8_t valid : 1; 495 RCL_CmdBleCs_PrecalEntry entries[]; 496 }; 497 498 /* Default callback implemented in the driver */ 499 void RCL_Handler_BLE_CS_PrecalDefaultCallback(RCL_CmdBleCs_PrecalTable *table, uint8_t channel, uint32_t *hdc, uint32_t *ldc); 500 501 /* Default configuration of DC precalibration */ 502 #define RCL_CmdBleCs_PrecalTable_Default() \ 503 { \ 504 .callback = RCL_Handler_BLE_CS_PrecalDefaultCallback, \ 505 .timestamp = 0, \ 506 .rxGain = 0x00F7, \ 507 .temperature = 0, \ 508 .numEntries = 4, \ 509 .valid = 0, \ 510 .entries = {{.channel = 10}, \ 511 {.channel = 30}, \ 512 {.channel = 50}, \ 513 {.channel = 70}}, \ 514 } 515 516 /** 517 * @brief DC precalibration command 518 * 519 * Command to run precalibration for a list of channels. 520 */ 521 struct RCL_CMD_BLE_CS_PRECAL_t { 522 RCL_Command common; 523 RCL_CmdBleCs_PrecalTable *table; 524 }; 525 526 /* Default configuration of DC precalibration command */ 527 #define RCL_CmdBleCs_Precal_Default(pTable) \ 528 { \ 529 .common = RCL_Command_Default(RCL_CMDID_BLE_CS_PRECAL, \ 530 RCL_Handler_BLE_CS_Precal), \ 531 .table = pTable \ 532 } 533 #define RCL_CmdBleCs_Precal_DefaultRuntime(pTable) (RCL_CmdBleCs_Precal) RCL_CmdBleCs_Precal_Default(pTable) 534 535 /***************************************************** 536 HCI interface 537 *****************************************************/ 538 /** 539 * @brief Container format for a single step in the subevent 540 * 541 * Compressed format used within a multibuffer 542 */ 543 struct RCL_CMD_BLE_CS_STEP_t { 544 uint32_t channelIdx : 7; /*!< Integer index of channel information (0: 2402MHz) */ 545 uint32_t mode : 2; /*!< Step mode @ref RCL_CmdBleCs_StepMode */ 546 uint32_t antennaPermIdx : 5; /*!< Index of entry to be used from the antenna permutation table @ref RCL_CmdBleCs_AntennaConfig */ 547 uint32_t toneExtension : 2; /*!< Enable tone extension, [0]=first tone (transmitted by initiator), [1]=second tone (transmitted by reflector) */ 548 uint32_t payloadLen : 3; /*!< Length of payload in units of 32bit words @ref RCL_CmdBleCs_Payload */ 549 uint32_t reserved : 13; 550 uint32_t aaTx; /*!< Access Address to be transmitted */ 551 uint32_t aaRx; /*!< Access Address to be received */ 552 uint32_t payloadTx[RCL_BLE_CS_MAX_PAYLOAD_SIZE]; /*!< Payload to transmit containing random bit sequence (TX) */ 553 uint32_t payloadRx[RCL_BLE_CS_MAX_PAYLOAD_SIZE]; /*!< Expected payload to receive containing random bit sequence (RX) */ 554 }; 555 556 /** 557 * @brief Container format for a batch of step results in the subevent (first segment) 558 * 559 * The data[] field contains the results in mode specific format (size varies with step-mode) 560 */ 561 struct RCL_CMD_BLE_CS_SUBEVENT_RESULTS_t { 562 uint8_t subeventCode; 563 uint16_t connectionHandle; 564 uint8_t configID; 565 uint16_t startAclConnectionEvent; 566 uint16_t procedureCounter; 567 int16_t frequencyCompensation; 568 uint8_t referencePowerLevel; 569 uint8_t procedureDoneStatus; 570 uint8_t subeventDoneStatus; 571 uint8_t abortReason; 572 uint8_t numAntennaPath; 573 uint8_t numStepsReported; 574 uint8_t data[]; 575 } __attribute__ ((packed)); 576 577 /** 578 * @brief Container format for a batch of step results in the subevent (second+ segment) 579 * 580 * The data[] field contains the results in mode specific format (size varies with step-mode) 581 */ 582 struct RCL_CMD_BLE_CS_SUBEVENT_RESULTS_CONTINUE_t { 583 uint8_t subeventCode; 584 uint16_t connectionHandle; 585 uint8_t configID; 586 uint8_t procedureDoneStatus; 587 uint8_t subeventDoneStatus; 588 uint8_t abortReason; 589 uint8_t numAntennaPath; 590 uint8_t numStepsReported; 591 uint8_t data[]; 592 } __attribute__ ((packed)); 593 594 /** 595 * @brief Container format for tones 596 * 597 */ 598 struct RCL_CMD_BLE_CS_STEP_RESULTS_TONE_t { 599 uint32_t i : 12; 600 uint32_t q : 12; 601 uint32_t quality : 8; 602 }; 603 604 /** 605 * @brief Container format for mode-0 step results 606 * 607 */ 608 struct RCL_CMD_BLE_CS_STEP_RESULTS_I0_t { 609 /* Common */ 610 uint8_t mode; 611 uint8_t channel; 612 uint8_t dataLength; 613 /* Packet */ 614 uint8_t packetAAQuality; 615 int8_t packetRssi; 616 uint8_t packetAntenna; 617 /* Frequency */ 618 int16_t measuredFreqOffset; 619 }; 620 621 /** 622 * @brief Container format for mode-0 step results 623 * 624 */ 625 struct RCL_CMD_BLE_CS_STEP_RESULTS_R0_t { 626 /* Common */ 627 uint8_t mode; 628 uint8_t channel; 629 uint8_t dataLength; 630 /* Packet */ 631 uint8_t packetAAQuality; 632 int8_t packetRssi; 633 uint8_t packetAntenna; 634 }; 635 636 /** 637 * @brief Container format for mode-1 step results 638 * 639 */ 640 struct RCL_CMD_BLE_CS_STEP_RESULTS_IR1_t { 641 /* Common */ 642 uint8_t mode; 643 uint8_t channel; 644 uint8_t dataLength; 645 /* Packet */ 646 uint8_t packetAAQuality; 647 uint8_t nadm; 648 int8_t packetRssi; 649 uint8_t packetAntenna; 650 int16_t packetToF; 651 }; 652 653 /** 654 * @brief Container format for mode-2 step results 655 * 656 */ 657 struct RCL_CMD_BLE_CS_STEP_RESULTS_IR2_t { 658 /* Common */ 659 uint8_t mode; 660 uint8_t channel; 661 uint8_t dataLength; 662 /* Tones */ 663 uint8_t antennaPermutationIndex; 664 RCL_CmdBleCs_Tone tones[]; 665 }; 666 667 /** 668 * @brief Container format for mode-3 step results 669 * 670 */ 671 struct RCL_CMD_BLE_CS_STEP_RESULTS_IR3_t { 672 /* Common */ 673 uint8_t mode; 674 uint8_t channel; 675 uint8_t dataLength; 676 /* Packet */ 677 uint8_t packetAAQuality; 678 uint8_t nadm; 679 int8_t packetRssi; 680 uint8_t packetAntenna; 681 int16_t packetToF; 682 /* Tones */ 683 uint8_t antennaPermutationIndex; 684 RCL_CmdBleCs_Tone tones[]; 685 }; 686 687 #endif 688
