General#

Basic APIs to set up and interact with the RAIL library.

Modules#

RAIL_Version_t

RAILSched_Config_t

RAIL_Config_t

EFR32XG2X

Enumerations#

enum
RAIL_STATUS_NO_ERROR
RAIL_STATUS_INVALID_PARAMETER
RAIL_STATUS_INVALID_STATE
RAIL_STATUS_INVALID_CALL
RAIL_STATUS_SUSPENDED
RAIL_STATUS_SCHED_ERROR
}

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

Typedefs#

typedef void *

A generic handle to a particular radio (e.g.

typedef void(*
RAIL_InitCompleteCallbackPtr_t)(RAIL_Handle_t railHandle)

A pointer to init complete callback function.

typedef uint8_t

Provided for backwards compatibility.

Functions#

RAIL_GetVersion(RAIL_Version_t *version, bool verbose)

Get the version information for the compiled RAIL library.

RAIL_AddStateBuffer3(RAIL_Handle_t genericRailHandle)

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

RAIL_AddStateBuffer4(RAIL_Handle_t genericRailHandle)

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

RAIL_UseDma(uint8_t channel)

Allocate a DMA channel for RAIL to work with.

RAIL_Init(RAIL_Config_t *railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

bool

Get RAIL initialization status.

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

Collect entropy from the radio if available.

Macros#

#define
RAIL_EFR32_HANDLE ((RAIL_Handle_t)0xFFFFFFFFUL)

A placeholder for a radio-generic RAIL handle.

#define

A value to signal that RAIL should not use DMA.

Enumeration Documentation#

RAIL_Status_t#

RAIL_Status_t

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

Enumerator
RAIL_STATUS_NO_ERROR

RAIL function reports no error.

RAIL_STATUS_INVALID_PARAMETER

Call to RAIL function threw an error because of an invalid parameter.

RAIL_STATUS_INVALID_STATE

Call to RAIL function threw an error because it was called during an invalid radio state.

RAIL_STATUS_INVALID_CALL

RAIL function is called in an invalid order.

RAIL_STATUS_SUSPENDED

RAIL function did not finish in the allotted time.

RAIL_STATUS_SCHED_ERROR

RAIL function could not be scheduled by the Radio scheduler.


Definition at line 125 of file common/rail_types.h

Typedef Documentation#

RAIL_Handle_t#

RAIL_Handle_t

A generic handle to a particular radio (e.g.

RAIL_EFR32_HANDLE), or a real handle of a RAIL instance, 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.


Definition at line 108 of file common/rail_types.h

RAIL_InitCompleteCallbackPtr_t#

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

A pointer to init complete callback function.

Parameters
[in]railHandle

The initialized RAIL instance handle.


Definition at line 162 of file common/rail_types.h

RAIL_StateBuffer_t#

RAIL_StateBuffer_t [1]

Provided for backwards compatibility.


Definition at line 180 of file common/rail_types.h

Function Documentation#

RAIL_GetVersion#

RAIL_Status_t RAIL_GetVersion (RAIL_Version_t *version, bool verbose)

Get the version information for the compiled RAIL library.

Parameters
[out]version

A non-NULL pointer to RAIL_Version_t structure to populate with version information.

[in]verbose

Populate RAIL_Version_t struct with verbose information.

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.


Definition at line 83 of file common/rail.h

RAIL_AddStateBuffer3#

RAIL_Status_t RAIL_AddStateBuffer3 (RAIL_Handle_t genericRailHandle)

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

Parameters
[in]genericRailHandle

A generic RAIL instance handle.

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.


Definition at line 152 of file common/rail.h

RAIL_AddStateBuffer4#

RAIL_Status_t RAIL_AddStateBuffer4 (RAIL_Handle_t genericRailHandle)

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

Parameters
[in]genericRailHandle

A generic RAIL instance handle.

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.


Definition at line 162 of file common/rail.h

RAIL_UseDma#

RAIL_Status_t RAIL_UseDma (uint8_t channel)

Allocate a DMA channel for RAIL to work with.

Parameters
[in]channel

The DMA channel to use when copying memory. If a value of RAIL_DMA_INVALID is passed, RAIL will stop using any DMA channel.

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.


Definition at line 178 of file common/rail.h

RAIL_Init#

RAIL_Handle_t RAIL_Init (RAIL_Config_t *railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

Parameters
[inout]railCfg

The configuration and state structure for setting up the library, which contains memory and other options that RAIL needs. This structure must be allocated in application global read-write memory. RAIL may modify fields within or referenced by this structure during its operation.

[in]cb

A callback that notifies the application when the radio is finished 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 the callback fires, the radio is ready for additional configuration before transmit and receive operations.

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.


Definition at line 321 of file common/rail.h

RAIL_IsInitialized#

bool RAIL_IsInitialized (void)

Get RAIL initialization status.

Parameters
N/A

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.


Definition at line 333 of file common/rail.h

RAIL_GetRadioEntropy#

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

Collect entropy from the radio if available.

Parameters
[in]railHandle

A RAIL instance handle.

[out]buffer

A non-NULL pointer to the buffer to write the collected entropy.

[in]bytes

The number of bytes to fill in the input buffer.

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.


Definition at line 353 of file common/rail.h

Macro Definition Documentation#

RAIL_EFR32_HANDLE#

#define RAIL_EFR32_HANDLE
Value:
((RAIL_Handle_t)0xFFFFFFFFUL)

A placeholder for a radio-generic 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.


Definition at line 118 of file common/rail_types.h

RAIL_DMA_INVALID#

#define RAIL_DMA_INVALID
Value:
(0xFFU)

A value to signal that RAIL should not use DMA.


Definition at line 165 of file common/rail_types.h