Data Management#

Data management functions.

These functions allow the application to choose how data is presented to the application. RAIL provides data in a packet-based method or in a FIFO-based method. As originally conceived, RAIL_DataMethod_t::PACKET_MODE was designed for handling packets that fit within RAIL's FIFOs while RAIL_DataMethod_t::FIFO_MODE was designed for handling packets larger than RAIL's FIFOs could hold. Conceptually it is still useful to think of these modes this way, but functionally their distinction has become blurred by improvements in RAIL's flexibility – applications now have much more control over both receive and transmit FIFO sizes, and the FIFO-management and threshold APIs and related events are no longer restricted to RAIL_DataMethod_t::FIFO_MODE operation but can be used in RAIL_DataMethod_t::PACKET_MODE too.

The application can configure RAIL data management through RAIL_ConfigData(). This function allows the application to specify the type of radio data (RAIL_TxDataSource_t and RAIL_RxDataSource_t) and the method of interacting with data (RAIL_DataMethod_t). By default, RAIL configures TX and RX both with packet data source and RAIL_DataMethod_t::PACKET_MODE.

For transmit, RAIL_DataMethod_t::PACKET_MODE and RAIL_DataMethod_t::FIFO_MODE are functionally the same:

The transmit FIFO is specified by the application and its size is the value returned from the most recent call to RAIL_SetTxFifo(). The transmit FIFO is edge-based in that it only provides the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event once when the threshold is crossed in the emptying direction.

For receive, the distinction between RAIL_DataMethod_t::PACKET_MODE and RAIL_DataMethod_t::FIFO_MODE basically boils down to how unsuccessfully-received packets are handled. In RAIL_DataMethod_t::PACKET_MODE, data from such packets is automatically rolled back as if the packet was never received, while in RAIL_DataMethod_t::FIFO_MODE, rollback does not occur putting more onus on the application to deal with that data.

In receive RAIL_DataMethod_t::PACKET_MODE data management:

In receive RAIL_DataMethod_t::FIFO_MODE data management:

  • Packet Lengths are determined from the Radio Configurator configuration or by application knowledge of packet payload structure.

  • Received data can be retrieved prior to packet completion through RAIL_ReadRxFifo() and is never rolled back on Filtered, Aborted, or FrameError packets. The application should enable and handle these events so it can flush any packet data it's already retrieved.

  • After packet completion, remaining packet data for Filtered, Aborted, or FrameError packets remains in the FIFO and the appropriate event is triggered to the user. This data may be consumed in the callback unlike in packet mode where it is automatically rolled back. At the end of the callback all remaining data in the FIFO will be cleaned up as usual. Keep in mind that RAIL_GetRxPacketDetailsAlt() provides packet detailed information only for successfully received packets.

Common receive data management features:

When trying to determine an appropriate threshold, the application needs to know the size of each FIFO. The default receive FIFO is internal to RAIL with a size of 512 bytes. This can be changed, however, using RAIL_SetRxFifo() and the default may be removed entirely by calling this from the RAILCb_SetupRxFifo() callback. The receive FIFO event is level-based in that the RAIL_EVENT_RX_FIFO_ALMOST_FULL event will constantly pend if the threshold is exceeded. This normally means that inside this event's callback, the application should empty enough of the FIFO to go under the threshold. To defer reading the FIFO to main context, the application can disable or re-enable the receive FIFO threshold event using RAIL_ConfigEvents() with the mask RAIL_EVENT_RX_FIFO_ALMOST_FULL.

The receive FIFO can store multiple packets and processing of a packet can be deferred from the RAIL event callback to main-loop processing by using RAIL_HoldRxPacket() in the event callback and RAIL_ReleaseRxPacket() in the main-loop. On some platforms, the receive FIFO is supplemented by an internal fixed-size packet metadata FIFO that limits the number of packets RAIL and applications can hold onto for deferred processing. See chip-specific documentation, such as EFR32, for more information. Note that when using multiprotocol the receive FIFO is reset prior to a protocol switch so held packets will be lost if not processed before then.

While RAIL_EVENT_RX_FIFO_ALMOST_FULL occurs solely based on the state of the receive FIFO used for packet data, both RAIL_EVENT_RX_FIFO_FULL and RAIL_EVENT_RX_FIFO_OVERFLOW can occur coincident with packet completion when either that or the internal packet metadata FIFO fills or overflows. RAIL_EVENT_RX_FIFO_FULL informs the application it should immediately process and free up the oldest packets/data to make room for new packets/data, reducing the possibility of packet/data loss and RAIL_EVENT_RX_FIFO_OVERFLOW.

Before a packet is fully received you can always use RAIL_PeekRxPacket() to look at the contents. In FIFO mode, you may also consume its data with RAIL_ReadRxFifo(). Remember that none of these APIs will read across a packet boundary (even in FIFO mode) so you will need to handle each received packet individually.

While RAIL defaults to RAIL_DataMethod_t::PACKET_MODE, the application can explicitly initialize RAIL for RAIL_DataMethod_t::PACKET_MODE in the following manner:

extern RAIL_Handle_t railHandle;
static const RAIL_DataConfig_t railDataConfig = {
  .txSource = TX_PACKET_DATA,
  .rxSource = RX_PACKET_DATA,
  .txMethod = PACKET_MODE,
  .rxMethod = PACKET_MODE,
};

status = RAIL_ConfigData(railHandle, &railDataConfig);

// Events that can occur in Packet Mode:
//    RAIL_EVENT_TX_PACKET_SENT
//    RAIL_EVENT_RX_PACKET_RECEIVED
// and optionally (packet data automatically dropped):
//    RAIL_EVENT_RX_ADDRESS_FILTERED
//    RAIL_EVENT_RX_PACKET_ABORTED
//    RAIL_EVENT_RX_FRAME_ERROR
// and if enabled:
//   RAIL_EVENT_TX_UNDERFLOW
//   RAIL_EVENT_TXACK_UNDERFLOW
//   RAIL_EVENT_TX_FIFO_ALMOST_EMPTY
//   RAIL_EVENT_RX_FIFO_ALMOST_FULL

Initializing RAIL for RAIL_DataMethod_t::FIFO_MODE requires a few more function calls:

extern RAIL_Handle_t railHandle;
static const RAIL_DataConfig_t railDataConfig = {
  .txSource = TX_PACKET_DATA,
  .rxSource = RX_PACKET_DATA,
  .txMethod = FIFO_MODE,
  .rxMethod = FIFO_MODE,
};

status = RAIL_ConfigData(railHandle, &railDataConfig);

// Gets the size of the FIFOs.
// Assume that the transmit and receive FIFOs are the same size
uint16_t fifoSize = RAIL_GetTxFifoSpaceAvailable(railHandle);

// Sets the transmit and receive FIFO thresholds.
// For this example, set the threshold in the middle of each FIFO.
RAIL_SetRxFifoThreshold(railHandle, fifoSize / 2);
RAIL_SetTxFifoThreshold(railHandle, fifoSize / 2);

// Events that can occur in FIFO mode:
//   RAIL_EVENT_TX_FIFO_ALMOST_EMPTY
//   RAIL_EVENT_TX_UNDERFLOW
//   RAIL_EVENT_TXACK_UNDERFLOW
//   RAIL_EVENT_TX_PACKET_SENT
//   RAIL_EVENT_RX_FIFO_ALMOST_FULL
//   RAIL_EVENT_RX_FIFO_OVERFLOW
//   RAIL_EVENT_RX_ADDRESS_FILTERED
//   RAIL_EVENT_RX_PACKET_ABORTED
//   RAIL_EVENT_RX_FRAME_ERROR
//   RAIL_EVENT_RX_PACKET_RECEIVED

On receive, an application can use a different RAIL_RxDataSource_t that is only compatible with RAIL_DataMethod_t::FIFO_MODE. 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 the CPU processing time. The sample rate depends on the chosen PHY, as determined by the data rate and the decimation chain. It is not recommended to use the IQ data source with sample rates above 300 k samples/second because the CPU might not be able to keep up with the data stream. Depending on the application and the needed CPU bandwidth, slower data rates may be required. On EFR32xG22 and later platforms, it is recommended to reset the RX buffer before initiating a receive for all modes except RAIL_RxDataSource_t::RX_PACKET_DATA since the RX buffer has to be 32-bit aligned. If the buffer is not reset but is 32-bit aligned, capture is performed on the remaining space available. If the buffer is not reset and is not 32-bit aligned, then RAIL_ConfigData() returns RAIL_STATUS_INVALID_STATE.

// Reset RX buffer (EFR32xG22 and later platforms)
RAIL_ResetFifo(railHandle, false, true);

// 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,
};

// IQ data comes in the following format when reading out of the FIFO:
//------------------------------------
// I[LSB] | I[MSB] | Q[LSB] | Q[MSB] |
//------------------------------------

Modules#

RAIL_DataConfig_t

Enumerations#

enum
TX_PACKET_DATA
TX_MFM_DATA
RAIL_TX_DATA_SOURCE_COUNT
}

Transmit data sources supported by RAIL.

enum
RX_PACKET_DATA
RX_DEMOD_DATA
RX_IQDATA_FILTLSB
RX_IQDATA_FILTMSB
RX_DIRECT_MODE_DATA
RX_DIRECT_SYNCHRONOUS_MODE_DATA
RAIL_RX_DATA_SOURCE_COUNT
}

Receive data sources supported by RAIL.

enum
PACKET_MODE
FIFO_MODE
RAIL_DATA_METHOD_COUNT
}

Methods for the application to provide and retrieve data from RAIL.

Functions#

RAIL_ConfigData(RAIL_Handle_t railHandle, const RAIL_DataConfig_t *dataConfig)

RAIL data management configuration.

uint16_t
RAIL_WriteTxFifo(RAIL_Handle_t railHandle, const uint8_t *dataPtr, uint16_t writeLength, bool reset)

Write data to the transmit FIFO previously established by RAIL_SetTxFifo().

uint16_t
RAIL_SetTxFifo(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data.

uint16_t
RAIL_SetTxFifoAlt(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t startOffset, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data which can start at offset distance from the FIFO base address.

RAIL_SetRxFifo(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t *size)

Set the address of the receive FIFO, a circular buffer used for RX data.

RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)

Set up the receive FIFO to use.

uint16_t
RAIL_ReadRxFifo(RAIL_Handle_t railHandle, uint8_t *dataPtr, uint16_t readLength)

Read packet data from RAIL's internal receive FIFO.

uint16_t
RAIL_SetTxFifoThreshold(RAIL_Handle_t railHandle, uint16_t txThreshold)

Configure the RAIL transmit FIFO almost empty threshold.

uint16_t
RAIL_SetRxFifoThreshold(RAIL_Handle_t railHandle, uint16_t rxThreshold)

Configure the RAIL receive FIFO almost full threshold.

uint16_t
RAIL_GetTxFifoThreshold(RAIL_Handle_t railHandle)

Get the RAIL transmit FIFO almost empty threshold value.

uint16_t
RAIL_GetRxFifoThreshold(RAIL_Handle_t railHandle)

Get the RAIL receive FIFO almost full threshold value.

void
RAIL_ResetFifo(RAIL_Handle_t railHandle, bool txFifo, bool rxFifo)

Reset the RAIL transmit and/or receive FIFOs.

uint16_t
RAIL_GetRxFifoBytesAvailable(RAIL_Handle_t railHandle)

Get the number of bytes used in the receive FIFO.

uint16_t
RAIL_GetTxFifoSpaceAvailable(RAIL_Handle_t railHandle)

Get the number of bytes unused in the transmit FIFO.

Macros#

#define

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

#define
RAIL_FIFO_ALIGNMENT (sizeof(RAIL_FIFO_ALIGNMENT_TYPE))

Alignment that is needed for the RX and TX FIFOs.

#define

A FIFO threshold value that disables the threshold.

Enumeration Documentation#

RAIL_TxDataSource_t#

RAIL_TxDataSource_t

Transmit data sources supported by RAIL.

Enumerator
TX_PACKET_DATA

Uses the frame hardware to packetize data.

TX_MFM_DATA

Uses the multi-level frequency modulation data.

RAIL_TX_DATA_SOURCE_COUNT

A count of the choices in this enumeration.


Definition at line 2470 of file common/rail_types.h

RAIL_RxDataSource_t#

RAIL_RxDataSource_t

Receive data sources supported by RAIL.

Note

Enumerator
RX_PACKET_DATA

Uses the frame hardware to packetize data.

RX_DEMOD_DATA

Gets 8-bit data output from the demodulator.

RX_IQDATA_FILTLSB

Gets lower 16 bits of I/Q data provided to the demodulator.

RX_IQDATA_FILTMSB

Gets highest 16 bits of I/Q data provided to the demodulator.

RX_DIRECT_MODE_DATA

Gets RX direct mode data output from the demodulator.

RX_DIRECT_SYNCHRONOUS_MODE_DATA

Gets synchronous RX direct mode data output from the demodulator.

RAIL_RX_DATA_SOURCE_COUNT

A count of the choices in this enumeration.


Definition at line 2497 of file common/rail_types.h

RAIL_DataMethod_t#

RAIL_DataMethod_t

Methods for the application to provide and retrieve data from RAIL.

For Transmit the distinction between RAIL_DataMethod_t::PACKET_MODE and RAIL_DataMethod_t::FIFO_MODE has become more cosmetic than functional, as the RAIL_WriteTxFifo() and RAIL_SetTxFifoThreshold() APIs and related RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event can be used in either mode. For Receive the distinction is functionally important because in RAIL_DataMethod_t::PACKET_MODE rollback occurs automatically for unsuccessfully-received packets (RAIL_RxPacketStatus_t ABORT statuses), flushing their data. In RAIL_DataMethod_t::FIFO_MODE rollback is prevented, leaving the data from unsuccessfully-received packets in the receive FIFO for the application to deal with. This allows for packets larger than the receive FIFO size where automatic rollback would corrupt the receive FIFO.

Enumerator
PACKET_MODE

Packet-based data method.

FIFO_MODE

FIFO-based data method.

RAIL_DATA_METHOD_COUNT

A count of the choices in this enumeration.


Definition at line 2553 of file common/rail_types.h

Function Documentation#

RAIL_ConfigData#

RAIL_Status_t RAIL_ConfigData (RAIL_Handle_t railHandle, const RAIL_DataConfig_t * dataConfig)

RAIL data management configuration.

Parameters
[in]railHandle

A RAIL instance handle.

[in]dataConfig

RAIL data configuration structure.

Returns

  • Status code indicating success of the function call.

This function configures how RAIL manages data. The application can configure RAIL to receive data in a packet-based or FIFO-based manner. RAIL_DataMethod_t::FIFO_MODE is necessary to receive packets larger than the radio's receive FIFO. It is also required for receive data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.

Generally with RAIL_DataMethod_t::FIFO_MODE, the application sets appropriate FIFO thresholds via RAIL_SetTxFifoThreshold() and RAIL_SetRxFifoThreshold() and then enables and handles the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event callback (to feed more packet data via RAIL_WriteTxFifo() before the FIFO underflows) and the RAIL_EVENT_RX_FIFO_ALMOST_FULL event callback (to consume packet data via RAIL_ReadRxFifo() before the receive FIFO overflows).

When configuring TX for RAIL_DataMethod_t::FIFO_MODE, this function resets the transmit FIFO. When configuring TX or RX for RAIL_DataMethod_t::PACKET_MODE, this function will reset the corresponding FIFO thresholds such that they won't trigger the RAIL_EVENT_RX_FIFO_ALMOST_FULL or RAIL_EVENT_TX_FIFO_ALMOST_EMPTY events.

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::FIFO_MODE, the radio won't drop packet data of aborted or CRC error packets, but will present it to the application to deal with accordingly. On completion of erroneous packets, the RAIL_Config_t::eventsCallback with RAIL_EVENT_RX_PACKET_ABORTED, RAIL_EVENT_RX_FRAME_ERROR, or RAIL_EVENT_RX_ADDRESS_FILTERED will tell the application it can drop any data it read via RAIL_ReadRxFifo() during reception. For CRC error packets when the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option is in effect, the application should check for that from the RAIL_RxPacketStatus_t obtained by calling RAIL_GetRxPacketInfo(). RAIL will automatically flush any remaining packet data after reporting one of these packet completion events or the application can explicitly flush it by calling RAIL_ReleaseRxPacket().

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::PACKET_MODE, the radio will roll back (drop) all packet data associated with aborted packets including those with CRC errors (unless configured to ignore CRC errors via the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option). The application will never have to deal with packet data from these packets. In either mode, the application can set RX options as needed.

When RAIL_DataConfig_t::rxSource is set to a value other than RX_PACKET_DATA and RAIL_Config_t::eventsCallbackRAIL_EVENT_RX_FIFO_OVERFLOW is enabled RX will be terminated if a RX FIFO overflow occurs. If RAIL_EVENT_RX_FIFO_OVERFLOW is not enabled, data will be discarded until the overflow condition is resolved. To continue capturing data RX must be restarted using RAIL_StartRx().


Definition at line 1899 of file common/rail.h

RAIL_WriteTxFifo#

uint16_t RAIL_WriteTxFifo (RAIL_Handle_t railHandle, const uint8_t * dataPtr, uint16_t writeLength, bool reset)

Write data to the transmit FIFO previously established by RAIL_SetTxFifo().

Parameters
[in]railHandle

A RAIL instance handle.

[in]dataPtr

An application-provided pointer to transmit data.

[in]writeLength

A number of bytes to write to the transmit FIFO.

[in]reset

If true, resets transmit FIFO before writing the data.

Returns

  • The number of bytes written to the transmit FIFO.

This function reads data from the provided dataPtr and writes it to the transmit FIFO that was previously established by RAIL_SetTxFifo(). If the requested writeLength exceeds the current number of bytes open in the transmit FIFO, the function only writes until the transmit FIFO is full. The function returns the number of bytes written to the transmit FIFO or returns zero if railHandle is NULL or if the transmit FIFO is full.

Note

  • The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the writeLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes, which the packet configuration causes to be sent automatically.

  • This function does not create a critical section but, depending on the application, a critical section could be appropriate.


Definition at line 1934 of file common/rail.h

RAIL_SetTxFifo#

uint16_t RAIL_SetTxFifo (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

An appropriately-aligned (see below) pointer to a read-write memory location in RAM used as the transmit FIFO. This memory must persist until the next call to this function or RAIL_SetTxFifoAlt.

[in]initLength

A number of initial bytes already in the transmit FIFO.

[in]size

A desired size of the transmit FIFO in bytes.

Returns

  • Returns the FIFO size in bytes, 0 if an error occurs.

This function sets the memory location for the transmit FIFO. RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size, in that case 0 is returned. If the initLength parameter is larger than the returned size, the FIFO will be filled up to its size.

A user may write to the custom memory location directly before calling this function, or use RAIL_WriteTxFifo to write to the memory location after calling this function. Users must specify the initLength for previously-written memory to be set in the transmit FIFO.

This function reserves the block of RAM starting at addr with a length of the returned FIFO size, which is used internally as a circular buffer for the transmit FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via calls to RAIL_WriteTxFifo) until the next call to this function.

Note

  • The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the initLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes which the packet configuration causes to be sent automatically.


Definition at line 1988 of file common/rail.h

RAIL_SetTxFifoAlt#

uint16_t RAIL_SetTxFifoAlt (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t startOffset, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data which can start at offset distance from the FIFO base address.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

An appropriately-aligned (see RAIL_SetTxFifo description) pointer to a read-write memory location in RAM used as the transmit FIFO. This memory must persist until the next call to this function or RAIL_SetTxFifo.

[in]startOffset

A number of bytes defining the start position of the TX data from the transmit FIFO base address, only valid if initLength is not 0.

[in]initLength

The number of valid bytes already in the transmit FIFO after startOffset.

[in]size

A desired size of the transmit FIFO in bytes.

Returns

  • Returns the FIFO size in bytes, 0 if an error occurs.

This function is similar to RAIL_SetTxFifo except a startOffset can be specified to indicate where the transmit packet data starts. This allows an application to place unaligned initial packet data within the aligned transmit FIFO (initLength > 0). Specifying a startOffset will not reduce the FIFO threshold or affect RAIL_GetTxFifoSpaceAvailable(). RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur. FIFO size handling is quite same as RAIL_SetTxFifo. Only difference is that if the initLength plus startOffset parameters are larger than the returned size, the FIFO will be filled up to its size from startOffset. Note that the startOffset is essentially forgotten after the next transmit – i.e. it applies onto to the next transmit operation, and is not re-established when the transmit FIFO is reset.


Definition at line 2021 of file common/rail.h

RAIL_SetRxFifo#

RAIL_Status_t RAIL_SetRxFifo (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t * size)

Set the address of the receive FIFO, a circular buffer used for RX data.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

A pointer to a read-write memory location in RAM used as the receive FIFO. This memory must persist until the next call to this function.

[inout]size

A desired size of the receive FIFO in bytes. This will be populated with the actual size during the function call.

Returns

  • Status code indicating success of the function call.

This function sets the memory location for the receive FIFO. It must be called at least once before any receive operations occur.

Note

  • After it is called, any prior receive FIFO is orphaned. To avoid orphaning the default internal 512-byte receive FIFO so it does not unnecessarily consume RAM resources in your application, implement RAILCb_SetupRxFifo() to call this function.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size.

This function reserves the block of RAM starting at addr with a length of size, which is used internally as a circular buffer for the receive FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via incoming packet data being written) until the next call to this function.

In multiprotocol, RAIL currently shares one receive FIFO across all protocols. This function will return RAIL_STATUS_INVALID_STATE if the requested RAIL_Handle_t is not active.


Definition at line 2064 of file common/rail.h

RAILCb_SetupRxFifo#

RAIL_Status_t RAILCb_SetupRxFifo (RAIL_Handle_t railHandle)

Set up the receive FIFO to use.

Parameters
[in]railHandle

A RAIL instance handle.

This function is optional to implement.

Returns

  • Status code indicating success of the function call.

This function is called during the RAIL_Init process to set up the FIFO to use for received packets. If not implemented by the application, a default implementation from within the RAIL library will be used to initialize an internal default 512-byte receive FIFO.

If this function returns an error, the RAIL_Init process will fail.

During this function, the application should generally call RAIL_SetRxFifo. If that does not happen, the application needs to set up the receive FIFO via a call to RAIL_SetRxFifo before attempting to receive any packets. An example implementation may look like the following:

#define RX_FIFO_SIZE 1024
static uint8_t rxFifo[RX_FIFO_SIZE];

RAIL_Status_t RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)
{
  uint16_t rxFifoSize = RX_FIFO_SIZE;
  RAIL_Status_t status = RAIL_SetRxFifo(railHandle, &rxFifo[0], &rxFifoSize);
  if (rxFifoSize != RX_FIFO_SIZE) {
    // We set up an incorrect FIFO size
    return RAIL_STATUS_INVALID_PARAMETER;
  }
  if (status == RAIL_STATUS_INVALID_STATE) {
    // Allow failures due to multiprotocol
    return RAIL_STATUS_NO_ERROR;
  }
  return status;
}

Definition at line 2103 of file common/rail.h

RAIL_ReadRxFifo#

uint16_t RAIL_ReadRxFifo (RAIL_Handle_t railHandle, uint8_t * dataPtr, uint16_t readLength)

Read packet data from RAIL's internal receive FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

[out]dataPtr

An application-provided pointer to store data. If NULL, the data is thrown away rather than copied out.

[in]readLength

A number of packet bytes to read from the FIFO.

Returns

  • The number of packet bytes read from the receive FIFO.

This function reads packet data from the head of receive FIFO and writes it to the provided dataPtr. It does not permit reading more data than is available in the FIFO, nor does it permit reading more data than remains in the oldest unreleased packet.

Because this function does not have a critical section, use it only in one context or make sure function calls are protected to prevent buffer corruption.

Warnings

Note

  • When reading data from an arriving packet that is not yet complete, keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the receive FIFO could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid reading this info because it will corrupt the packet's details and possibly corrupt the receive FIFO.


Definition at line 2140 of file common/rail.h

RAIL_SetTxFifoThreshold#

uint16_t RAIL_SetTxFifoThreshold (RAIL_Handle_t railHandle, uint16_t txThreshold)

Configure the RAIL transmit FIFO almost empty threshold.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txThreshold

The threshold below which the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event will fire.

Returns

  • Configured transmit FIFO threshold value.

This function configures the threshold for the transmit FIFO. When the number of bytes in the transmit FIFO falls below the configured threshold, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_TX_FIFO_ALMOST_EMPTY set. The txThreshold value should be smaller than or equal to the transmit FIFO size; higher values will be pegged to the FIFO size. A value of 0 or RAIL_FIFO_THRESHOLD_DISABLED will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.


Definition at line 2161 of file common/rail.h

RAIL_SetRxFifoThreshold#

uint16_t RAIL_SetRxFifoThreshold (RAIL_Handle_t railHandle, uint16_t rxThreshold)

Configure the RAIL receive FIFO almost full threshold.

Parameters
[in]railHandle

A RAIL instance handle.

[in]rxThreshold

The threshold above which the RAIL_EVENT_RX_FIFO_ALMOST_FULL event will fire.

Returns

  • Configured receive FIFO threshold value.

This function configures the threshold for the receive FIFO. When the number of bytes of packet data in the receive FIFO exceeds the configured threshold, RAIL_Config_t::eventsCallback will keep firing with RAIL_EVENT_RX_FIFO_ALMOST_FULL set as long as the number of bytes in the receive FIFO exceeds the configured threshold value. The rxThreshold value should be smaller than the receive FIFO size; anything else, including a value of RAIL_FIFO_THRESHOLD_DISABLED, will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.

Note


Definition at line 2189 of file common/rail.h

RAIL_GetTxFifoThreshold#

uint16_t RAIL_GetTxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL transmit FIFO almost empty threshold value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Configured TX Threshold value.

Retrieves the configured TX threshold value.


Definition at line 2200 of file common/rail.h

RAIL_GetRxFifoThreshold#

uint16_t RAIL_GetRxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL receive FIFO almost full threshold value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Configured RX Threshold value.

Retrieves the configured RX threshold value.


Definition at line 2210 of file common/rail.h

RAIL_ResetFifo#

void RAIL_ResetFifo (RAIL_Handle_t railHandle, bool txFifo, bool rxFifo)

Reset the RAIL transmit and/or receive FIFOs.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txFifo

If true, reset the transmit FIFO.

[in]rxFifo

If true, reset the receive FIFO.

This function can reset each FIFO independently. The application should not reset the receive FIFO while receiving a frame, nor should it reset the transmit FIFO while transmitting a frame.


Definition at line 2223 of file common/rail.h

RAIL_GetRxFifoBytesAvailable#

uint16_t RAIL_GetRxFifoBytesAvailable (RAIL_Handle_t railHandle)

Get the number of bytes used in the receive FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

Only use this function in RX RAIL_DataMethod_t::FIFO_MODE. Apps should use RAIL_GetRxPacketInfo() instead.

Returns

  • Number of bytes used in the receive FIFO.

This function indicates how much packet-related data exists in the receive FIFO that could be read.

Note

  • The number of bytes returned may not just reflect the current packet's data but could also include raw appended info bytes added after successful packet reception and bytes from subsequently received packets. It is up to the app to never try to consume more than the packet's actual data when using the value returned here in a subsequent call to RAIL_ReadRxFifo(), otherwise the receive FIFO will be corrupted.


Definition at line 2243 of file common/rail.h

RAIL_GetTxFifoSpaceAvailable#

uint16_t RAIL_GetTxFifoSpaceAvailable (RAIL_Handle_t railHandle)

Get the number of bytes unused in the transmit FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Number of bytes unused in the transmit FIFO.

This function indicates how much space is available in the transmit FIFO for writing additional packet data.


Definition at line 2254 of file common/rail.h

Macro Definition Documentation#

RAIL_FIFO_ALIGNMENT_TYPE#

#define RAIL_FIFO_ALIGNMENT_TYPE
Value:
uint32_t

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


Definition at line 2461 of file common/rail_types.h

RAIL_FIFO_ALIGNMENT#

#define RAIL_FIFO_ALIGNMENT
Value:
(sizeof(RAIL_FIFO_ALIGNMENT_TYPE))

Alignment that is needed for the RX and TX FIFOs.


Definition at line 2464 of file common/rail_types.h

RAIL_FIFO_THRESHOLD_DISABLED#

#define RAIL_FIFO_THRESHOLD_DISABLED
Value:
0xFFFFU

A FIFO threshold value that disables the threshold.


Definition at line 2571 of file common/rail_types.h