ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update to Gecko SDK 5.1.2 

Update RAIL library to 1.5.1
pull/3934/head
Steven Cooreman 2017-03-14 02:34:23 +01:00 committed by Steven Cooreman
parent ca91e7c2d5
commit 59dc6da5c4
15 changed files with 1116 additions and 384 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
features/nanostack/FEATURE_NANOSTACK/targets/TARGET_SL_RAIL/NanostackRfPhyEfr32.cpp
View File

@ -826,4 +826,59 @@ static bool rail_checkAndSwitchChannel(uint8_t newChannel) {
} else {
return false;
}
}
/**
* Callback that fires when the receive fifo exceeds the configured threshold
* value
*
* @param[in] bytesAvailable Number of bytes available in the receive fifo at
* the time of the callback dispatch
*
* @return void
* @warning You must implement a stub for this in your RAIL application.
*
* Callback that fires when the receive fifo exceeds the configured threshold
* value. Provides the number of bytes available in the receive fifo at the
* time of the callback dispatch.
*/
void RAILCb_RxFifoAlmostFull(uint16_t bytesAvailable) {
tr_debug("RX near full (%d)\n", bytesAvailable);
}
/**
* Callback that fires when the transmit fifo falls under the configured
* threshold value
*
* @param[in] spaceAvailable Number of bytes open in the transmit fifo at the
* time of the callback dispatch
*
* @return void
* @warning You must implement a stub for this in your RAIL application.
*
* Callback that fires when the transmit fifo falls under the configured
* threshold value. It only fires if a rising edge occurs across this
* threshold. This callback will not fire on initailization nor after resetting
* the transmit fifo with RAIL_ResetFifo().
*
* Provides the number of bytes open in the transmit fifo at the time of the
* callback dispatch.
*/
void RAILCb_TxFifoAlmostEmpty(uint16_t spaceAvailable) {
tr_debug("TX near empty (%d)\n", spaceAvailable);
}
/**
* Callback for when AGC averaged RSSI is done
*
* @param avgRssi Contains the the RSSI in quarter dBm (dbm*4) on success and
* returns \ref RAIL_RSSI_INVALID if there was a problem computing the result.
*
* Called in response to RAIL_StartAverageRSSI() to indicate that the hardware
* has completed averaging. If you would like you can instead use the
* RAIL_AverageRSSIReady() to wait for completion and RAIL_GetAverageRSSI() to
* get the result.
*/
void RAILCb_RssiAverageDone(int16_t avgRssi) {
tr_debug("RSSI done (%d)\n", avgRssi);
}

25
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/buffer-pool-memory-manager/buffer_pool_allocator.c
View File

@ -9,7 +9,7 @@
#include "buffer_pool_allocator.h"
#include "em_int.h"
#include "em_core.h"
#ifdef CONFIGURATION_HEADER
#include CONFIGURATION_HEADER
@ -19,12 +19,11 @@
// Configuration Macros
// -----------------------------------------------------------------------------
// Default to a ping-pong buffer pool with a size of 128 (127 MTU + 1 length) bytes per buffer
#ifndef BUFFER_POOL_SIZE
#define BUFFER_POOL_SIZE 8
#endif
#ifndef MAX_BUFFER_SIZE
#define MAX_BUFFER_SIZE 150
#define MAX_BUFFER_SIZE 160
#endif
#define INVALID_BUFFER_OBJ ((void*)0xFFFFFFFF)
@ -46,7 +45,8 @@ void* memoryAllocate(uint32_t size)
return INVALID_BUFFER_OBJ;
}
INT_Disable();
CORE_DECLARE_IRQ_STATE;
CORE_ENTER_CRITICAL();
for(i = 0; i < BUFFER_POOL_SIZE; i++)
{
if(memoryObjs[i].refCount == 0)
@ -56,7 +56,7 @@ void* memoryAllocate(uint32_t size)
break;
}
}
INT_Enable();
CORE_EXIT_CRITICAL();
return handle;
}
@ -71,32 +71,35 @@ void *memoryPtrFromHandle(void *handle)
return NULL;
}
INT_Disable();
CORE_DECLARE_IRQ_STATE;
CORE_ENTER_CRITICAL();
if(memoryObjs[(uint32_t)handle].refCount > 0)
{
ptr = memoryObjs[(uint32_t)handle].data;
}
INT_Enable();
CORE_EXIT_CRITICAL();
return ptr;
}
void memoryFree(void *handle)
{
INT_Disable();
CORE_DECLARE_IRQ_STATE;
CORE_ENTER_CRITICAL();
if(memoryPtrFromHandle(handle) != NULL)
{
memoryObjs[(uint32_t)handle].refCount--;
}
INT_Enable();
CORE_EXIT_CRITICAL();
}
void memoryTakeReference(void *handle)
{
INT_Disable();
CORE_DECLARE_IRQ_STATE;
CORE_ENTER_CRITICAL();
if(memoryPtrFromHandle(handle) != NULL)
{
memoryObjs[(uint32_t)handle].refCount++;
}
INT_Enable();
CORE_EXIT_CRITICAL();
}

103
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/ieee802154_efr32xg1_configurator_out.c
View File

@ -1,103 +0,0 @@
/***************************************************************************//**
* @brief RAIL Configuration
* @copyright Copyright 2016 Silicon Laboratories, Inc. http://www.silabs.com
******************************************************************************/
//=============================================================================
//
// WARNING: Auto-Generated Radio Config - DO NOT EDIT
//
//=============================================================================
#include <stdint.h>
const uint32_t ieee802154_config_base[] = {
0x01010FF4UL, 0x00000000UL,
0x01010FF8UL, 0x0003C000UL,
0x01010FFCUL, 0x0003C00EUL,
0x00010004UL, 0x00157001UL,
0x00010008UL, 0x0000007FUL,
0x00010018UL, 0x00000000UL,
0x0001001CUL, 0x00000000UL,
0x00010028UL, 0x00000000UL,
0x0001002CUL, 0x00000000UL,
0x00010030UL, 0x00000000UL,
0x00010034UL, 0x00000000UL,
0x0001003CUL, 0x00000000UL,
0x00010040UL, 0x000007A0UL,
0x00010048UL, 0x00000000UL,
0x00010054UL, 0x00000000UL,
0x00010058UL, 0x00000000UL,
0x000100A0UL, 0x00004000UL,
0x000100A4UL, 0x00004CFFUL,
0x000100A8UL, 0x00004100UL,
0x000100ACUL, 0x00004DFFUL,
0x00012000UL, 0x00000704UL,
0x00012010UL, 0x00000000UL,
0x00012018UL, 0x00008408UL,
0x00013008UL, 0x0000AC3FUL,
0x0001302CUL, 0x01F50AAAUL,
0x00013030UL, 0x00104924UL,
0x00013034UL, 0x00000001UL,
0x0001303CUL, 0x00010AABUL,
0x00013040UL, 0x00000000UL,
0x000140A0UL, 0x0F00277AUL,
0x000140F4UL, 0x00001020UL,
0x00014134UL, 0x00000880UL,
0x00014138UL, 0x000087E6UL,
0x00014140UL, 0x0088006DUL,
0x00014144UL, 0x1153E6C0UL,
0x00016014UL, 0x00000010UL,
0x00016018UL, 0x0413F920UL,
0x0001601CUL, 0x0052C007UL,
0x00016020UL, 0x000000C8UL,
0x00016024UL, 0x00000000UL,
0x00016028UL, 0x03000000UL,
0x0001602CUL, 0x00000000UL,
0x00016030UL, 0x00FF0264UL,
0x00016034UL, 0x000008A2UL,
0x00016038UL, 0x00000001UL,
0x0001603CUL, 0x000807B0UL,
0x00016040UL, 0x000000A7UL,
0x00016044UL, 0x00000000UL,
0x00016048UL, 0x0AC00141UL,
0x0001604CUL, 0x744AC39BUL,
0x00016050UL, 0x000003F0UL,
0x00016054UL, 0x00000000UL,
0x00016058UL, 0x00000000UL,
0x0001605CUL, 0x30100101UL,
0x00016060UL, 0x7F7F7050UL,
0x00016064UL, 0x00000000UL,
0x00017014UL, 0x000270FAUL,
0x00017018UL, 0x00001800UL,
0x0001701CUL, 0x82840000UL,
0x00017028UL, 0x01800000UL,
0x00017048UL, 0x00003D3CUL,
0x0001704CUL, 0x000019BCUL,
0x00017070UL, 0x00010103UL,
0x00017074UL, 0x00000442UL,
0x00017078UL, 0x00552300UL,
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_base_min[] = {
0x01010FFCUL, 0x0003C00EUL,
0x0001303CUL, 0x00010AABUL,
0x00016034UL, 0x000008A2UL,
0x00016038UL, 0x00000001UL,
0x00017078UL, 0x00552300UL,
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_2415MHz_min[] = {
0x01010FFCUL, 0x0003C00AUL,
0x0001303CUL, 0x00003555UL,
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_2420MHz_min[] = {
0x0001303CUL, 0x00003555UL,
0x00016034UL, 0x000004A1UL,
0x00016038UL, 0x00000009UL,
0x00017078UL, 0x0049E006UL,
0xFFFFFFFFUL,
};

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1.a
View File

Binary file not shown.

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a Normal file
View File

Binary file not shown.

133
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/ieee802154_efr32xg12_configurator_out.c
View File

@ -1,133 +0,0 @@
/***************************************************************************//**
* @brief RAIL Configuration
* @copyright Copyright 2016 Silicon Laboratories, Inc. http://www.silabs.com
******************************************************************************/
//=============================================================================
//
// WARNING: Auto-Generated Radio Config - DO NOT EDIT
//
//=============================================================================
#include <stdint.h>
const uint32_t ieee802154_config_base[] = {
0x01011FF4UL, 0x00000000UL,
0x00010004UL, 0x00157001UL,
0x00010008UL, 0x0000007FUL,
0x00010018UL, 0x00000000UL,
0x0001001CUL, 0x00000000UL,
0x00010028UL, 0x00000000UL,
0x0001002CUL, 0x00000000UL,
0x00010030UL, 0x00000000UL,
0x00010034UL, 0x00000000UL,
0x0001003CUL, 0x00000000UL,
0x00010040UL, 0x000007A0UL,
0x00010048UL, 0x00000000UL,
0x00010054UL, 0x00000000UL,
0x00010058UL, 0x00000000UL,
0x000100A0UL, 0x00004000UL,
0x000100A4UL, 0x00004CFFUL,
0x000100A8UL, 0x00004100UL,
0x000100ACUL, 0x00004DFFUL,
0x00012000UL, 0x00000704UL,
0x00012010UL, 0x00000000UL,
0x00012018UL, 0x00008408UL,
0x00013008UL, 0x0100AC37UL,
0x0001302CUL, 0x01F50AAAUL,
0x00013030UL, 0x00104911UL,
0x00013034UL, 0x00000001UL,
0x0001303CUL, 0x00010AABUL,
0x00013040UL, 0x00000000UL,
0x000140A0UL, 0x0F00277AUL,
0x000140B8UL, 0x00A3C000UL,
0x000140F4UL, 0x00001020UL,
0x00014134UL, 0x00000880UL,
0x00014138UL, 0x000087E6UL,
0x00014140UL, 0x0088006DUL,
0x00014144UL, 0x4D52E6C0UL,
0x00014160UL, 0x00000000UL,
0x00014164UL, 0x00000000UL,
0x00014168UL, 0x00000006UL,
0x0001416CUL, 0x00000006UL,
0x00016014UL, 0x00000010UL,
0x00016018UL, 0x0413F920UL,
0x0001601CUL, 0x0052C007UL,
0x00016020UL, 0x000000C8UL,
0x00016024UL, 0x00000000UL,
0x00016028UL, 0x03000000UL,
0x0001602CUL, 0x00000000UL,
0x00016030UL, 0x00000000UL,
0x00016050UL, 0x00FF0264UL,
0x00016054UL, 0x00000841UL,
0x00016058UL, 0x00000001UL,
0x0001605CUL, 0x000807B0UL,
0x00016060UL, 0x000000A7UL,
0x00016064UL, 0x00000000UL,
0x00016078UL, 0x08A00141UL,
0x0001607CUL, 0x744AC39BUL,
0x00016080UL, 0x000003F0UL,
0x00016084UL, 0x00000000UL,
0x00016088UL, 0x00000000UL,
0x0001608CUL, 0x30100101UL,
0x00016090UL, 0x7F7F7050UL,
0x00016094UL, 0x00000000UL,
0x00016098UL, 0x00000000UL,
0x0001609CUL, 0x00000000UL,
0x000160A0UL, 0x00000000UL,
0x000160A4UL, 0x00000000UL,
0x000160E4UL, 0x8BD70080UL,
0x000160E8UL, 0x00000000UL,
0x000160ECUL, 0x07830464UL,
0x000160F0UL, 0x3AC81388UL,
0x000160F4UL, 0x0006209CUL,
0x000160F8UL, 0x00206100UL,
0x000160FCUL, 0x208556B7UL,
0x00016104UL, 0x00124887UL,
0x00016108UL, 0x00003020UL,
0x0001610CUL, 0x0000BB88UL,
0x00016120UL, 0x00001003UL,
0x00017014UL, 0x000270FAUL,
0x00017018UL, 0x00001800UL,
0x0001701CUL, 0x850A0000UL,
0x00017020UL, 0x00000000UL,
0x00017024UL, 0x00000082UL,
0x00017028UL, 0x01800000UL,
0x00017048UL, 0x00003D3CUL,
0x0001704CUL, 0x000019BCUL,
0x00017070UL, 0x00210103UL,
0x00017074UL, 0x0008300BUL,
0x00017078UL, 0x0049E006UL,
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_base_min[] = {
0x00013030UL, 0x00104911UL,
0x0001303CUL, 0x00010AABUL,
0x000140B8UL, 0x00A3C000UL,
0x00014144UL, 0x4D52E6C0UL,
0x00016054UL, 0x00000841UL,
0x00016058UL, 0x00000001UL,
0x00016078UL, 0x08A00141UL,
0x000160E4UL, 0x8BD70080UL,
0x00016104UL, 0x00124887UL,
0x00016120UL, 0x00001003UL,
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_2415MHz_min[] = {
0xFFFFFFFFUL,
};
const uint32_t ieee802154_config_2420MHz_min[] = {
0x00013030UL, 0x00104924UL,
0x0001303CUL, 0x00003555UL,
0x000140B8UL, 0x0093C000UL,
0x00014144UL, 0x4D52E6C1UL,
0x00016054UL, 0x00000441UL,
0x00016058UL, 0x00000009UL,
0x00016078UL, 0x04600141UL,
0x000160E4UL, 0xCC4D087FUL,
0x00016104UL, 0x0012491FUL,
0x00016120UL, 0x00000000UL,
0xFFFFFFFFUL,
};

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12.a
View File

Binary file not shown.

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12_gcc_release.a Normal file
View File

Binary file not shown.

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32_iar_release.a
View File

Binary file not shown.

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a Normal file
View File

Binary file not shown.

BIN
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG12/librail_efr32xg12_iar_release.a Normal file
View File

Binary file not shown.

190
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/pa.h
View File

@ -39,22 +39,22 @@ extern "C" {
#endif
/***************************************************************************//**
* @addtogroup RF_Library
* @addtogroup Chip_Specific
* @{
******************************************************************************/
/***************************************************************************//**
* @addtogroup PA
* @addtogroup EFR32xG1x_PA
* @{
******************************************************************************/
/*******************************************************************************
**************************** CONFIGURATION ********************************
******************************************************************************/
/** Scaling factor applied to all dBm power level inputs and outputs * */
#define PA_SCALING_FACTOR 10
/**
* @struct RADIO_PASel_t
* @brief Selection of the rf power amplifier (PA) to use
*/
typedef enum RADIO_PASel
@ -64,9 +64,15 @@ typedef enum RADIO_PASel
/** Low power PA */
PA_SEL_2P4_LP,
/** SubGig PA*/
PA_SEL_SUBGIG
PA_SEL_SUBGIG,
/** Invalid PA Selection */
PA_SEL_INVALID
} RADIO_PASel_t;
/**
* @brief Selection should match the configuration of the voltage on the vPa pin
* of the chip.
*/
typedef enum RADIO_PAVoltMode
{
/** Vpa = Vbat = 3.3V */
@ -76,7 +82,6 @@ typedef enum RADIO_PAVoltMode
} RADIO_PAVoltMode_t;
/**
* @struct RADIO_PAInit_t
* @brief Configuration structure for the rf power amplifier (PA)
*/
typedef struct RADIO_PAInit {
@ -84,9 +89,9 @@ typedef struct RADIO_PAInit {
RADIO_PASel_t paSel;
/** Power Amplifier vPA Voltage mode */
RADIO_PAVoltMode_t voltMode;
/** Desired output power in dBm * 10 */
/** Desired output power in dBm * \ref PA_SCALING_FACTOR */
int16_t power;
/** Output power offset in dBm * 10 */
/** Output power offset in dBm * \ref PA_SCALING_FACTOR */
int16_t offset;
/** Desired ramp time in us */
uint16_t rampTime;
@ -96,16 +101,169 @@ typedef struct RADIO_PAInit {
****************************** PROTOTYPES *********************************
******************************************************************************/
bool RADIO_PA_Init(RADIO_PAInit_t * paInit);
int32_t PA_OutputPowerGet(void);
int32_t PA_OutputPowerSet(int32_t power);
int32_t PA_MaxOutputPowerSet(void);
uint32_t PA_RampTimeGet(void);
uint32_t PA_RampTimeSet(uint32_t ramptime);
void PA_CTuneSet(uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue);
/**
* @brief
* Initilize the PA settings based on the settings provided in the paInit
* structure.
*
* @param[in] paInit
* Pointer to a structure containing the desired PA configuration settings.
*
* @return
* True if the settings were accepted.
* False if settings were invalid.
*
* @warning
* The radio should not be transmitting when this function is called!
*/
bool RADIO_PA_Init(RADIO_PAInit_t * paInit);
/** @} (end addtogroup PA) */
/** @} (end addtogroup RF_Library) */
/**
* @brief
* Returns the current power level of transmit power
*
* @return
* Current power level in dBm * \ref PA_SCALING_FACTOR
*/
int32_t PA_OutputPowerGet(void);
/**
* @brief
* Sets the output power of the PA.
*
* Each PA has distinct maximum power, minimum power, and power step sizes.
* This API will calculate the best pa output power level setting to acheieve
* the desired output power.
*
* @note
* Board and chip variations will affect the accuracy of this API. Use
* of the RADIO_PAInit_t.offset paramter can help account for this variation.
*
* @param[in] power
* Power value in dBm * \ref PA_SCALING_FACTOR
*
* Examples with \ref PA_SCALING_FACTOR of 10:
* - 10 dBm --> 100
* - 5.5 dBm --> 55
*
* @return
* Returns the actual power that was set in dBm * \ref PA_SCALING_FACTOR
*
* @warning
* The radio should not be transmitting when this function is called!
*/
int32_t PA_OutputPowerSet(int32_t power);
/**
* @brief
* Set the maximum possible output power for the selected PA.
*
* @return
* Returns the actual power that was set in dBm * \ref PA_SCALING_FACTOR
*
* @warning
* The radio should not be transmitting when this function is called!
*/
int32_t PA_MaxOutputPowerSet(void);
/**
* @brief
* Return the current ramp time in microseconds
*
* @return
* Current ramp time in microseconds
*/
uint32_t PA_RampTimeGet(void);
/**
* @brief
* Sets up the ramp configuration so that it best matches the given ramp time
*
* @details
* Each PA has a distinct ramp level and ramp rate that can be used to
* achieve various ramp times. This API will pick the ramp rate that closest
* approximates the desired ramp time.
*
* @param[in] ramptime
* Desired ramp time in microseconds
*
* @return
* The actual ramp time that was set in microseconds.
*
* @warning
* The radio should not be transmitting when this function is called!
*/
uint32_t PA_RampTimeSet(uint32_t ramptime);
/***************************************************************************//**
* @addtogroup EFR32xG1x_PA_Advanced
* @{
******************************************************************************/
/**
* @brief
* Set PACTUNE value for TX and RX mode.
*
* This value can vary depending on band and match and board design.
*
* @param[in] txPaCtuneValue
* Transmit value for pa ctune
* @param[in] rxPaCtuneValue
* Receive value for pa ctune
*
* @note PACTUNE will reset to default values when RADIO_PA_Init() or
* RAIL_RadioConfig() are called.
*
* @warning
* The radio should not be transmitting when this function is called!
*/
void PA_CTuneSet(uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue);
/**
* @brief
* Set the output power level based on power steps available in the chosen PA.
*
* @details
* Each PA has distinct maximum power, minimum power, and power step sizes.
* This API allows direct access to these power steps to tune between the
* maximum and minimum output power the selected PA is capable of.
*
* @param[in] pwrLevel
* Output power level. Note that the maximum power level will change
* depending on PA selection.
* @param[in] boostMode
* Output boost mode. Some PA selections have a mode that will increase the
* output power for each step if this is enabled.
*
* @return
* MSB Configured boost mode. \n
* LSB Configured power level
*
* @warning
* The radio should not be transmitting when this function is called!
*/
uint16_t PA_PowerLevelSet(uint8_t pwrLevel, uint8_t boostMode);
/**
* @brief
* Optimize the PA settings based on expected output power level.
*
* @details
* This API optimizes the current consumption of the radio based on the
* provided output power. This is only necessary when output power is
* controlled by PA_PowerLevelSet().
*
* @param[in] power
* Power value in dBm * \ref PA_SCALING_FACTOR
*
* @warning
* The radio should not be transmitting when this function is called!
*/
void PA_PowerLevelOptimize(int32_t power);
/** @} (end addtogroup EFR32xG1x_PA_Advanced) */
/** @} (end addtogroup EFR32xG1x_PA) */
/** @} (end addtogroup Chip_Specific) */
#ifdef __cplusplus
}

633
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail.h
View File

@ -13,7 +13,7 @@
#include <stdbool.h>
// Get the RAIL specific structures and types
#include "rail/rail_types.h"
#include "rail_types.h"
/**
* @addtogroup RAIL_API
@ -62,10 +62,9 @@ uint8_t RAIL_RfInit(const RAIL_Init_t *railInit);
* @return Returns zero on success and an error code on error.
*
* The protocol is output via the Packet Trace Interface (PTI) for each packet.
* Before any protocol is set, the default value is \ref RAIL_PTI_PROTOCOL_CUSTOM.
* A custom value may be used if it does not conflict with one of the available
* \ref RAIL_PtiProtocol_t enum values, though values may only go up to \ref
* RAIL_PTI_PROTOCOL_MAX.
* Before any protocol is set, the default value is \ref
* RAIL_PTI_PROTOCOL_CUSTOM. One of the enum values should be used in order for
* Network Analyzer to be able to decode the packet.
*/
RAIL_Status_t RAIL_SetPtiProtocol(RAIL_PtiProtocol_t protocol);
@ -76,7 +75,7 @@ RAIL_Status_t RAIL_SetPtiProtocol(RAIL_PtiProtocol_t protocol);
* @return void
*
* Callback that notifies the application when the radio is finished
* initializing and is ready for further configuration. This is callback is
* initializing and is ready for further configuration. This callback is
* useful for potential transceiver products that require a power up sequence
* before further configuration is available. After this callback fires, the
* radio is ready for additional configuration before transmit and receive
@ -110,7 +109,8 @@ RAIL_RadioState_t RAIL_RfStateGet(void);
* This function fails if unsupported transitions are passed in, or if the
* radio is currently in the RX state. Success can transition to TX, RX, or
* IDLE, while error can transition to RX or IDLE. The full list of options for
* the ignoreErrors parameter is any define that starts with RAIL_IGNORE_.
* the ignoreErrors parameter is any define that starts with
* \link RAIL_IGNORE_NO_ERRORS RAIL_IGNORE_\endlink.
*/
RAIL_Status_t RAIL_SetRxTransitions(RAIL_RadioState_t success,
RAIL_RadioState_t error,
@ -209,6 +209,20 @@ uint32_t RAIL_RfSense(RAIL_RfSenseBand_t band, uint32_t senseTime, bool enableCb
*/
bool RAIL_RfSensed(void);
/**
* Modify the currently configured fixed length
*
* @param[in] length Expected fixed length; 0 is infinite
* @return Length configured; 0xFFFF if not in fixed length, 0 if in infinite
*
* Set the fixed length configuration for transmit and receive. Users should
* be careful when using this function in receive and transmit. This function
* returns \ref RAIL_SETFIXEDLENGTH_INVALID if the radio is not in fixed length
* mode. The function returns 0 if in infinite length mode. Otherwise it will
* return the length configured into the hardware.
*/
uint16_t RAIL_SetFixedLength(uint16_t length);
/***************************************************************************//**
* Collect entropy from the radio if available.
*
@ -288,6 +302,7 @@ uint16_t RAIL_GetRadioEntropy(uint8_t *buffer, uint16_t bytes);
* {
* int i = 0;
* void *ptr = NULL;
* CORE_DECLARE_IRQ_STATE;
*
* // We can't support sizes greater than the maximum buffer size
* if(size > (MAX_PACKET_SIZE + sizeof(RAIL_RxPacketInfo_t))) {
@ -295,23 +310,23 @@ uint16_t RAIL_GetRadioEntropy(uint8_t *buffer, uint16_t bytes);
* }
*
* // Disable interrupts and attempt to grab the buffer
* INT_Disable();
* CORE_ENTER_CRITICAL();
* if (isAllocated) {
* ptr = NULL;
* } else {
* isAllocated = true;
* ptr = buffer;
* }
* INT_Enable();
* CORE_EXIT_CRITICAL();
*
* return ptr;
* }
*
* void RAILCb_FreeMemory(void *ptr)
* {
* INT_Disable();
* isAllocated = false;
* INT_Enable();
* CORE_CRITICAL_SECTION(
* isAllocated = false;
* );
* }
*
* void *RAILCb_BeginWriteMemory(void *handle,
@ -391,6 +406,380 @@ void *RAILCb_BeginWriteMemory(void *handle,
*/
void RAILCb_EndWriteMemory(void *handle, uint32_t offset, uint32_t size);
/**
* @}
*/
/******************************************************************************
* Data Management
*****************************************************************************/
/**
* @addtogroup Data_Management
* @brief Data management functions
*
* These functions allow the application to choose how data is presented to the
* application. There are two methods for RAIL to provide data, in a packet
* based method leveraging \ref Memory_Management callbacks or in a FIFO based
* method which gives the application more granularity and responsibility in
* managing transmit and receive data.
*
* The application can configure RAIL data mangement through RAIL_DataConfig();
* this function allows the application to specify the type of radio data (\ref
* RAIL_TxDataSource_t and \ref RAIL_RxDataSource_t) and the method of
* interacting with this data (\ref RAIL_DataMethod_t). By default, RAIL
* configures Tx and Rx both with packet data source and packet mode.
*
* In packet based data management:
* - Load transmit data with RAIL_TxDataLoad()
* - Received data is returned in RAILCb_RxPacketReceived()
* - Packet lengths are determined from the Radio Configurator configuration
* - \ref Memory_Management callbacks will fire to ask for pointers to store
* data
*
* In FIFO based data management:
* - Load transmit data with RAIL_WriteTxFifo()
* - Received data is retrieved through RAIL_ReadRxFifo()
* - Packet Lengths are determined from the Radio Configurator configuration
* - Set fifo thresholds through RAIL_SetTxFifoThreshold() and
* RAIL_SetRxFifoThreshold() which fires RAILCb_RxFifoAlmostFull() and
* RAILCb_TxFifoAlmostEmpty().
* - Get fifo count information through RAIL_GetRxFifoBytesAvailable()
* and RAIL_GetTxFifoSpaceAvailable()
* - Reset fifos with RAIL_ResetFifo()
* - CRC Error acceptance is on by default
*
* Both transmit and receive fifos are the same size; when trying to determine
* an appropriate threshold, the application can use
* RAIL_GetTxFifoSpaceAvailable() to query the size of the fifo if it is empty
* and use that as the size of the receive fifo as well. The transmit fifo is edge
* based where it only provides an interrupt once when the threshold is
* crossed. The receive fifo is level based where the interrupt will constantly
* pend if the threshold is exceeded. This normally means that inside
* RAILCb_RxFifoAlmostFull(), the application should empty enough of the fifo
* to go under the threshold. If the application wishes to defer reading the
* fifo to main, it can disable the receive fifo threshold interrupt via
* RAIL_DisableRxFifoThreshold(). The application can reenable the interrupt
* via RAIL_EnableRxFifoThreshold().
*
* In fifo mode, the fifos can store multiple packets. Depending on traffic,
* RAIL can receive multiple packets into the receive fifo before the
* application gets around to reading out the received data from the fifo. If
* appended info is enabled, make sure to read out the appended info with
* RAIL_ReadRxFifoAppendedInfo() before attempting to read out the next packet.
* If the application aborts during packet reception, appended info will not be
* present in the receive fifo. If a frame error occurs in fifo mode, the
* contents of the receive fifo is unreliable and should be flushed.
*
* When calling RAIL_DataConfig() for fifo mode, RAIL will set \ref
* RAIL_IGNORE_CRC_ERRORS. Otherwise for packet mode, RAIL will set \ref
* RAIL_IGNORE_NO_ERRORS. It is highly suggested that the application maintains
* \ref RAIL_IGNORE_CRC_ERRORS in fifo mode if using hardware crc checking.
*
* While RAIL defaults to packet mode, the application can explicitly
* initialize RAIL for packet mode in the following manner:
* @code{.c}
* static const RAIL_DataConfig_t railDataConfig = {
* .txSource = TX_PACKET_DATA,
* .rxSource = RX_PACKET_DATA,
* .txMethod = PACKET_MODE,
* .rxMethod = PACKET_MODE,
* };
*
* status = RAIL_DataConfig(&railDataConfig);
*
* // Callbacks that occur in Packet Mode
* void RAILCb_TxPacketSent(RAIL_TxPacketInfo_t *txPacketInfo);
* void RAILCb_RxPacketReceived(void *rxPacketHandle);
* void *RAILCb_AllocateMemory(uint32_t size);
* void RAILCb_FreeMemory(void *handle);
* void *RAILCb_BeginWriteMemory(void *handle,
* uint32_t offset,
* uint32_t *available);
* void RAILCb_EndWriteMemory(void *handle, uint32_t offset, uint32_t size);
* @endcode
*
* Initializing RAIL for Fifo Mode requires a few more function calls:
* @code{.c}
* static const RAIL_DataConfig_t railDataConfig = {
* .txSource = TX_PACKET_DATA,
* .rxSource = RX_PACKET_DATA,
* .txMethod = FIFO_MODE,
* .rxMethod = FIFO_MODE,
* };
*
* status = RAIL_DataConfig(&railDataConfig);
*
* // Get the size of the fifos
* // The transmit and receive fifos are the same size
* uint16_t fifoSize = RAIL_GetTxFifoSpaceAvailable();
*
* // Set the transmit and receive fifo thresholds
* // For this example, set the threshold in the middle of each fifo
* RAIL_SetRxFifoThreshold(fifoSize / 2);
* RAIL_SetTxFifoThreshold(fifoSize / 2);
*
* //Callbacks that occur in Fifo mode
* void RAILCb_TxPacketSent(RAIL_TxPacketInfo_t *txPacketInfo);
* void RAILCb_RxPacketReceived(void *rxPacketHandle);
* void RAILCb_TxFifoAlmostEmpty(uint16_t spaceAvailable);
* void RAILCb_RxFifoAlmostFull(uint16_t bytesAvailable);
* @endcode
*
* On receive, there are multiple data sources that an application can use that
* are only compatible with the fifo method of data delivery. All that differs
* from the fifo mode example above is the RAIL_DataConfig_t::rxSource setting.
* IQ data samples are taken at the hardware's oversample rate and the amount
* of data can easily overwhelm CPU processing time. The sample rate depends on
* the chosen PHY as is determined by the data rate as well as the decimation
* chain. It is <b>not</b> recommended to use the IQ data source with sample
* rates above 300k samples/second as the CPU might not be able to keep up with
* the data. Depending on the application and needed CPU bandwidth, slower
* data rates may be required.
* @code{.c}
* // IQ data is provided into the receive fifo
* static const RAIL_DataConfig_t railDataConfig = {
* .txSource = TX_PACKET_DATA,
* .rxSource = RX_IQDATA_FILTLSB,
* .txMethod = FIFO_MODE,
* .rxMethod = FIFO_MODE,
* };
*
* // When reading IQ data out of the fifo, it comes in the following format:
* //------------------------------------
* // I[LSB] | I[MSB] | Q[LSB] | Q[MSB] |
* //------------------------------------
* @endcode
*
* @note \ref RAIL_DataConfig_t.txMethod and \ref RAIL_DataConfig_t.rxMethod
* must have the same \ref RAIL_DataMethod_t configuration.
*
* @warning Do not call RAIL fifo functions while in \ref
* RAIL_DataMethod_t::PACKET_MODE.
* @{
*/
/**
* RAIL data management configuration
*
* @param[in] dataConfig RAIL data configuration structure
* @return RAIL Status of configuration
*
* This function configures how RAIL manages data. The application can
* configure RAIL to receive data in a packet based or FIFO based format. When
* configuring tx or rx for fifo mode, this function will reset the configured
* fifos.
*
* If \ref RAIL_DataConfig_t.rxMethod is set to \ref
* RAIL_DataMethod_t.PACKET_MODE, the radio will filter packets with invalid
* CRCs by default. This is similar to setting the <b>ignoreErrors</b>
* parameter in RAIL_SetRxTransitions() to \ref RAIL_IGNORE_NO_ERRORS.
*
* If \ref RAIL_DataConfig_t.rxMethod is set to \ref
* RAIL_DataMethod_t.FIFO_MODE, the radio will accept packets with CRCs as
* 'valid' packets by default. This is meant to treat 'fully received' packets
* the same way regardless if CRC passes or fails. The application can parse
* CRC errors via appended info obtained from RAIL_ReadRxFifoAppendedInfo().
* This is similar to setting the <b>ignoreErrors</b> parameter in
* RAIL_SetRxTransitions() to \ref RAIL_IGNORE_CRC_ERRORS.
*
* In either situation, the application can set <b>ignoreErrors</b> as needed;
* in fifo mode, appended info will not be present for frame errors. The
* defaults defined above are the recommended setting.
*/
RAIL_Status_t RAIL_DataConfig(RAIL_DataConfig_t *dataConfig);
/**
* Write data to the transmit fifo
*
* @param[in] dataPtr Application provided pointer to transmit data
* @param[in] writeLength Number of bytes to write to the transmit fifo
*
* @return The number of bytes written to the transmit fifo
*
* This function reads data from the provided dataPtr and writes it to the TX
* Fifo. If the requested writeLength exceeds the current number of bytes open
* in the transmit fifo, the function will only write until the transmit fifo
* is full. The function returns the number of bytes written to the transmit
* fifo.
*
* @note This function does not create a critical section but depending on the
* application a critical section could be appropriate.
*/
uint16_t RAIL_WriteTxFifo(uint8_t *dataPtr, uint16_t writeLength);
/**
* Read data from the receive fifo
*
* @param[out] dataPtr Application provided pointer to store data
* @param[in] readLength Number of bytes to read from the fifo
*
* @return The number of bytes read from the receive fifo
*
* This function reads data from the receive fifo and writes it to the provided
* dataPtr. If the requested readLength exceeds the current number of bytes in
* the receive fifo, the function will only read the current amount of bytes
* available.
*
* This function does not have a critical section, so either use it only in one
* context or make sure function calls are protected to prevent buffer
* corruption.
*/
uint16_t RAIL_ReadRxFifo(uint8_t *dataPtr, uint16_t readLength);
/**
* Read appended info from the receive fifo
*
* @param[out] appendedInfo Application provided pointer to store RAIL_AppendedInfo_t
* @return void
*
* This function reads appended info from the receive fifo and writes it to the
* provided pointer; appended info is added to the receive fifo once a packet is
* received. Using this function while not at the end of a packet can corrupt
* your buffer by processing receive data as appended info.
*
* @note The following fields in appended info are not implemented in fifo mode and
* do not contain valid info:
* - RAIL_AppendedInfo_t.isAck
* - RAIL_AppendedInfo_t.lqi
* - RAIL_AppendedInfo_t.frameCodingStatus (will reflect the last received packet)
*/
void RAIL_ReadRxFifoAppendedInfo(RAIL_AppendedInfo_t *appendedInfo);
/**
* Configure the RAIL transmit fifo almost empty threshold
*
* @param[in] txThreshold Threshold once fallen under
* will fire RAILCb_TxFifoAlmostEmpty()
* @return Configured transmit fifo threshold value
*
* This function configures the threshold for the transmit fifo. When the count
* of the transmit fifo is less than the configured threshold,
* RAILCb_TxFifoAlmostEmpty() will fire. A value of 0 is invalid and will not
* change the current configuration.
*/
uint16_t RAIL_SetTxFifoThreshold(uint16_t txThreshold);
/**
* Configure the RAIL receive fifo almost full threshold
*
* @param[in] rxThreshold Threshold once exceeded will fire
* RAILCb_RxFifoAlmostFull()
* @return Configured receive fifo threshold value
*
* This function configures the threshold for the transmit fifo. When the count
* of the receive fifo is greater than the configured threshold,
* RAILCb_RxFifoAlmostFull() will fire. A value of 0xFFFF is invalid and will
* not change the current configuration. Depending on the hardware the maximum
* value can vary. If the rxThreshold value exceeds the capability of the
* hardware, the rx threshold will be configured so that it fires only when the
* FIFO is one byte away from being full.
*
*/
uint16_t RAIL_SetRxFifoThreshold(uint16_t rxThreshold);
/**
* Get the RAIL transmit fifo almost empty threshold value
*
* @return Configured Tx Threshold value
*
* Retrieve the configured tx threshold value
*/
uint16_t RAIL_GetTxFifoThreshold(void);
/**
* Get the RAIL receive fifo almost full threshold value
*
* @return Configured Rx Threshold value
*
* Retrieve the configured rx threshold value
*/
uint16_t RAIL_GetRxFifoThreshold(void);
/**
* Enable the RAIL receive fifo threshold interrupt
*
* @return void
*
* Enable the RAIL receive fifo threshold interrupt.
*/
void RAIL_EnableRxFifoThreshold(void);
/**
* Disable the RAIL receive fifo threshold interrupt
*
* @return void
*
* Disable the RAIL receive fifo threshold interrupt. This is useful if the
* application wishes to defer reading the receive fifo into another context.
*/
void RAIL_DisableRxFifoThreshold(void);
/**
* Reset the RAIL Fifos
*
* @param[in] txFifo If true, reset the transmit fifo
* @param[in] rxFifo If true, reset the receive fifo
* @return void
*
* This function can reset each fifo. The application should not reset the Rx
* Fifo while receiving a frame.
*/
//@TODO interrupt protect when clearing; need to check race conditions with hw team
void RAIL_ResetFifo(bool txFifo, bool rxFifo);
/**
* Get the number of bytes in the receive fifo
*
* @return Number of bytes in the receive fifo
*
* Get the number of bytes in the receive fifo
*/
uint16_t RAIL_GetRxFifoBytesAvailable(void);
/**
* Get the number of bytes open in the transmit fifo
*
* @return Number of bytes open in the transmit fifo
*
* Get the number of bytes open in the transmit fifo
*/
uint16_t RAIL_GetTxFifoSpaceAvailable(void);
/**
* Callback that fires when the receive fifo exceeds the configured threshold
* value
*
* @param[in] bytesAvailable Number of bytes available in the receive fifo at
* the time of the callback dispatch
*
* @return void
* @warning You must implement a stub for this in your RAIL application.
*
* Callback that fires when the receive fifo exceeds the configured threshold
* value. Provides the number of bytes available in the receive fifo at the
* time of the callback dispatch.
*/
void RAILCb_RxFifoAlmostFull(uint16_t bytesAvailable);
/**
* Callback that fires when the transmit fifo falls under the configured
* threshold value
*
* @param[in] spaceAvailable Number of bytes open in the transmit fifo at the
* time of the callback dispatch
*
* @return void
* @warning You must implement a stub for this in your RAIL application.
*
* Callback that fires when the transmit fifo falls under the configured
* threshold value. It only fires if a rising edge occurs across this
* threshold. This callback will not fire on initailization nor after resetting
* the transmit fifo with RAIL_ResetFifo().
*
* Provides the number of bytes open in the transmit fifo at the time of the
* callback dispatch.
*/
void RAILCb_TxFifoAlmostEmpty(uint16_t spaceAvailable);
/**
* @}
*/
@ -564,7 +953,9 @@ uint8_t RAIL_RadioConfig(void *radioConfig);
*
* @param[in] frameType Frame type configuration structure.
*
* Currently the frame type passed in only handles packet length decoding.
* Currently the frame type passed in only handles packet length decoding. If
* NULL is passed into this function, it will clear any currently configured
* frame type settings.
*/
void RAIL_PacketLengthConfigFrameType(const RAIL_FrameType_t *frameType);
@ -598,7 +989,7 @@ RAIL_Status_t RAIL_ChannelExists(uint8_t channel);
*
* @return The symbol rate in symbols per second
*
* The symbol rate is the number of symbol changes over the air. For non DSSS
* The symbol rate is the rate of symbol changes over the air. For non-DSSS
* PHYs this is the same as the baudrate. For DSSS PHYs it is the baudrate
* divided by the length of a chipping sequence. For more information on this
* consult the modem calculator documentation.
@ -647,8 +1038,8 @@ RAIL_Status_t RAIL_PaCtuneSet(uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue);
/**
* Set the radio transmit power level
*
* @param[in] powerLevel TX Power Level defined in deci dBm (0.0 dBm)
* @return TX Power Level in deci dBm (0.0 dBm)
* @param[in] powerLevel TX Power Level defined in deci dBm (10 * dBm)
* @return TX Power Level in deci dBm (10 * dBm)
*
* Not all values of powerLevel are achievable, but this function will set the
* power output to be close to the given powerLevel, and return the value that
@ -659,7 +1050,7 @@ int32_t RAIL_TxPowerSet(int32_t powerLevel);
/**
* Get the radio transmit power level
*
* @return TX Power Level defined in deci dBm (0.0 dBm)
* @return TX Power Level defined in deci dBm (10 * dBm)
*
* This will return what the power output was actually set to, not just the
* value passed into RAIL_TxPowerSet.
@ -667,19 +1058,39 @@ int32_t RAIL_TxPowerSet(int32_t powerLevel);
int32_t RAIL_TxPowerGet(void);
/**
* Load payload to send.
* Configure which radio transmit actions trigger callbacks
*
* @param[in] cbToEnable Define which callbacks to trigger for transmit events.
* The full list of available callabcks can be found by looking at the
* RAIL_TX_CONFIG_* set of defines.
* @return Return 0 for success or an error code
*
* Setup which receive interrupts will generate a RAILCb_TxRadioStatus()
* callback. The full list of options is any define that starts with
* RAIL_TX_CONFIG_. Before this function is called, the actions which will
* generate callbacks are:
* - \ref RAIL_TX_CONFIG_BUFFER_UNDERFLOW
* - \ref RAIL_TX_CONFIG_CHANNEL_BUSY
* - \ref RAIL_TX_CONFIG_TX_ABORTED
* - \ref RAIL_TX_CONFIG_TX_BLOCKED
*/
RAIL_Status_t RAIL_TxConfig(uint32_t cbToEnable);
/**
* Load payload to transmit.
*
* @param[in] txData Pointer to a RAIL_TxData_t structure which defines the
* payload bytes and length to transmit. If the fields are configured for
* fixed length.
* payload bytes and the number of bytes to write into the transmit buffer.
* @return Returns 0 on success and an error code on fail.
*
* This function may overwrite current TX data held by RAIL, and should not be
* called repetitively or during TX. The recommended way to use this is to call
* RAIL_TxDataLoad() and RAIL_TxStart() almost immediately in succession.
* This function will overwrite current TX data held by RAIL, and will return
* an error if called during transmit operations. RAIL_TxData_t.dataLength
* defines the number of bytes to load into the transmit buffer from
* RAIL_TxData_t.dataPtr while the number of bytes transmitted is determined by
* the packet configuration defined in the radio configuration.
*
* Will return \ref RAIL_STATUS_INVALID_CALL if the Tx buffer is in use by the
* radio and cannot be updated.
* @note This function creates a critical section while writing to the transmit
* buffer.
*/
uint8_t RAIL_TxDataLoad(RAIL_TxData_t *txData);
@ -692,12 +1103,14 @@ uint8_t RAIL_TxDataLoad(RAIL_TxData_t *txData);
* @param[in] preTxOpParams Pointer to the pre-transmit operation's
* configuration parameters, or NULL if none.
* @return Returns 0 on successfully initiating the transmit process, or an
* error code on failure. If successfully initiated, transmit completion
* error code on failure. If successfully initiated, transmit completion
* or failure will be reported by later callbacks RAILCb_TxPacketSent()
* (success) or RAILCb_TxRadioStatus() (failure).
*
* Begins transmission of the payload previously loaded via RAIL_TxDataLoad().
* Return error if currently transmitting or receiving.
* Will begin transmitting after a received packet if currently receiving a
* packet. Returns error if the radio is active and the channel needs to be
* changed.
*/
uint8_t RAIL_TxStart(uint8_t channel,
RAIL_PreTxOp_t preTxOp,
@ -722,7 +1135,9 @@ uint8_t RAIL_TxStart(uint8_t channel,
* transmit options will only be configured if the preTxOp is successful.
*
* Begins transmission of the payload previously loaded via RAIL_TxDataLoad().
* Return error if currently transmitting or receiving.
* Will begin transmitting after a received packet if currently receiving a
* packet. Returns error if the radio is active and the channel needs to be
* changed.
*/
uint8_t RAIL_TxStartWithOptions(uint8_t channel,
RAIL_TxOptions_t *options,
@ -754,6 +1169,9 @@ void RAILCb_TxPacketSent(RAIL_TxPacketInfo_t *txPacketInfo);
* - \ref RAIL_TX_CONFIG_CHANNEL_BUSY
* - \ref RAIL_TX_CONFIG_TX_ABORTED
* - \ref RAIL_TX_CONFIG_TX_BLOCKED
* - \ref RAIL_TX_CONFIG_CHANNEL_CLEAR
* - \ref RAIL_TX_CONFIG_CCA_RETRY
* - \ref RAIL_TX_CONFIG_START_CCA
*/
void RAILCb_TxRadioStatus(uint8_t status);
@ -792,7 +1210,9 @@ void RAILCb_TxRadioStatus(uint8_t status);
*
* A RAIL_PreTxOp_t function that schedules the transmit to occur at the
* specified absolute or relative time within a RAIL_TxStart() transmit
* operation.
* operation. If RAIL is receiving a packet at the scheduled time, the transmit
* will be delayed until after the packet is received. To guarantee the time of
* the outgoing transmit, only call this function while the radio is idle.
*/
uint8_t RAIL_ScheduleTx(void *params);
@ -804,8 +1224,15 @@ uint8_t RAIL_ScheduleTx(void *params);
* @return - Returns 0 on success and anything else on error.
*
* A RAIL_PreTxOp_t function that performs the CSMA algorithm when specified
* within a RAIL_TxStart() transmit operation.
* within a RAIL_TxStart() transmit operation. Packets can be received during
* CSMA backoff periods if receive is active throughout the CSMA process. This
* will happen either by starting the CSMA process while receive is already
* active, or if the ccaBackoff time in the RAIL_CsmaConfig_t is less than the
* idleToRx time (set by RAIL_SetStateTimings). If the ccaBackoff time is
* greater than the idleToRx time, then receive will only be active during the
* clear channel assessments.
*/
uint8_t RAIL_CcaCsma(void *params);
/**
@ -816,10 +1243,32 @@ uint8_t RAIL_CcaCsma(void *params);
* @return Returns 0 on success and anything else on error.
*
* A RAIL_PreTxOp_t function that performs the LBT algorithm when specified
* within a RAIL_TxStart() transmit operation.
* within a RAIL_TxStart() transmit operation. Packets can be received during
* CSMA backoff periods if receive is active throughout the LBT process. This
* will happen either by starting the LBT process while receive is already
* active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the
* idleToRx time (set by RAIL_SetStateTimings). If the lbtBackoff time is
* greater than the idleToRx time, then receive will only be active during the
* clear channel assessments.
*/
uint8_t RAIL_CcaLbt(void *params);
/**
* Sets the CCA threshold in dBm
*
* @param[in] ccaThresholdDbm CCA threshold in dBm.
* @return \ref RAIL_STATUS_NO_ERROR on success.
*
* A RAIL_PreTxOp_t function will normally set CCA threshold, assuming it is
* enabled either in LBT or CSMA mode. Unlike RAIL_CcaCsma and RAIL_CcaLbt,
* which are called as RAIL_PreTxOp_t functions, this function only modifies
* CCA threshold. A possible usecase for this function is to set CCA threshold
* to invalid RSSI of -128 which disables transmission by canceling
* the current CCA check.
*
*/
RAIL_Status_t RAIL_SetCcaThreshold(int8_t ccaThresholdDbm);
/**
* end of group Pre-Transmit
* @}
@ -850,10 +1299,23 @@ uint8_t RAIL_CcaLbt(void *params);
*
* Setup which receive interrupts will generate a RAILCb_RxRadioStatus()
* callback. The full list of options is any define that starts with
* RAIL_RX_CONFIG_. This function cannot be called while receiving.
* RAIL_RX_CONFIG_.
*/
uint8_t RAIL_RxConfig(uint32_t cbToEnable, bool appendedInfoEnable);
/**
* Configure receive options
*
* @param[in] options Bitfield of options which affect recieve. The available
* options begin with RAIL_RX_OPTION.
* @return Return 0 for success or an error code
*
* Configure the radio receive flow, based on the list of available options.
* This will fail with RAIL_STATUS_INVALID_STATE if a packet is being received
* during this configuration.
*/
RAIL_Status_t RAIL_SetRxOptions(uint32_t options);
/**
* Listen on a channel for a packet
*
@ -861,7 +1323,7 @@ uint8_t RAIL_RxConfig(uint32_t cbToEnable, bool appendedInfoEnable);
* @return Return 0 for success or an error code
*
* This is a non-blocking function. RAILCb_RxPacketReceived() will be called
* when a packet has been received. Returns an error is currently transmitting
* when a packet has been received. Returns an error if currently transmitting
* or receiving.
*/
uint8_t RAIL_RxStart(uint8_t channel);
@ -878,7 +1340,7 @@ uint8_t RAIL_RxStart(uint8_t channel);
* end time then you may call this API later with an end time as long as you set
* the start time to disabled. You can also terminate the whole receive
* operation immediately using the RAIL_RfIdle() function. Note that relative
* end times are always relative to the start unless there is not start
* end times are always relative to the start unless there is no start time
* specified.
*/
uint8_t RAIL_ScheduleRx(uint8_t channel, RAIL_ScheduleRxConfig_t *cfg);
@ -899,6 +1361,71 @@ uint8_t RAIL_ScheduleRx(uint8_t channel, RAIL_ScheduleRxConfig_t *cfg);
*/
int16_t RAIL_RxGetRSSI(void);
/**
* Compute the average RSSI over a specified time in us
*
* @param[in] averageTimeUs Averaging time in microseconds.
* @return Return \ref RAIL_RSSI_INVALID if the receiver is disabled and we are
* unable to get an RSSI value, otherwise, return the RSSI in quarter dBm,
* dbm*4.
*
* This blocking function will poll the hardware for RSSI values and compute
* the average RSSI over the requested time period. If no valid readings have
* been made function will return \ref RAIL_RSSI_INVALID reading. Receiving a
* packet during the averaging will cause invalid reading(s). However, invalid
* readings during the averaging will not be included in the average. Number of
* RSSI readings per baud depends on the phy.
*/
int16_t RAIL_PollAverageRSSI(uint32_t averageTimeUs);
/**
* Start the RSSI averaging over specified time in us
*
* @param[in] channel The physical channel to set
* @param[in] averagingTimeUs Averaging time in microseconds.
* @return Returns 0 on success, error code on error.
*
* Start a non-blocking hardware based RSSI averaging mechanism. Only a single
* instance of RSSI averaging can be run at any time and the radio must be idle
* to start.
*/
RAIL_Status_t RAIL_StartAverageRSSI(uint8_t channel, uint32_t averagingTimeUs);
/**
* Queries whether the RSSI averaging is done
*
* @return Returns true if done and false otherwise.
*
* This function can be used to poll for completion of the RSSI averaging so
* that you do not have to rely on an interrupt based callback.
*/
bool RAIL_AverageRSSIReady(void);
/**
* Get the RSSI averaged over specified time in us
*
* @return Return \ref RAIL_RSSI_INVALID if the receiver is disabled and we are
* unable to get an RSSI value, otherwise, return the RSSI in quarter dBm,
* dbm*4.
*
* Get the hardware RSSI average after issuing RAIL_StartAverageRSSI. Should be
* used after RAIL_StartAverageRSSI.
*/
int16_t RAIL_GetAverageRSSI(void);
/**
* Callback for when AGC averaged RSSI is done
*
* @param avgRssi Contains the the RSSI in quarter dBm (dbm*4) on success and
* returns \ref RAIL_RSSI_INVALID if there was a problem computing the result.
*
* Called in response to RAIL_StartAverageRSSI() to indicate that the hardware
* has completed averaging. If you would like you can instead use the
* RAIL_AverageRSSIReady() to wait for completion and RAIL_GetAverageRSSI() to
* get the result.
*/
void RAILCb_RssiAverageDone(int16_t avgRssi);
/**
* Receive packet callback.
*
@ -912,6 +1439,9 @@ int16_t RAIL_RxGetRSSI(void);
* stored. After this callback is done we will release the memory handle so you
* must somehow increment a reference count or copy the data out within this
* function.
*
* If \ref RAIL_IGNORE_CRC_ERRORS is set, this callback will fire for packets
* with crc errors as well.
*/
void RAILCb_RxPacketReceived(void *rxPacketHandle);
@ -965,6 +1495,7 @@ void RAILCb_RxRadioStatus(uint8_t status);
* - \ref RAIL_RX_CONFIG_RF_SENSED
* - \ref RAIL_RX_CONFIG_TIMEOUT
* - \ref RAIL_RX_CONFIG_SCHEDULED_RX_END
* - \ref RAIL_RX_CONFIG_PACKET_ABORTED
*/
void RAILCb_RxRadioStatusExt(uint32_t status);
@ -1031,8 +1562,9 @@ void RAILCb_RxRadioStatusExt(uint32_t status);
* ADDRCONFIG_MATCH_TABLE_DOUBLE_FIELD. For more complex systems you'll have to
* create a valid table on your own.
*
* @note When using a 38.4 MHz crystal, address filtering will not function with
* any data rate greater than 1Mbps.
* @note Address filtering does not function properly with PHYs that use a data
* rate greater than 500kbps. If you require this you must filter in software
* for the time being.
*
* @{
*/
@ -1139,7 +1671,7 @@ bool RAIL_AddressFilterDisableAddress(uint8_t field, uint8_t index);
*
* @param validFrames The frames on which to enable address filtering. Each bit
* corresponds to a frame, where a 1 means to enable address filtering during
* that frame, and a 0 means to ignore addresses during that frame.. The least
* that frame, and a 0 means to ignore addresses during that frame. The least
* significant bit corresponds to frame 0, and the most significant bit to
* frame 7.
* @return True if configuration was set properly, false otherwise
@ -1216,6 +1748,8 @@ bool RAIL_AddressFilterByFrameType(uint8_t validFrames);
* @code{.c}
* void RAILCb_RxPacketReceived(void *rxPacketHandle)
* {
* RAIL_RxPacketInfo_t rxPacketInfo = (RAIL_RxPacketInfo_t)rxPacketHandle;
*
* // If we have just received an ACK, don't respond with an ACK
* if (rxPacketInfo->dataPtr[2] == 0xF1)
* {
@ -1589,6 +2123,7 @@ uint8_t RAIL_TxStreamStop(void);
* During BER test mode, this device will expect to receive a standard PN9
* signal (x^9 + x^5 + 1). In order to use this BER test, the selection
* for BER mode should be enabled from the radio configurator.
* This function has been deprecated.
*/
void RAIL_BerConfigSet(RAIL_BerConfig_t *berConfig);
@ -1599,6 +2134,7 @@ void RAIL_BerConfigSet(RAIL_BerConfig_t *berConfig);
*
* Enter BER receive with the settings specified by RAIL_BerConfigSet().
* This also resets the BER status.
* This function has been deprecated.
*/
void RAIL_BerRxStart(void);
@ -1608,6 +2144,7 @@ void RAIL_BerRxStart(void);
* @return void
*
* Halt a test early, or exit infinite BER receive mode.
* This function has been deprecated.
*/
void RAIL_BerRxStop(void);
@ -1618,6 +2155,7 @@ void RAIL_BerRxStop(void);
* @return void
*
* Get status of latest BER test.
* This function has been deprecated.
*/
void RAIL_BerStatusGet(RAIL_BerStatus_t *status);
@ -1658,7 +2196,7 @@ uint32_t RAIL_DebugModeGet(void);
*
* @param[in] freq Desired frequency in Hz
*
* Sets the radio to transmit at a the frequency given. This function can only
* Sets the radio to transmit at the frequency given. This function can only
* be used while in RAIL_DEBUG_MODE_FREQ_OVERRIDE. The given frequency needs
* to be close to the base frequency of the current PHY.
*/
@ -1666,24 +2204,21 @@ RAIL_Status_t RAIL_DebugFrequencyOverride(uint32_t freq);
#endif
/**
* Interrupt level callback to signify when the radio changes state. This is
* for debug and __NOT__ for application use. It is not called by default but
* is required for the linking process.
* Callback function to signify when the radio changes state.
*
* Create an empty function for this callback.
* @param[in] state Current state of the radio. Exact values are for internal
* use only.
*
* This is for debug and __NOT__ for application use. It is not called by
* default but is required for the linking process.
*
* Create an empty function for this callback as shown below.
*
* @code{.c}
* RAILCb_RadioStateChanged(uint8_t state) {
* }
* @endcode
*/
#ifndef DOXYGEN_SHOULD_SKIP_THIS
/**
* @param[in] state Current state of the radio, as defined by EFR32 data sheet
* TODO: Unify these states with the RAIL_RadioState_t type? (There are much
* more than just TX, RX, and IDLE)
*/
#endif
void RAILCb_RadioStateChanged(uint8_t state);
/**

17
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_chip_specific.h
View File

@ -31,13 +31,16 @@
* something that can be computed once and stored off or computed each time at
* startup. It is PHY specific and provides sensitivity improvements so we
* highly recommend using it. The IR calibration should only be run when the
* radio is IDLE. The temperature dependent calibrations are used to
* recalibrate the synth if the temperature falls below 0 or changes by a
* certain amount while sitting in receive. We will do this automatically upon
* entering the receive state so you may omit this calibration if you feel that
* your stack will turn receive on and off frequently enough. If you do not
* calibrate for temperature it's possible to miss receive packets due to drift
* in the carrier frequency.
* radio is IDLE.
*
* The temperature dependent calibrations are used to recalibrate the synth if
* the temperature crosses 0C or the temperature delta since the last
* calibration exceeds 70C while sitting in receive. RAIL will run VCO
* calibration automatically upon entering receive state so the application can
* omit this calibration if the stack will re-enter receive with enough
* frequency to not hit this temperature delta. If the application does not
* calibrate for temperature, it's possible to miss receive packets due to
* drift in the carrier frequency.
*/
/**

344
targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_types.h
View File

@ -13,7 +13,7 @@
#include <stdbool.h>
#include <stddef.h>
#include "rail/rail_chip_specific.h"
#include "rail_chip_specific.h"
/**
* @addtogroup RAIL_API
@ -77,7 +77,7 @@ typedef struct RAIL_Version {
* @brief Initialization structure for the RAIL library.
*/
typedef struct RAIL_Init {
uint16_t maxPacketLength; /**< The maximum number of bytes in a packet. */
uint16_t maxPacketLength; /**< The maximum number of bytes in a packet. UNUSED! */
const uint32_t rfXtalFreq; /**< The xtal frequency of the radio. */
RAIL_CalMask_t calEnable; /**< Mask that defines calibrations to perform in RAIL. */
} RAIL_Init_t;
@ -88,11 +88,10 @@ typedef struct RAIL_Init {
*/
typedef enum RAIL_PtiProtocol {
RAIL_PTI_PROTOCOL_CUSTOM = 0, /**< PTI output for a custom protocol */
RAIL_PTI_PROTOCOL_ZIGBEE = 1, /**< PTI output for the Zigbee protocol */
RAIL_PTI_PROTOCOL_THREAD = 2, /**< PTI output for the Thread protocol */
RAIL_PTI_PROTOCOL_BLE = 3, /**< PTI output for the Bluetooth Smart protocol */
RAIL_PTI_PROTOCOL_CONNECT = 4, /**< PTI output for the Connect protocol */
RAIL_PTI_PROTOCOL_MAX = 0xF /**< Maximum possible protocol value for PTI */
RAIL_PTI_PROTOCOL_ZIGBEE = 5, /**< PTI output for the Zigbee protocol */
} RAIL_PtiProtocol_t;
/**
@ -150,9 +149,80 @@ typedef enum {
* abort all current operations and cancel any pending scheduled operations.
* It may also corrupt receive or transmit buffers and end up clearing them.
*/
RAIL_IDLE_FORCE_SHUTDOWN
RAIL_IDLE_FORCE_SHUTDOWN,
/**
* Similar to the \ref RAIL_IDLE_FORCE_SHUTDOWN command this will quickly
* put the radio into the idle state. In addition to this it will clear any
* pending receive or transmit callbacks and clear both the receive and
* transmit storage.
*/
RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS
} RAIL_RfIdleMode_t;
/**
* @}
*/
// -----------------------------------------------------------------------------
// Data Management Structures
// -----------------------------------------------------------------------------
/**
* @addtogroup Data_Management
* @{
*/
/**
* @enum RAIL_TxDataSource_t
* @brief Transmit data sources supported by RAIL.
*/
typedef enum{
TX_PACKET_DATA, /**< Use the frame hardware to packetize data */
} RAIL_TxDataSource_t;
/**
* @enum RAIL_RxDataSource_t
* @brief Receive data sources supported by RAIL.
*/
typedef enum{
RX_PACKET_DATA, /**< Use the frame hardware to packetize data */
RX_DEMOD_DATA, /**< Get 8-bit data output from the demodulator */
RX_IQDATA_FILTLSB, /**< Get lower 16 bits of I/Q data provided to demodulator */
RX_IQDATA_FILTMSB /**< Get highest 16 bits of I/Q data provided to demodulator */
} RAIL_RxDataSource_t;
/**
* @enum RAIL_DataMethod_t
* @brief Methods for the application to provide and retreive data from RAIL.
*/
typedef enum{
PACKET_MODE, /**< Packet based data method */
FIFO_MODE, /**< FIFO based data method */
} RAIL_DataMethod_t;
/**
* @struct RAIL_DataConfig_t
* @brief RAIL data configuration structure
*
* This structure is used to select the transmit/receive data sources, and the
* method the application uses to provide/retreive data from RAIL.
*/
typedef struct {
RAIL_TxDataSource_t txSource; /**< Source of TX Data */
RAIL_RxDataSource_t rxSource; /**< Source of RX Data */
RAIL_DataMethod_t txMethod; /**< Method of providing transmit data */
RAIL_DataMethod_t rxMethod; /**< Method of retrieving receive data */
} RAIL_DataConfig_t;
/**
* @def RAIL_SETFIXEDLENGTH_INVALID
* @brief Invalid return value when calling RAIL_SetFixedLength()
*
* Invalid return value when calling RAIL_SetFixedLength() while the radio is
* not in fixed length mode.
*/
#define RAIL_SETFIXEDLENGTH_INVALID (0xFFFF)
/**
* @}
*/
@ -203,6 +273,8 @@ typedef struct RAIL_FrameType {
* channel space and the channel indexes that are valid within this range.
*
* * frequency = baseFrequency + channelSpacing * (channel - channelNumberStart);
*
* Each RAIL_ChannelConfigEntry_t should not span more than 64 channels.
*/
typedef struct RAIL_ChannelConfigEntry {
uint16_t channelNumberStart; /**< RAIL Channel number in which this channel set begins.*/
@ -214,7 +286,47 @@ typedef struct RAIL_ChannelConfigEntry {
/**
* @struct RAIL_ChannelConfig_t
* @brief Channel configuration structure which defines the channel meaning when
* passed into RAIL functions, eg. RAIL_TxStart(), RAIL_RxStart()
* a channel number is passed into a RAIL function, eg. RAIL_TxStart(), RAIL_RxStart()
*
* A RAIL_ChannelConfig_t structure defines the channel scheme that an
* application uses when registered in RAIL_ChannelConfig(). A channel scheme
* must be in the same band, it can not span across frequencies that would
* change the divider.
*
* A few examples of different channel schemes:
* @code{.c}
* // Ten channels starting a 915 Mhz with a channel spacing of 1 Mhz
* RAIL_ChannelConfigEntry_t channels = {
* 0, 9, 1000000, 915000000
* };
* RAIL_ChannelConfig_t channelScheme = {
* channels,
* 1
* };
*
* // 120 channels starting at 915Mhz with channel spacing of 100KHz
* RAIL_ChannelConfigEntry_t channels[] = {
* {0, 63, 100000, 910000000},
* {64, 119, 100000, 916400000},
* };
* RAIL_ChannelConfig_t channelScheme = {
* channels,
* 2
* };
*
* // 5 nonlinear channels
* RAIL_ChannelConfigEntry_t channels[] = {
* {0, 0, 0, 910123456},
* {1, 1, 0, 911654789},
* {2, 2, 0, 912321456},
* {3, 3, 0, 913147852},
* {4, 4, 0, 914567890}
* };
* RAIL_ChannelConfig_t channelScheme = {
* channels,
* 5
* };
* @endcode
*/
typedef struct RAIL_ChannelConfig {
RAIL_ChannelConfigEntry_t *configs; /**< Pointer to an array of RAIL_ChannelConfigEntry_t entries.*/
@ -314,13 +426,39 @@ typedef struct RAIL_AddrConfig {
/**
* @enum RAIL_TimeMode_t
* @brief Enumeration for specifying timing offsets in RAIL for any APIs that
* use them.
* @brief This type is used to specifying a time offset in RAIL APIs.
*
* Different APIs use these same constants and may provide more specifics of how
* they're used but the general philosophy for each is described below.
*/
typedef enum RAIL_TimeMode {
RAIL_TIME_ABSOLUTE, /**< The time specified is an exact time in the RAIL timebase */
RAIL_TIME_DELAY, /**< The time specified is relative to now */
RAIL_TIME_DISABLED /**< The time specified is not intended to be used */
/**
* The time specified is an exact time in the RAIL timebase and the given
* event should happen at exactly that time. If this time is already in the
* past we will return an error and fail. Since the RAIL timebase wraps at 32
* bits there is no real 'past' so we instead consider any event greater than
* 3/4 of the way into the future to be in the past.
*/
RAIL_TIME_ABSOLUTE,
/**
* The time specified is relative to now and the event should occur that many
* ticks in the future. Delays are only guaranteed to be at least as long as
* the value specified. There may be some overhead between when the API is
* called and when the delay starts so we _do not_ recommend using this for
* operations that must happen at exactly a given time. For that you must use
* \ref RAIL_TIME_ABSOLUTE delays.
*
* Note that if you specify a delay of 0 we will trigger that event as soon as
* possible. This is different than specifying an absolute time of now which
* would return an error unless it was possible.
*/
RAIL_TIME_DELAY,
/**
* The specified time is invalid and should be ignored. For some APIs this can
* also indicate that any previously stored delay should be invalidated and
* disabled.
*/
RAIL_TIME_DISABLED
} RAIL_TimeMode_t;
/**
@ -350,8 +488,17 @@ typedef uint8_t (*RAIL_PreTxOp_t)(void *params);
* must be passed as its argument.
*/
typedef struct RAIL_ScheduleTxConfig {
uint32_t when; /**< When to transmit this packet in the RAIL timebase. */
RAIL_TimeMode_t mode; /**< Specifies whether when is an absolute time or an offset from now. */
/**
* When to transmit this packet. The exact interpretation of this value
* depends on the mode specified below.
*/
uint32_t when;
/**
* They type of delay to use. See the \ref RAIL_TimeMode_t documentation for
* more information. Be sure to use \ref RAIL_TIME_ABSOLUTE delays for time
* critical protocols.
*/
RAIL_TimeMode_t mode;
} RAIL_ScheduleTxConfig_t;
/**
@ -368,8 +515,14 @@ typedef struct RAIL_ScheduleTxConfig {
* argument.
*/
typedef struct RAIL_CsmaConfig {
uint8_t csmaMinBoExp; /**< Minimum (starting) exponent for CSMA backoff (2^exp - 1) */
uint8_t csmaMaxBoExp; /**< Maximum exponent for CSMA backoff */
/**
* Minimum (starting) exponent for CSMA backoff (2^exp - 1)
*/
uint8_t csmaMinBoExp;
/**
* Maximum exponent for CSMA backoff
*/
uint8_t csmaMaxBoExp;
/**
* Number of CCA failures before report CCA_FAIL. With a maximum value defined
* in @ref RAIL_MAX_LBT_TRIES). A value of 0 will perform no CCA assessments,
@ -383,15 +536,16 @@ typedef struct RAIL_CsmaConfig {
int8_t ccaThreshold;
/**
* The backoff unit period, in RAIL's microsecond time base. This is
* mulitiplied by the random backoff multiplier controlled by @ref
* mulitiplied by the random backoff exponential controlled by @ref
* csmaMinBoExp and @ref csmaMaxBoExp to determine the overall backoff
* period. This value must be at least the idleToRx time (set by
* RAIL_SetStateTimings). For random backoffs, any value above 511
* microseconds will be truncated; for fixed backoffs it can go up to 65535
* microseconds.
* period. For random backoffs, any value above 511 microseconds will
* be truncated; for fixed backoffs it can go up to 65535 microseconds.
*/
uint16_t ccaBackoff;
uint16_t ccaDuration; /**< CCA check duration, in microseconds */
/**
* CCA check duration in microseconds.
*/
uint16_t ccaDuration;
/**
* An overall timeout, in RAIL's microsecond time base, for the operation. If
* transmission doesn't start before this timeout expires, the transmission
@ -442,14 +596,20 @@ typedef struct RAIL_CsmaConfig {
* argument.
*/
typedef struct RAIL_LbtConfig {
uint8_t lbtMinBoRand; /**< Minimum backoff random multiplier */
uint8_t lbtMaxBoRand; /**< Maximum backoff random multiplier */
/**
* Maximum backoff random multiplier
*/
uint8_t lbtMinBoRand;
/**
* Maximum backoff random multiplier
*/
uint8_t lbtMaxBoRand;
/**
* Number of CCA failures before report CCA_FAIL. With a maximum value defined
* in @ref RAIL_MAX_LBT_TRIES). A value of 0 will perform no CCA assessments,
* and always transmit immediately.
*/
uint8_t lbtTries; /**< Number of LBT failures before report CCA_FAIL */
uint8_t lbtTries;
/**
* The CCA RSSI threshold, in dBm, above which the channel is
* considered 'busy'.
@ -458,13 +618,15 @@ typedef struct RAIL_LbtConfig {
/**
* The backoff unit period, in RAIL's microsecond time base. This is
* mulitiplied by the random backoff multiplier controlled by @ref
* csmaMinBoExp and @ref csmaMaxBoExp to determine the overall backoff
* period. For random backoffs, this value must be in the range from
* idleToRx time (set by RAIL_SetStateTimings) to 511 microseconds; for fixed
* backoffs it can go up to 65535 microseconds.
* lbtMinBoRand and @ref lbtMaxBoRand to determine the overall backoff
* period. For random backoffs, any value above 511 microseconds will
* be truncated; for fixed backoffs it can go up to 65535 microseconds.
*/
uint16_t lbtBackoff;
uint16_t lbtDuration; /**< LBT check duration, in microseconds */
/**
* LBT check duration in microseconds.
*/
uint16_t lbtDuration;
/**
* An overall timeout, in RAIL's microsecond time base, for the
* operation. If transmission doesn't start before this timeout expires, the
@ -508,6 +670,8 @@ typedef struct RAIL_LbtConfig {
*/
// Tx Config Callback Defines
/** Callback for a transmit buffer overflow event */
#define RAIL_TX_CONFIG_BUFFER_OVERFLOW (0x01 << 0)
/** Callback for a transmit buffer underflow event */
#define RAIL_TX_CONFIG_BUFFER_UNDERFLOW (0x01 << 1)
/** Callback for CCA/CSMA/LBT failure */
@ -516,6 +680,12 @@ typedef struct RAIL_LbtConfig {
#define RAIL_TX_CONFIG_TX_ABORTED (0x01 << 3)
/** Callback for when a Tx is blocked by something like PTA or RHO */
#define RAIL_TX_CONFIG_TX_BLOCKED (0x01 << 4)
/** Callback for CCA/CSMA/LBT success */
#define RAIL_TX_CONFIG_CHANNEL_CLEAR (0x01 << 5)
/** Callback for when an CCA check is being retried */
#define RAIL_TX_CONFIG_CCA_RETRY (0x01 << 6)
/** Callback for when a clear channel assessment (CCA) is begun */
#define RAIL_TX_CONFIG_START_CCA (0x01 << 7)
/**
* @struct RAIL_TxData_t
@ -525,7 +695,7 @@ typedef struct RAIL_LbtConfig {
*/
typedef struct RAIL_TxData {
uint8_t *dataPtr; /**< Pointer to data to transmit */
uint16_t dataLength; /**< Number of bytes to transmit */
uint16_t dataLength; /**< Number of bytes to load into transmit buffer */
} RAIL_TxData_t;
/**
@ -534,7 +704,8 @@ typedef struct RAIL_TxData {
*/
typedef struct RAIL_TxPacketInfo {
/**
* Time recorded when the last bit is transmitted out of the modulator.
* Timestamp of the transmitted packet in the RAIL timebase of microseconds.
* The time is the end of the last bit of the transmitted packet.
*/
uint32_t timeUs;
} RAIL_TxPacketInfo_t;
@ -562,13 +733,21 @@ typedef struct RAIL_TxOptions {
*/
// Rx Config Callback Defines
/** Callback for when more is read from the Rx buffer than is available */
#define RAIL_RX_CONFIG_BUFFER_UNDERFLOW (0x01 << 0)
/** Callback for preamble detection */
#define RAIL_RX_CONFIG_PREAMBLE_DETECT (0x01 << 1)
/** Callback for detection of the first sync word */
#define RAIL_RX_CONFIG_SYNC1_DETECT (0x01 << 2)
/** Callback for detection of the second sync word */
#define RAIL_RX_CONFIG_SYNC2_DETECT (0x01 << 3)
/** Callback for detection of frame errors */
/** Callback for detection of frame errors
*
* For efr32xg1x parts, frame errors include violations of variable length
* min/max limits, frame coding errors, and crc errors. If \ref
* RAIL_IGNORE_CRC_ERRORS are set, \ref RAIL_RX_CONFIG_FRAME_ERROR will not be
* asserted for crc errors.
*/
#define RAIL_RX_CONFIG_FRAME_ERROR (0x01 << 4)
/** Callback for when we run out of Rx buffer space */
#define RAIL_RX_CONFIG_BUFFER_OVERFLOW (0x01 << 5)
@ -580,16 +759,42 @@ typedef struct RAIL_TxOptions {
#define RAIL_RX_CONFIG_TIMEOUT (0x01 << 8)
/** Callback for when the scheduled Rx window ends */
#define RAIL_RX_CONFIG_SCHEDULED_RX_END (0x01 << 9)
/** Callback for an aborted packet. This is triggered when a more specific
* reason the packet was aborted, such as RAIL_RX_CONFIG_ADDRESS_FILTERED, is
* not known. */
#define RAIL_RX_CONFIG_PACKET_ABORTED (0x01 << 10)
/**
* Callback for when the packet has passed any configured address and frame
* filtering options.
*/
#define RAIL_RX_CONFIG_FILTER_PASSED (0x01 << 11)
/** To maintain backwards compatibility with RAIL 1.1,
* RAIL_RX_CONFIG_INVALID_CRC is the same as RAIL_RX_CONFIG_FRAME_ERROR
*/
#define RAIL_RX_CONFIG_INVALID_CRC RAIL_RX_CONFIG_FRAME_ERROR
// Rx Option Defines
/** Option to configure whether the CRC portion of the packet is included in
* the dataPtr field of the RAIL_RxPacketInfo_t passed via
* RAILCb_RxPacketReceived(). Defaults to false. */
#define RAIL_RX_OPTION_STORE_CRC (1 << 0)
// Rx Config Ignore Error Defines
/** Ignore no errors. Drop all packets with errors */
/**
* Ignore no errors.
*
* Drop all packets with errors. With this setting, crc errors will generate a
* RAILCb_RxRadioStatus() with \ref RAIL_RX_CONFIG_FRAME_ERROR.
*/
#define RAIL_IGNORE_NO_ERRORS (0x00)
/** Ignore CRC errors. Receive packets with CRC errors */
/**
* Hardware ignores CRC errors.
*
* When this setting is enabled and a CRC error occurs, RAILCb_RxRadioStatus()
* with \ref RAIL_RX_CONFIG_FRAME_ERROR will not occur. Instead packets with crc
* errors will generate RAILCb_RxPacketReceived().
*/
#define RAIL_IGNORE_CRC_ERRORS (0x01 << 0)
/** Ignore all possible errors. Receive all possible packets */
#define RAIL_IGNORE_ALL_ERRORS (0xFF)
@ -606,8 +811,8 @@ typedef struct RAIL_TxOptions {
*/
typedef struct RAIL_AppendedInfo {
/**
* Timestamp of the received packet in the RAIL timebase of microseconds.
* This time is recorded at sync detect.
* Timestamp of the received packet in the RAIL timebase of microseconds. The
* time is the end of the sync word of the received packet.
*/
uint32_t timeUs;
/**
@ -623,7 +828,8 @@ typedef struct RAIL_AppendedInfo {
/**
* Indicates if the received packet is an ack. An 'ack' is defined as a
* packet received during the rx ack window when autoack is enabled.
* Set to 0 for not an ack, and 1 for is an ack.
* Set to 0 for not an ack, and 1 for is an ack. Will always be 0 if
* autoack is not enabled.
*/
bool isAck:1;
/**
@ -632,8 +838,8 @@ typedef struct RAIL_AppendedInfo {
*/
int8_t rssiLatch;
/**
* Link quality indicator of the received packet. This is not currently
* implemented.
* Link quality indicator of the received packet. This is calculated as the
* average correlation for the first 8 symbols in a frame.
*/
uint8_t lqi;
/**
@ -645,26 +851,35 @@ typedef struct RAIL_AppendedInfo {
/**
* @struct RAIL_RxPacketInfo_t
* @brief Rx Packet Information structure passed into RAILCb_RxPacketReceived
* after a packet has been received. Contains a pointer to the data recieved,
* as well as other packet information.
* @brief Receive packet information structure
*
* The structure used to pass an over the air packet and some associated
* information up to the application code. The memory handle that you receive
* in the call to RAILCb_RxPacketReceived() will contain this data structure.
*/
typedef struct RAIL_RxPacketInfo {
RAIL_AppendedInfo_t appendedInfo; /**< A structure containing various extra information about the received packet. */
uint16_t dataLength; /**< The number of bytes in the dataPtr array. */
uint8_t dataPtr[]; /**< A variable length array holding the packet contents. */
/**
* A structure containing the extra information associated with this received
* packet.
*/
RAIL_AppendedInfo_t appendedInfo;
/**
* The number of bytes that are in the dataPtr array.
*/
uint16_t dataLength;
/**
* A variable length array holding the receive packet data bytes.
*/
uint8_t dataPtr[];
} RAIL_RxPacketInfo_t;
/**
* @struct RAIL_ScheduleRxConfig_t
* @brief This structure is used to configure the Scheduled Rx algorithm. It
* allows you to define the start and end times of the window in either absolute
* or relative times. If start is set to \ref RAIL_TIME_DISABLED it will be
* assumed that we should start receive now. If end is set to \ref
* RAIL_TIME_DISABLED then the only way to end this scheduled receive is with an
* explicit call to RAIL_RfIdle(). If end is relative it is relative to the
* start time not the current time. All times are assumed to be specified in the
* RAIL timebase.
* @brief This structure is used to configure the Scheduled Rx algorithm.
*
* It allows you to define the start and end times of the receive window created
* for scheduled receive. If either start or end times are disabled then they
* will be ignored.
*/
typedef struct RAIL_ScheduleRxConfig {
/**
@ -672,15 +887,12 @@ typedef struct RAIL_ScheduleRxConfig {
* types of start times that you can specify.
*/
uint32_t start;
/**
* The type of time value specified in the start parameter. If this is
* \ref RAIL_TIME_ABSOLUTE then it's an exact time, if it's \ref
* RAIL_TIME_DELAY then it's an offset relative to the current time. If you
* specify \ref RAIL_TIME_DISABLED for this then the start event will be
* ignored.
* How to interpret the time value specified in the start parameter. See the
* \ref RAIL_TimeMode_t documentation for more information. Use
* \ref RAIL_TIME_ABSOLUTE for absolute times, \ref RAIL_TIME_DELAY for times
* relative to now, and \ref RAIL_TIME_DISABLED to ignore the start time.
*/
RAIL_TimeMode_t startMode;
/**
* The time to end receive. See endMode for more information about the types
@ -688,11 +900,13 @@ typedef struct RAIL_ScheduleRxConfig {
*/
uint32_t end;
/**
* The type of time value specified in the end parameter. If this is
* \ref RAIL_TIME_ABSOLUTE then it's an exact time, if it's \ref RAIL_TIME_DELAY then
* it's an offset relative to the start time as long as the startMode isn't
* \ref RAIL_TIME_DISABLED and if it's \ref RAIL_TIME_DISABLED we will not configure the
* end event so that this can run indefinitely.
* How to interpret the time value specified in the end parameter. See the
* \ref RAIL_TimeMode_t documentation for more information. Note that in this
* API if you specify a \ref RAIL_TIME_DELAY it will be relative to the start
* time if given and relative to now if none is specified. Also, using \ref
* RAIL_TIME_DISABLED means that this window will not end unless you
* explicitly call RAIL_RfIdle() or add an end event through a future update
* to this configuration.
*/
RAIL_TimeMode_t endMode;
/**