//***************************************************************************** // //! @file am_hal_ble.h //! //! @brief HAL Functions for the BLE Interface. //! //! @addtogroup BLE3p BLE - BLE functions //! @ingroup apollo3p_hal //! @{ // //***************************************************************************** //***************************************************************************** // // Copyright (c) 2024, Ambiq Micro, Inc. // All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are met: // // 1. Redistributions of source code must retain the above copyright notice, // this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in the // documentation and/or other materials provided with the distribution. // // 3. Neither the name of the copyright holder nor the names of its // contributors may be used to endorse or promote products derived from this // software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE // POSSIBILITY OF SUCH DAMAGE. // // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. // //***************************************************************************** #ifndef AM_HAL_BLE_H #define AM_HAL_BLE_H #include "am_hal_global.h" #include "am_hal_status.h" //***************************************************************************** // //! CMSIS-style macro for handling a variable BLEIF module number. // #define BLEIFn(n) ((BLEIF_Type*)(BLEIF_BASE + (n * (BLEIF_BASE - BLEIF_BASE)))) //***************************************************************************** //***************************************************************************** // //! BLE-specific status values. // //***************************************************************************** typedef enum { // //! This error occurs when an HCI read or write function is called while //! another HCI communication function is already in progress. // AM_HAL_BLE_STATUS_BUS_BUSY = AM_HAL_STATUS_MODULE_SPECIFIC_START, // //! This error happens when the MCU tries to execute an HCI read, but the //! BLE core hasn't asserted the BLEIRQ line. Try waiting for a BLEIRQ //! interrupt, or polling the BLECIRQ bit in the BSTATUS register before //! calling an HCI read function. // AM_HAL_BLE_STATUS_IRQ_LOW, // //! This error means that the MCU tried to execute an HCI write, but the BLE //! core didn't assert its SPI_STATUS signal within the allotted timeout. //! This might mean that there has been some error inside the BLE core. This //! may require a reboot of the BLE core. // AM_HAL_BLE_STATUS_SPI_NOT_READY, // //! This error means we were trying to write, but the BLE core has requested //! a READ instead. We will need to perform a read before we can retry this //! write. // AM_HAL_BLE_REQUESTING_READ, // //! We are expecting an HCI response to a packet we just sent, but the BLE //! core isn't asserting BLEIRQ. Its software may have crashed, and it may //! need to restart. // AM_HAL_BLE_NO_HCI_RESPONSE, // //! Any of these errors indicate a problem with the BLE hardware that //! requires a complete restart. // AM_HAL_BLE_FEATURE_DISABLED, AM_HAL_BLE_SHUTDOWN_FAILED, AM_HAL_BLE_REGULATOR_FAILED, AM_HAL_BLE_POWERUP_INCOMPLETE, AM_HAL_BLE_HCI_PACKET_INCOMPLETE, AM_HAL_BLE_FIFO_ERROR, AM_HAL_BLE_32K_CLOCK_UNSTABLE, } am_ble_status_e; //***************************************************************************** // //! BLE power modes. // //***************************************************************************** typedef enum { AM_HAL_BLE_POWER_ACTIVE, AM_HAL_BLE_POWER_OFF, } am_hal_ble_power_state_e; //***************************************************************************** // //! BLE SPI Clock settings. // //***************************************************************************** typedef enum { AM_HAL_BLE_HCI_CLK_DIV2 = BLEIF_CLKCFG_FSEL_HFRC_DIV2, AM_HAL_BLE_HCI_CLK_DIV4 = BLEIF_CLKCFG_FSEL_HFRC_DIV4, AM_HAL_BLE_HCI_CLK_DIV8 = BLEIF_CLKCFG_FSEL_HFRC_DIV8, AM_HAL_BLE_HCI_CLK_DIV16 = BLEIF_CLKCFG_FSEL_HFRC_DIV16, AM_HAL_BLE_HCI_CLK_DIV32 = BLEIF_CLKCFG_FSEL_HFRC_DIV32, AM_HAL_BLE_HCI_CLK_DIV64 = BLEIF_CLKCFG_FSEL_HFRC_DIV8, } am_hal_ble_hci_clock_e; //***************************************************************************** // //! BLE Core Clock settings. // //***************************************************************************** typedef enum { AM_HAL_BLE_CORE_MCU_CLK = 0x02, AM_HAL_BLE_CORE_INTERNAL_CLK = 0x00, } am_hal_ble_core_clock_e; //***************************************************************************** // //! Interrupts. // //***************************************************************************** //! The B2M_STATE went into the shutdown state #define AM_BLEIF_INT_B2MSHUTDN AM_REG_BLEIF_INTEN_B2MSHUTDN_M //! The B2M_STATE went into the active state #define AM_BLEIF_INT_B2MACTIVE AM_REG_BLEIF_INTEN_B2MACTIVE_M //! The B2M_STATE went into the sleep state #define AM_BLEIF_INT_B2MSLEEP AM_REG_BLEIF_INTEN_B2MSLEEP_M //! command queue received and error #define AM_BLEIF_INT_CQERR AM_REG_BLEIF_INTEN_CQERR_M //! CQ write operation performed a register write with the register address bit //! 0 set to 1. The low address bits in the CQ address fields are unused and //! bit 0 can be used to trigger an interrupt to indicate when this register //! write is performed by the CQ operation. #define AM_BLEIF_INT_CQUPD AM_REG_BLEIF_INTEN_CQUPD_M //! The command queue is waiting interrupt #define AM_BLEIF_INT_CQPAUSED AM_REG_BLEIF_INTEN_CQPAUSED_M //! DMA Error #define AM_BLEIF_INT_DERR AM_REG_BLEIF_INTEN_DERR_M //! DMA Complete #define AM_BLEIF_INT_DCMP AM_REG_BLEIF_INTEN_DCMP_M //! THis is the BLE Core IRQ signal #define AM_BLEIF_INT_BLECIRQ AM_REG_BLEIF_INTEN_BLECIRQ_M //! This is the illegal command interrupt. #define AM_BLEIF_INT_ICMD AM_REG_BLEIF_INTEN_ICMD_M //! This is the illegal FIFO access interrupt. #define AM_BLEIF_INT_IACC AM_REG_BLEIF_INTEN_IACC_M //! Any change in the B2M_STATE signal from the BLE Core will set this interrupt #define AM_BLEIF_INT_B2MST AM_REG_BLEIF_INTEN_B2MST_M //! This is the Write FIFO Overflow interrupt. #define AM_BLEIF_INT_FOVFL AM_REG_BLEIF_INTEN_FOVFL_M //! This is the Read FIFO Underflow interrupt. #define AM_BLEIF_INT_FUNDFL AM_REG_BLEIF_INTEN_FUNDFL_M //! This is the FIFO Threshold interrupt. #define AM_BLEIF_INT_THR AM_REG_BLEIF_INTEN_THR_M //! This is the Command Complete interrupt. #define AM_BLEIF_INT_CMDCMP AM_REG_BLEIF_INTEN_CMDCMP_M #define AM_HAL_BLE_INT_B2MSHUTDN BLEIF_INTEN_B2MSHUTDN_Msk //!< The B2M_STATE went into the shutdown state #define AM_HAL_BLE_INT_B2MACTIVE BLEIF_INTEN_B2MACTIVE_Msk //!< The B2M_STATE went into the active state #define AM_HAL_BLE_INT_B2MSLEEP BLEIF_INTEN_B2MSLEEP_Msk //!< The B2M_STATE went into the sleep state #define AM_HAL_BLE_INT_CQERR BLEIF_INTEN_CQERR_Msk //!< command queue received and error //! CQ write operation performed a register write with the register address bit //! 0 set to 1. The low address bits in the CQ address fields are unused and //! bit 0 can be used to trigger an interrupt to indicate when this register //! write is performed by the CQ operation. #define AM_HAL_BLE_INT_CQUPD BLEIF_INTEN_CQUPD_Msk #define AM_HAL_BLE_INT_CQPAUSED BLEIF_INTEN_CQPAUSED_Msk //!< The command queue is waiting interrupt #define AM_HAL_BLE_INT_DERR BLEIF_INTEN_DERR_Msk //!< DMA Error #define AM_HAL_BLE_INT_DCMP BLEIF_INTEN_DCMP_Msk //!< DMA Complete #define AM_HAL_BLE_INT_BLECSSTAT BLEIF_INTEN_BLECSSTAT_Msk //!< This is the BLE Core SPI STATUS signal. #define AM_HAL_BLE_INT_BLECIRQ BLEIF_INTEN_BLECIRQ_Msk //!< This is the BLE Core IRQ signal #define AM_HAL_BLE_INT_ICMD BLEIF_INTEN_ICMD_Msk //!< This is the illegal command interrupt. #define AM_HAL_BLE_INT_IACC BLEIF_INTEN_IACC_Msk //!< This is the illegal FIFO access interrupt. #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 #define AM_HAL_BLE_INT_FOVFL BLEIF_INTEN_FOVFL_Msk //!< This is the Write FIFO Overflow interrupt. #define AM_HAL_BLE_INT_FUNDFL BLEIF_INTEN_FUNDFL_Msk //!< This is the Read FIFO Underflow interrupt. #define AM_HAL_BLE_INT_THR BLEIF_INTEN_THR_Msk //!< This is the FIFO Threshold interrupt. #define AM_HAL_BLE_INT_CMDCMP BLEIF_INTEN_CMDCMP_Msk //!< This is the Command Complete interrupt. #define AM_HAL_BLE_INT_BLECSSTATN BLEIF_INTSTAT_B2MSHUTDN_Msk #define AM_HAL_BLE_INT_BLECIRQN BLEIF_INTSTAT_B2MACTIVE_Msk //***************************************************************************** // // Type definitions. // //***************************************************************************** #define am_hal_ble_buffer(A) \ union \ { \ uint32_t words[(A + 3) >> 2]; \ uint8_t bytes[A]; \ } //! Function pointer for non-blocking ble read callbacks. typedef void (*am_hal_ble_transfer_complete_cb_t)(uint8_t *pui8Data, uint32_t ui32Length, void *pvContext); // //! Patch container // typedef struct { uint32_t ui32Type; uint32_t ui32Length; uint32_t ui32CRC; const uint32_t *pui32Data; } am_hal_ble_patch_t; // //! Configuration structure for the BLE module. // typedef struct { // HCI interface options. uint32_t ui32SpiClkCfg; //!< Configure the HCI interface clock. uint32_t ui32ReadThreshold; //!< Internal HCI READ FIFO size uint32_t ui32WriteThreshold; //!< Internal HCI WRITE FIFO size. // BLE options. uint32_t ui32BleClockConfig; //!< Configure the BLE core clock. #if 0 uint32_t ui32ClockDrift; //!< Set the expected BLE clock drift. uint32_t ui32SleepClockDrift; //!< Set the expected sleep clock accuracy. bool bAgcEnabled; //!< Enable/Disable AGC bool bSleepEnabled; //!< Enable/Disable Sleep Algorithm #endif // Patches bool bUseDefaultPatches; //!< Apply the default patches? } am_hal_ble_config_t; // //! Default options for the BLE module. // extern const am_hal_ble_config_t am_hal_ble_default_config; //***************************************************************************** // //! Structure for sending SPI commands. // //***************************************************************************** typedef struct { uint32_t *pui32Data; uint8_t pui8Offset[3]; uint8_t ui8OffsetLen; uint16_t ui16Length; uint8_t ui8Command; uint8_t ui8RepeatCount; bool bContinue; am_hal_ble_transfer_complete_cb_t pfnTransferCompleteCB; void *pvContext; } am_hal_ble_transfer_t; //***************************************************************************** // //! Vendor Specific commands. // //! @note Lengths are reported as "4 + ". Each vendor-specific //! header is 4 bytes long. This definition allows the macro version of the //! length to be used in all BLE APIs. // //***************************************************************************** #define AM_HAL_BLE_SET_BD_ADDR_OPCODE 0xFC32 #define AM_HAL_BLE_SET_BD_ADDR_LENGTH (4 + 6) #define AM_HAL_BLE_SET_TX_POWER_OPCODE 0xFC3B #define AM_HAL_BLE_SET_TX_POWER_LENGTH (4 + 3) #define AM_HAL_BLE_READ_VERSIONS_OPCODE 0xFD01 #define AM_HAL_BLE_READ_VERSIONS_LENGTH (4 + 0) #define AM_HAL_BLE_PLF_REGISTER_READ_OPCODE 0xFD02 #define AM_HAL_BLE_PLF_REGISTER_READ_LENGTH (4 + 4) #define AM_HAL_BLE_PLF_REGISTER_WRITE_OPCODE 0xFD03 #define AM_HAL_BLE_PLF_REGISTER_WRITE_LENGTH (4 + 8) #define AM_HAL_BLE_GET_RSSI_OPCODE 0x1405 #define AM_HAL_BLE_GET_RSSI_LENGTH (4 + 0) #define AM_HAL_BLE_SET_SLEEP_OPCODE 0xFD09 #define AM_HAL_BLE_SET_SLEEP_LENGTH (4 + 0) #define AM_HAL_BLE_SPI_SENDFRAME_OPCODE 0xFD04 #define AM_HAL_BLE_SPI_SENDFRAME_LENGTH (4 + 1) #define AM_HAL_BLE_SET_BD_ADDR_CMD(...) {0x01, 0x32, 0xFC, 0x06, __VA_ARGS__} #define AM_HAL_BLE_SET_TX_POWER_CMD(...) {0x01, 0x3B, 0xFC, 0x03, __VA_ARGS__} #define AM_HAL_BLE_SET_READ_VERSIONS_CMD() {0x01, 0x01, 0xFD, 0x00} #define AM_HAL_BLE_PLF_REGISTER_READ_CMD(...) {0x01, 0x02, 0xFD, 0x04, __VA_ARGS__} #define AM_HAL_BLE_PLF_REGISTER_WRITE_CMD(...) {0x01, 0x03, 0xFD, 0x08, __VA_ARGS__} #define AM_HAL_BLE_GET_RSSI_CMD() {0x01, 0x05, 0x14, 0x00} #define AM_HAL_BLE_SET_SLEEP_CMD() {0x01, 0x09, 0xFD, 0x00} #define AM_HAL_BLE_SPI_SENDFRAME_CMD(...) {0x01, 0x04, 0xFD, 0x01, __VA_ARGS__} //***************************************************************************** // //! State variables for the BLE module. // //***************************************************************************** typedef struct { //! Handle validation prefix. am_hal_handle_prefix_t prefix; //! Which BLE module instance is this? uint32_t ui32Module; //! Apply the default patches during the "boot" function? bool bUseDefaultPatches; //! What was the last command that we started? am_hal_ble_transfer_t sCurrentTransfer; //! If a write is interrupted by a read, we have to save the write //! transaction to execute later. That saved write goes here. am_hal_ble_transfer_t sSavedTransfer; //! How far along are we? uint32_t ui32TransferIndex; //! Has this radio already been patched? bool bPatchComplete; //! Are we in the middle of a continue packet? bool bContinuePacket; //! Was our last operation to send a TX packet? If we have two TX packets in //! a row, we need special handling to get the timing right. bool bLastPacketWasTX; //! Do we have a saved packet? bool bSavedPacket; //! Is the bus already in use? bool bBusy; //! Has the last command completed? bool bCmdComplete; //! Has the last DMA action completed? bool bDmaComplete; //! Has the BLE core's flow control signal been reset? bool bFlowControlComplete; } am_hal_ble_state_t; //***************************************************************************** // //! SPI command macros. // //***************************************************************************** #define AM_HAL_BLE_WRITE 1 #define AM_HAL_BLE_READ 2 //***************************************************************************** // //! HCI packet types. // //***************************************************************************** #define AM_HAL_BLE_RAW 0x0 #define AM_HAL_BLE_CMD 0x1 #define AM_HAL_BLE_ACL 0x2 #define AM_HAL_BLE_EVT 0x4 //***************************************************************************** // // External function declarations. // //***************************************************************************** #ifdef __cplusplus extern "C" { #endif //***************************************************************************** // // Basics // // Initialization, enable/disable, and general configuration. // //***************************************************************************** //***************************************************************************** // //! @brief Initialize the internal state variables for the BLE module. //! //! @param ui32Module - Which BLE module to use. //! @param ppHandle - Pointer to a handle variable to be initialized. //! //! @details This function initializes the internal state variables associated with a //! particular BLE module and yields a handle that may be used to perform //! additional operations with that BLE module. //! //! This function must be called before any other BLE module operation. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_initialize(uint32_t ui32Module, void **ppHandle); //***************************************************************************** // //! @brief De-initialize the internal state variables for the BLE module. //! //! @param pHandle - Handle variable to be de-initialized. //! //! @note This function invalidates a previously initialized BLE module handle and //! deletes the contents of the internal state variables associated with it. //! This could be used in situations where the caller wants to prevent future //! function calls to a particular BLE module. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_deinitialize(void *pHandle); //***************************************************************************** // //! @brief Configure a BLE module. //! //! @param pHandle - Handle for the BLE module. //! @param psConfig - Pointer to a BLE configuration structure. //! //! @details This routine performs the necessary configuration steps to prepare the //! physical BLE interface for operation. This function should be called after //! \e am_hal_ble_enable() and before any other BLE operation. The \e psConfig //! parameter may be used to set a specific interface clock frequency or modify //! the FIFO read and write thresholds, but most users will get the best //! results from the default settings stored in the global configuration //! structure \e am_hal_ble_default_config. //! //! @note This function will only work if the BLE module has previously been //! enabled. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_config(void *pHandle, const am_hal_ble_config_t *psConfig); //***************************************************************************** // //! @brief Enable the BLE module. //! //! @note Performs the power-up or power-down sequence for the BLE module referred to //! be \e pHandle. This should be called after am_hal_ble_initialize(), but //! before am_hal_ble_config(). //! @par //! @note The ui32PowerState variable must be set to either AM_HAL_BLE_POWER_ACTIVE //! or AM_HAL_BLE_POWER_OFF. //! @par //! @note After this function is called, the BLE core will be in its startup or //! "patching" mode. //! //! @param pHandle - Handle for the BLE module. //! @param ui32PowerState - Determines whether BLE is powered on or off. //! //! @return BLE status code. //! // //***************************************************************************** uint32_t am_hal_ble_power_control(void *pHandle, uint32_t ui32PowerState); //***************************************************************************** // //! @brief Boot the BLE module //! //! @note This function performs the complete patching process for the BLE core and //! returns with the BLE core in HCI mode. If you ask for the default patches //! your am_hal_ble_config_t structure, then this is the last function you need //! to call on startup. You don't need to call any of the patching functions. //! //! @param pHandle - Handle for the BLE module. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_boot(void *pHandle); //***************************************************************************** // //! @brief Patching functions. // //! @note The following functions allow the caller to apply "patches" to the BLE core //! during its startup phase. These are pre-made configuration files that change //! the operation parameters of the BLE radio. If you have received a patch file //! from the manufacturer, you may use the \e am_hal_ble_patch_apply() function //! during startup to apply these settings to the BLE core. Otherwise, you may //! skip this step by calling the \e am_hal_ble_patch_complete() function. // //***************************************************************************** //***************************************************************************** // //! @brief Apply a patch to the BLE core. //! //! @param pHandle - Handle for the BLE module. //! @param psPatch - Pointer to a structure describing the patch. //! //! The BLE core is an independent processor that executes code from an //! on-board ROM. Its behavior can be altered through "patches" which are //! binary snippets of code that may be loaded at startup to overlay or replace //! sections of the original ROM (for instance, to modify trim settings). This //! function allows the caller to apply one of these patches. //! //! @note Patches must be applied after the BLE module is enabled and configured, but //! before standard HCI operation begins. This is the only time where the BLE //! core is able to accept patch files. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_patch_apply(void *pHandle, am_hal_ble_patch_t *psPatch); //***************************************************************************** //! @brief Apply a B0 silicon patch to the BLE core //! //! @param pHandle - Handle for BLE Module //! //! @return BLE status code //***************************************************************************** extern uint32_t am_hal_ble_patch_preload(void *pHandle); //***************************************************************************** // //! @brief Apply the default manufacturer patch to the BLE core. //! //! @param pHandle Handle for the BLE module. //! //! The BLE core is an independent processor that executes code from an //! on-board ROM. Its behavior can be altered through "patches" which are //! binary snippets of code that may be loaded at startup to overlay or replace //! sections of the original ROM (for instance, to modify trim settings). This //! function allows the caller to apply one of these patches. //! //! Patches must be applied after the BLE module is enabled and configured, but //! before standard HCI operation begins. This is the only time where the BLE //! core is able to accept patch files. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_default_patch_apply(void *pHandle); //***************************************************************************** // //! @brief Complete the patching phase. //! //! @param pHandle Handle for the BLE module. //! //! After the BLE core is enabled and configured, it enters a "patching mode" //! where it can accept patches from the main CPU. Once all patches have been //! applied using the \e am_hal_ble_patch_apply() function. The application //! must call this function to command the BLE core to switch to standard HCI //! mode. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_patch_complete(void *pHandle); //***************************************************************************** // //! @brief Manually set modulation characteristic //! based on the tested values at customer side. //! manually set frequency offset for 10101010 or 01010101 pattern //! @param pHandle //! @param ui8ModFrqOffset //! @return // //***************************************************************************** extern uint32_t am_hal_ble_transmitter_modex_set(void *pHandle, uint8_t ui8ModFrqOffset); //***************************************************************************** // //! @brief Performs a blocking read or write to the BLE core. //! //! @param pHandle - Handle for the BLE module. //! @param psTransfer - Structure describing the transaction to execute. //! //! @return BLE status code. //***************************************************************************** extern uint32_t am_hal_ble_blocking_transfer(void *pHandle, am_hal_ble_transfer_t *psTransfer); //***************************************************************************** // //! @brief Complete the patching phase. //! //! @param pHandle - Handle for the BLE module. //! @param psTransfer - pointer to transfer parameters //! //! After the BLE core is enabled and configured, it enters a "patching mode" //! where it can accept patches from the main CPU. Once all patches have been //! applied using the \e am_hal_ble_patch_apply() function. The application //! must call this function to command the BLE core to switch to standard HCI //! mode. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_nonblocking_transfer(void *pHandle, am_hal_ble_transfer_t *psTransfer); // High-level HCI APIs //***************************************************************************** //! @brief //! //! @param pui32Command //! @param ui32OpCode //! @param ui32TotalLength //! @param pui8Parameters //! @return uint32_t // //***************************************************************************** extern uint32_t am_hal_ble_vs_command_build(uint32_t *pui32Command, uint32_t ui32OpCode, uint32_t ui32TotalLength, uint8_t *pui8Parameters); //***************************************************************************** //! @brief //! //! @param pHandle //! @param pui32Data //! @param pui32BytesReceived //! @return uint32_t // //***************************************************************************** extern uint32_t am_hal_ble_blocking_hci_read(void *pHandle, uint32_t *pui32Data, uint32_t *pui32BytesReceived); //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui8Type //! @param pui32Data //! @param ui32NumBytes //! @return uint32_t // //***************************************************************************** extern uint32_t am_hal_ble_blocking_hci_write(void *pHandle, uint8_t ui8Type, uint32_t *pui32Data, uint32_t ui32NumBytes); //***************************************************************************** //! @brief //! //! @param pHandle //! @param pui32Data //! @param pfnCallback //! @param pvContext //! @return uint32_t // //***************************************************************************** extern uint32_t am_hal_ble_nonblocking_hci_read(void *pHandle, uint32_t *pui32Data, am_hal_ble_transfer_complete_cb_t pfnCallback, void *pvContext); //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui8Type //! @param pui32Data //! @param ui32NumBytes //! @param pfnCallback //! @param pvContext //! @return uint32_t // //***************************************************************************** extern uint32_t am_hal_ble_nonblocking_hci_write(void *pHandle, uint8_t ui8Type, uint32_t *pui32Data, uint32_t ui32NumBytes, am_hal_ble_transfer_complete_cb_t pfnCallback, void *pvContext); //***************************************************************************** // //! @brief Set one of the trim values for the BLE core. //! //! @param pHandle is the BLE module handle //! @param ui32BleCoreAddress is the target address for the trim value. //! @param ui32TrimValue is the trim value to write to the BLE core. //! @param ui32TrimMask is the trim mask for ui32TrimValue //! //! This function takes a BLE core trim value from the MCU memory and writes it //! to a trim register in the BLE core. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_trim_set(void *pHandle, uint32_t ui32BleCoreAddress, uint32_t ui32TrimValue, uint32_t ui32TrimMask); //***************************************************************************** //! @brief Set the bandgap voltage, bandgap current, and retention LDO output values //! //! @details Set the bandgap voltage, bandgap current, and retention LDO output //! valuesbased on the tested values stored in non-volatile memory. //! //! @param pHandle //! @return uint32_t //***************************************************************************** uint32_t am_hal_ble_default_trim_set_ramcode(void *pHandle); //***************************************************************************** // //! @brief Sends a signal to wake up the BLE controller //! //! @param pHandle is the Handle for the BLE module. //! @param ui32Mode is determines the value of the WAKE signal. //! //! The BLE core needs to be awake before we send data to it. This function //! sends a signal to the BLE core that tells it that we intend to send it //! data. When the BLE core wakes up, it will generate a BLECSSTAT interrupt, //! and the SPISTATUS bit in the BSTATUS register will be set. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_wakeup_set(void *pHandle, uint32_t ui32Mode); //***************************************************************************** // //! @brief Read a register value directly from the BLE Core. //! //! @param pHandle is the Handle for the BLE module. //! @param ui32Address is the address of the register. //! @param *pui32Value is a pointer where the register value will be stored. //! //! This function uses a vendor-specific sequence of blocking HCI commands to //! read one of the internal registers within the BLE Core. The value stored in //! this register will be written to the location specified by \e pui32Value. //! //! This function is mostly used during initial radio setup or for internal //! test commands. Standard applications will not need to call this function //! directly. //! //! @note This function uses multiple blocking HCI commands in sequence. It //! should not be used in any situation where blocking commands are not //! desired. Do not use it in applications where interrupt-driven BLE //! operations have already started. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_plf_reg_read(void *pHandle, uint32_t ui32Address, uint32_t *pui32Value); //***************************************************************************** // //! @brief Write a register value directly to the BLE Core. //! //! @param pHandle - the Handle for the BLE module. //! @param ui32Address - the address of the register. //! @param ui32Value - the value to write. //! //! This function uses a vendor-specific sequence of blocking HCI commands to //! write one of the internal registers within the BLE Core. //! //! This function is mostly used during initial radio setup or for internal //! test commands. Standard applications will not need to call this function //! directly. //! //! @note This function uses multiple blocking HCI commands in sequence. It //! should not be used in any situation where blocking commands are not //! desired. Do not use it in applications where interrupt-driven BLE //! operations have already started. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_plf_reg_write(void *pHandle, uint32_t ui32Address, uint32_t ui32Value); //***************************************************************************** // //! @brief Change the sleep behavior of the BLE core. //! //! Set BLE sleep enable/disable for the BLE core. //! //! @param pHandle - the Handle for the BLE module. //! @param enable - sets the desired sleep behavior. //! - 'true' set sleep enable, //! - 'false' set sleep disable //! //! This function uses a vendor-specific sequence of blocking HCI commands to //! change the default behavior of the BLE core between radio events. Set \e //! enable to true to allow the BLE core to sleep between radio events, or //! false to keep the BLE core awake at all times. The default behavior on //! startup allows the BLE core to sleep. Most applications will not need to //! modify this setting. //! //! @note This function uses multiple blocking HCI commands in sequence. It //! should not be used in any situation where blocking commands are not //! desired. Do not use it in applications where interrupt-driven BLE //! operations have already started. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_sleep_set(void *pHandle, bool enable); //***************************************************************************** // //! @brief Check the sleep behavior of the BLE core. //! //! @param pHandle - is the Handle for the BLE module. //! //! This function uses a vendor-specific sequence of blocking HCI commands to //! check whether the BLE core is set to go to sleep between BLE transactions. //! This function will return "true" if BLE sleep is enabled, or "false" if it //! is disabled. //! //! @note This function uses multiple blocking HCI commands in sequence. It //! should not be used in any situation where blocking commands are not //! desired. Do not use it in applications where interrupt-driven BLE //! operations have already started. //! //! @return BLE status code. // //***************************************************************************** extern bool am_hal_ble_sleep_get(void *pHandle); //***************************************************************************** // //! @brief Change the TX power setting of the BLE core. //! //! @param pHandle - the Handle for the BLE module. //! @param ui32TxPower - the desired power setting. //! 0x03->-20dBm 0x04->-10dBm 0x05->-5dBm 0x08->0dBm 0x0F->4dBm //! //! This function uses a vendor-specific sequence of blocking HCI commands to //! change the TX power setting of the radio. //! //! @note This function uses multiple blocking HCI commands in sequence. It //! should not be used in any situation where blocking commands are not //! desired. Do not use it in applications where interrupt-driven BLE //! operations have already started. //! //! @return BLE status code. // //***************************************************************************** extern uint32_t am_hal_ble_tx_power_set(void *pHandle, uint8_t ui32TxPower); //***************************************************************************** // // Interrupts. // //***************************************************************************** //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui32Status //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_int_service(void *pHandle, uint32_t ui32Status); //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui32InterruptMask //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_int_enable(void *pHandle, uint32_t ui32InterruptMask); //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui32InterruptMask //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_int_disable(void *pHandle, uint32_t ui32InterruptMask); //***************************************************************************** //! @brief //! //! @param pHandle //! @param bEnabledOnly //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_int_status(void *pHandle, bool bEnabledOnly); //***************************************************************************** //! @brief //! //! @param pHandle //! @param ui32InterruptMask //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_int_clear(void *pHandle, uint32_t ui32InterruptMask); //***************************************************************************** //! @brief //! //! @param pHandle //! @return uint32_t //***************************************************************************** extern uint32_t am_hal_ble_check_32k_clock(void *pHandle); //***************************************************************************** // //! Debug trace pins. // //***************************************************************************** #ifdef AM_DEBUG_BLE_TIMING #define BLE_DEBUG_TRACE_01 11 #define BLE_DEBUG_TRACE_02 28 #define BLE_DEBUG_TRACE_03 26 #define BLE_DEBUG_TRACE_04 4 #define BLE_DEBUG_TRACE_05 18 #define BLE_DEBUG_TRACE_06 14 #define BLE_DEBUG_TRACE_07 6 #define BLE_DEBUG_TRACE_08 45 #define BLE_DEBUG_TRACE_09 12 #define BLE_DEBUG_TRACE_10 13 #define BLE_DEBUG_TRACE_11 10 #define BLE_LOCK_TRACE_PIN BLE_DEBUG_TRACE_11 #define am_hal_debug_gpio_set(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_SET) #define am_hal_debug_gpio_clear(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_CLEAR) #define am_hal_debug_gpio_toggle(x) am_hal_gpio_state_write(x, AM_HAL_GPIO_OUTPUT_TOGGLE) #define am_hal_debug_gpio_pinconfig(x) am_hal_gpio_pinconfig(x, g_AM_HAL_GPIO_OUTPUT) #else #define am_hal_debug_gpio_set(...) #define am_hal_debug_gpio_clear(...) #define am_hal_debug_gpio_toggle(...) #define am_hal_debug_gpio_pinconfig(...) #endif // AM_DEBUG_BLE_TIMING #ifdef __cplusplus } #endif #endif // AM_HAL_BLE_H //***************************************************************************** // // End Doxygen group. //! @} // //*****************************************************************************