1 //***************************************************************************** 2 // 3 //! @file am_hal_ble.h 4 //! 5 //! @brief HAL Functions for the BLE Interface. 6 //! 7 //! @addtogroup BLE3p BLE - BLE functions 8 //! @ingroup apollo3p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_BLE_H 49 #define AM_HAL_BLE_H 50 51 #include "am_hal_global.h" 52 #include "am_hal_status.h" 53 54 //***************************************************************************** 55 // 56 //! CMSIS-style macro for handling a variable BLEIF module number. 57 // 58 #define BLEIFn(n) ((BLEIF_Type*)(BLEIF_BASE + (n * (BLEIF_BASE - BLEIF_BASE)))) 59 //***************************************************************************** 60 61 //***************************************************************************** 62 // 63 //! BLE-specific status values. 64 // 65 //***************************************************************************** 66 typedef enum 67 { 68 // 69 //! This error occurs when an HCI read or write function is called while 70 //! another HCI communication function is already in progress. 71 // 72 AM_HAL_BLE_STATUS_BUS_BUSY = AM_HAL_STATUS_MODULE_SPECIFIC_START, 73 74 // 75 //! This error happens when the MCU tries to execute an HCI read, but the 76 //! BLE core hasn't asserted the BLEIRQ line. Try waiting for a BLEIRQ 77 //! interrupt, or polling the BLECIRQ bit in the BSTATUS register before 78 //! calling an HCI read function. 79 // 80 AM_HAL_BLE_STATUS_IRQ_LOW, 81 82 // 83 //! This error means that the MCU tried to execute an HCI write, but the BLE 84 //! core didn't assert its SPI_STATUS signal within the allotted timeout. 85 //! This might mean that there has been some error inside the BLE core. This 86 //! may require a reboot of the BLE core. 87 // 88 AM_HAL_BLE_STATUS_SPI_NOT_READY, 89 90 // 91 //! This error means we were trying to write, but the BLE core has requested 92 //! a READ instead. We will need to perform a read before we can retry this 93 //! write. 94 // 95 AM_HAL_BLE_REQUESTING_READ, 96 97 // 98 //! We are expecting an HCI response to a packet we just sent, but the BLE 99 //! core isn't asserting BLEIRQ. Its software may have crashed, and it may 100 //! need to restart. 101 // 102 AM_HAL_BLE_NO_HCI_RESPONSE, 103 104 // 105 //! Any of these errors indicate a problem with the BLE hardware that 106 //! requires a complete restart. 107 // 108 AM_HAL_BLE_FEATURE_DISABLED, 109 AM_HAL_BLE_SHUTDOWN_FAILED, 110 AM_HAL_BLE_REGULATOR_FAILED, 111 AM_HAL_BLE_POWERUP_INCOMPLETE, 112 AM_HAL_BLE_HCI_PACKET_INCOMPLETE, 113 AM_HAL_BLE_FIFO_ERROR, 114 AM_HAL_BLE_32K_CLOCK_UNSTABLE, 115 } 116 am_ble_status_e; 117 118 //***************************************************************************** 119 // 120 //! BLE power modes. 121 // 122 //***************************************************************************** 123 typedef enum 124 { 125 AM_HAL_BLE_POWER_ACTIVE, 126 AM_HAL_BLE_POWER_OFF, 127 } 128 am_hal_ble_power_state_e; 129 130 //***************************************************************************** 131 // 132 //! BLE SPI Clock settings. 133 // 134 //***************************************************************************** 135 typedef enum 136 { 137 AM_HAL_BLE_HCI_CLK_DIV2 = BLEIF_CLKCFG_FSEL_HFRC_DIV2, 138 AM_HAL_BLE_HCI_CLK_DIV4 = BLEIF_CLKCFG_FSEL_HFRC_DIV4, 139 AM_HAL_BLE_HCI_CLK_DIV8 = BLEIF_CLKCFG_FSEL_HFRC_DIV8, 140 AM_HAL_BLE_HCI_CLK_DIV16 = BLEIF_CLKCFG_FSEL_HFRC_DIV16, 141 AM_HAL_BLE_HCI_CLK_DIV32 = BLEIF_CLKCFG_FSEL_HFRC_DIV32, 142 AM_HAL_BLE_HCI_CLK_DIV64 = BLEIF_CLKCFG_FSEL_HFRC_DIV8, 143 } 144 am_hal_ble_hci_clock_e; 145 146 //***************************************************************************** 147 // 148 //! BLE Core Clock settings. 149 // 150 //***************************************************************************** 151 typedef enum 152 { 153 AM_HAL_BLE_CORE_MCU_CLK = 0x02, 154 AM_HAL_BLE_CORE_INTERNAL_CLK = 0x00, 155 } 156 am_hal_ble_core_clock_e; 157 158 //***************************************************************************** 159 // 160 //! Interrupts. 161 // 162 //***************************************************************************** 163 //! The B2M_STATE went into the shutdown state 164 #define AM_BLEIF_INT_B2MSHUTDN AM_REG_BLEIF_INTEN_B2MSHUTDN_M 165 //! The B2M_STATE went into the active state 166 #define AM_BLEIF_INT_B2MACTIVE AM_REG_BLEIF_INTEN_B2MACTIVE_M 167 //! The B2M_STATE went into the sleep state 168 #define AM_BLEIF_INT_B2MSLEEP AM_REG_BLEIF_INTEN_B2MSLEEP_M 169 //! command queue received and error 170 #define AM_BLEIF_INT_CQERR AM_REG_BLEIF_INTEN_CQERR_M 171 //! CQ write operation performed a register write with the register address bit 172 //! 0 set to 1. The low address bits in the CQ address fields are unused and 173 //! bit 0 can be used to trigger an interrupt to indicate when this register 174 //! write is performed by the CQ operation. 175 #define AM_BLEIF_INT_CQUPD AM_REG_BLEIF_INTEN_CQUPD_M 176 //! The command queue is waiting interrupt 177 #define AM_BLEIF_INT_CQPAUSED AM_REG_BLEIF_INTEN_CQPAUSED_M 178 //! DMA Error 179 #define AM_BLEIF_INT_DERR AM_REG_BLEIF_INTEN_DERR_M 180 //! DMA Complete 181 #define AM_BLEIF_INT_DCMP AM_REG_BLEIF_INTEN_DCMP_M 182 //! THis is the BLE Core IRQ signal 183 #define AM_BLEIF_INT_BLECIRQ AM_REG_BLEIF_INTEN_BLECIRQ_M 184 //! This is the illegal command interrupt. 185 #define AM_BLEIF_INT_ICMD AM_REG_BLEIF_INTEN_ICMD_M 186 //! This is the illegal FIFO access interrupt. 187 #define AM_BLEIF_INT_IACC AM_REG_BLEIF_INTEN_IACC_M 188 //! Any change in the B2M_STATE signal from the BLE Core will set this interrupt 189 #define AM_BLEIF_INT_B2MST AM_REG_BLEIF_INTEN_B2MST_M 190 //! This is the Write FIFO Overflow interrupt. 191 #define AM_BLEIF_INT_FOVFL AM_REG_BLEIF_INTEN_FOVFL_M 192 //! This is the Read FIFO Underflow interrupt. 193 #define AM_BLEIF_INT_FUNDFL AM_REG_BLEIF_INTEN_FUNDFL_M 194 //! This is the FIFO Threshold interrupt. 195 #define AM_BLEIF_INT_THR AM_REG_BLEIF_INTEN_THR_M 196 //! This is the Command Complete interrupt. 197 #define AM_BLEIF_INT_CMDCMP AM_REG_BLEIF_INTEN_CMDCMP_M 198 199 #define AM_HAL_BLE_INT_B2MSHUTDN BLEIF_INTEN_B2MSHUTDN_Msk //!< The B2M_STATE went into the shutdown state 200 #define AM_HAL_BLE_INT_B2MACTIVE BLEIF_INTEN_B2MACTIVE_Msk //!< The B2M_STATE went into the active state 201 #define AM_HAL_BLE_INT_B2MSLEEP BLEIF_INTEN_B2MSLEEP_Msk //!< The B2M_STATE went into the sleep state 202 #define AM_HAL_BLE_INT_CQERR BLEIF_INTEN_CQERR_Msk //!< command queue received and error 203 204 //! CQ write operation performed a register write with the register address bit 205 //! 0 set to 1. The low address bits in the CQ address fields are unused and 206 //! bit 0 can be used to trigger an interrupt to indicate when this register 207 //! write is performed by the CQ operation. 208 #define AM_HAL_BLE_INT_CQUPD BLEIF_INTEN_CQUPD_Msk 209 210 #define AM_HAL_BLE_INT_CQPAUSED BLEIF_INTEN_CQPAUSED_Msk //!< The command queue is waiting interrupt 211 #define AM_HAL_BLE_INT_DERR BLEIF_INTEN_DERR_Msk //!< DMA Error 212 #define AM_HAL_BLE_INT_DCMP BLEIF_INTEN_DCMP_Msk //!< DMA Complete 213 #define AM_HAL_BLE_INT_BLECSSTAT BLEIF_INTEN_BLECSSTAT_Msk //!< This is the BLE Core SPI STATUS signal. 214 #define AM_HAL_BLE_INT_BLECIRQ BLEIF_INTEN_BLECIRQ_Msk //!< This is the BLE Core IRQ signal 215 #define AM_HAL_BLE_INT_ICMD BLEIF_INTEN_ICMD_Msk //!< This is the illegal command interrupt. 216 #define AM_HAL_BLE_INT_IACC BLEIF_INTEN_IACC_Msk //!< This is the illegal FIFO access interrupt. 217 #define AM_HAL_BLE_INT_B2MST BLEIF_INTEN_B2MST_Msk //!< Any change in the B2M_STATE signal from the BLE Core will set this interrupt 218 #define AM_HAL_BLE_INT_FOVFL BLEIF_INTEN_FOVFL_Msk //!< This is the Write FIFO Overflow interrupt. 219 #define AM_HAL_BLE_INT_FUNDFL BLEIF_INTEN_FUNDFL_Msk //!< This is the Read FIFO Underflow interrupt. 220 #define AM_HAL_BLE_INT_THR BLEIF_INTEN_THR_Msk //!< This is the FIFO Threshold interrupt. 221 #define AM_HAL_BLE_INT_CMDCMP BLEIF_INTEN_CMDCMP_Msk //!< This is the Command Complete interrupt. 222 223 #define AM_HAL_BLE_INT_BLECSSTATN BLEIF_INTSTAT_B2MSHUTDN_Msk 224 #define AM_HAL_BLE_INT_BLECIRQN BLEIF_INTSTAT_B2MACTIVE_Msk 225 226 //***************************************************************************** 227 // 228 // Type definitions. 229 // 230 //***************************************************************************** 231 #define am_hal_ble_buffer(A) \ 232 union \ 233 { \ 234 uint32_t words[(A + 3) >> 2]; \ 235 uint8_t bytes[A]; \ 236 } 237 238 //! Function pointer for non-blocking ble read callbacks. 239 typedef void (*am_hal_ble_transfer_complete_cb_t)(uint8_t *pui8Data, uint32_t ui32Length, void *pvContext); 240 241 // 242 //! Patch container 243 // 244 typedef struct 245 { 246 uint32_t ui32Type; 247 uint32_t ui32Length; 248 uint32_t ui32CRC; 249 const uint32_t *pui32Data; 250 } 251 am_hal_ble_patch_t; 252 253 // 254 //! Configuration structure for the BLE module. 255 // 256 typedef struct 257 { 258 // HCI interface options. 259 uint32_t ui32SpiClkCfg; //!< Configure the HCI interface clock. 260 uint32_t ui32ReadThreshold; //!< Internal HCI READ FIFO size 261 uint32_t ui32WriteThreshold; //!< Internal HCI WRITE FIFO size. 262 263 // BLE options. 264 uint32_t ui32BleClockConfig; //!< Configure the BLE core clock. 265 #if 0 266 uint32_t ui32ClockDrift; //!< Set the expected BLE clock drift. 267 uint32_t ui32SleepClockDrift; //!< Set the expected sleep clock accuracy. 268 bool bAgcEnabled; //!< Enable/Disable AGC 269 bool bSleepEnabled; //!< Enable/Disable Sleep Algorithm 270 #endif 271 272 // Patches 273 bool bUseDefaultPatches; //!< Apply the default patches? 274 } 275 am_hal_ble_config_t; 276 277 // 278 //! Default options for the BLE module. 279 // 280 extern const am_hal_ble_config_t am_hal_ble_default_config; 281 282 //***************************************************************************** 283 // 284 //! Structure for sending SPI commands. 285 // 286 //***************************************************************************** 287 typedef struct 288 { 289 uint32_t *pui32Data; 290 uint8_t pui8Offset[3]; 291 uint8_t ui8OffsetLen; 292 uint16_t ui16Length; 293 uint8_t ui8Command; 294 uint8_t ui8RepeatCount; 295 bool bContinue; 296 am_hal_ble_transfer_complete_cb_t pfnTransferCompleteCB; 297 void *pvContext; 298 } 299 am_hal_ble_transfer_t; 300 301 //***************************************************************************** 302 // 303 //! Vendor Specific commands. 304 // 305 //! @note Lengths are reported as "4 + <parameter length>". Each vendor-specific 306 //! header is 4 bytes long. This definition allows the macro version of the 307 //! length to be used in all BLE APIs. 308 // 309 //***************************************************************************** 310 #define AM_HAL_BLE_SET_BD_ADDR_OPCODE 0xFC32 311 #define AM_HAL_BLE_SET_BD_ADDR_LENGTH (4 + 6) 312 313 #define AM_HAL_BLE_SET_TX_POWER_OPCODE 0xFC3B 314 #define AM_HAL_BLE_SET_TX_POWER_LENGTH (4 + 3) 315 316 #define AM_HAL_BLE_READ_VERSIONS_OPCODE 0xFD01 317 #define AM_HAL_BLE_READ_VERSIONS_LENGTH (4 + 0) 318 319 #define AM_HAL_BLE_PLF_REGISTER_READ_OPCODE 0xFD02 320 #define AM_HAL_BLE_PLF_REGISTER_READ_LENGTH (4 + 4) 321 322 #define AM_HAL_BLE_PLF_REGISTER_WRITE_OPCODE 0xFD03 323 #define AM_HAL_BLE_PLF_REGISTER_WRITE_LENGTH (4 + 8) 324 325 #define AM_HAL_BLE_GET_RSSI_OPCODE 0x1405 326 #define AM_HAL_BLE_GET_RSSI_LENGTH (4 + 0) 327 328 #define AM_HAL_BLE_SET_SLEEP_OPCODE 0xFD09 329 #define AM_HAL_BLE_SET_SLEEP_LENGTH (4 + 0) 330 331 #define AM_HAL_BLE_SPI_SENDFRAME_OPCODE 0xFD04 332 #define AM_HAL_BLE_SPI_SENDFRAME_LENGTH (4 + 1) 333 334 #define AM_HAL_BLE_SET_BD_ADDR_CMD(...) {0x01, 0x32, 0xFC, 0x06, __VA_ARGS__} 335 #define AM_HAL_BLE_SET_TX_POWER_CMD(...) {0x01, 0x3B, 0xFC, 0x03, __VA_ARGS__} 336 #define AM_HAL_BLE_SET_READ_VERSIONS_CMD() {0x01, 0x01, 0xFD, 0x00} 337 #define AM_HAL_BLE_PLF_REGISTER_READ_CMD(...) {0x01, 0x02, 0xFD, 0x04, __VA_ARGS__} 338 #define AM_HAL_BLE_PLF_REGISTER_WRITE_CMD(...) {0x01, 0x03, 0xFD, 0x08, __VA_ARGS__} 339 #define AM_HAL_BLE_GET_RSSI_CMD() {0x01, 0x05, 0x14, 0x00} 340 #define AM_HAL_BLE_SET_SLEEP_CMD() {0x01, 0x09, 0xFD, 0x00} 341 #define AM_HAL_BLE_SPI_SENDFRAME_CMD(...) {0x01, 0x04, 0xFD, 0x01, __VA_ARGS__} 342 343 //***************************************************************************** 344 // 345 //! State variables for the BLE module. 346 // 347 //***************************************************************************** 348 typedef struct 349 { 350 //! Handle validation prefix. 351 am_hal_handle_prefix_t prefix; 352 353 //! Which BLE module instance is this? 354 uint32_t ui32Module; 355 356 //! Apply the default patches during the "boot" function? 357 bool bUseDefaultPatches; 358 359 //! What was the last command that we started? 360 am_hal_ble_transfer_t sCurrentTransfer; 361 362 //! If a write is interrupted by a read, we have to save the write 363 //! transaction to execute later. That saved write goes here. 364 am_hal_ble_transfer_t sSavedTransfer; 365 366 //! How far along are we? 367 uint32_t ui32TransferIndex; 368 369 //! Has this radio already been patched? 370 bool bPatchComplete; 371 372 //! Are we in the middle of a continue packet? 373 bool bContinuePacket; 374 375 //! Was our last operation to send a TX packet? If we have two TX packets in 376 //! a row, we need special handling to get the timing right. 377 bool bLastPacketWasTX; 378 379 //! Do we have a saved packet? 380 bool bSavedPacket; 381 382 //! Is the bus already in use? 383 bool bBusy; 384 385 //! Has the last command completed? 386 bool bCmdComplete; 387 388 //! Has the last DMA action completed? 389 bool bDmaComplete; 390 391 //! Has the BLE core's flow control signal been reset? 392 bool bFlowControlComplete; 393 } 394 am_hal_ble_state_t; 395 396 //***************************************************************************** 397 // 398 //! SPI command macros. 399 // 400 //***************************************************************************** 401 #define AM_HAL_BLE_WRITE 1 402 #define AM_HAL_BLE_READ 2 403 404 //***************************************************************************** 405 // 406 //! HCI packet types. 407 // 408 //***************************************************************************** 409 #define AM_HAL_BLE_RAW 0x0 410 #define AM_HAL_BLE_CMD 0x1 411 #define AM_HAL_BLE_ACL 0x2 412 #define AM_HAL_BLE_EVT 0x4 413 414 //***************************************************************************** 415 // 416 // External function declarations. 417 // 418 //***************************************************************************** 419 #ifdef __cplusplus 420 extern "C" 421 { 422 #endif 423 424 //***************************************************************************** 425 // 426 // Basics 427 // 428 // Initialization, enable/disable, and general configuration. 429 // 430 //***************************************************************************** 431 432 //***************************************************************************** 433 // 434 //! @brief Initialize the internal state variables for the BLE module. 435 //! 436 //! @param ui32Module - Which BLE module to use. 437 //! @param ppHandle - Pointer to a handle variable to be initialized. 438 //! 439 //! @details This function initializes the internal state variables associated with a 440 //! particular BLE module and yields a handle that may be used to perform 441 //! additional operations with that BLE module. 442 //! 443 //! This function must be called before any other BLE module operation. 444 //! 445 //! @return BLE status code. 446 // 447 //***************************************************************************** 448 extern uint32_t am_hal_ble_initialize(uint32_t ui32Module, void **ppHandle); 449 450 //***************************************************************************** 451 // 452 //! @brief De-initialize the internal state variables for the BLE module. 453 //! 454 //! @param pHandle - Handle variable to be de-initialized. 455 //! 456 //! @note This function invalidates a previously initialized BLE module handle and 457 //! deletes the contents of the internal state variables associated with it. 458 //! This could be used in situations where the caller wants to prevent future 459 //! function calls to a particular BLE module. 460 //! 461 //! @return BLE status code. 462 // 463 //***************************************************************************** 464 extern uint32_t am_hal_ble_deinitialize(void *pHandle); 465 466 //***************************************************************************** 467 // 468 //! @brief Configure a BLE module. 469 //! 470 //! @param pHandle - Handle for the BLE module. 471 //! @param psConfig - Pointer to a BLE configuration structure. 472 //! 473 //! @details This routine performs the necessary configuration steps to prepare the 474 //! physical BLE interface for operation. This function should be called after 475 //! \e am_hal_ble_enable() and before any other BLE operation. The \e psConfig 476 //! parameter may be used to set a specific interface clock frequency or modify 477 //! the FIFO read and write thresholds, but most users will get the best 478 //! results from the default settings stored in the global configuration 479 //! structure \e am_hal_ble_default_config. 480 //! 481 //! @note This function will only work if the BLE module has previously been 482 //! enabled. 483 //! 484 //! @return BLE status code. 485 // 486 //***************************************************************************** 487 extern uint32_t am_hal_ble_config(void *pHandle, const am_hal_ble_config_t *psConfig); 488 489 //***************************************************************************** 490 // 491 //! @brief Enable the BLE module. 492 //! 493 //! @note Performs the power-up or power-down sequence for the BLE module referred to 494 //! be \e pHandle. This should be called after am_hal_ble_initialize(), but 495 //! before am_hal_ble_config(). 496 //! @par 497 //! @note The ui32PowerState variable must be set to either AM_HAL_BLE_POWER_ACTIVE 498 //! or AM_HAL_BLE_POWER_OFF. 499 //! @par 500 //! @note After this function is called, the BLE core will be in its startup or 501 //! "patching" mode. 502 //! 503 //! @param pHandle - Handle for the BLE module. 504 //! @param ui32PowerState - Determines whether BLE is powered on or off. 505 //! 506 //! @return BLE status code. 507 //! 508 // 509 //***************************************************************************** 510 uint32_t am_hal_ble_power_control(void *pHandle, uint32_t ui32PowerState); 511 512 //***************************************************************************** 513 // 514 //! @brief Boot the BLE module 515 //! 516 //! @note This function performs the complete patching process for the BLE core and 517 //! returns with the BLE core in HCI mode. If you ask for the default patches 518 //! your am_hal_ble_config_t structure, then this is the last function you need 519 //! to call on startup. You don't need to call any of the patching functions. 520 //! 521 //! @param pHandle - Handle for the BLE module. 522 //! 523 //! @return BLE status code. 524 // 525 //***************************************************************************** 526 extern uint32_t am_hal_ble_boot(void *pHandle); 527 528 //***************************************************************************** 529 // 530 //! @brief Patching functions. 531 // 532 //! @note The following functions allow the caller to apply "patches" to the BLE core 533 //! during its startup phase. These are pre-made configuration files that change 534 //! the operation parameters of the BLE radio. If you have received a patch file 535 //! from the manufacturer, you may use the \e am_hal_ble_patch_apply() function 536 //! during startup to apply these settings to the BLE core. Otherwise, you may 537 //! skip this step by calling the \e am_hal_ble_patch_complete() function. 538 // 539 //***************************************************************************** 540 541 //***************************************************************************** 542 // 543 //! @brief Apply a patch to the BLE core. 544 //! 545 //! @param pHandle - Handle for the BLE module. 546 //! @param psPatch - Pointer to a structure describing the patch. 547 //! 548 //! The BLE core is an independent processor that executes code from an 549 //! on-board ROM. Its behavior can be altered through "patches" which are 550 //! binary snippets of code that may be loaded at startup to overlay or replace 551 //! sections of the original ROM (for instance, to modify trim settings). This 552 //! function allows the caller to apply one of these patches. 553 //! 554 //! @note Patches must be applied after the BLE module is enabled and configured, but 555 //! before standard HCI operation begins. This is the only time where the BLE 556 //! core is able to accept patch files. 557 //! 558 //! @return BLE status code. 559 // 560 //***************************************************************************** 561 extern uint32_t am_hal_ble_patch_apply(void *pHandle, am_hal_ble_patch_t *psPatch); 562 563 //***************************************************************************** 564 //! @brief Apply a B0 silicon patch to the BLE core 565 //! 566 //! @param pHandle - Handle for BLE Module 567 //! 568 //! @return BLE status code 569 //***************************************************************************** 570 extern uint32_t am_hal_ble_patch_preload(void *pHandle); 571 572 //***************************************************************************** 573 // 574 //! @brief Apply the default manufacturer patch to the BLE core. 575 //! 576 //! @param pHandle Handle for the BLE module. 577 //! 578 //! The BLE core is an independent processor that executes code from an 579 //! on-board ROM. Its behavior can be altered through "patches" which are 580 //! binary snippets of code that may be loaded at startup to overlay or replace 581 //! sections of the original ROM (for instance, to modify trim settings). This 582 //! function allows the caller to apply one of these patches. 583 //! 584 //! Patches must be applied after the BLE module is enabled and configured, but 585 //! before standard HCI operation begins. This is the only time where the BLE 586 //! core is able to accept patch files. 587 //! 588 //! @return BLE status code. 589 // 590 //***************************************************************************** 591 extern uint32_t am_hal_ble_default_patch_apply(void *pHandle); 592 593 //***************************************************************************** 594 // 595 //! @brief Complete the patching phase. 596 //! 597 //! @param pHandle Handle for the BLE module. 598 //! 599 //! After the BLE core is enabled and configured, it enters a "patching mode" 600 //! where it can accept patches from the main CPU. Once all patches have been 601 //! applied using the \e am_hal_ble_patch_apply() function. The application 602 //! must call this function to command the BLE core to switch to standard HCI 603 //! mode. 604 //! 605 //! @return BLE status code. 606 // 607 //***************************************************************************** 608 extern uint32_t am_hal_ble_patch_complete(void *pHandle); 609 610 //***************************************************************************** 611 // 612 //! @brief Manually set modulation characteristic 613 //! based on the tested values at customer side. 614 //! manually set frequency offset for 10101010 or 01010101 pattern 615 //! @param pHandle 616 //! @param ui8ModFrqOffset 617 //! @return 618 // 619 //***************************************************************************** 620 extern uint32_t am_hal_ble_transmitter_modex_set(void *pHandle, uint8_t ui8ModFrqOffset); 621 622 //***************************************************************************** 623 // 624 //! @brief Performs a blocking read or write to the BLE core. 625 //! 626 //! @param pHandle - Handle for the BLE module. 627 //! @param psTransfer - Structure describing the transaction to execute. 628 //! 629 //! @return BLE status code. 630 //***************************************************************************** 631 extern uint32_t am_hal_ble_blocking_transfer(void *pHandle, am_hal_ble_transfer_t *psTransfer); 632 633 //***************************************************************************** 634 // 635 //! @brief Complete the patching phase. 636 //! 637 //! @param pHandle - Handle for the BLE module. 638 //! @param psTransfer - pointer to transfer parameters 639 //! 640 //! After the BLE core is enabled and configured, it enters a "patching mode" 641 //! where it can accept patches from the main CPU. Once all patches have been 642 //! applied using the \e am_hal_ble_patch_apply() function. The application 643 //! must call this function to command the BLE core to switch to standard HCI 644 //! mode. 645 //! 646 //! @return BLE status code. 647 // 648 //***************************************************************************** 649 extern uint32_t am_hal_ble_nonblocking_transfer(void *pHandle, am_hal_ble_transfer_t *psTransfer); 650 651 // High-level HCI APIs 652 653 654 //***************************************************************************** 655 //! @brief 656 //! 657 //! @param pui32Command 658 //! @param ui32OpCode 659 //! @param ui32TotalLength 660 //! @param pui8Parameters 661 //! @return uint32_t 662 // 663 //***************************************************************************** 664 extern uint32_t am_hal_ble_vs_command_build(uint32_t *pui32Command, 665 uint32_t ui32OpCode, 666 uint32_t ui32TotalLength, 667 uint8_t *pui8Parameters); 668 //***************************************************************************** 669 //! @brief 670 //! 671 //! @param pHandle 672 //! @param pui32Data 673 //! @param pui32BytesReceived 674 //! @return uint32_t 675 // 676 //***************************************************************************** 677 extern uint32_t am_hal_ble_blocking_hci_read(void *pHandle, 678 uint32_t *pui32Data, 679 uint32_t *pui32BytesReceived); 680 //***************************************************************************** 681 //! @brief 682 //! 683 //! @param pHandle 684 //! @param ui8Type 685 //! @param pui32Data 686 //! @param ui32NumBytes 687 //! @return uint32_t 688 // 689 //***************************************************************************** 690 extern uint32_t am_hal_ble_blocking_hci_write(void *pHandle, 691 uint8_t ui8Type, 692 uint32_t *pui32Data, 693 uint32_t ui32NumBytes); 694 695 //***************************************************************************** 696 //! @brief 697 //! 698 //! @param pHandle 699 //! @param pui32Data 700 //! @param pfnCallback 701 //! @param pvContext 702 //! @return uint32_t 703 // 704 //***************************************************************************** 705 extern uint32_t am_hal_ble_nonblocking_hci_read(void *pHandle, 706 uint32_t *pui32Data, 707 am_hal_ble_transfer_complete_cb_t pfnCallback, 708 void *pvContext); 709 710 //***************************************************************************** 711 //! @brief 712 //! 713 //! @param pHandle 714 //! @param ui8Type 715 //! @param pui32Data 716 //! @param ui32NumBytes 717 //! @param pfnCallback 718 //! @param pvContext 719 //! @return uint32_t 720 // 721 //***************************************************************************** 722 extern uint32_t am_hal_ble_nonblocking_hci_write(void *pHandle, 723 uint8_t ui8Type, 724 uint32_t *pui32Data, 725 uint32_t ui32NumBytes, 726 am_hal_ble_transfer_complete_cb_t pfnCallback, 727 void *pvContext); 728 729 //***************************************************************************** 730 // 731 //! @brief Set one of the trim values for the BLE core. 732 //! 733 //! @param pHandle is the BLE module handle 734 //! @param ui32BleCoreAddress is the target address for the trim value. 735 //! @param ui32TrimValue is the trim value to write to the BLE core. 736 //! @param ui32TrimMask is the trim mask for ui32TrimValue 737 //! 738 //! This function takes a BLE core trim value from the MCU memory and writes it 739 //! to a trim register in the BLE core. 740 //! 741 //! @return BLE status code. 742 // 743 //***************************************************************************** 744 extern uint32_t am_hal_ble_trim_set(void *pHandle, 745 uint32_t ui32BleCoreAddress, 746 uint32_t ui32TrimValue, 747 uint32_t ui32TrimMask); 748 749 750 //***************************************************************************** 751 //! @brief Set the bandgap voltage, bandgap current, and retention LDO output values 752 //! 753 //! @details Set the bandgap voltage, bandgap current, and retention LDO output 754 //! valuesbased on the tested values stored in non-volatile memory. 755 //! 756 //! @param pHandle 757 //! @return uint32_t 758 //***************************************************************************** 759 uint32_t am_hal_ble_default_trim_set_ramcode(void *pHandle); 760 761 762 763 //***************************************************************************** 764 // 765 //! @brief Sends a signal to wake up the BLE controller 766 //! 767 //! @param pHandle is the Handle for the BLE module. 768 //! @param ui32Mode is determines the value of the WAKE signal. 769 //! 770 //! The BLE core needs to be awake before we send data to it. This function 771 //! sends a signal to the BLE core that tells it that we intend to send it 772 //! data. When the BLE core wakes up, it will generate a BLECSSTAT interrupt, 773 //! and the SPISTATUS bit in the BSTATUS register will be set. 774 //! 775 //! @return BLE status code. 776 // 777 //***************************************************************************** 778 extern uint32_t am_hal_ble_wakeup_set(void *pHandle, uint32_t ui32Mode); 779 780 //***************************************************************************** 781 // 782 //! @brief Read a register value directly from the BLE Core. 783 //! 784 //! @param pHandle is the Handle for the BLE module. 785 //! @param ui32Address is the address of the register. 786 //! @param *pui32Value is a pointer where the register value will be stored. 787 //! 788 //! This function uses a vendor-specific sequence of blocking HCI commands to 789 //! read one of the internal registers within the BLE Core. The value stored in 790 //! this register will be written to the location specified by \e pui32Value. 791 //! 792 //! This function is mostly used during initial radio setup or for internal 793 //! test commands. Standard applications will not need to call this function 794 //! directly. 795 //! 796 //! @note This function uses multiple blocking HCI commands in sequence. It 797 //! should not be used in any situation where blocking commands are not 798 //! desired. Do not use it in applications where interrupt-driven BLE 799 //! operations have already started. 800 //! 801 //! @return BLE status code. 802 // 803 //***************************************************************************** 804 extern uint32_t am_hal_ble_plf_reg_read(void *pHandle, uint32_t ui32Address, uint32_t *pui32Value); 805 806 //***************************************************************************** 807 // 808 //! @brief Write a register value directly to the BLE Core. 809 //! 810 //! @param pHandle - the Handle for the BLE module. 811 //! @param ui32Address - the address of the register. 812 //! @param ui32Value - the value to write. 813 //! 814 //! This function uses a vendor-specific sequence of blocking HCI commands to 815 //! write one of the internal registers within the BLE Core. 816 //! 817 //! This function is mostly used during initial radio setup or for internal 818 //! test commands. Standard applications will not need to call this function 819 //! directly. 820 //! 821 //! @note This function uses multiple blocking HCI commands in sequence. It 822 //! should not be used in any situation where blocking commands are not 823 //! desired. Do not use it in applications where interrupt-driven BLE 824 //! operations have already started. 825 //! 826 //! @return BLE status code. 827 // 828 //***************************************************************************** 829 extern uint32_t am_hal_ble_plf_reg_write(void *pHandle, uint32_t ui32Address, uint32_t ui32Value); 830 831 //***************************************************************************** 832 // 833 //! @brief Change the sleep behavior of the BLE core. 834 //! 835 //! Set BLE sleep enable/disable for the BLE core. 836 //! 837 //! @param pHandle - the Handle for the BLE module. 838 //! @param enable - sets the desired sleep behavior. 839 //! - 'true' set sleep enable, 840 //! - 'false' set sleep disable 841 //! 842 //! This function uses a vendor-specific sequence of blocking HCI commands to 843 //! change the default behavior of the BLE core between radio events. Set \e 844 //! enable to true to allow the BLE core to sleep between radio events, or 845 //! false to keep the BLE core awake at all times. The default behavior on 846 //! startup allows the BLE core to sleep. Most applications will not need to 847 //! modify this setting. 848 //! 849 //! @note This function uses multiple blocking HCI commands in sequence. It 850 //! should not be used in any situation where blocking commands are not 851 //! desired. Do not use it in applications where interrupt-driven BLE 852 //! operations have already started. 853 //! 854 //! @return BLE status code. 855 // 856 //***************************************************************************** 857 extern uint32_t am_hal_ble_sleep_set(void *pHandle, bool enable); 858 859 //***************************************************************************** 860 // 861 //! @brief Check the sleep behavior of the BLE core. 862 //! 863 //! @param pHandle - is the Handle for the BLE module. 864 //! 865 //! This function uses a vendor-specific sequence of blocking HCI commands to 866 //! check whether the BLE core is set to go to sleep between BLE transactions. 867 //! This function will return "true" if BLE sleep is enabled, or "false" if it 868 //! is disabled. 869 //! 870 //! @note This function uses multiple blocking HCI commands in sequence. It 871 //! should not be used in any situation where blocking commands are not 872 //! desired. Do not use it in applications where interrupt-driven BLE 873 //! operations have already started. 874 //! 875 //! @return BLE status code. 876 // 877 //***************************************************************************** 878 extern bool am_hal_ble_sleep_get(void *pHandle); 879 880 //***************************************************************************** 881 // 882 //! @brief Change the TX power setting of the BLE core. 883 //! 884 //! @param pHandle - the Handle for the BLE module. 885 //! @param ui32TxPower - the desired power setting. 886 //! 0x03->-20dBm 0x04->-10dBm 0x05->-5dBm 0x08->0dBm 0x0F->4dBm 887 //! 888 //! This function uses a vendor-specific sequence of blocking HCI commands to 889 //! change the TX power setting of the radio. 890 //! 891 //! @note This function uses multiple blocking HCI commands in sequence. It 892 //! should not be used in any situation where blocking commands are not 893 //! desired. Do not use it in applications where interrupt-driven BLE 894 //! operations have already started. 895 //! 896 //! @return BLE status code. 897 // 898 //***************************************************************************** 899 extern uint32_t am_hal_ble_tx_power_set(void *pHandle, uint8_t ui32TxPower); 900 901 //***************************************************************************** 902 // 903 // Interrupts. 904 // 905 //***************************************************************************** 906 //***************************************************************************** 907 //! @brief 908 //! 909 //! @param pHandle 910 //! @param ui32Status 911 //! @return uint32_t 912 //***************************************************************************** 913 extern uint32_t am_hal_ble_int_service(void *pHandle, uint32_t ui32Status); 914 915 //***************************************************************************** 916 //! @brief 917 //! 918 //! @param pHandle 919 //! @param ui32InterruptMask 920 //! @return uint32_t 921 //***************************************************************************** 922 extern uint32_t am_hal_ble_int_enable(void *pHandle, uint32_t ui32InterruptMask); 923 924 //***************************************************************************** 925 //! @brief 926 //! 927 //! @param pHandle 928 //! @param ui32InterruptMask 929 //! @return uint32_t 930 //***************************************************************************** 931 extern uint32_t am_hal_ble_int_disable(void *pHandle, uint32_t ui32InterruptMask); 932 933 //***************************************************************************** 934 //! @brief 935 //! 936 //! @param pHandle 937 //! @param bEnabledOnly 938 //! @return uint32_t 939 //***************************************************************************** 940 extern uint32_t am_hal_ble_int_status(void *pHandle, bool bEnabledOnly); 941 942 //***************************************************************************** 943 //! @brief 944 //! 945 //! @param pHandle 946 //! @param ui32InterruptMask 947 //! @return uint32_t 948 //***************************************************************************** 949 extern uint32_t am_hal_ble_int_clear(void *pHandle, uint32_t ui32InterruptMask); 950 //***************************************************************************** 951 //! @brief 952 //! 953 //! @param pHandle 954 //! @return uint32_t 955 //***************************************************************************** 956 extern uint32_t am_hal_ble_check_32k_clock(void *pHandle); 957 958 959 //***************************************************************************** 960 // 961 //! Debug trace pins. 962 // 963 //***************************************************************************** 964 #ifdef AM_DEBUG_BLE_TIMING 965 966 #define BLE_DEBUG_TRACE_01 11 967 #define BLE_DEBUG_TRACE_02 28 968 #define BLE_DEBUG_TRACE_03 26 969 #define BLE_DEBUG_TRACE_04 4 970 #define BLE_DEBUG_TRACE_05 18 971 #define BLE_DEBUG_TRACE_06 14 972 #define BLE_DEBUG_TRACE_07 6 973 #define BLE_DEBUG_TRACE_08 45 974 #define BLE_DEBUG_TRACE_09 12 975 #define BLE_DEBUG_TRACE_10 13 976 #define BLE_DEBUG_TRACE_11 10 977 #define BLE_LOCK_TRACE_PIN BLE_DEBUG_TRACE_11 978 979 #define am_hal_debug_gpio_set(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_SET) 980 981 #define am_hal_debug_gpio_clear(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_CLEAR) 982 983 #define am_hal_debug_gpio_toggle(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_TOGGLE) 984 985 #define am_hal_debug_gpio_pinconfig(x) am_hal_gpio_pinconfig(x, g_AM_HAL_GPIO_OUTPUT) 986 987 #else 988 989 #define am_hal_debug_gpio_set(...) 990 #define am_hal_debug_gpio_clear(...) 991 #define am_hal_debug_gpio_toggle(...) 992 #define am_hal_debug_gpio_pinconfig(...) 993 994 #endif // AM_DEBUG_BLE_TIMING 995 996 #ifdef __cplusplus 997 } 998 #endif 999 1000 #endif // AM_HAL_BLE_H 1001 1002 //***************************************************************************** 1003 // 1004 // End Doxygen group. 1005 //! @} 1006 // 1007 //***************************************************************************** 1008
