espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-09-10 03:00:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

[radio] clarify otPlatRadioSleep() expected behavior during rx/ack (#13504)

Browse Source 
This commit updates the documentation for `otPlatRadioSleep()` to clarify
its expected behavior when invoked while the radio is in the middle of
receiving an incoming frame or transmitting an automatic ACK (including
during AIFS/turnaround wait).

In these scenarios, the radio driver must complete the ongoing reception
and/or ACK transmission before transitioning the radio to Sleep. The
radio platform  must return `OT_ERROR_NONE` to indicate that the sleep
request has been accepted and scheduled, and must not return
`OT_ERROR_BUSY`.
This commit is contained in:
Abtin Keshavarzian
2026-08-20 18:48:43 -07:00
committed by GitHub
parent 77f1f6122f
commit 7aeb1b18d3
2 changed files with 22 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openthread/instance.h
+1 -1
View File
@@ -52,7 +52,7 @@ extern "C" {
*
* @note This number versions both OpenThread platform and user APIs.
*/
#define OPENTHREAD_API_VERSION (616)
#define OPENTHREAD_API_VERSION (617)
/**
* @addtogroup api-instance
include/openthread/platform/radio.h
+21 -4
View File
@@ -873,12 +873,29 @@ otError otPlatRadioDisable(otInstance *aInstance);
bool otPlatRadioIsEnabled(otInstance *aInstance);
/**
* Transition the radio from Receive to Sleep (turn off the radio).
* Transition the radio to the Sleep state (turn off the radio).
*
* @param[in] aInstance The OpenThread instance structure.
* If the radio is already in the Sleep state, this function MUST return `OT_ERROR_NONE` with no effect.
*
* @retval OT_ERROR_NONE Successfully transitioned to Sleep.
* @retval OT_ERROR_BUSY The radio was transmitting.
* If `otPlatRadioSleep()` is called while the radio is in the middle of receiving a frame or transmitting an ACK
* (e.g., during AIFS/turnaround wait or actively transmitting the ACK frame), the radio MUST complete the ongoing
* operation (finish frame reception and/or ACK transmission) and transition to Sleep immediately thereafter. In this
* scenario:
* - The radio MUST return `OT_ERROR_NONE` to indicate that the sleep request has been accepted and scheduled.
* - Upon finishing the frame reception (and any associated ACK transmission), the radio driver MUST invoke
* `otPlatRadioReceiveDone()` to deliver the received frame (or report reception error) before transitioning
* to Sleep.
*
* If any subsequent radio state transition function (e.g., `otPlatRadioReceive()` or `otPlatRadioTransmit()`) is
* called while a scheduled transition to Sleep is pending, the pending Sleep transition MUST be canceled/superseded,
* and the radio MUST transition to the newly requested state upon completing the ongoing reception and/or ACK
* transmission.
*
* @param[in] aInstance The OpenThread instance structure.
*
* @retval OT_ERROR_NONE Successfully transitioned to Sleep, radio is already in Sleep, or transition is
* accepted and scheduled.
* @retval OT_ERROR_BUSY The radio was transmitting a frame (initiated by `otPlatRadioTransmit()`).
* @retval OT_ERROR_INVALID_STATE The radio was disabled.
*/
otError otPlatRadioSleep(otInstance *aInstance);