This commit redesigns IEEE 802.15.4 Information Element (IE) handling by
introducing dedicated subclass definitions (`CslIe`, `TimeIe`,
`ConnectionIe`, `RendezvousTimeIe`, `LinkMetricsProbingIe`, etc.) inheriting
from `HeaderIe` or `VendorIe`.
In addition, `Mac::Frame` is updated with generic template methods:
- `Has<IeType>()`: Checks if the frame contains a well-formed instance of
the specified IE subclass.
- `Find<IeType>()`: Finds, validates and returns a type-safe pointer to the
IE.
Key benefits of this redesign:
- Streamlined IE Generation: Constructing and populating IEs is significantly
simplified. Each subclass exposes a unified `Init()` method that cleanly
computes the exact IE content length, sets the Element ID and known content
(e.g. vendor OUI) in a single step.
- True Encapsulation: Each IE subclass serves as the single source of truth
for its Element ID (`kId`), content layout, and structural validation logic
(`IsValid()`). Callers no longer pass magic ID constants or perform
error-prone pointer arithmetic.
- By implementing `HeaderIe::ValidateAs<IeType>()` as a static polymorphic
matcher passed to `FindHeaderIe()`, the compiler devirtualizes
and inlines ID match and content verifications directly into MAC frame
parsing loops.
- Scalable Integration: Adding new Information Elements is trivial. Defining
a new subclass automatically equips MAC frame handling with type-safe
search without bloating `Mac::Frame` with ad-hoc getter methods.
This commit refactors `Mac::HeaderIe` generation and parsing to
improve code readability, type safety, and bounds checking.
Key changes include:
- Adds `HeaderIe::GetSize()` and `HeaderIe::GetContent()` to
encapsulate pointer arithmetic inside the class and eliminate ad-hoc
pointer offset math across `Mac` modules.
- Updates `Frame::FindPayloadIndex()`, `Frame::GetHeaderIe()`,
`Frame::GetThreadIe()`, and `Frame::GetTimeIe()` to utilize the
new helper methods, simplifying boundary checks.
- Simplifies `HeaderIe::Init()` by replacing the union with a clearer
`mLenIdType` field and updating the internal bitwise operations
to use `bit_utils.hpp` helper methods.
Retransmissions of frames containing time-dependent header Information
Elements (IEs), such as CSL or Time Sync, require updates to these
IEs to reflect the exact time of sending. If the frame counter is not
incremented for these retransmissions, it leads to nonce reuse in
AES-CCM encryption, which is a security vulnerability.
This commit addresses this issue by ensuring that every transmission
attempt (initial or retry) uses a fresh frame counter:
- Deferred security processing from `SubMac::Send()` to
`SubMac::BeginTransmit()`.
- Upon retransmission in `SubMac::HandleTransmitDone()`, the frame is
restored to plaintext via `TxFrame::DecryptTransmitAesCcm()` and
security flags are cleared.
- This allows time-dependent IEs to be updated and a new frame counter
to be assigned for every attempt.
Added a Nexus test case `retransmission_security` to verify that both
CSL and standard MAC retransmissions use incrementing frame counters
and updated CSL phases.
This commit enables the format-nonliteral check for code missed in
`#12236`. This commit also enables the format-nonliteral warnings in
CMake to catch such warnings in future in CMake build.
The description of the method `otPlatRadioEnableCsl()` requires the platform
to include the CSL IE in the enhanced ACK when the received data frame's source
address matches the CSL receiver's peer address. This commit implements this
requirement in the simulation radio.
The simulation platform radio driver doesn't set the 'mInfo.mTxInfo.mIeInfo'
field of the ACK frame. And the function 'otMacFrameUpdateTimeIe()' directly
use the 'mInfo.mTxInfo.mIeInfo' field, this may cause the program crash.
This commit checks whether 'mInfo.mTxInfo.mIeInfo' is null before using it
and sets the 'mInfo.mTxInfo.mIeInfo' field of the ACK frame to null in
simulation platform.
The wakeup frame is sent from the wakeup coordinator rather than the
wakeup end device. Current code processes the key id mode 2 only when
the device is the wakeup end device. This commit corrects this issue.
If the radio driver supports the `OT_RADIO_CAPS_TRANSMIT_SEC`, the
radio driver should process the security of the send frame. But the
current method `otMacFrameProcessTransmitSecurity()` doesn't process
the security of the wakeup frame. Which causes sent wakeup frame is not
encrypted.
This commit enables the method `otMacFrameProcessTransmitSecurity()`
to process the security of the wakeup frame.
This commit introduces a mechanism for a device transitioning from
child to router role to keep receiving frames addressed to its
previous short address for a brief period.
A new radio platform API, `otPlatRadioSetAlternateShortAddress()`, is
introduced. This allows the OT stack to configure an alternate short
address. Radio platform support for this function is indicated by the
`OT_RADIO_CAPS_ALT_SHORT_ADDR` capability in `otPlatRadioGetCaps()`
The same function can be used with `OT_RADIO_INVALID_SHORT_ADDR`
(`0xfffe`) to clear a previously set alternate short address. Support
for the new API is implemented in RCP and `RadioSpinel`, ensuring
backward compatibility by dynamically checking supported radio
capabilities.
MLE code is updated to instruct the radio to use the old child RLOC16
as an alternate address upon role transition. The MLE layer will
automatically clear the alternate address after eight seconds, or if
other state/mode changes occur. This eight-second window ensures the
new router can transmit four MLE Advertisement messages.
This commit updates how we prepare the MAC headers:
- New `enum`s are defined in `Mac::Frame` to specify the frame
`Type`, `Version`, `SecurityLevel`, etc.
- `InitMacHeader()` will itself determine the Frame Control Field
from the given address info.
- It now uses `FrameBuilder` to prepare the headers.
- New helper `MeshForwarder::PrepareMacHeaders()` is added which
takes care of adding MAC (address, security header) along with
any IE headers.
- These changes ensure that PAN ID Compression bit is properly
set on MAC frames when using 2015 version (ensure that PAN
IDs are not omitted when both addresses use Extended format).
This commit splits OPENTHREAD_CONFIG_MLE_LINK_METRICS_ENABLE macro
into two subsequent ones:
- OPENTHREAD_CONFIG_MLE_LINK_METRICS_SUBJECT_ENABLE
- OPENTHREAD_CONFIG_MLE_LINK_METRICS_INITIATOR_ENABLE
This commit refactors the code to set frame version, IE present field
in frame control field and to append Header IE.
- Split UpdateFrameControlField into two methods: CalcIePresent and
CalcFrameVersion. Currently UpdateFrameControlField` is not
easy-to-read and hard to extend the method to handle more cases.
- Move this code from Mac to MeshForwarder. I think it should be
MeshForwarder's responsibility (PrepareDataFrame) to prepare the
frame (though Mac sometimes prepare data frames itself). Since when
preparing the frame, most information comes from the Message which
is only in MeshForwarder, we can put this code for preparing frame
in MeshForwarder.
- Enhance the way to append Header IEs to the frame. Currently in
Mac::AppendHeaderIe, it generates a list of HeaderIe first and then
call Frame::AppendHeaderIe. There are two problems here: 1. it uses
another copy (copy HeaderIe to the frame's buffer). 2. it has to
initialize Vendor IE (e.g. TimeSync IE) after Vendor IE header has
been copied to the buffer. Currently it directly finds the first
Vendor IE in the buffer and initialize it as TimeSync IE, which is
not extensible. This commit shifts the responsibility of 'how to
append the IE' to Frame, by providing AppendHeaderIeAt method. And
MeshForwarder can decide which IEs to append and directly call the
method to append IEs to the frame.
This commit implements Enhanced-ACK Probing (on simulation platform).
- Add a new public API otLinkMetricsConfigEnhAckProbing which sends
Link Metrics Management Request to configure the probing. This is
called on Probing Initiator side.
- Add a new radio platform API otPlatRadioConfigureEnhAckProbing. This
API should be called on Probing Subject side when handling the
requests from Initiators. This API notifies the radio to start/stop
aggregating link metrics info and include the data into Vendor IE in
enhanced-ACK for the specific neighbor. As discussed in #5746, the
code for doing such thing should be put in radio driver.
- Add a util module util/link_metrics, which provides a group of APIs
to implement Probing Subject side logic for Enh-ACK Probing. Any
platform could use this module to implement the feature easily in
radio driver.
- Add new util APIs in util/mac_frame to generate Enh-ACK Probing IE
(Vendor IE with Thread OUI and SubType = 0) and set value for this
IE.
- Update the implementation in simulation/radio.c to support Probing
Subject side logic for Enh-ACK Probing, using APIs in
util/link_metrics and util/mac_frame.
- Add a test
v1_2_LowPower_7_1_01_SingleProbeLinkMetricsWithEnhancedAcks.py for
testing.
Misc:
- Add check for all the public Link Metrics APIs (Initiator side) to
ensure that the Subject is a neighbor of the Initiator. If the
address is not link-local or the neighbor is not found, an error
UNKNOWN_NEIGHBOR would be returned.
- Update PrepareEmptyFrame so that when it's called for reference
device, its frame version would be set to 2015.
MAC command frame has its command ID encrypted in frame version
802.15.4-2015. Radio driver cannot decrypt this frame payload without
extended address. So the frame pending bit is not correctly set in the
ACK in response to data request command with version 2015. This commit
adds a special handling for frame version 2015 and only checks the
frame type when deciding if it needs to set the frame pending bit.
In 802.15.4-2015 spec Table 7-2, it is possible to receive frame with
destination address but without destination PAN ID. This commit
changes the address filter function to avoid dropping such frames.
This commit adds transmit security support for simulation radio so
that security Enh-ACK could be handled at radio layer. This commit
also fixes issue #5041.
This commit adds mac frame util functions to generate acks (both Imm
and Enh acks) from a received frame. These funtions are utils APIs for
platforms which don't provide ack generation.
This commit also introduces compile options for CSL to control the CSL
IE related part.
This commit adds enhanced frame pending feature of Thread 1.2. This
requires the platform radio driver to correctly set frame pending bit
for Data frames and MAC Data Request frames.
`otPlatRadioFrameUpdated()` is declared not to access any state within
OpenThread. However, the current implementation does read the extended
address. This commit moves the AES process into `Mac::TxFrame`, which
is free of `otInstance` and eliminates the current deep callback
stacks when the radio driver wants to process tx AES from interrupt
context.
Abtin Keshavarzian