From 68312101cab97a3a87a9f701782ea1f74da8d82c Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Thu, 13 Feb 2025 12:56:55 -0800 Subject: [PATCH] [radio] clarify `otPlatRadioReceiveAt()` behavior (#11221) This commit clarifies the documentation for `otPlatRadioReceiveAt()` regarding its behavior when called multiple times after successfully scheduling a reception window. If a subsequent call occurs before the start of the previous window, it MUST cancel the previous window and effectively replace it. If the call occurs after the start of the previously scheduled window, even if still within it, it MUST NOT impact the ongoing reception. --- include/openthread/instance.h | 2 +- include/openthread/platform/radio.h | 13 ++++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index e2cc51602..234ee3428 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 (476) +#define OPENTHREAD_API_VERSION (477) /** * @addtogroup api-instance diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 8f7f38f9a..7cef06b9d 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -865,6 +865,17 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); /** * Schedule a radio reception window at a specific time and duration. * + * After a radio reception is successfully scheduled for a future time and duration, a subsequent call to this + * function MUST be handled as follows: + * + * - If the start time of the previously scheduled reception window has not yet been reached, the new call to + * `otPlatRadioReceiveAt()` MUST cancel the previous schedule, effectively replacing it. + * + * - If the start of the previous window has already passed, the previous receive schedule is already being executed + * by the radio and MUST NOT be replaced or impacted. The new call to `otPlatRadioReceiveAt()` would then schedule + * a new future receive window. In particular, if the new `otPlatRadioReceiveAt()` call occurs after the start + * but while still within the previous reception window, the ongoing reception window MUST NOT be impacted. + * * @param[in] aChannel The radio channel on which to receive. * @param[in] aStart The receive window start time relative to the local * radio clock, see `otPlatRadioGetNow`. The radio @@ -879,7 +890,7 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); * reception has either succeeded or failed. * * @retval OT_ERROR_NONE Successfully scheduled receive window. - * @retval OT_ERROR_FAILED The receive window could not be scheduled. + * @retval OT_ERROR_FAILED The receive window could not be scheduled. For example, if @p aStart is in the past. */ otError otPlatRadioReceiveAt(otInstance *aInstance, uint8_t aChannel, uint32_t aStart, uint32_t aDuration);