Multiprotocol#

Multiprotocol scheduler APIs to support multiple time-sliced PHYs.

Modules#

RAIL_SchedulerInfo_t

EFR32XG2X

Enumerations#

enum
RAIL_SCHEDULER_STATUS_NO_ERROR = (0U << 0 )
RAIL_SCHEDULER_STATUS_UNSUPPORTED = (1U << 0 )
RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED = (2U << 0 )
RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL = (3U << 0 )
RAIL_SCHEDULER_STATUS_TASK_FAIL = (4U << 0 )
RAIL_SCHEDULER_STATUS_INTERNAL_ERROR = (5U << 0 )
RAIL_SCHEDULER_TASK_EMPTY = (0U << 4 )
RAIL_SCHEDULER_TASK_SCHEDULED_RX = (1U << 4 )
RAIL_SCHEDULER_TASK_SCHEDULED_TX = (2U << 4 )
RAIL_SCHEDULER_TASK_SINGLE_TX = (3U << 4 )
RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX = (4U << 4 )
RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX = (5U << 4 )
RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX = (6U << 4 )
RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX = (7U << 4 )
RAIL_SCHEDULER_TASK_TX_STREAM = (8U << 4 )
RAIL_SCHEDULER_TASK_AVERAGE_RSSI = (9U << 4 )
RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_RX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL = (RAIL_SCHEDULER_TASK_TX_STREAM | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_RX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_RX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_TASK_FAIL)
RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED = (RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_TX_STREAM | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_TX_STREAM_INTERRUPTED = (RAIL_SCHEDULER_TASK_TX_STREAM | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI | RAIL_SCHEDULER_STATUS_INTERNAL_ERROR)
RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI | RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL)
RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED = (RAIL_SCHEDULER_TASK_AVERAGE_RSSI | RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED)
}

Multiprotocol scheduler status returned by RAIL_GetSchedulerStatus().

enum
RAIL_TASK_TYPE_START_RX = 0
RAIL_TASK_TYPE_OTHER = 1
}

Multiprotocol radio operation task types, used with RAIL_SetTaskPriority.

Functions#

RAIL_YieldRadio(RAIL_Handle_t railHandle)

Yield the radio to other configurations.

RAIL_GetSchedulerStatus(RAIL_Handle_t railHandle)

Get the status of the RAIL scheduler.

RAIL_GetSchedulerStatusAlt(RAIL_Handle_t railHandle, RAIL_SchedulerStatus_t *pSchedulerStatus, RAIL_Status_t *pRailStatus)

Get the status of the RAIL scheduler, specific to the radio operation, along with RAIL_Status_t returned by RAIL API invoked by the RAIL scheduler.

RAIL_SetTaskPriority(RAIL_Handle_t railHandle, uint8_t priority, RAIL_TaskType_t taskType)

Change the priority of a specified task type in multiprotocol.

Get time needed to switch between protocols.

void
RAIL_SetTransitionTime(RAIL_Time_t transitionTime)

Set time needed to switch between protocols.

Macros#

#define

Radio Scheduler Status mask.

#define

Radio Scheduler Status shift.

#define

Radio Scheduler Task mask.

#define

Radio Scheduler Task shift.

Enumeration Documentation#

RAIL_SchedulerStatus_t#

RAIL_SchedulerStatus_t

Multiprotocol scheduler status returned by RAIL_GetSchedulerStatus().

Multiprotocol scheduler status is a combination of the upper 4 bits which constitute the type of scheduler task and the lower 4 bits which constitute the type of scheduler error.

Enumerator
RAIL_SCHEDULER_STATUS_NO_ERROR

Multiprotocol scheduler reports no error.

RAIL_SCHEDULER_STATUS_UNSUPPORTED

The scheduler is disabled or the requested scheduler operation is unsupported.

RAIL_SCHEDULER_STATUS_EVENT_INTERRUPTED

The scheduled task was started but was interrupted by a higher-priority event before it could be completed.

RAIL_SCHEDULER_STATUS_SCHEDULE_FAIL

Scheduled task could not be scheduled given its priority and the other tasks running on the system.

RAIL_SCHEDULER_STATUS_TASK_FAIL

Calling the RAIL API associated with the Radio scheduler task returned an error code.

RAIL_SCHEDULER_STATUS_INTERNAL_ERROR

An internal error occurred in scheduler data structures, which should not happen and indicates a problem.

RAIL_SCHEDULER_TASK_EMPTY

Radio scheduler has no task.

RAIL_SCHEDULER_TASK_SCHEDULED_RX

Radio scheduler calls RAIL_ScheduleRx().

RAIL_SCHEDULER_TASK_SCHEDULED_TX

Radio scheduler calls RAIL_StartScheduledTx().

RAIL_SCHEDULER_TASK_SINGLE_TX

Radio scheduler calls RAIL_StartTx().

RAIL_SCHEDULER_TASK_SINGLE_CCA_CSMA_TX

Radio scheduler calls RAIL_StartCcaCsmaTx().

RAIL_SCHEDULER_TASK_SINGLE_CCA_LBT_TX

Radio scheduler calls RAIL_StartCcaLbtTx().

RAIL_SCHEDULER_TASK_SCHEDULED_CCA_CSMA_TX

Radio scheduler calls RAIL_StartScheduledCcaCsmaTx().

RAIL_SCHEDULER_TASK_SCHEDULED_CCA_LBT_TX

Radio scheduler calls RAIL_StartScheduledCcaLbtTx().

RAIL_SCHEDULER_TASK_TX_STREAM

Radio scheduler calls RAIL_StartTxStream().

RAIL_SCHEDULER_TASK_AVERAGE_RSSI

Radio scheduler calls RAIL_StartAverageRssi().

RAIL_SCHEDULER_STATUS_SCHEDULED_TX_FAIL

RAIL_StartScheduledTx() returned error status.

RAIL_SCHEDULER_STATUS_SINGLE_TX_FAIL

RAIL_StartTx() returned error status.

RAIL_SCHEDULER_STATUS_CCA_CSMA_TX_FAIL

RAIL_StartCcaCsmaTx() returned error status.

RAIL_SCHEDULER_STATUS_CCA_LBT_TX_FAIL

RAIL_StartCcaLbtTx() returned error status.

RAIL_SCHEDULER_STATUS_SCHEDULED_RX_FAIL

RAIL_ScheduleRx() returned error status.

RAIL_SCHEDULER_STATUS_TX_STREAM_FAIL

RAIL_StartTxStream() returned error status.

RAIL_SCHEDULER_STATUS_AVERAGE_RSSI_FAIL

RAIL_StartAverageRssi() returned error status.

RAIL_SCHEDULER_SCHEDULED_RX_INTERNAL_ERROR

Multiprotocol scheduled receive function internal error.

RAIL_SCHEDULER_SCHEDULED_RX_SCHEDULING_ERROR

Multiprotocol scheduled receive scheduling error.

RAIL_SCHEDULER_SCHEDULED_RX_INTERRUPTED

RAIL_ScheduleRx() operation interrupted

RAIL_SCHEDULER_SCHEDULED_TX_INTERNAL_ERROR

Multiprotocol scheduled TX internal error.

RAIL_SCHEDULER_SCHEDULED_TX_SCHEDULING_ERROR

Multiprotocol scheduled TX scheduling error.

RAIL_SCHEDULER_SCHEDULED_TX_INTERRUPTED

RAIL_StartScheduledTx() operation interrupted

RAIL_SCHEDULER_SINGLE_TX_INTERNAL_ERROR

Multiprotocol instantaneous TX internal error.

RAIL_SCHEDULER_SINGLE_TX_SCHEDULING_ERROR

Multiprotocol instantaneous TX scheduling error.

RAIL_SCHEDULER_SINGLE_TX_INTERRUPTED

RAIL_StartTx() operation interrupted

RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERNAL_ERROR

Multiprotocol single CSMA transmit function internal error.

RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_SCHEDULING_ERROR

Multiprotocol single CSMA transmit scheduling error.

RAIL_SCHEDULER_SINGLE_CCA_CSMA_TX_INTERRUPTED

RAIL_StartCcaCsmaTx() operation interrupted

RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERNAL_ERROR

Multiprotocol single LBT transmit function internal error.

RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_SCHEDULING_ERROR

Multiprotocol single LBT transmit scheduling error.

RAIL_SCHEDULER_SINGLE_CCA_LBT_TX_INTERRUPTED

RAIL_StartCcaLbtTx() operation interrupted

RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERNAL_ERROR

Multiprotocol scheduled CSMA transmit function internal error.

RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_FAIL

RAIL_StartScheduledCcaCsmaTx() returned error status.

RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_SCHEDULING_ERROR

Multiprotocol scheduled CSMA transmit scheduling error.

RAIL_SCHEDULER_SCHEDULED_CCA_CSMA_TX_INTERRUPTED

RAIL_StartScheduledCcaCsmaTx() operation interrupted

RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERNAL_ERROR

Multiprotocol scheduled LBT transmit function internal error.

RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_FAIL

RAIL_StartScheduledCcaLbtTx() returned error status.

RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_SCHEDULING_ERROR

Multiprotocol scheduled LBT transmit scheduling error.

RAIL_SCHEDULER_SCHEDULED_CCA_LBT_TX_INTERRUPTED

RAIL_StartScheduledCcaLbtTx() operation interrupted

RAIL_SCHEDULER_TX_STREAM_INTERNAL_ERROR

Multiprotocol stream transmit function internal error.

RAIL_SCHEDULER_TX_STREAM_SCHEDULING_ERROR

Multiprotocol stream transmit scheduling error.

RAIL_SCHEDULER_TX_STREAM_INTERRUPTED

RAIL_StartTxStream() operation interrupted

RAIL_SCHEDULER_AVERAGE_RSSI_INTERNAL_ERROR

Multiprotocol RSSI averaging function internal error.

RAIL_SCHEDULER_AVERAGE_RSSI_SCHEDULING_ERROR

Multiprotocol RSSI average scheduling error.

RAIL_SCHEDULER_AVERAGE_RSSI_INTERRUPTED

RAIL_StartAverageRssi() operation interrupted


Definition at line 540 of file common/rail_types.h

RAIL_TaskType_t#

RAIL_TaskType_t

Multiprotocol radio operation task types, used with RAIL_SetTaskPriority.

Enumerator
RAIL_TASK_TYPE_START_RX

Indicate a task started using RAIL_StartRx.

RAIL_TASK_TYPE_OTHER

Indicate a task started functions other than RAIL_StartRx.


Definition at line 772 of file common/rail_types.h

Function Documentation#

RAIL_YieldRadio#

RAIL_Status_t RAIL_YieldRadio (RAIL_Handle_t railHandle)

Yield the radio to other configurations.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

This function is used to indicate that the previous transmit or scheduled receive operation has completed. It must be used in multiprotocol RAIL because the scheduler assumes that any transmit or receive operation that is started can go on indefinitely based on state transitions and your protocol. RAIL will not allow a lower priority tasks to run until this is called so it can negatively impact performance of those protocols if this is omitted or delayed. It is also possible to call the RAIL_Idle() API to both terminate the operation and idle the radio. In single protocol RAIL this API does nothing, however, if RAIL Power Manager is initialized, calling RAIL_YieldRadio after scheduled TX/RX and instantaneous TX completion, is required, to indicate to the Power Manager that the the radio is no longer busy and can be idled for sleeping.

See Yielding the Radio for more details.


Definition at line 5687 of file common/rail.h

RAIL_GetSchedulerStatus#

RAIL_SchedulerStatus_t RAIL_GetSchedulerStatus (RAIL_Handle_t railHandle)

Get the status of the RAIL scheduler.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

This function can only be called from a callback context after the RAIL_EVENT_SCHEDULER_STATUS event occurs.


Definition at line 5698 of file common/rail.h

RAIL_GetSchedulerStatusAlt#

RAIL_Status_t RAIL_GetSchedulerStatusAlt (RAIL_Handle_t railHandle, RAIL_SchedulerStatus_t *pSchedulerStatus, RAIL_Status_t *pRailStatus)

Get the status of the RAIL scheduler, specific to the radio operation, along with RAIL_Status_t returned by RAIL API invoked by the RAIL scheduler.

Parameters
[in]railHandle

A RAIL instance handle.

[out]pSchedulerStatus

An application-provided pointer to store RAIL_SchedulerStatus_t status. Can be NULL as long as pRailStatus is not NULL.

[out]pRailStatus

An application-provided pointer to store RAIL_Status_t of the RAIL API invoked by the RAIL scheduler. Can be NULL as long as pSchedulerStatus is not NULL.

Returns

  • Status code indicating success of the function call.

This function can only be called from a callback context after the RAIL_EVENT_SCHEDULER_STATUS event occurs.


Definition at line 5717 of file common/rail.h

RAIL_SetTaskPriority#

RAIL_Status_t RAIL_SetTaskPriority (RAIL_Handle_t railHandle, uint8_t priority, RAIL_TaskType_t taskType)

Change the priority of a specified task type in multiprotocol.

Parameters
[in]railHandle

A RAIL instance handle.

[in]priority

Desired new priority for the railHandle's active task

[in]taskType

Type of task whose priority should be updated

Returns

  • Status code indicating success of the function call.

While the application can use this function however it likes, a major use case is being able to increase an infinite receive priority while receiving a packet. In other words, a given RAIL_Handle_t can maintain a very low priority background receive, but upon getting a RAIL_EVENT_RX_SYNC1_DETECT_SHIFT or RAIL_EVENT_RX_SYNC2_DETECT_SHIFT event, the app can call this function to increase the background RX priority to lower the risk another protocol might preempt during packet reception.


Definition at line 5738 of file common/rail.h

RAIL_GetTransitionTime#

RAIL_Time_t RAIL_GetTransitionTime (void)

Get time needed to switch between protocols.

Parameters
N/A

Returns


Definition at line 5747 of file common/rail.h

RAIL_SetTransitionTime#

void RAIL_SetTransitionTime (RAIL_Time_t transitionTime)

Set time needed to switch between protocols.

Parameters
[in]transitionTime

Time needed to switch between protocols.

Call this API only once, before any protocol is initialized via RAIL_Init(). Changing this value during normal operation can result in improper scheduling behavior.


Definition at line 5757 of file common/rail.h

Macro Definition Documentation#

RAIL_SCHEDULER_STATUS_MASK#

#define RAIL_SCHEDULER_STATUS_MASK
Value:
0x0FU

Radio Scheduler Status mask.


Definition at line 523 of file common/rail_types.h

RAIL_SCHEDULER_STATUS_SHIFT#

#define RAIL_SCHEDULER_STATUS_SHIFT
Value:
0

Radio Scheduler Status shift.


Definition at line 525 of file common/rail_types.h

RAIL_SCHEDULER_TASK_MASK#

#define RAIL_SCHEDULER_TASK_MASK
Value:
0xF0U

Radio Scheduler Task mask.


Definition at line 528 of file common/rail_types.h

RAIL_SCHEDULER_TASK_SHIFT#

#define RAIL_SCHEDULER_TASK_SHIFT
Value:
4

Radio Scheduler Task shift.


Definition at line 530 of file common/rail_types.h