From 7aeb1b18d36d30491d3a9a21092c1ea8a62cc953 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Thu, 20 Aug 2026 18:48:43 -0700 Subject: [PATCH] [radio] clarify `otPlatRadioSleep()` expected behavior during rx/ack (#13504) 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`. --- include/openthread/instance.h | 2 +- include/openthread/platform/radio.h | 25 +++++++++++++++++++++---- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 4c2565400..f0fc191c0 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -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 diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index dded80343..14a7749e0 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -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);