RAIL Multiprotocol#
Overview#
As of version 2.1, the RAIL library supports dynamic multiprotocol. In dynamic multiprotocol, an application can allocate multiple RAIL instances and configure them independently. Some radio operations are then arbitrated by a radio scheduler, which is internal to RAIL, to allow the different instances to coexist. The scheduler attempts to allow as many of these operations to run as possible by moving them around within the bounds allowed by the protocol.
Radio Scheduler#
The radio scheduler is critical for multiprotocol operation. Its job is to arbitrate all radio operations, switch radio configurations, and ensure that radio operations run at the time requested. Not every RAIL function is a radio operation considered by the scheduler. Simple state update functions, such as RAIL_SetTxPower(), will directly change the hardware if active or update the state cache if inactive to have that change take affect the next time this protocol is loaded. The following RAIL functions are handled by the scheduler:
To arbitrate the radio operations, the scheduler uses startTime, priority, slipTime, and transactionTime. startTime comes implicitly from the RAIL API that started the transaction. For example, calling RAIL_StartTx() will use a start time of right now while calling RAIL_StartScheduledTx() takes an explicit start time as a parameter. The other three parameters are passed to all RAIL functions that require the scheduler in the RAIL_SchedulerInfo_t structure. The scheduler attempts to run each task at its desired startTime, but may also choose to run it up until startTime + slipTime. If it cannot run the task within that window, it will trigger a RAIL_Config_t::eventsCallback with the RAIL_EVENT_SCHEDULER_STATUS event set once that window has passed.
The scheduler is preemptive and will always ensure that a higher-priority task runs over a lower-priority task, but it does not guarantee ordering of these tasks. For example, it could choose to run a short lower-priority task with a small slipTime before a higher-priority task with a long slipTime to reduce dropped operations. Once an operation is started by the radio scheduler, it will either run to completion and trigger a normal RAIL event callback to indicate it is done or it will be aborted by a higher-priority task and ended with a RAIL_EVENT_SCHEDULER_STATUS event. Ultimately, the application is responsible for terminating most operations with a call to RAIL_YieldRadio(). This call cleans up internal state and allows the scheduler to switch to a lower priority operation.
Note
For the RAIL_SchedulerInfo_t::priority parameter, 0 is the highest priority while 255 is the lowest.
Scheduler Operations#
The APIs mentioned above can be classified as finite operations, infinite operations, and debug operations.
Finite Operations#
Finite operations include the following APIs:
Finite operations make up the majority of the radio scheduler calls. A finite operation has a defined start time and either a defined or estimated end time. Each RAIL handle may only have one of these types of operations queued up at any time. The upper level application code is responsible for waiting until the previous operation has completed before starting a new one like in the single protocol RAIL library. If a new task is issued while a previous task is in progress, or if a higher-priority task interrupts an operation before the user has yielded, it will trigger the RAIL_EVENT_SCHEDULER_STATUS event with an appropriate RAIL_SchedulerStatus_t set and this operation will not be scheduled again.
Once a finite operation has begun, the scheduler will use the same priority until a new finite event is provided or a yield occurs. The scheduler will ensure that unnecessary switches do not occur if this next event is in the near future at the same or a higher priority. For more information see Yielding the Radio.
Infinite Operations#
Infinite operations include the following APIs:
An infinite or background operation is treated by the scheduler as a radio state change. It still has a priority associated with it and will be started whenever it can be, but it will never fail. Another difference is that if this event is interrupted by a higher-priority task, it will be restarted whenever that task finishes where a finite task would be aborted.
Each RAIL handle may have only one infinite task but it may have both an infinite and finite or debug task at the same time. The one interesting aspect of this is that, if a finite task starts for this RAIL handle, the state will be updated to reflect what the infinite task has requested for that finite task's time period even if the infinite task is lower priority than another task in the system. For example, if you have one handle with a RAIL_StartRx() of priority 5 and another handle with a RAIL_StartRx() priority of 6 and a RAIL_StartTx() priority of 3, the scheduler will choose the second handle's finite transmit task. While running this transmit task though, the receiver will be set to on so that, as soon as this transmit completes, the radio will transition from transmit into receive. It will remain in receive until the finite operation yields at which time the first handle's receive will take precedence.
This implementation is intended to get the radio to stay in receive for a very long time on one of the RAIL handles. It is generally only advisable to do this on one radio configuration at a time and for this to be the lowest-priority task. For well defined receive events, such as looking for an ACK scheduled receive, windows or state transitions will generally work better.
Note
A known bug exists with turning on an infinite task during a finite task. For now, you must always configure the infinite task first to ensure it takes effect.
If using state transitions that can lead from receive to idle, the user must tell the scheduler that this happened with a call to RAIL_Idle(). This restriction will hopefully be removed in future versions.
Debug Operations#
Debug operations include the following APIs:
Debug operations are somewhat special because they don't allow the user to pass a RAIL_SchedulerInfo_t structure to them. Instead, they implicitly provide a start time of now and use the highest possible priority. This means that they will have the highest priority and interrupt most other protocol operations to switch into the test mode. Nothing can preempt them once started because the scheduler does not allow tasks of equal priority to preempt. These operations can be stooped by calling RAIL_StopTxStream(), RAIL_YieldRadio(), or RAIL_Idle().
The modal nature of these debug operations is intentional to prevent multiple tone or stream operations from happening concurrently. It is expected that the user will manage these test modes from a higher level to prevent the different protocols from using tone or stream at the same time.
Yielding the Radio#
Yielding is used by finite radio scheduler operations. Once an operation is started, that operation will run until explicitly yielded by the upper layer or interrupted by a higher-priority task. A yield is forced by a call to RAIL_YieldRadio() or RAIL_Idle(). It is important that the application yield the radio as soon as it's done to allow lower-priority tasks to run.
Yielding is not handled by RAIL since terminating an operation can be application-specific. While RAIL may know that an individual transmit or receive operation is completed, there are sometimes other reasons to prevent a switch or to run a follow on operation. For example, if you are using ACKing you may want to wait for the RAIL_EVENT_TXACK_PACKET_SENT after a receive packet instead of yielding right after the receive. This also allows you to chain together many protocol-specific operations without the scheduler constantly context switching. If you do schedule a follow on operation that is far in the future, the scheduler will also be smart enough to treat this as a yield and slot in other lower-priority operations.
This does mean that you must carefully look through the Events in RAIL and subscribe to any that can impact your state machine. Specifically, things like transmit or receive success conditions, transmit and receive error conditions, and scheduler events (RAIL_EVENT_SCHEDULER_STATUS, RAIL_EVENT_CONFIG_UNSCHEDULED, and RAIL_EVENT_CONFIG_SCHEDULED) are important to keep track of. These would likely be needed in any upper layer to properly update the internal state machine as well so they're likely already in the implementation.
Building a Multiprotocol Application#
The RAIL API is the same whether the targeted application is using the multiprotocol version or not. This was done intentionally to make switching between the two versions simple. From a build perspective, choose the desired RAIL library binary file to link into the application. For multiprotocol applications, the file name is librail_multiprotocol_CHIP_COMPILER_release.a while for other applications the file name is librail_CHIP_COMPILER_release.a.
Optionally, non multiprotocol applications can save memory by not allocating the RAIL_Config_t::scheduler state structure and passing NULL for all RAIL_SchedulerInfo_t pointers in APIs.
Starting in RAIL 2.12, the RAIL multiprotocol library internally provides two statically allocated RAM state buffers supporting two protocols, and both RAILSched_Config_t and RAIL_StateBuffer_t have been reduced to minimally-sized dummy structures solely for backwards compatibility. RAIL_Config_t structures no longer need to be in RAM or globals but can be allocated on the stack just for RAIL_Init(). In addition, RAIL_Config_t::protocol no longer needs to be provided for BLE (can always be NULL). If your multiprotocol application needs more than two protocols, additional state buffers for them must be provided by calling RAIL_AddStateBuffer3() or RAIL_AddStateBuffer4() prior to calling RAIL_Init() for these protocols. If more than four protocols are needed, contact Silicon Labs for advice.
Example#
Below is a simple example showing how to initialize two RAIL protocols and have one stay in infinite receive while the other one periodically transmits a packet at a higher priority.
#include <stdint.h>
#include <stdbool.h>
#include "rail.h"
#include "rail_config.h" // Generated by radio calculator
static RAIL_Handle_t gRailHandle1 = NULL;
static RAIL_Handle_t gRailHandle2 = NULL;
// Boolean to track when a packet has been sent.
static bool packetSendComplete = true;
// Creates transmit FIFOs for each PHY.
#define TX_FIFO_SIZE 128
static uint8_t txFifo1[TX_FIFO_SIZE];
static uint8_t txFifo2[TX_FIFO_SIZE];
static void radioConfigChangedHandler(RAIL_Handle_t railHandle,
const RAIL_ChannelConfigEntry_t *entry)
{
bool isSubgig = (entry->baseFrequency < 1000000000UL);
// ... handle radio configuration change, e.g., select the desired PA possibly
// using isSubgig to handle multiple configurations.
RAIL_ConfigTxPower(railHandle, &railTxPowerConfig);
// Reapply the Tx power after changing the PA above.
RAIL_SetTxPowerDbm(railHandle, txPower);
}
static void radioEventHandler(RAIL_Handle_t railHandle,
RAIL_Events_t events)
{
// Note that two different callbacks above could be used,
// but this example only uses one which is split based on the handle.
if (railHandle == gRailHandle1) {
// Handle events for protocol 1.
// NOTE: Since in infinite receive, the radio does not have to be yielded
// here as below. If this were changed, the radio would have to be yielded here.
} else if(railHandle == gRailHandle2) {
// Handle any packet completion event (success or failure) and set us up
// to send another packet.
if (events & (RAIL_EVENT_TX_PACKET_SENT
| RAIL_EVENT_TX_ABORTED
| RAIL_EVENT_TX_UNDERFLOW
| RAIL_EVENT_SCHEDULER_STATUS)) {
packetSendComplete = true;
RAIL_YieldRadio(railHandle);
}
}
}
// Initializes the two PHY configurations for the radio.
void radioInitialize(void)
{
// Creates each RAIL handle with their own configuration structures.
RAIL_Config_t railCfg1 = {
.eventsCallback = &radioEventHandler,
};
RAIL_Config_t railCfg2 = {
.eventsCallback = &radioEventHandler,
};
gRailHandle1 = RAIL_Init(&railCfg1, NULL);
gRailHandle2 = RAIL_Init(&railCfg2, NULL);
// Sets up transmit FIFOs.
RAIL_SetTxFifo(gRailHandle1, txFifo1, 0, TX_FIFO_SIZE);
RAIL_SetTxFifo(gRailHandle2, txFifo2, 0, TX_FIFO_SIZE);
// Configures radio according to the generated radio settings.
RAIL_ConfigChannels(gRailHandle1, channelConfigs[0], &radioConfigChangedHandler);
RAIL_ConfigChannels(gRailHandle2, channelConfigs[1], &radioConfigChangedHandler);
// Configures the most useful callbacks plus catch a few errors.
RAIL_ConfigEvents(gRailHandle1,
RAIL_EVENTS_ALL,
RAIL_EVENT_TX_PACKET_SENT
| RAIL_EVENT_TX_ABORTED
| RAIL_EVENT_TX_UNDERFLOW
| RAIL_EVENT_SCHEDULER_STATUS
| RAIL_EVENT_RX_PACKET_RECEIVED
| RAIL_EVENT_RX_FRAME_ERROR // invalid CRC
| RAIL_EVENT_RX_ADDRESS_FILTERED);
RAIL_ConfigEvents(gRailHandle2,
RAIL_EVENTS_ALL,
RAIL_EVENT_TX_PACKET_SENT
| RAIL_EVENT_TX_ABORTED
| RAIL_EVENT_TX_UNDERFLOW
| RAIL_EVENT_SCHEDULER_STATUS
| RAIL_EVENT_RX_PACKET_RECEIVED
| RAIL_EVENT_RX_FRAME_ERROR // invalid CRC
| RAIL_EVENT_RX_ADDRESS_FILTERED);
}
int main(void)
{
RAIL_SchedulerInfo_t schedulerInfo;
uint32_t sendTime;
// Initializes the radio and creates the two RAIL handles.
radioInitialize();
// Only set priority because transactionTime is meaningless for infinite
// operations and slipTime has a reasonable default for relative operations.
schedulerInfo = (RAIL_SchedulerInfo_t){ .priority = 200 };
RAIL_StartRx(gRailHandle1, 0, &schedulerInfo);
// Starts the first send 2 seconds after getting set up.
sendTime = RAIL_GetTime() + 2000000;
// Issues a transmit periodically on the second RAIL handle.
while (true) {
if (packetSendComplete) {
RAIL_Status_t res;
RAIL_ScheduleTxConfig_t scheduledTxConfig = { .when = sendTime,
.mode = RAIL_TIME_ABSOLUTE };
uint8_t packetData[] = { 0, 1, 2, 3, 4, 5, 6, 7, 7, 8, 10 };
// This assumes the Tx time is around 10 ms but should be tweaked based on
// the specific PHY configuration.
schedulerInfo = (RAIL_SchedulerInfo_t){ .priority = 100,
.slipTime = 50000,
.transactionTime = 10000 };
// Loads the transmit buffer with something to send.
RAIL_WriteTxFifo(gRailHandle2, packetData, sizeof(packetData), true);
// Transmits this packet at the specified time or up to 50 ms late.
res = RAIL_StartScheduledTx(gRailHandle2,
0,
RAIL_TX_OPTIONS_DEFAULT,
&scheduledTxConfig,
&schedulerInfo);
if (res == RAIL_STATUS_NO_ERROR) {
packetSendComplete = false;
sendTime += 2000000; // Add 2 seconds to the previous time.
} else {
// In the current configuration this should never happen.
assert(false);
}
}
}
return 0;
}
Understanding the Protocol Switch Time#
Current EFR32 chips that run dynamic multiprotocol code only have a single radio in their hardware. As a result, when DMP switches protocols, it must fully reconfigure the radio accordingly. The time this reconfiguration takes, as well as the time it takes the scheduler to decide which radio task to run, and timings passed into RAIL via RAIL_SetStateTiming (idleToRx, idleToTx), make up the Protocol Switch Time. This is essentially the amount of time in advance the radio must be made aware of new tasks in order to execute them on time. If this time is not respected at higher layers, users may get a RAIL_SchedulerStatus_t that indicates a failed scheduled event. By default, RAIL uses TRANSITION_TIME_US as the time for all protocol switches. The following sections explain how to characterize this time for a specific app and reconfigure it.
Measuring the Protocol Switch Time#
For users using only Silicon Labs provided standards-based stacks, the provided TRANSITION_TIME_US will be accurate. However, users implementing proprietary stacks or complex callbacks around scheduler events (RAIL_EVENT_CONFIG_UNSCHEDULED, RAIL_EVENT_CONFIG_SCHEDULED, and RAIL_EVENT_SCHEDULER_STATUS) may need to recharacterize this time if they find that the current switch time is causing scheduling failures in their application. Users can empirically determine this time for their system with the following algorithm: On the EFR, set a small (e.g. 0) transition time using RAIL_SetTransitionTime (this API must be called before RAIL_Init is called on any protocols). On protocol 1, enter infinite RX with RAIL_StartRx. On protocol 2, request an absolutely scheduled TX for some time in future (e.g. RAIL_GetTime() + 1000000). For small transition time values, the application should get RAIL_EVENT_SCHEDULER_STATUS on protocol 2, with a scheduler status of RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL. Repeat this test (resetting the device each time between runs to ensure RAIL_SetTransitionTime) is called before RAIL_Init) with increasing transition times. Eventually, for some large enough value, the application should begin getting RAIL_EVENT_TX_PACKET_SENT events, indicating that the supplied transition time was sufficient, and thus the radio was able to transition in time to complete the scheduled transmit at the correct time. Ideally this test should be run in both directions (i.e. repeat the test, swapping protocols 1 and 2).
Sample code for the above algorithm is provided below:
#include <stdint.h>
#include <stdbool.h>
#include "rail.h"
#include "rail_config.h" // Generated by radio calculator
static RAIL_Handle_t gRailHandle1 = NULL;
static RAIL_Handle_t gRailHandle2 = NULL;
// Boolean to track when a packet has been sent.
static bool packetSendComplete = true;
// Creates transmit FIFOs for each PHY.
#define TX_FIFO_SIZE 128
static uint8_t txFifo1[TX_FIFO_SIZE];
static uint8_t txFifo2[TX_FIFO_SIZE];
uint32_t transitionTime = 0;
void success(void) {
// Indicate test success to user
}
void fail(void) {
// Indicate test failure to user
}
static void radioConfigChangedHandler(RAIL_Handle_t railHandle,
const RAIL_ChannelConfigEntry_t *entry)
{
bool isSubgig = (entry->baseFrequency < 1000000000UL);
// ... handle radio configuration change, e.g., select the desired PA possibly
// using isSubgig to handle multiple configurations.
RAIL_ConfigTxPower(railHandle, &railTxPowerConfig);
// Reapply the Tx power after changing the PA above.
RAIL_SetTxPowerDbm(railHandle, txPower);
}
static void radioEventHandler(RAIL_Handle_t railHandle,
RAIL_Events_t events)
{
// Note that two different callbacks above could be used,
// but this example only uses one which is split based on the handle.
if (railHandle == gRailHandle1) {
// We don't care about events on protocol 1 for this test
return;
} else if(railHandle == gRailHandle2) {
// Handle any packet completion event (success or failure) and set us up
// to send another packet.
if (events & RAIL_EVENT_TX_PACKET_SENT) {
success();
}
if ((events & RAIL_EVENT_SCHEDULER_STATUS)
&& (RAIL_GetSchedulerStatus(railHandle) & RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL)) {
fail();
}
}
}
// Initializes the two PHY configurations for the radio.
void radioInitialize(void)
{
// transitionTime should be swept via testing instrumentation between
// runs
RAIL_SetTransitionTime(transitionTime)
// Creates each RAIL handle with their own configuration structures.
RAIL_Config_t railCfg1 = {
.eventsCallback = &radioEventHandler,
};
RAIL_Config_t railCfg2 = {
.eventsCallback = &radioEventHandler,
};
gRailHandle1 = RAIL_Init(&railCfg1, NULL);
gRailHandle2 = RAIL_Init(&railCfg2, NULL);
// Sets up transmit FIFOs.
RAIL_SetTxFifo(gRailHandle1, txFifo1, 0, TX_FIFO_SIZE);
RAIL_SetTxFifo(gRailHandle2, txFifo2, 0, TX_FIFO_SIZE);
// Configures radio according to the generated radio settings.
RAIL_ConfigChannels(gRailHandle1, channelConfigs[0], &radioConfigChangedHandler);
RAIL_ConfigChannels(gRailHandle2, channelConfigs[1], &radioConfigChangedHandler);
// Only need a few events on the second handle for this test
RAIL_ConfigEvents(gRailHandle2,
RAIL_EVENTS_ALL,
RAIL_EVENT_TX_PACKET_SENT
| RAIL_EVENT_SCHEDULER_STATUS);
}
int main(void)
{
RAIL_SchedulerInfo_t schedulerInfo;
uint32_t sendTime;
// Initializes the radio and creates the two RAIL handles.
radioInitialize();
// Get into receive on handle 1
schedulerInfo = (RAIL_SchedulerInfo_t){ .priority = 200,
.transactionTime = 1000,
.slipTime = 0 };
RAIL_StartRx(gRailHandle1, 0, &schedulerInfo);
// Starts the first send 1 second after getting set up.
sendTime = RAIL_GetTime() + 1000000;
// Request a TX for some time in the future
RAIL_ScheduleTxConfig_t scheduledTxConfig = { .when = sendTime,
.mode = RAIL_TIME_ABSOLUTE };
schedulerInfo.priority = 100;
res = RAIL_StartScheduledTx(gRailHandle2,
0,
RAIL_TX_OPTIONS_DEFAULT,
&scheduledTxConfig,
&schedulerInfo);
return 0;
}
Minimizing the Protocol Switch Time#
Currently, the best way to minimize the switch time is by proper design of RAIL_Config_t::eventsCallback. Specifically, the three scheduler events RAIL_EVENT_CONFIG_UNSCHEDULED, RAIL_EVENT_CONFIG_SCHEDULED, and RAIL_EVENT_SCHEDULER_STATUS, will be passed to the callback independently of all other events. Additionally, they are only raised during protocol switch process, and so their handling is part of the critical path for the protocol switch. Ideally, if they are not needed, RAIL_ConfigEvents should disable these events. Otherwise they should be handled first, after which the event handler should return immediately.
Additionally, short transition times should be specified in RAIL_SetStateTiming. Note that 0 for these values can be unreliable in a DMP context, as that tells the radio to go "as fast as possible" as opposed to a reliable, known value.