diff --git a/features/nanostack/FEATURE_NANOSTACK/targets/TARGET_SL_RAIL/NanostackRfPhyEfr32.cpp b/features/nanostack/FEATURE_NANOSTACK/targets/TARGET_SL_RAIL/NanostackRfPhyEfr32.cpp index 925895bac5..bc677ff89f 100644 --- a/features/nanostack/FEATURE_NANOSTACK/targets/TARGET_SL_RAIL/NanostackRfPhyEfr32.cpp +++ b/features/nanostack/FEATURE_NANOSTACK/targets/TARGET_SL_RAIL/NanostackRfPhyEfr32.cpp @@ -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); } \ No newline at end of file diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/buffer-pool-memory-manager/buffer_pool_allocator.c b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/buffer-pool-memory-manager/buffer_pool_allocator.c index 5a216c000d..d112b4277a 100644 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/buffer-pool-memory-manager/buffer_pool_allocator.c +++ b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/buffer-pool-memory-manager/buffer_pool_allocator.c @@ -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(); } diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/ieee802154_efr32xg1_configurator_out.c b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/ieee802154_efr32xg1_configurator_out.c deleted file mode 100644 index 213dac66fc..0000000000 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/ieee802154_efr32xg1_configurator_out.c +++ /dev/null @@ -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 - -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, -}; - diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1.a deleted file mode 100644 index d505e1ccad..0000000000 Binary files a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1.a and /dev/null differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a new file mode 100644 index 0000000000..bc0ab389b7 Binary files /dev/null and b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/ieee802154_efr32xg12_configurator_out.c b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/ieee802154_efr32xg12_configurator_out.c deleted file mode 100644 index 7ad3edf01b..0000000000 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/ieee802154_efr32xg12_configurator_out.c +++ /dev/null @@ -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 - -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, -}; - diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12.a deleted file mode 100644 index 57c1427a22..0000000000 Binary files a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12.a and /dev/null differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12_gcc_release.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12_gcc_release.a new file mode 100644 index 0000000000..ac00f614cd Binary files /dev/null and b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_GCC_ARM/TARGET_EFR32MG12/librail_efr32xg12_gcc_release.a differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32_iar_release.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32_iar_release.a deleted file mode 100644 index a089e35b1d..0000000000 Binary files a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32_iar_release.a and /dev/null differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a new file mode 100644 index 0000000000..bc0ab389b7 Binary files /dev/null and b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG1/librail_efr32xg1_gcc_release.a differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG12/librail_efr32xg12_iar_release.a b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG12/librail_efr32xg12_iar_release.a new file mode 100644 index 0000000000..d5526f106d Binary files /dev/null and b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/TOOLCHAIN_IAR/TARGET_EFR32MG12/librail_efr32xg12_iar_release.a differ diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/pa.h b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/pa.h index faeefeca14..f8cd45ca4c 100644 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/pa.h +++ b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/pa.h @@ -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 } diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail.h b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail.h index af1fb40699..b5d858d6ee 100644 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail.h +++ b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail.h @@ -13,7 +13,7 @@ #include // 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 not 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 ignoreErrors + * 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 ignoreErrors parameter in + * RAIL_SetRxTransitions() to \ref RAIL_IGNORE_CRC_ERRORS. + * + * In either situation, the application can set ignoreErrors 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); /** diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_chip_specific.h b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_chip_specific.h index fad46dab6c..dfe2c87305 100644 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_chip_specific.h +++ b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_chip_specific.h @@ -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. */ /** diff --git a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_types.h b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_types.h index 75de9d0e98..8578404bb7 100644 --- a/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_types.h +++ b/targets/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/rail_types.h @@ -13,7 +13,7 @@ #include #include -#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; /**