[thread-direct] API surface for TD link establishment

Author: suveshpratapa

include/openthread/BUILD.gn

@@ -113,6 +113,7 @@ source_set("openthread") {
     "platform/settings.h",
     "platform/spi-slave.h",
     "platform/tcp.h",
+    "platform/thread_direct.h",
     "platform/time.h",
     "platform/toolchain.h",
     "platform/trel.h",

include/openthread/platform/thread_direct.h

@@ -0,0 +1,168 @@
+/*
+ *  Copyright (c) 2025, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file
+ *   This file includes the platform abstraction for Thread Direct link operations.
+ */
+
+#ifndef OPENTHREAD_PLATFORM_THREAD_DIRECT_H_
+#define OPENTHREAD_PLATFORM_THREAD_DIRECT_H_
+
+#include <stdint.h>
+
+#include <openthread/error.h>
+#include <openthread/instance.h>
+#include <openthread/thread_direct.h>
+#include <openthread/platform/radio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup plat-thread-direct
+ *
+ * @brief
+ *   This module includes the platform abstraction for Thread Direct.
+ *
+ * @{
+ *
+ */
+
+/**
+ * Pre-configures the IE payload to inject into the Enh-ACK sent in response
+ * to a TD Link Command frame received from @p aWiExtAddress.
+ *
+ * The stack calls this during the connection window, before the TD Link Command
+ * is expected, because the Enh-ACK must be transmitted within the 192 us
+ * IEEE 802.15.4 turnaround window.
+ *
+ * Pass @p aIeData = NULL / @p aIeLength = 0 to remove a previously registered
+ * entry for @p aWiExtAddress.
+ *
+ * @param[in] aInstance     The OpenThread instance.
+ * @param[in] aWiExtAddress Extended address of the WI peer.
+ * @param[in] aIeData       IE payload bytes to inject, or NULL to remove.
+ * @param[in] aIeLength     Length of @p aIeData in bytes (0 to remove).
+ *
+ * @retval OT_ERROR_NONE             Entry registered or removed successfully.
+ * @retval OT_ERROR_NO_BUFS         Platform Enh-ACK IE table is full.
+ * @retval OT_ERROR_NOT_FOUND       @p aIeData is NULL and no entry exists for @p aWiExtAddress.
+ * @retval OT_ERROR_NOT_IMPLEMENTED Feature is not implemented.
+ */
+otError otPlatRadioConfigureThreadDirectEnhAckIe(otInstance         *aInstance,
+                                                 const otExtAddress *aWiExtAddress,
+                                                 const uint8_t      *aIeData,
+                                                 uint16_t            aIeLength);
+
+/**
+ * Enables or disables the Scheduled Listen Window (SLW) receive schedule for
+ * the Thread Direct link with @p aWiExtAddress.
+ *
+ * Called by the WL after a TD link is established to program the platform with
+ * its SLW period.  Pass @p aSlwPeriod = 0 to disable SLW scheduling for this
+ * peer.
+ *
+ * @param[in] aInstance      The OpenThread instance.
+ * @param[in] aSlwPeriod     SLW period in 160 us slots (0 = disable).
+ * @param[in] aWiExtAddress  WI peer extended address.
+ *
+ * @retval OT_ERROR_NONE             SLW schedule updated.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  Feature is not implemented.
+ */
+otError otPlatRadioEnableThreadDirectSlw(otInstance *aInstance, uint16_t aSlwPeriod, const otExtAddress *aWiExtAddress);
+
+/**
+ * Updates the next SLW sample time for the Thread Direct link with @p aWiExtAddress.
+ *
+ * Called after each received or missed frame to advance the window to the next
+ * expected arrival time.  @p aSlwSampleTime is in microseconds on the local
+ * radio clock (see `otPlatRadioGetNow()`).
+ *
+ * @param[in] aInstance      The OpenThread instance.
+ * @param[in] aWiExtAddress  WI peer extended address.
+ * @param[in] aSlwSampleTime Next expected frame arrival time in us.
+ */
+void otPlatRadioUpdateThreadDirectSlwSampleTime(otInstance         *aInstance,
+                                                const otExtAddress *aWiExtAddress,
+                                                uint32_t            aSlwSampleTime);
+
+/**
+ * Returns the worst-case clock accuracy of the local radio in PPM for Thread
+ * Direct SLW transmit scheduling.
+ *
+ * Used by the WI to calculate the guard time when scheduling a unicast TX to
+ * arrive within the WL's SLW window.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ *
+ * @returns Worst-case clock accuracy in PPM.
+ */
+uint8_t otPlatRadioGetThreadDirectSlwAccuracy(otInstance *aInstance);
+
+/**
+ * Returns the fixed arrival-time uncertainty for Thread Direct SLW frames in
+ * units of 10 us.
+ *
+ * Used by the WI alongside `otPlatRadioGetThreadDirectSlwAccuracy()` to compute
+ * the total guard window.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ *
+ * @returns Fixed SLW arrival-time uncertainty in units of 10 us.
+ */
+uint8_t otPlatRadioGetThreadDirectSlwUncertainty(otInstance *aInstance);
+
+/**
+ * Retrieves the current Radio Availability Mask (RAM) parameters from the
+ * platform radio driver.
+ *
+ * Called when `OPENTHREAD_CONFIG_THREAD_DIRECT_COEX_ENABLE` is set.  The
+ * platform fills @p aParams with the current CoEx constraints (bitmap of
+ * unavailable slots within the SLW period, signed offset, and RAM Duration
+ * code).  Platforms without CoEx support may return `OT_ERROR_NOT_IMPLEMENTED`.
+ *
+ * @param[in]  aInstance  The OpenThread instance.
+ * @param[out] aParams    Filled with current CoEx constraints.
+ *
+ * @retval OT_ERROR_NONE             @p aParams populated.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  Feature is not implemented.
+ */
+otError otPlatRadioGetThreadDirectRamParams(otInstance *aInstance, otThreadDirectRamParams *aParams);
+
+/**
+ * @}
+ *
+ */
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // OPENTHREAD_PLATFORM_THREAD_DIRECT_H_

include/openthread/thread_direct.h

@@ -91,8 +91,10 @@ typedef struct otThreadDirectPeerInfo
  */
 typedef enum otThreadDirectEvent
 {
-    OT_THREAD_DIRECT_EVENT_LINK_FAILED   = 0, ///< Wake attempt failed (timeout or authentication failure).
-    OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED = 1, ///< WL received a TD Wake Command from a WI peer.
+    OT_THREAD_DIRECT_EVENT_LINKED        = 0, ///< Thread Direct link successfully established.
+    OT_THREAD_DIRECT_EVENT_LINK_FAILED   = 1, ///< Wake attempt failed (timeout or authentication failure).
+    OT_THREAD_DIRECT_EVENT_UNLINKED      = 2, ///< Thread Direct link torn down (supervision timeout or teardown frame).
+    OT_THREAD_DIRECT_EVENT_WAKE_RECEIVED = 3, ///< WL received a TD Wake Command from a WI peer.
 } otThreadDirectEvent;
 
 /**
@@ -141,7 +143,8 @@ typedef enum
  * Transmits Wake Frames of type @p aWakeType at @p aIntervalUs for @p aDurationMs.
  * When @p aWakeType is OT_THREAD_DIRECT_WAKE_TYPE_LINK, a connection window is opened
  * after the burst; the registered event callback (see otThreadDirectSetEventCallback())
- * fires OT_THREAD_DIRECT_EVENT_LINK_FAILED if the window expires without a response.
+ * fires OT_THREAD_DIRECT_EVENT_LINKED on receipt of a TD Link Command, or
+ * OT_THREAD_DIRECT_EVENT_LINK_FAILED if the window expires without a response.
  *
  * Pass @p aIntervalUs = 0 to use OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INTERVAL_US.
  * Pass @p aDurationMs = 0 to use OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_DURATION_MS.
@@ -228,6 +231,127 @@ bool otThreadDirectIsWakeListenerEnabled(otInstance *aInstance);
  */
 bool otThreadDirectIsWakeBurstActive(otInstance *aInstance);
 
+/**
+ * Configures the Scheduled Listen Window (SLW) period this device advertises to
+ * its peer in the SCA LTV.  Both WI and WL may call this function.
+ *
+ * Requires `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE` or
+ * `OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE`.
+ *
+ * Phase is a dynamic, stack-computed value (time until the next SLW window at
+ * frame-build time) and is not configurable by the application.
+ *
+ * Passing @p aSlwPeriodSlots = 0 clears the schedule and causes a teardown SCA LTV
+ * (empty payload) to be sent in the next frame to each peer.
+ *
+ * @param[in] aInstance        The OpenThread instance.
+ * @param[in] aSlwPeriodSlots  SLW period in 160 us slots (0 = clear schedule).
+ *
+ * @retval OT_ERROR_NONE          Schedule updated.
+ * @retval OT_ERROR_INVALID_ARGS  @p aSlwPeriodSlots is non-zero and below the minimum.
+ */
+otError otThreadDirectSetSlwSchedule(otInstance *aInstance, uint16_t aSlwPeriodSlots);
+
+/**
+ * Represents the Radio Availability Mask (RAM) parameters this device will
+ * advertise in outgoing SCA LTVs.
+ *
+ * RAM Duration semantics (valid stored values):
+ *   1    - device has no CoEx constraints (no bitmap transmitted); this is the default.
+ *   2-31 - CoEx bitmap present; (mDuration + 1) bits are valid in mBits.
+ *
+ * Note: mDuration = 0 ("no change to prior RAM") is a wire-encoding sentinel and
+ * is NOT a valid value for otThreadDirectSetRamOverride().
+ */
+typedef struct otThreadDirectRamParams
+{
+    int16_t mOffsetUs; ///< RAM Offset in us, signed [-1024, 1023].
+    uint8_t mDuration; ///< RAM Duration code (1 = no constraints, 2-31 = CoEx bitmap).
+    uint8_t mBits[4];  ///< RAM bitmap bytes (used when mDuration >= 2).
+} otThreadDirectRamParams;
+
+/**
+ * Represents the full local SCA state as advertised in outgoing SCA LTVs.
+ */
+typedef struct otThreadDirectLocalSca
+{
+    uint16_t                mSlwPeriodSlots; ///< SLW period in 160 us slots (0 = not configured).
+    otThreadDirectRamParams mRam;            ///< RAM parameters.
+} otThreadDirectLocalSca;
+
+/**
+ * Overrides the RAM parameters this device advertises in outgoing SCA LTVs.
+ *
+ * Intended for testing and for platforms where the CoEx schedule is managed at
+ * the application layer.  When `OPENTHREAD_CONFIG_THREAD_DIRECT_COEX_ENABLE`
+ * is enabled, the stack obtains RAM parameters from the platform radio driver
+ * at SCA LTV build time; this override does not apply.
+ *
+ * Pass @p aParams->mDuration = 1 to explicitly clear CoEx constraints.
+ * @p aParams->mDuration = 0 is invalid (wire-encoding sentinel; not storable).
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ * @param[in] aParams    RAM parameters to store.
+ *
+ * @retval OT_ERROR_NONE          Parameters stored.
+ * @retval OT_ERROR_INVALID_ARGS  @p aParams is NULL, @p aParams->mDuration is 0,
+ *                                @p aParams->mDuration is outside [1, 31], or
+ *                                @p aParams->mOffsetUs is outside [-1024, 1023].
+ */
+otError otThreadDirectSetRamOverride(otInstance *aInstance, const otThreadDirectRamParams *aParams);
+
+/**
+ * Gets the local SCA state (SLW schedule and RAM parameters) this device advertises.
+ *
+ * @param[in]  aInstance   The OpenThread instance.
+ * @param[out] aLocalSca   Populated with the local SCA state.
+ *
+ * @retval OT_ERROR_NONE  @p aLocalSca populated.
+ */
+otError otThreadDirectGetLocalSca(otInstance *aInstance, otThreadDirectLocalSca *aLocalSca);
+
+/**
+ * Returns the SLW link inactivity timeout in seconds.
+ *
+ * The timeout is the number of seconds without receiving a unicast frame from
+ * a WI peer before the stack tears down the TD link and stops the SLW schedule.
+ * 0 means the timeout has not been explicitly set and the default from
+ * OPENTHREAD_CONFIG_THREAD_DIRECT_SLW_TIMEOUT applies.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ *
+ * @returns The current SLW timeout in seconds.
+ */
+uint32_t otThreadDirectGetSlwTimeout(otInstance *aInstance);
+
+/**
+ * Sets the SLW link inactivity timeout in seconds.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ * @param[in] aTimeout   Timeout in seconds.  0 restores the compile-time
+ *                       default (OPENTHREAD_CONFIG_THREAD_DIRECT_SLW_TIMEOUT).
+ *
+ * @retval OT_ERROR_NONE          Timeout updated.
+ * @retval OT_ERROR_INVALID_ARGS  @p aTimeout exceeds
+ *                                OPENTHREAD_CONFIG_THREAD_DIRECT_SLW_MAX_TIMEOUT.
+ */
+otError otThreadDirectSetSlwTimeout(otInstance *aInstance, uint32_t aTimeout);
+
+/**
+ * Gets the current SLW schedule and link state of an established Thread Direct peer.
+ *
+ * @param[in]  aInstance    The OpenThread instance.
+ * @param[in]  aExtAddress  Extended address of the peer.
+ * @param[out] aPeerInfo    Output structure populated with peer state.
+ *
+ * @retval OT_ERROR_NONE             @p aPeerInfo populated.
+ * @retval OT_ERROR_NOT_FOUND        No established link to @p aExtAddress.
+ * @retval OT_ERROR_NOT_IMPLEMENTED  Feature is not implemented.
+ */
+otError otThreadDirectGetPeerInfo(otInstance             *aInstance,
+                                  const otExtAddress     *aExtAddress,
+                                  otThreadDirectPeerInfo *aPeerInfo);
+
 /**
  * Adds or replaces a guest Wake Key at the given key index.
  *
@@ -243,6 +367,7 @@ bool otThreadDirectIsWakeBurstActive(otInstance *aInstance);
  * @retval OT_ERROR_INVALID_ARGS      @p aKeyIndex is outside [130, 192].
  * @retval OT_ERROR_NO_BUFS           Guest key table is full.
  * @retval OT_ERROR_DISABLED_FEATURE  OPENTHREAD_CONFIG_THREAD_DIRECT_GUEST_WAKE_KEY_ENABLE = 0.
+ * @retval OT_ERROR_NOT_IMPLEMENTED   Feature is not implemented.
  */
 otError otThreadDirectSetGuestWakeKey(otInstance *aInstance, uint8_t aKeyIndex, const otThreadDirectWakeKey *aKey);