General#

RAIL_Handle_t#

RAIL_Handle_t

A radio-generic handle (e.g., RAIL_EFR32_HANDLE), or a real RAIL instance handle as returned from RAIL_Init().

Generic handles should be used for certain RAIL APIs that are called prior to RAIL initialization. However, once RAIL has been initialized, the real handle returned by RAIL_Init() should be used instead.

DeprecatedRAIL 2.x synonym of sl_rail_handle_t.

RAIL_Status_t#

RAIL_Status_t

A status returned by many RAIL API calls indicating their success or failure.

It is a subset of sl_status_t.

DeprecatedRAIL 2.x synonym of sl_rail_status_t.

RAIL_InitCompleteCallbackPtr_t#

typedef void(* RAIL_InitCompleteCallbackPtr_t) (RAIL_Handle_t railHandle) )(RAIL_Handle_t railHandle)

A pointer to an initialization complete callback function.

DeprecatedRAIL 2.x synonym of sl_rail_init_complete_callback_t().

RAIL_StateBuffer_t#

RAIL_StateBuffer_t [1]

Provided for backwards compatibility.

DeprecatedRAIL 2.x synonym of sl_rail_opaque_value_t.

sl_rail_handle_t#

sl_rail_handle_t

A radio-generic handle (e.g., SL_RAIL_EFR32_HANDLE), or a real RAIL instance handle as returned from sl_rail_init().

Generic-radio handles must be used for certain RAIL APIs that are called prior to RAIL initialization. However, once RAIL has been initialized, the real handle returned by sl_rail_init() should be used instead.

sl_rail_status_t#

sl_rail_status_t

A status returned by many RAIL API calls indicating their success or failure.

It is a subset of sl_status_t.

sl_rail_init_complete_callback_t#

typedef void(* sl_rail_init_complete_callback_t) (sl_rail_handle_t rail_handle) )(sl_rail_handle_t rail_handle)

A pointer to an initialization complete callback function.

sl_rail_opaque_value_t#

sl_rail_opaque_value_t [1]

An opaque type not examined by RAIL; can be used for application- specific purposes.

sl_rail_events_callback_t#

typedef void(* sl_rail_events_callback_t) (sl_rail_handle_t rail_handle, sl_rail_events_t events) )(sl_rail_handle_t rail_handle, sl_rail_events_t events)

A pointer to the callback called when some RAIL event(s) occur.

RAIL_GetVersion#

RAIL_Status_t RAIL_GetVersion (RAIL_Version_t * version, bool verbose)

Get the version information for the compiled RAIL library.

Returns

• Status code indicating success of the function call.

The version information contains a major version number, a minor version number, and a rev (revision) number.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_version() with fewer parameters and always returns verbose information.

RAIL_AddStateBuffer3#

RAIL_Status_t RAIL_AddStateBuffer3 (RAIL_Handle_t genericRailHandle)

Add a 3rd multiprotocol internal state buffer for use by RAIL_Init().

Returns

• Status code indicating success of the function call. An error is returned if the 3rd state buffer was previously added or this isn't the RAIL multiprotocol library.

DeprecatedRAIL 2.x synonym of sl_rail_add_state_buffer_3().

RAIL_AddStateBuffer4#

RAIL_Status_t RAIL_AddStateBuffer4 (RAIL_Handle_t genericRailHandle)

Add a 4th multiprotocol internal state buffer for use by RAIL_Init().

Returns

• Status code indicating success of the function call. An error is returned if the 4th state buffer was previously added. or this isn't the RAIL multiprotocol library.

DeprecatedRAIL 2.x synonym of sl_rail_add_state_buffer_4().

RAIL_UseDma#

RAIL_Status_t RAIL_UseDma (uint8_t channel)

Allocate a DMA channel for RAIL to work with.

Returns

• Status code indicating success of the function call.

To use this API, the application must initialize the DMA engine on the chip and allocate a DMA channel. This channel will be used periodically to copy memory more efficiently. Call this function before RAIL_Init() to have the most benefit. If the application needs to take back control of the DMA channel that RAIL is using, this API may be called with a channel of RAIL_DMA_INVALID to tell RAIL to stop using DMA.

Warnings

• To allocate and use a DMA channel for RAIL to work with when TrustZone is enabled and LDMA is configured as secure peripheral, the secure application must initialize the DMA engine and call this API. The non-secure application must provide a non-NULL RAIL_TZ_Config_t::radioPerformM2mLdmaCallback to RAIL_TZ_InitNonSecure(). To take back control of the DMA channel when TrustZone is enabled and LDMA is configured as secure peripheral, the secure application must call this API with a channel of RAIL_DMA_INVALID. The non-secure application must provide a NULL RAIL_TZ_Config_t::radioPerformM2mLdmaCallback to RAIL_TZ_InitNonSecure().

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_use_dma() with additional sl_rail_handle_t parameter.

RAIL_CopyDeviceInfo#

RAIL_Status_t RAIL_CopyDeviceInfo (RAIL_Handle_t genericRailHandle)

Reads out device specific data that may be needed by RAIL and populates appropriate data structures in the library.

Returns

• Status code indicating success of the function call.

Note

• This function must be called before calling RAIL_Init() on any platforms that require this data and should not be called inside a critical section. This function does nothing on EFR32 Series 2 devices.

DeprecatedRAIL 2.x synonym of sl_rail_copy_device_info().

RAIL_Init#

RAIL_Handle_t RAIL_Init (const RAIL_Config_t * railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

Returns

• Handle for initialized rail instance or NULL if an invalid value was passed in the railCfg.

Note

• Call this function only once per protocol. If called again, it will do nothing and return NULL. RAIL_CopyDeviceInfo() should be called once before calling this function for Silicon Labs Series 3 devices.

• The first call to RAIL_Init() implicitly enables PTI, but it won't take effect unless or until RAIL_ConfigPti() has been called with a mode other than the default RAIL_PTI_MODE_DISABLED.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_init() with different parameters, return value, and functionality allowing per-protocol configuration of Rx FIFO and Rx Packet Queue (formerly hidden in RAIL 2.x and shared across all protocols in multiprotocol applications), in addition to configuring the Tx FIFO. See sl_rail_config_t.

RAIL_IsInitialized#

bool RAIL_IsInitialized (void )

Get RAIL initialization status.

Returns

• true if the radio has finished initializing and false otherwise.

RAIL APIs, e.g., RAIL_GetTime(), which work only if RAIL_Init() has been called, can use RAIL_IsInitialized() to determine whether RAIL has been initialized or not.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_is_initialized() with additional sl_rail_handle_t parameter.

RAIL_GetRadioEntropy#

uint16_t RAIL_GetRadioEntropy (RAIL_Handle_t railHandle, uint8_t * buffer, uint16_t bytes)

Collect entropy from the radio if available.

Returns

• The number of bytes of entropy collected. For radios that don't support entropy collection, the function returns 0. Values less than the requested amount may also be returned on platforms that use entropy pools to collect random data periodically.

Attempts to fill the provided buffer with the requested number of bytes of entropy. If the requested number of bytes can't be provided, as many bytes as possible will be filled and returned. For radios that do not support this function, 0 bytes are always returned. For information about the specific mechanism for gathering entropy, see documentation for the chip family.

DeprecatedRAIL 2.x synonym of sl_rail_get_radio_entropy().

sl_rail_get_version#

sl_rail_status_t sl_rail_get_version (sl_rail_version_t * p_version)

Get the version information for the compiled RAIL library.

Returns

• Status code indicating success of the function call.

The p_version information contains a major version number, a minor version number, a rev (revision) number, and some supplemental build details.

sl_rail_add_state_buffer_3#

sl_rail_status_t sl_rail_add_state_buffer_3 (sl_rail_handle_t radio_handle)

Add a 3rd multiprotocol internal state buffer for use by sl_rail_init().

Returns

• Status code indicating success of the function call. An error is returned if the 3rd state buffer was previously added or this isn't the RAIL multiprotocol library.

sl_rail_add_state_buffer_4#

sl_rail_status_t sl_rail_add_state_buffer_4 (sl_rail_handle_t radio_handle)

Add a 4th multiprotocol internal state buffer for use by sl_rail_init().

Returns

• Status code indicating success of the function call. An error is returned if the 4th state buffer was previously added. or this isn't the RAIL multiprotocol library.

sl_rail_use_dma#

sl_rail_status_t sl_rail_use_dma (sl_rail_handle_t rail_handle, uint8_t dma_channel)

Allocate a DMA channel for RAIL to work with.

Returns

• Status code indicating success of the function call.

To use this API, the application must initialize the DMA engine on the chip and allocate a DMA channel. This channel will be used periodically to copy memory more efficiently. Call this function before sl_rail_init() to have the most benefit. If the application needs to take back control of the DMA channel that RAIL is using, this API may be called with a channel of SL_RAIL_DMA_INVALID to tell RAIL to stop using DMA.

Warnings

• To allocate and use a DMA channel for RAIL to work with when TrustZone is enabled and LDMA is configured as secure peripheral, the secure application must initialize the DMA engine and call this API. The non-secure application must provide a non-NULL sl_rail_tz_config_t::radio_perform_m2m_ldma_callback to sl_rail_tz_init_non_secure(). To take back control of the DMA channel when TrustZone is enabled and LDMA is configured as secure peripheral, the secure application must call this API with a channel of SL_RAIL_DMA_INVALID. The non-secure application must provide a NULL sl_rail_tz_config_t::radio_perform_m2m_ldma_callback to sl_rail_tz_init_non_secure().

sl_rail_copy_device_info#

sl_rail_status_t sl_rail_copy_device_info (sl_rail_handle_t radio_handle)

Reads out device specific data that may be needed by RAIL and populates appropriate data structures in the library.

Returns

• Status code indicating success of the function call.

Note

• This function must be called before calling sl_rail_init() on any platforms that require this data and should not be called inside a critical section. This function does nothing on EFR32 Series 2 devices.

sl_rail_init#

sl_rail_status_t sl_rail_init (sl_rail_handle_t * p_rail_handle, const sl_rail_config_t * p_rail_config, sl_rail_init_complete_callback_t init_complete_callback)

Initialize RAIL.

Returns

• Status code indicating success of the function call.

Note

• Call this function only once per protocol. If called again, it will do nothing and return SL_RAIL_STATUS_INVALID_STATE. sl_rail_copy_device_info() should be called once before calling this function for Silicon Labs Series 3 devices.

• The first call to sl_rail_init() implicitly enables PTI, but it won't take effect unless or until sl_rail_config_pti() has been called with a mode other than the default SL_RAIL_PTI_MODE_DISABLED.

sl_rail_is_initialized#

bool sl_rail_is_initialized (sl_rail_handle_t rail_handle)

Get RAIL initialization status.

Returns

• true if the radio has finished initializing and false otherwise.

RAIL APIs, e.g., sl_rail_get_time(), which work only if sl_rail_init() has been called, can use sl_rail_is_initialized() to determine whether RAIL has been initialized or not.

sl_rail_get_config#

const sl_rail_config_t * sl_rail_get_config (sl_rail_handle_t rail_handle)

Get the sl_rail_config_t pointer associated with a sl_rail_handle_t.

Returns

• The pointer to the sl_rail_config_t associated with the RAIL instance handle, or NULL if the handle is not a valid instance provided by a sl_rail_init() call.

Applications can read but must not change any sl_rail_config_t fields using the returned pointer.

sl_rail_get_radio_entropy#

uint16_t sl_rail_get_radio_entropy (sl_rail_handle_t rail_handle, uint8_t * p_buffer, uint16_t bytes)

Collect entropy from the radio if available.

Returns

• The number of bytes of entropy collected. For radios that don't support entropy collection, the function returns 0. Values less than the requested amount may also be returned on platforms that use entropy pools to collect random data periodically.

Attempts to fill the provided buffer with the requested number of bytes of entropy. If the requested number of bytes can't be provided, as many bytes as possible will be filled and returned. For radios that do not support this function, 0 bytes are always returned. For information about the specific mechanism for gathering entropy, see documentation for the chip family.

This function returns 0 if a radio configuration is not loaded. If a channel is not set then this function sets the first channel in the loaded configuration implicitly. If the implicit channel setting fails, the function returns 0.

Returns 0 if no receive FIFO or Packet Queue have been configured.