Mbed OS Reference | pal_bb.h Source File

Go to the documentation of this file.
 /*************************************************************************************************/
 /*!
  *  \file
  *
  *  \brief      Baseband interface file.
  *
  *  Copyright (c) 2016-2019 Arm Ltd. All Rights Reserved.
  *
  *  Copyright (c) 2019-2020 Packetcraft, Inc.
  *  
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
  *  You may obtain a copy of the License at
  *  
  *      http://www.apache.org/licenses/LICENSE-2.0
  *  
  *  Unless required by applicable law or agreed to in writing, software
  *  distributed under the License is distributed on an "AS IS" BASIS,
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
 /*************************************************************************************************/
 
 #ifndef PAL_BB_H
 #define PAL_BB_H
 
 #include "pal_types.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**************************************************************************************************
   Macros
 **************************************************************************************************/
 
 /*! \brief      Protocol types */
 typedef enum
 {
   BB_PROT_NONE,                         /*!< Non-protocol specific operation. */
   BB_PROT_BLE,                          /*!< Bluetooth Low Energy normal mode. */
   BB_PROT_BLE_DTM,                      /*!< Bluetooth Low Energy direct test mode. */
   BB_PROT_PRBS15,                       /*!< Enable the continuous PRBS15 transmit sequence. */
   BB_PROT_15P4,                         /*!< 802.15.4. */
   BB_PROT_NUM                           /*!< Number of protocols. */
 } PalBbProt_t;
 
 /*! \brief      Status codes */
 enum
 {
   BB_STATUS_SUCCESS,                    /*!< Operation successful. */
   BB_STATUS_FAILED,                     /*!< General failure. */
   BB_STATUS_CANCELED,                   /*!< Receive canceled. */
   BB_STATUS_RX_TIMEOUT,                 /*!< Receive packet timeout. */
   BB_STATUS_CRC_FAILED,                 /*!< Receive packet with CRC verification failed. */
   BB_STATUS_FRAME_FAILED,               /*!< Receive packet with frame verification failed. */
   BB_STATUS_ACK_FAILED,                 /*!< ACK packet failure. */
   BB_STATUS_ACK_TIMEOUT,                /*!< ACK packet timeout. */
   BB_STATUS_TX_CCA_FAILED,              /*!< Transmit CCA failure. */
   BB_STATUS_TX_FAILED                   /*!< Transmit failure. */
 };
 
 /*! \brief      PHY types. */
 typedef enum
 {
   BB_PHY_BLE_1M    = 1,                 /*!< Bluetooth Low Energy 1Mbps PHY. */
   BB_PHY_BLE_2M    = 2,                 /*!< Bluetooth Low Energy 2Mbps PHY. */
   BB_PHY_BLE_CODED = 3,                 /*!< Bluetooth Low Energy Coded PHY (data coding unspecified). */
   BB_PHY_15P4      = 4,                 /*!< 802.15.4 PHY. */
 } PalBbPhy_t;
 
 /*! \brief      PHY options. */
 enum
 {
   BB_PHY_OPTIONS_DEFAULT          = 0,  /*!< BB defined PHY Options behavior. */
   BB_PHY_OPTIONS_BLE_S2           = 1,  /*!< Always use S=2 coding when transmitting on LE Coded PHY. */
   BB_PHY_OPTIONS_BLE_S8           = 2   /*!< Always use S=8 coding when transmitting on LE Coded PHY. */
 };
 
 #ifndef BB_CLK_RATE_HZ
 /*! \brief      BB clock rate in hertz. */
 #define BB_CLK_RATE_HZ              1000000
 #endif
 
 /*! \brief      Binary divide with 1,000,000 divisor (n[max]=0xFFFFFFFF). */
 #define BB_MATH_DIV_10E6(n)         ((uint32_t)(((uint64_t)(n) * UINT64_C(4295)) >> 32))
 
 #if (BB_CLK_RATE_HZ == 1000000)
 /*! \brief      Return microseconds (no conversion required). */
 #define BB_US_TO_BB_TICKS(us)       (us)
 #elif (BB_CLK_RATE_HZ == 8000000)
 /*! \brief      Compute BB ticks from given time in microseconds (max time is interval=1,996s). */
 #define BB_US_TO_BB_TICKS(us)       ((uint32_t)((us) << 3))
 #elif (BB_CLK_RATE_HZ == 32768)
 /*! \brief      Compute BB ticks from given time in microseconds (max time is interval=1,996s). */
 #define BB_US_TO_BB_TICKS(us)       ((uint32_t)(((uint64_t)(us) * (uint64_t)(70368745)) >> 31))   /* calculated value may be one tick low */
 #else
 /*! \brief      Compute BB ticks from given time in microseconds (max time is interval=1,996s). */
 #define BB_US_TO_BB_TICKS(us)       BB_MATH_DIV_10E6((uint64_t)(us) * (uint64_t)(BB_CLK_RATE_HZ))
 #endif
 
 #define RTC_CLOCK_RATE              32768
 #define USE_RTC_BB_CLK              (BB_CLK_RATE_HZ == RTC_CLOCK_RATE)
 
 #if (BB_CLK_RATE_HZ == 1000000)
 /*! \brief      BB ticks to microseconds (no conversion required). */
 #define BB_TICKS_TO_US(n)           (n)
 #elif (BB_CLK_RATE_HZ == 8000000)
 /*! \brief      BB ticks to microseconds (8MHz). */
 #define BB_TICKS_TO_US(n)           ((n) >> 3)
 #elif (BB_CLK_RATE_HZ == 32768)
 /*! \brief      BB ticks to microseconds (32768 Hz). */
 #define BB_TICKS_TO_US(n)           (uint32_t)(((uint64_t)(n) * 15625) >> 9)
 #else
 /*! \brief      BB ticks to microseconds. */
 #define BB_TICKS_TO_US(n)           (uint32_t)((uint64_t)(n) * 1000000 / BB_CLK_RATE_HZ)
 #endif
 
 /*! \brief      Typical maximum duration to scan in a scan interval (BbRtCfg_t::maxScanPeriodMs). */
 #define BB_MAX_SCAN_PERIOD_MS       1000
 
 /*! \brief      Typical RF setup delay (BbRtCfg_t::rfSetupDelayUs). */
 #define BB_RF_SETUP_DELAY_US        150
 
 /*! \brief      Typical operation setup delay in microseconds (BbRtCfg_t::schSetupDelayUs). */
 #define BB_SCH_SETUP_DELAY_US       500
 
 /*! \brief      Maximum time tick for 32 bit timer(1MHz) in microseconds (BbRtCfg_t::schSetupDelayUs). */
 #define BB_TIMER_1MHZ_MAX_VALUE_US  0xFFFFFFFF  /* 2^32 - 1 = 0xFFFFFFFF. */
 
 /*! \brief      Maximum time tick for 32 bit timer(8MHz) in microseconds (BbRtCfg_t::schSetupDelayUs). */
 #define BB_TIMER_8MHZ_MAX_VALUE_US  0x1FFFFFFF  /* 2^29 - 1 = 0x1FFFFFFF. */
 
 /*! \brief      Maximum time tick for 24 bit RTC counter(32768Hz) in microseconds. (BbRtCfg_t::BbTimerBoundaryUs) */
 #define BB_RTC_MAX_VALUE_US         511999999   /* 2^24 / 32768 * 10^6 - 1 = 512 * 10^6 - 1 = 511999999. */
 
 /**************************************************************************************************
   Type Definitions
 **************************************************************************************************/
 
 /*! \brief  IRQ callback datatypes. */
 typedef void (*bbDrvIrqCback_t)(void);
 
 /*! \brief  BB configuration. */
 typedef struct
 {
   uint16_t clkPpm;                  /*!< Clock accuracy in PPM. */
   uint8_t  rfSetupDelayUsec;        /*!< RF setup delay in microseconds. */
   uint16_t maxScanPeriodMsec;       /*!< Maximum scan period in milliseconds. */
   uint16_t schSetupDelayUsec;       /*!< Schedule setup delay in microseconds. */
   uint32_t BbTimerBoundaryUsec;     /*!< BB timer boundary translated in microseconds before wraparound. */
 } PalBbCfg_t;
 
 /**************************************************************************************************
   Function Declarations
 **************************************************************************************************/
 
 /*! \addtogroup PAL_BB_INIT
  *  \{
  *  This section contains driver routines which initialize as well as enable the sleep mode
  *  of the BB hardware.
  */
 
 /*************************************************************************************************/
 /*!
  *  \brief      Initialize the baseband driver.
  *
  *  One-time initialization of baseband resources. This routine can be used to setup baseband
  *  resources, load RF trim parameters and execute RF calibrations and seed the random number
  *  generator.
  *
  *  This routine should block until the BB hardware is completely initialized.
  */
 /*************************************************************************************************/
 void PalBbInit(void);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Enable the BB hardware.
  *
  *  This routine brings the BB hardware out of low power (enable power and clocks) just before a
  *  first BB operation is executed.
  */
 /*************************************************************************************************/
 void PalBbEnable(void);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Disable the BB hardware.
  *
  *  This routine signals the BB hardware to go into low power (disable power and clocks) after all
  *  BB operations have been disabled.
  */
 /*************************************************************************************************/
 void PalBbDisable(void);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Load BB timing configuration.
  *
  *  \param      pCfg                Return configuration values.
  */
 /*************************************************************************************************/
 void PalBbLoadCfg(PalBbCfg_t *pCfg);
 
 /*! \} */    /* PAL_BB_INIT */
 
 /*! \addtogroup PAL_BB_CLOCK
  *  \{
  *  This section contains driver routines related to the BB clock.
  */
 
 /*************************************************************************************************/
 /*!
  *  \brief      Get the current BB clock value in microseconds.
  *
  *  \return     Current BB clock value, units are microseconds.
  *
  *  This routine reads the current value from the BB clock and returns its value.
  */
 /*************************************************************************************************/
 uint32_t PalBbGetCurrentTime(void);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Get the current FRC time.
  *
  *  \param      pTime   Pointer to return the current time.
  *
  *  \return     TRUE if time is valid, FALSE otherwise.
  *
  *  Get the current FRC time.
  *
  *  \note       FRC is limited to the same bit-width as the BB clock. Return value is available
  *              only when the BB is active.
  */
 /*************************************************************************************************/
 bool_t PalBbGetTimestamp(uint32_t *pTime);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Called to register a protocol's Radio and Timer IRQ callback functions.
  *
  *  \param      protId      Protocol ID.
  *  \param      timerCback  Timer IRQ callback.
  *  \param      radioCback  Timer IRQ callback.
  */
 /*************************************************************************************************/
 void PalBbRegisterProtIrq(uint8_t protId, bbDrvIrqCback_t timerCback, bbDrvIrqCback_t radioCback);
 
 /*************************************************************************************************/
 /*!
  *  \brief      Set protocol ID.
  *
  *  \param      protId      Protocol ID.
  */
 /*************************************************************************************************/
 void PalBbSetProtId(uint8_t protId);
 
 /*! \} */    /* PAL_BB_CLOCK */
 
 #ifdef __cplusplus
 };
 #endif
 
 #endif /* PAL_BB_H */
Important Information for this Arm website
