[api] allow CSL receiver to gather parent CSL capabilities (#7991)

This commit extends the Thread API to allow a CSL Receiver application
to adjust its CSL parameters depending on the parent capabilities.

Specifically, it might decide to switch to polling operation instead
of CSL synchronization when the attached parent does not support CSL
Transmitter role (Thread Version 2) or it advertises poor CSL accuracy
or uncertainty.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (231)
+#define OPENTHREAD_API_VERSION (232)
 
 /**
  * @addtogroup api-instance

include/openthread/thread.h

@@ -138,6 +138,14 @@ typedef struct
     uint8_t      mAge;                 ///< Time last heard
     bool         mAllocated : 1;       ///< Router ID allocated or not
     bool         mLinkEstablished : 1; ///< Link established with Router ID or not
+    uint8_t      mVersion;             ///< Thread version
+
+    /**
+     * Parent CSL parameters are only relevant when OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE is enabled.
+     *
+     */
+    uint8_t mCslClockAccuracy; ///< CSL clock accuracy, in ± ppm
+    uint8_t mCslUncertainty;   ///< CSL uncertainty, in ±10 us
 } otRouterInfo;
 
 /**

src/cli/README.md

@@ -1995,7 +1995,7 @@ Done
 
 Get the diagnostic information for a Thread Router as parent.
 
-Note: When operating as a Thread Router, this command will return the cached information from when the device was previously attached as a Thread Child. Returning cached information is necessary to support the Thread Test Harness - Test Scenario 8.2.x requests the former parent (i.e. Joiner Router's) MAC address even if the device has already promoted to a router.
+Note: When operating as a Thread Router when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled, this command will return the cached information from when the device was previously attached as a Thread Child. Returning cached information is necessary to support the Thread Test Harness - Test Scenario 8.2.x requests the former parent (i.e. Joiner Router's) MAC address even if the device has already promoted to a router.
 
 ```bash
 > parent
@@ -2004,9 +2004,17 @@ Rloc: 5c00
 Link Quality In: 3
 Link Quality Out: 3
 Age: 20
+Version: 4
 Done
 ```
 
+Note: When `OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE` is enabled, this command will return two extra lines with information relevant for CSL Receiver operation.
+
+```bash
+CSL clock accuracy: 20
+CSL uncertainty: 5
+```
+
 ### parentpriority
 
 Get the assigned parent priority value, -2 means not assigned.

src/cli/cli.cpp

@@ -3787,7 +3787,11 @@ template <> otError Interpreter::Process<Cmd("parent")>(Arg aArgs[])
     OutputLine("Link Quality In: %d", parentInfo.mLinkQualityIn);
     OutputLine("Link Quality Out: %d", parentInfo.mLinkQualityOut);
     OutputLine("Age: %d", parentInfo.mAge);
-
+    OutputLine("Version: %d", parentInfo.mVersion);
+#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
+    OutputLine("CSL clock accuracy: %d", parentInfo.mCslClockAccuracy);
+    OutputLine("CSL uncertainty: %d", parentInfo.mCslUncertainty);
+#endif
 exit:
     return error;
 }

src/core/api/thread_api.cpp

@@ -368,6 +368,11 @@ otError otThreadGetParentInfo(otInstance *aInstance, otRouterInfo *aParentInfo)
     aParentInfo->mAge            = static_cast<uint8_t>(Time::MsecToSec(TimerMilli::GetNow() - parent->GetLastHeard()));
     aParentInfo->mAllocated      = true;
     aParentInfo->mLinkEstablished = parent->IsStateValid();
+    aParentInfo->mVersion         = parent->GetVersion();
+#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
+    aParentInfo->mCslClockAccuracy = parent->GetCslClockAccuracy();
+    aParentInfo->mCslUncertainty   = parent->GetCslUncertainty();
+#endif
 
 #if !OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
 exit:

src/lib/spinel/spinel.h

@@ -2295,7 +2295,7 @@ enum
     SPINEL_PROP_THREAD_LEADER_ADDR = SPINEL_PROP_THREAD__BEGIN + 0,
 
     /// Thread Parent Info
-    /** Format: `ESLccCC` - Read only
+    /** Format: `ESLccCCCCC` - Read only
      *
      *  `E`: Extended address
      *  `S`: RLOC16
@@ -2304,6 +2304,9 @@ enum
      *  `c`: Last RSSI (in dBm)
      *  `C`: Link Quality In
      *  `C`: Link Quality Out
+     *  `C`: Version
+     *  `C`: CSL clock accuracy
+     *  `C`: CSL uncertainty
      *
      */
     SPINEL_PROP_THREAD_PARENT = SPINEL_PROP_THREAD__BEGIN + 1,

src/ncp/ncp_base_mtd.cpp

@@ -806,6 +806,11 @@ template <> otError NcpBase::HandlePropertyGet<SPINEL_PROP_THREAD_PARENT>(void)
             SuccessOrExit(error = mEncoder.WriteInt8(lastRssi));
             SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mLinkQualityIn));
             SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mLinkQualityOut));
+            SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mVersion));
+#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
+            SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mCslClockAccuracy));
+            SuccessOrExit(error = mEncoder.WriteUint8(parentInfo.mCslUncertainty));
+#endif
         }
         else
         {