Skip to main content
Draft specification — subject to change.

Overview

This section describes the main features of the Radio Abstraction Layer (RAL), how commands transition the RAL between states, and how the RAL manages radio operations and the lifecycle of commands.

The operational model described here underpins the normative behavior specified in RAL Services, explaining the terminology used in command descriptions.

RAL States​

The RAL operates in one of four states:

StateDescription
SLEEPInitial RAL state. Some commands cannot be accepted or executed, notably including commands that schedule receptions and transmissions.
IDLEThe RAL is ready to execute scheduling commands, but no radio operation is scheduled or ongoing.
PENDINGThe RAL is tracking a pending radio operation that will run in the future.
RUNNINGA radio operation is actively in progress (including ramp-up time, transmission or reception, and ramp-down time).

Active Command​

When the RAL accepts a command that schedules a transmission or a reception, that command becomes the "active command", and the RAL transitions to the PENDING state. The RAL tracks the active command and its associated parameters internally until the command lifecycle concludes, at which point the RAL returns to its IDLE state and is ready to accept a new prospective active command. A RAL in PENDING or RUNNING state always tracks an active command.

At most one active command exists at any time. A new command that schedules a transmission or a reception can only be accepted when no active command exists and the RAL is in IDLE state.

State Transitions​

The following diagram shows the RAL state transitions. Every transition is driven by a command, a radio event, or an error condition.

flowchart TD
SLEEP["SLEEP"]
IDLE["IDLE"]
PENDING["PENDING"]
RUNNING["RUNNING"]

SLEEP -->|"RAL_State_Wakeup_Command"| IDLE
IDLE -->|"RAL_State_Sleep_Command"| SLEEP
IDLE -->|"TX/RX command
accepted"| PENDING
PENDING -->|"Radio operation starts"| RUNNING
PENDING -->|"Active command
lifecycle closed"| IDLE
RUNNING -->|"Active command
lifecycle closed"| IDLE
FromToTriggerDescription
SLEEPIDLERAL_State_Wakeup_CommandThe RAL ensures the radio is operational and ready to accept commands that schedule transmissions or receptions.
IDLESLEEPRAL_State_Sleep_CommandThe RAL may cause the radio hardware to enter a power-saving mode.
IDLEPENDINGAccepted RAL_Tx_Schedule_Command RAL_Rx_Schedule_CommandThe RAL accepts a triggering command, which becomes the active command. The RAL transitions to PENDING and prepares the radio for the scheduled operation.
PENDINGRUNNINGThe radio operation associated to the active startsThe scheduled point in time is reached and the radio begins transmitting or receiving.
PENDINGIDLEActive command lifecycle closedThe scheduled operation is concluded before it starts on air, due to an error condition or a cancellation request. The RAL emits the corresponding terminal event, closing the command lifecycle. Refer to the command description for the normative behavior.
RUNNINGIDLEActive command lifecycle closedThe radio operation concludes on air, whether successfully, due to an error condition, or due to a cancellation request. The RAL emits the corresponding terminal event, closing the command lifecycle. Refer to the command description for the normative behavior.

Command Cancellation​

The active command may be cancelled at the request of the upper layer.

In the normative behavior of command descriptions, the terms "cancel" and "abort" describe distinct aspects of terminating an activity:

  • "Cancel" applies to the active command. An upper layer issues RAL_Cancel_Command to request cancellation of the active command.
  • "Abort" applies to the radio operation itself. When the active command is cancelled, the RAL aborts the scheduled or ongoing radio operation. However, the RAL may also abort radio operations autonomously due to error conditions.

Radio Time​

The RAL maintains an internal tick counter incrementing at a frequency RAL_TICK_FREQ_HZ. All RAL timestamps are derived from this counter. The counter is a non-negative integer of RAL_TICK_COUNTER_WIDTH bits (RAL-specific, constant per RAL instance), wrapping around to 0 after reaching 2^RAL_TICK_COUNTER_WIDTH - 1. It is monotonically non-decreasing except upon wraparound, and as long as the RAL remains in a state other than SLEEP.

RalInstant​

RalInstant is a parameter type used for RAL timestamps. It is an Unsigned Integer of width greater or equal RAL_TICK_COUNTER_WIDTH bits, whose valid range is 0 to 2^RAL_TICK_COUNTER_WIDTH - 1.

Since all RAL timestamps are based on the internal tick counter, RalInstant values may be affected by wraparound. Consider two valid RalInstant values t_1 and t_2, where t_2 refers to a point in time in the future w.r.t. t_1. t_2 may be lower than t_1 due to wraparound. The upper layer is responsible for handling wraparound. The RAL_Time_Instant_Diff_Command provides wraparound-safe difference computation.

RalInstantDiff​

RalInstantDiff is a parameter type used for time intervals between RAL timestamps. It is a (signed) Integer of width greater or equal RAL_TICK_COUNTER_WIDTH bits, whose valid range is -2^(RAL_TICK_COUNTER_WIDTH - 1) to 2^(RAL_TICK_COUNTER_WIDTH - 1) - 1.

PacketBuffer​

The RAL defines the PacketBuffer abstraction to represent the memory space used for transmitting or receiving the PSDU of a single transmission unit.

Each PacketBuffer is characterized by the following parameters:

NameTypeValid RangeDescription
buffer_typeEnumerationBUFFER_TYPE_GENERAL_PURPOSE, BUFFER_TYPE_TIGHTLY_COUPLEDSpecifies the type of the buffer, as defined in §Buffer Specializations.
buffer_dataOctet Buffer—Octet region in memory used for the buffer's data, including the PSDU, as well as headroom and tailroom reserved for the RAL.
buffer_sizeUnsigned Integer—Size of buffer_data, i.e., the number of octets the buffer is able to store.
psduOctet Buffer—Reference to the PSDU within buffer_data.
psdu_lengthPSDULengthas defined in §PSDULengthLength of the PSDU, excluding the MIC.
psdu_region_unsecuredOctet Buffer—Reference to the octet region BUFFER_REGION_UNSECURED within the PSDU. Defined only if a non-zero size for the region has been declared through §RAL_Buffer_Configure_Regions_Command.
psdu_region_unsecured_sizeUnsigned Integer—Size of the PSDU octet region BUFFER_REGION_UNSECURED.
psdu_region_authenticatedOctet Buffer—Reference to the octet region BUFFER_REGION_AUTHENTICATED within the PSDU. Defined only if a non-zero size for the region has been declared through §RAL_Buffer_Configure_Regions_Command.
psdu_region_authenticated_sizeUnsigned Integer—Size of the PSDU octet region BUFFER_REGION_AUTHENTICATED.
psdu_region_encryptedOctet Buffer—Reference to the octet region BUFFER_REGION_ENCRYPTED within the PSDU. Defined only if a non-zero size for the region has been declared through §RAL_Buffer_Configure_Regions_Command.
psdu_region_encrypted_sizeUnsigned Integer—Size of the PSDU octet region BUFFER_REGION_ENCRYPTED.

The Buffer Manager Document details the rules governing the lifecycle and behavior of PacketBuffers.

PSDULength​

PSDULength is an unsigned integer limited by the PHY-specific maximal PSDU length: PHY_MAX_PSDU_LENGTH.

psdu_length includes the FCS, where present, and excludes the MIC. In length expressions, F is §fcsLength, the number of FCS octets the PSDU carries. The three regions cover psdu_length - F octets; the FCS requires no caller commit. Restoration applies only to these regions. The complete on-air PSDU length is psdu_length + M, where M is the current micSize for a protected partition and zero otherwise. This length MUST NOT exceed PHY_MAX_PSDU_LENGTH.

Buffer Specializations​

The RAL distinguishes the following PacketBuffer specializations:

NameAbbreviationbuffer_type enum valueDescription
GeneralPurposePacketBufferGPPBBUFFER_TYPE_GENERAL_PURPOSEBuffer that is represented in RAM and encoded with the buffer_type enum value. Its data can be accessed directly through the buffer_data parameter. The support for GPPB is mandatory for all RAL implementations.
TightlyCoupledPacketBufferTCPBBUFFER_TYPE_TIGHTLY_COUPLEDRepresents a buffer located close to the radio hardware, for which the associated buffer_data serves as a staging region (or "shadow buffer"). A TCPB can be implemented in a RAL-specific way, potentially enabling performance benefits for selected platforms. The support for TCPBs is optional for all RAL implementations.

Detailed descriptions of buffer specializations are located in the Buffer Manager document.

RAL Services​

Table RAL Services summarizes each service. Each service has a dedicated section where all its primitives (commands and events) are presented.

Table: Specification Contents.

ComponentDescriptionVersion
Execution ServiceSchedule radio operations, providing the functionalities necessary to meet real-time constraints.0.0.1
Time ServiceAccess the current radio timestamp and perform basic transformations on it.0.0.1
Configuration ServiceRead and modify the radio configuration.0.0.1
Buffer Manager ServiceManage and use packet buffers.0.0.1
Security ServiceInstall and remove the key, and draw the IV seed.0.0.1