License#

__RAIL_CHIP_SPECIFIC_H_#

#define __RAIL_CHIP_SPECIFIC_H_

Include guard.

RAIL_ENUM#

#define RAIL_ENUM

(name)

The RAIL library does not use enumerations because the ARM EABI leaves their size ambiguous, which causes problems if the application is built with different flags than the library.

Instead, uint8_t typedefs are used in compiled code for all enumerations. For documentation purposes, this is converted to an actual enumeration since it's much easier to read in Doxygen.

RAIL_ENUM_GENERIC#

#define RAIL_ENUM_GENERIC

(name, type)

This macro is a more generic version of the RAIL_ENUM() macro that allows the size of the type to be overridden instead of forcing the use of a uint8_t.

See RAIL_ENUM() for more information.

RAIL_EFR32_HANDLE#

#define RAIL_EFR32_HANDLE

((RAIL_Handle_t)0xFFFFFFFFUL)

A placeholder for a chip-specific RAIL handle.

Using NULL as a RAIL handle is not recommended. As a result, another value that can't be de-referenced is used.

This generic handle can and should be used for RAIL APIs that are called prior to RAIL initialization.

TRANSITION_TIME_US#

#define TRANSITION_TIME_US

430

Time it takes to take care of protocol switching.

RAIL_CAL_TEMP_VCO#

#define RAIL_CAL_TEMP_VCO

(0x00000001U)

EFR32-specific temperature calibration bit.

RAIL_CAL_TEMP_HFXO#

#define RAIL_CAL_TEMP_HFXO

(0U)

EFR32-specific HFXO temperature check bit.

RAIL_CAL_COMPENSATE_HFXO#

#define RAIL_CAL_COMPENSATE_HFXO

(0U)

EFR32-specific HFXO compensation bit.

RAIL_CAL_RX_IRCAL#

#define RAIL_CAL_RX_IRCAL

(0x00010000U)

EFR32-specific IR calibration bit.

RAIL_CAL_ONETIME_IRCAL#

#define RAIL_CAL_ONETIME_IRCAL

(RAIL_CAL_RX_IRCAL)

EFR32-specific IR calibration bit.

RAIL_CAL_TEMP#

#define RAIL_CAL_TEMP

(RAIL_CAL_TEMP_VCO)

A mask to run temperature-dependent calibrations.

RAIL_CAL_ONETIME#

#define RAIL_CAL_ONETIME

(RAIL_CAL_ONETIME_IRCAL)

A mask to run one-time calibrations.

RAIL_CAL_PERF#

#define RAIL_CAL_PERF

(0)

A mask to run optional performance calibrations.

RAIL_CAL_OFFLINE#

#define RAIL_CAL_OFFLINE

(RAIL_CAL_ONETIME_IRCAL)

A mask for calibrations that require the radio to be off.

RAIL_CAL_ALL#

#define RAIL_CAL_ALL

(RAIL_CAL_TEMP | RAIL_CAL_ONETIME)

A mask to run all possible calibrations for this chip.

RAIL_CAL_ALL_PENDING#

#define RAIL_CAL_ALL_PENDING

(0x00000000U)

A mask to run all pending calibrations.

RAIL_CAL_INVALID_VALUE#

#define RAIL_CAL_INVALID_VALUE

(0xFFFFFFFFU)

An invalid calibration value.

RAIL_RF_PATHS#

#define RAIL_RF_PATHS

1

Indicates the number of RF Paths supported.

RAIL_IRCALVALUES_UNINIT#

#define RAIL_IRCALVALUES_UNINIT

A define to set all RAIL_IrCalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_IRCALVAL#

#define RAIL_IRCALVAL

(irCalStruct, rfPath)

A define allowing Rx calibration value access compatibility between series 1 and series 2.

RAIL_CALVALUES_UNINIT#

#define RAIL_CALVALUES_UNINIT

RAIL_IRCALVALUES_UNINIT

A define to set all RAIL_CalValues_t values to uninitialized.

This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.

RAIL_FREQUENCY_OFFSET_MAX#

#define RAIL_FREQUENCY_OFFSET_MAX

((RAIL_FrequencyOffset_t) 0x3FFF)

The maximum frequency offset value supported by this radio.

RAIL_FREQUENCY_OFFSET_MIN#

#define RAIL_FREQUENCY_OFFSET_MIN

((RAIL_FrequencyOffset_t) -RAIL_FREQUENCY_OFFSET_MAX)

The minimum frequency offset value supported by this radio.

RAIL_FREQUENCY_OFFSET_INVALID#

#define RAIL_FREQUENCY_OFFSET_INVALID

((RAIL_FrequencyOffset_t) 0x8000)

Specify an invalid frequency offset value.

This will be returned if you call RAIL_GetRxFreqOffset() at an invalid time.

RAIL_TX_PA_POWER_SETTING_UNSUPPORTED#

#define RAIL_TX_PA_POWER_SETTING_UNSUPPORTED

(0U)

Returned by RAIL_SetPaPowerSetting when the current PA does not support the dBm to power setting mapping table.

RAIL_TX_POWER_LEVEL_2P4_LP_MAX#

#define RAIL_TX_POWER_LEVEL_2P4_LP_MAX

(7U)

The maximum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_2P4_LP mode.

RAIL_TX_POWER_LEVEL_2P4_HP_MAX#

#define RAIL_TX_POWER_LEVEL_2P4_HP_MAX

(252U)

The maximum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_2P4_HP mode.

RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX#

#define RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX

(248U)

The maximum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_SUBGIG mode.

RAIL_TX_POWER_LEVEL_2P4_LP_MIN#

#define RAIL_TX_POWER_LEVEL_2P4_LP_MIN

(1U)

The minimum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_2P4_LP mode.

RAIL_TX_POWER_LEVEL_2P4_HP_MIN#

#define RAIL_TX_POWER_LEVEL_2P4_HP_MIN

(0U)

The minimum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_2P4_HP mode.

RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN#

#define RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN

(0U)

The minimum valid value for the RAIL_TxPowerLevel_t when in RAIL_TX_POWER_MODE_SUBGIG mode.

RAIL_TX_POWER_LEVEL_INVALID#

#define RAIL_TX_POWER_LEVEL_INVALID

(255U)

Invalid RAIL_TxPowerLevel_t value returned when an error occurs with RAIL_GetTxPower.

RAIL_TX_POWER_LEVEL_MAX#

#define RAIL_TX_POWER_LEVEL_MAX

(254U)

Sentinel value that can be passed to RAIL_SetTxPower to set the highest power level available on the current PA, regardless of which one is selected.

RAIL_TX_POWER_LEVEL_LP_MAX#

#define RAIL_TX_POWER_LEVEL_LP_MAX

RAIL_TX_POWER_LEVEL_2P4_LP_MAX

Backwards compatibility define.

RAIL_TX_POWER_LEVEL_HP_MAX#

#define RAIL_TX_POWER_LEVEL_HP_MAX

RAIL_TX_POWER_LEVEL_2P4_HP_MAX

Backwards compatibility define.

RAIL_TX_POWER_LEVEL_SUBGIG_MAX#

#define RAIL_TX_POWER_LEVEL_SUBGIG_MAX

RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX

Backwards compatibility define.

RAIL_TX_POWER_LEVEL_LP_MIN#

#define RAIL_TX_POWER_LEVEL_LP_MIN

RAIL_TX_POWER_LEVEL_2P4_LP_MIN

Backwards compatibility define.

RAIL_TX_POWER_LEVEL_HP_MIN#

#define RAIL_TX_POWER_LEVEL_HP_MIN

RAIL_TX_POWER_LEVEL_2P4_HP_MIN

Backwards compatibility define.

RAIL_TX_POWER_LEVEL_SUBGIG_MIN#

#define RAIL_TX_POWER_LEVEL_SUBGIG_MIN

RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN

Backwards compatibility define.

RAIL_TX_POWER_MODE_2P4_HP#

#define RAIL_TX_POWER_MODE_2P4_HP

RAIL_TX_POWER_MODE_2P4GIG_HP

DeprecatedPlease use RAIL_TX_POWER_MODE_2P4GIG_HP instead.

RAIL_TX_POWER_MODE_2P4_LP#

#define RAIL_TX_POWER_MODE_2P4_LP

RAIL_TX_POWER_MODE_2P4GIG_LP

DeprecatedPlease use RAIL_TX_POWER_MODE_2P4GIG_LP instead.

RAIL_NUM_PA#

#define RAIL_NUM_PA

(3U)

The number of PA's on this chip.

(Including Virtual PAs)

RAIL_TX_POWER_MODE_NAMES#

#define RAIL_TX_POWER_MODE_NAMES

The names of the TX power modes.

A list of the names for the TX power modes on the EFR32 series 1 parts. This macro is useful for test applications and debugging output.

RAIL_PACTUNE_IGNORE#

#define RAIL_PACTUNE_IGNORE

(255U)

Use this value with either TX or RX values in RAIL_SetPaCTune to use whatever value is already set and do no update.

RAIL_RETIME_OPTION_HFXO#

#define RAIL_RETIME_OPTION_HFXO

(1U << RAIL_RETIME_OPTION_HFXO_SHIFT)

An option to configure HFXO retiming.

RAIL_RETIME_OPTION_HFRCO#

#define RAIL_RETIME_OPTION_HFRCO

(1U << RAIL_RETIME_OPTION_HFRCO_SHIFT)

An option to configure HFRCO retiming.

RAIL_RETIME_OPTION_DCDC#

#define RAIL_RETIME_OPTION_DCDC

(1U << RAIL_RETIME_OPTION_DCDC_SHIFT)

An option to configure DCDC retiming.

RAIL_RETIME_OPTIONS_NONE#

#define RAIL_RETIME_OPTIONS_NONE

0x0U

A value representing no retiming options.

RAIL_RETIME_OPTIONS_ALL#

#define RAIL_RETIME_OPTIONS_ALL

0xFFU

A value representing all retiming options.

RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL#

#define RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL

(53U)

The static amount of memory needed per channel for channel hopping, measured in 32 bit words, regardless of the size of radio configuration structures.

RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT#

#define RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT

(7U)

Default PRS channel to use when configuring sleep.

RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT#

#define RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT

(0U)

Default RTCC channel to use when configuring sleep.

RAIL_TIMER_SYNC_DEFAULT#

#define RAIL_TIMER_SYNC_DEFAULT

Default timer synchronization configuration.

RAIL_FIFO_ALIGNMENT_TYPE#

#define RAIL_FIFO_ALIGNMENT_TYPE

uint8_t

Fixed-width type indicating the needed alignment for RX and TX FIFOs.

Note that docs.silabs.com will incorrectly indicate that this is always a uint8_t, but it does vary across RAIL platforms.

RAIL_FIFO_ALIGNMENT#

#define RAIL_FIFO_ALIGNMENT

(sizeof(RAIL_FIFO_ALIGNMENT_TYPE))

Alignment that is needed for the RX and TX FIFOs.

RAIL_MINIMUM_TRANSITION_US#

#define RAIL_MINIMUM_TRANSITION_US

(100U)

The minimum value for a consistent RAIL transition.

Note

• Transitions may need to be slower than this when using longer RAIL_TxPowerConfig_t::rampTime values

RAIL_MAXIMUM_TRANSITION_US#

#define RAIL_MAXIMUM_TRANSITION_US

(1000000U)

The maximum value for a consistent RAIL transition.

(_SILICON_LABS_32B_SERIES_1_CONFIG == 1)

RAIL_AntennaSel_t#

RAIL_AntennaSel_t

Antenna path Selection enumeration.

RAIL_TxPowerMode_t#

RAIL_TxPowerMode_t

An enumeration of the EFR32 power modes.

The power modes on the EFR32 correspond to the different on-chip PAs that are available. For more information about the power and performance characteristics of a given amplifier, see the data sheet.

RAIL_PtiMode_t#

RAIL_PtiMode_t

A channel type enumeration.

RAIL_RetimeOptions_t#

RAIL_RetimeOptions_t

Retiming options bit shifts.

RAIL_StateBuffer_t#

RAIL_StateBuffer_t [1]

Provided for backwards compatibility.

RAIL_IrCalValues_t#

typedef uint32_t RAIL_IrCalValues_t[1] [1]

RAIL_IrCalValues_t.

An IR calibration value structure.

This definition contains the set of persistent calibration values for EFR32. You can set these beforehand and apply them at startup to save the time required to compute them. Any of these values may be set to RAIL_IRCAL_INVALID_VALUE to force the code to compute that calibration value.

RAIL_CalValues_t#

RAIL_CalValues_t

A calibration value structure.

This structure contains the set of persistent calibration values for EFR32. You can set these beforehand and apply them at startup to save the time required to compute them. Any of these values may be set to RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.

RAIL_FrequencyOffset_t#

RAIL_FrequencyOffset_t

Chip-specific type that represents the number of Frequency Offset units.

It is used with RAIL_GetRxFreqOffset() and RAIL_SetFreqOffset().

The units on this chip are radio synthesizer resolution steps (synthTicks). On EFR32 (at least for now), the frequency offset is limited to 15 bits (size of SYNTH_CALOFFSET). A value of RAIL_FREQUENCY_OFFSET_INVALID means that this value is invalid.

RAIL_RadioConfig_t#

typedef const uint32_t* RAIL_RadioConfig_t

The radio configuration structure.

The radio configuration properly configures the radio for operation on a protocol. These configurations should not be created or edited by hand.

RAIL_TxPowerLevel_t#

typedef uint8_t RAIL_TxPowerLevel_t

Raw power levels used directly by the RAIL_Get/SetTxPower API where a higher numerical value corresponds to a higher output power.

These are referred to as 'raw (values/units)'. On EFR32, they can range from one of RAIL_TX_POWER_LEVEL_2P4_LP_MIN, RAIL_TX_POWER_LEVEL_2P4_HP_MIN, or RAIL_TX_POWER_LEVEL_SUBGIG_HP_MIN to one of RAIL_TX_POWER_LEVEL_2P4_LP_MAX, RAIL_TX_POWER_LEVEL_2P4_HP_MAX, and RAIL_TX_POWER_LEVEL_SUBGIG_HP_MAX, respectively, depending on the selected RAIL_TxPowerMode_t.

RAIL_PaPowerSetting_t#

typedef uint32_t RAIL_PaPowerSetting_t

PA power setting used directly by the RAIL_GetPaPowerSetting() and RAIL_SetPaPowerSetting() APIs which is decoded to the actual hardware register value(s).

RAIL_TransitionTime_t#

RAIL_TransitionTime_t

(_SILICON_LABS_32B_SERIES_1_CONFIG == 1)

Suitable type for the supported transition time range.

RAIL_ApplyIrCalibration#

RAIL_Status_t RAIL_ApplyIrCalibration (RAIL_Handle_t railHandle, uint32_t imageRejection)

Apply a given image rejection calibration value.

Returns

• A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIr on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.

DeprecatedPlease use RAIL_ApplyIrCalibrationAlt instead.

RAIL_ApplyIrCalibrationAlt#

RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Apply a given image rejection calibration value.

Returns

• A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIrAlt on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. Note

• : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.

RAIL_CalibrateIr#

RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Run the image rejection calibration.

Returns

• A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image.

If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, it will return RAIL_STATUS_INVALID_STATE. In this case, RAIL_ApplyIrCalibration may be called to apply a previously determined IR calibration value, or the app must defer calibration until the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.

DeprecatedPlease use RAIL_CalibrateIrAlt instead.

RAIL_CalibrateIrAlt#

RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Run the image rejection calibration.

Returns

• A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image. Note

• : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.

RAIL_IEEE802154_CalibrateIr2p4Ghz#

RAIL_Status_t RAIL_IEEE802154_CalibrateIr2p4Ghz (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for IEEE 802.15.4 2.4 GHz.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

RAIL_IEEE802154_CalibrateIrSubGhz#

RAIL_Status_t RAIL_IEEE802154_CalibrateIrSubGhz (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for IEEE 802.15.4 915 MHz and 868 MHz.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

RAIL_BLE_CalibrateIr#

RAIL_Status_t RAIL_BLE_CalibrateIr (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for Bluetooth Low Energy.

Returns

• A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.

RAIL_CalibrateTemp#

RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)

Run the temperature calibration.

Returns

• A status code indicating success of the function call.

Run the temperature calibration, which needs to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.

RAIL_CalibrateHFXO#

RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t *crystalPPMError)

Performs HFXO compensation.

Returns

• A status code indicating the result of the function call.

Compute the PPM correction using the thermistor value available when RAIL_EVENT_THERMISTOR_DONE occurs, after RAIL_StartThermistorMeasurement() call. Then correct the RF frequency as well as Tx and Rx sampling.

This function calls the following RAIL functions in sequence saving having to call them individually:

• RAIL_ConvertThermistorImpedance()

• RAIL_ComputeHFXOPPMError()

• RAIL_CompensateHFXO()

Note

• This function makes the radio idle.

RAIL_ConfigRetimeOptions#

RAIL_Status_t RAIL_ConfigRetimeOptions (RAIL_Handle_t railHandle, RAIL_RetimeOptions_t mask, RAIL_RetimeOptions_t options)

Configure retiming options.

Returns

• Status code indicating success of the function call.

RAIL_GetRetimeOptions#

RAIL_Status_t RAIL_GetRetimeOptions (RAIL_Handle_t railHandle, RAIL_RetimeOptions_t *pOptions)

Get the currently configured retiming option.

Returns

• Status code indicating success of the function call.

RAIL_ChangedDcdc#

RAIL_Status_t RAIL_ChangedDcdc (void)

Indicate that the DCDC peripheral bus clock enable has changed allowing RAIL to react accordingly.

Note

• This should be called after DCDC has been enabled or disabled.

Returns

• Status code indicating success of the function call.