Skip to main content

otPlatRadioGetScheduledTxFrame

Function otPlatRadioGetScheduledTxFrame 

Source
pub unsafe extern "C" fn otPlatRadioGetScheduledTxFrame(
    aInstance: *mut otInstance,
) -> *mut otRadioFrame
Expand description

Get the radio transmit frame buffer dedicated for scheduled transmissions (otPlatRadioScheduleTx()).

This API requires the radio platform to support the OT_RADIO_CAPS_SCHEDULED_TX capability.

Similar to how otPlatRadioGetTransmitBuffer() provides the otRadioFrame buffer used for regular transmissions via otPlatRadioTransmit(), this function provides a separate, single otRadioFrame buffer used exclusively for scheduled transmissions via otPlatRadioScheduleTx(). Having a dedicated frame buffer allows the OpenThread stack to prepare and schedule a future timed transmission independently of ongoing or regular transmissions via otPlatRadioTransmit().

Frame buffer ownership and lifecycle:

  • The OpenThread stack forms the IEEE 802.15.4 frame in this buffer and then calls otPlatRadioScheduleTx() to schedule its transmission.
  • Upon a successful call to otPlatRadioScheduleTx() (returning OT_ERROR_NONE), the radio platform takes ownership of this frame buffer. The OpenThread stack guarantees that it will not modify or access the frame buffer or its PSDU content while it is owned by the radio platform.
  • Ownership of the frame buffer is released back to the OpenThread stack when:
    1. The radio platform invokes the otPlatRadioScheduledTxDone() callback,
    2. A call to otPlatRadioCancelScheduledTx() succeeds (returning OT_ERROR_NONE), or
    3. The radio is disabled via otPlatRadioDisable().
  • Once ownership is released back to OpenThread, the stack may immediately modify the buffer to prepare and schedule a new transmission (including directly from within the otPlatRadioScheduledTxDone() callback).
  • The returned otRadioFrame pointer (and its mPsdu buffer of at least OT_RADIO_FRAME_MAX_SIZE bytes) MUST remain valid and constant for the lifetime of @p aInstance (including before otPlatRadioEnable() is called).

@param[in] aInstance The OpenThread instance structure.

@returns A pointer to the scheduled transmit frame buffer.