From a514b1ccffca8ab8c7464a57aedd83e201b6fc10 Mon Sep 17 00:00:00 2001 From: Esko Dijk Date: Wed, 28 Oct 2026 10:31:19 +0100 Subject: [PATCH] [radio][api] Set 'ABORT' callback for Rx to 'MAY' and reword 'MAY' requirements (#13580) Previously, both SHOULD and MAY were used for reporting an 'ABORT' of a frame being received due to a higher-priority action taking place. This unifies these requirements to "MAY" level and also clarifies the wording for otPlatRadioScheduleTx(): so that the callback is clearly a purely optional action. Background: in these specific ABORT cases the callback is only used for counter updates. In RCPs, the extra callback would incur RCP/host communication which may be unwanted. Making it optional leaves this trade-off to the RCP/platform implementer. Also, some instances where 'MAY' was used for not fully optional behaviors are reworded to clarify that there is a choice of alternatives so that doing none of these is ruled out. One of the alternatives must be picked. --- include/openthread/platform/radio.h | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 53f563800..5cdbef548 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -1056,8 +1056,8 @@ otError otPlatRadioSleep(otInstance *aInstance); * If the radio is receiving a frame or transmitting an ACK, the ongoing receive operation SHOULD be completed * first before switching to `aChannel`. In this case, the channel change is scheduled to occur right after the * receive operation is done. - * In the exceptional case that a frame receive operation is aborted, this event SHOULD be reported via - * `otPlatRadioReceiveDone()` with `aError` set to `OT_ERROR_ABORT`. + * In the exceptional case that a frame receive operation is aborted, this event MAY be reported via + * `otPlatRadioReceiveDone()` with `aError` set to `OT_ERROR_ABORT` (or the callback MAY be omitted). * * @param[in] aInstance The OpenThread instance structure. * @param[in] aChannel The channel to use for receiving. @@ -1245,8 +1245,8 @@ otRadioFrame *otPlatRadioGetTransmitBuffer(otInstance *aInstance); * and `OT_RADIO_CAPS_TRANSMIT_TIMING`). In that case, the timed frame transmission has priority over ongoing * reception and the ongoing receive operation (frame reception and/or ACK transmission) MUST be aborted if * the radio determines it cannot finish the operation before the scheduled frame transmission is due. - * An ongoing frame reception that is aborted SHOULD be reported via `otPlatRadioReceiveDone()` with `aError` - * set to `OT_ERROR_ABORT`. + * An ongoing frame reception that is aborted MAY be reported via `otPlatRadioReceiveDone()` with `aError` + * set to `OT_ERROR_ABORT` (or the callback MAY be omitted). * * @param[in] aInstance The OpenThread instance structure. * @param[in] aFrame A pointer to the frame to be transmitted. @@ -1368,7 +1368,7 @@ otRadioFrame *otPlatRadioGetScheduledTxFrame(otInstance *aInstance); * invoking `otPlatRadioScheduledTxDone()` with `OT_ERROR_ABORT`. The radio platform MUST NOT invoke * `otPlatRadioScheduledTxDone()` synchronously from within `otPlatRadioScheduleTx()`. If * `otPlatRadioCancelScheduledTx()` is called before this deferred `OT_ERROR_ABORT` callback is invoked, the radio - * platform MAY either cancel the pending callback and return `OT_ERROR_NONE`, or return `OT_ERROR_BUSY` and + * platform MUST either cancel the pending callback and return `OT_ERROR_NONE`, or return `OT_ERROR_BUSY` and * proceed with invoking the `otPlatRadioScheduledTxDone()` callback. * * - Operational Precedence, Preemption, and State Restoration: @@ -1377,15 +1377,15 @@ otRadioFrame *otPlatRadioGetScheduledTxFrame(otInstance *aInstance); * frame (e.g., after SHR detection) or transmitting an acknowledgment for a received frame when the radio needs * to prepare/transmit for @p aTxTime, the scheduled transmission SHOULD take precedence—the active reception or * acknowledgment transmission SHOULD be stopped/aborted so that the scheduled transmission goes out on time at - * @p aTxTime. When an ongoing reception or acknowledgment transmission is aborted, the radio platform MAY either - * invoke `otPlatRadioReceiveDone()` with `OT_ERROR_ABORT` or not invoke `otPlatRadioReceiveDone()` at all (if the - * radio platform still delivers a received frame whose acknowledgment transmission was aborted via - * `otPlatRadioReceiveDone()` with `OT_ERROR_NONE`, `mAckedWithFramePending` and `mAckedWithSecEnhAck` MUST be set - * to `false`). + * @p aTxTime. When an ongoing frame reception is aborted, the radio platform MAY report this via + * `otPlatRadioReceiveDone()` with `OT_ERROR_ABORT` (or omit invoking otPlatRadioReceiveDone()). If a frame was + * already received and only its ACK transmission was aborted, and the radio platform still delivers the received + * frame via `otPlatRadioReceiveDone()` with OT_ERROR_NONE, then `mAckedWithFramePending` and + * `mAckedWithSecEnhAck` MUST be both set to false. * - Concurrent `otPlatRadioTransmit()`: If the radio is instructed to transmit a frame via `otPlatRadioTransmit()` * close to or overlapping with a previously scheduled transmission, the scheduled transmission SHOULD take * precedence and be performed at @p aTxTime. For the conflicting `otPlatRadioTransmit()` operation, the radio - * platform MAY either: + * platform MUST either: * - Abort the `otPlatRadioTransmit()` operation and invoke `otPlatRadioTxDone()` with `OT_ERROR_ABORT` (so the * OpenThread stack does not remain blocked waiting for `otPlatRadioTxDone()` and can handle any retries), or * - Defer the `otPlatRadioTransmit()` operation until after the scheduled transmission completes, provided that @@ -1540,7 +1540,7 @@ otError otPlatRadioScheduleTx(otInstance *aInstance, otRadioTime64 aTxTime); * - The OpenThread stack will wait until `otPlatRadioScheduledTxDone()` is invoked before modifying the scheduled TX * frame buffer or scheduling a new transmission. * - Note that if a deferred `OT_ERROR_ABORT` callback is pending (e.g., due to a past/missed target time or Coex - * denial), the radio platform MAY handle `otPlatRadioCancelScheduledTx()` in whichever way it prefers: it may either + * denial), the radio platform handles `otPlatRadioCancelScheduledTx()` in one of these two ways: either * cancel the pending callback and return `OT_ERROR_NONE`, or return `OT_ERROR_BUSY` and let the * `otPlatRadioScheduledTxDone()` callback be invoked. *