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:
- RAIL_StartRx()
- RAIL_ScheduleRx()
- RAIL_StartTx()
- RAIL_StartScheduledTx()
- RAIL_StartCcaCsmaTx()
- RAIL_StartCcaLbtTx()
- RAIL_StartAverageRssi()
- RAIL_StartTxStream()
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:
- RAIL_ScheduleRx()
- RAIL_StartTx()
- RAIL_StartScheduledTx()
- RAIL_StartCcaCsmaTx()
- RAIL_StartCcaLbtTx()
- RAIL_StartAverageRssi()
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.
Example
Below is a simple example showing how to initialize two RAIL configurations and have one stay in infinite receive while the other one periodically transmits a packet at a higher priority.
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:
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.