[low-power] enhance mCslFrameRequestAheadUs calculation for RCP

Implement `otPlatRadioGetBusLatency` and `otPlatRadioSetBusLatency`
APIs, add optional latency arguments to ot-daemon and `rcp latency`
CLI commands.

Add APIs to update frame request ahead from runtime, which
recalculate `mCslFrameRequestAheadUs` value.

Changes allow setting a bus latency while starting a new session
between host and RCP device. This way, one host can be connected
to different devices and vice versa, ensuring that the latency
will be added to `mCslFrameRequestAheadUs` calculations and CSL
tx requests will not be sent too late.

Signed-off-by: Maciej Baczmanski <maciej.baczmanski@nordicsemi.no>

Author: maciejbaczmanski

include/openthread/instance.h

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

include/openthread/platform/radio.h

@@ -757,6 +757,28 @@ uint64_t otPlatRadioGetNow(otInstance *aInstance);
  */
 uint32_t otPlatRadioGetBusSpeed(otInstance *aInstance);
 
+/**
+ * Get the bus latency in microseconds between the host and the radio chip.
+ *
+ * @param[in]   aInstance    A pointer to an OpenThread instance.
+ *
+ * @returns The bus latency in microseconds between the host and the radio chip.
+ *          Return 0 when the MAC and above layer and Radio layer resides on the same chip.
+ *
+ */
+uint32_t otPlatRadioGetBusLatency(otInstance *aInstance);
+
+/**
+ * Set the bus latency in microseconds between the host and the radio chip.
+ *
+ * @note This function does not do anything when the MAC and above layer and Radio layer resides on the same chip.
+ *
+ * @param[in]   aInstance    A pointer to an OpenThread instance.
+ * @param[in]   aLatency     Bus latency in microseconds.
+ *
+ */
+void otPlatRadioSetBusLatency(otInstance *aInstance, uint32_t aLatency);
+
 /**
  * @}
  *

include/openthread/thread_ftd.h

@@ -953,6 +953,15 @@ void otThreadGetNextHopAndPathCost(otInstance *aInstance,
                                    uint16_t   *aNextHopRloc16,
                                    uint8_t    *aPathCost);
 
+/**
+ * Calculates and updates value of CSL Frame Request Ahead, based on bus speed, bus latency and
+ * `OPENTHREAD_CONFIG_MAC_CSL_REQUEST_AHEAD_US`.
+ *
+ * @param[in] aInstance A pointer to an OpenThread instance.
+ *
+ */
+void otThreaUpdateFrameRequestAhead(otInstance *aInstance);
+
 /**
  * @}
  *

src/cli/README.md

@@ -3218,6 +3218,25 @@ OPENTHREAD/20191113-00825-g82053cc9d-dirty; SIMULATION; Jun  4 2020 17:53:16
 Done
 ```
 
+### rcp latency
+
+Get the bus latency in microseconds between the host and the radio chip.
+
+```bash
+> rcp latency
+0
+Done
+```
+
+### rcp latency \<latency\>
+
+Set the bus latency in microseconds between the host and the radio chip.
+
+```bash
+> rcp latency 1000
+Done
+```
+
 ### releaserouterid \<routerid\>
 
 Release a Router ID that has been allocated by the device in the Leader role.

src/cli/cli.cpp

@@ -5928,7 +5928,29 @@ template <> otError Interpreter::Process<Cmd("rcp")>(Arg aArgs[])
     {
         OutputLine("%s", version);
     }
-
+#if OPENTHREAD_FTD && OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
+    /**
+     * @cli rcp latency (get,set)
+     * @code
+     * rcp latency
+     * 0
+     * Done
+     * @endcode
+     * @code
+     * rcp latency 1000
+     * Done
+     * @endcode
+     * @cparam rcp latency [@ca{latency}]
+     * @par
+     * Gets or sets the bus latency in microseconds between the host and the radio chip.
+     * @sa otPlatRadioGetBusLatency
+     * @sa otPlatRadioSetBusLatency
+     */
+    else if (aArgs[0] == "latency")
+    {
+        SuccessOrExit(error = ProcessGetSet(aArgs + 1, otPlatRadioGetBusLatency, otPlatRadioSetBusLatency));
+    }
+#endif
     else
     {
         error = OT_ERROR_INVALID_ARGS;

src/core/api/thread_ftd_api.cpp

@@ -428,4 +428,12 @@ void otThreadGetNextHopAndPathCost(otInstance *aInstance,
         (aPathCost != nullptr) ? *aPathCost : pathcost);
 }
 
+#if OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
+void otThreaUpdateFrameRequestAhead(otInstance *aInstance)
+{
+    AsCoreType(aInstance).Get<CslTxScheduler>().UpdateFrameRequestAhead();
+}
+
+#endif // OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
+
 #endif // OPENTHREAD_FTD

src/core/radio/radio_platform.cpp

@@ -250,6 +250,19 @@ OT_TOOL_WEAK uint32_t otPlatRadioGetBusSpeed(otInstance *aInstance)
     return 0;
 }
 
+OT_TOOL_WEAK uint32_t otPlatRadioGetBusLatency(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+
+    return 0;
+}
+
+OT_TOOL_WEAK void otPlatRadioSetBusLatency(otInstance *aInstance, uint32_t aLatency)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aLatency);
+}
+
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
 OT_TOOL_WEAK otError otPlatRadioResetCsl(otInstance *aInstance)
 {

src/core/thread/csl_tx_scheduler.cpp

@@ -32,6 +32,7 @@
 
 #include "common/locator_getters.hpp"
 #include "common/log.hpp"
+#include "common/num_utils.hpp"
 #include "common/time.hpp"
 #include "mac/mac.hpp"
 
@@ -68,16 +69,20 @@ CslTxScheduler::CslTxScheduler(Instance &aInstance)
     , mFrameContext()
     , mCallbacks(aInstance)
 {
-    InitFrameRequestAhead();
+    UpdateFrameRequestAhead();
 }
 
-void CslTxScheduler::InitFrameRequestAhead(void)
+void CslTxScheduler::UpdateFrameRequestAhead(void)
 {
     uint32_t busSpeedHz = otPlatRadioGetBusSpeed(&GetInstance());
+    uint32_t busLatency = otPlatRadioGetBusLatency(&GetInstance());
+
     // longest frame on bus is 127 bytes with some metadata, use 150 bytes for bus Tx time estimation
     uint32_t busTxTimeUs = ((busSpeedHz == 0) ? 0 : (150 * 8 * 1000000 + busSpeedHz - 1) / busSpeedHz);
 
-    mCslFrameRequestAheadUs = OPENTHREAD_CONFIG_MAC_CSL_REQUEST_AHEAD_US + busTxTimeUs;
+    mCslFrameRequestAheadUs = OPENTHREAD_CONFIG_MAC_CSL_REQUEST_AHEAD_US + busTxTimeUs + busLatency;
+    LogInfo("Bus TX Time: %lu usec, Latency: %lu usec. Calculated CSL Frame Request Ahead: %lu usec",
+            ToUlong(busTxTimeUs), ToUlong(busLatency), ToUlong(mCslFrameRequestAheadUs));
 }
 
 void CslTxScheduler::Update(void)

src/core/thread/csl_tx_scheduler.hpp

@@ -231,11 +231,17 @@ class CslTxScheduler : public InstanceLocator, private NonCopyable
      */
     void Clear(void);
 
+    /**
+     * Updates the value of `mCslFrameRequestAheadUs`, based on bus speed, bus latency
+     * and `OPENTHREAD_CONFIG_MAC_CSL_REQUEST_AHEAD_US`.
+     *
+     */
+    void UpdateFrameRequestAhead(void);
+
 private:
     // Guard time in usec to add when checking delay while preparing the CSL frame for tx.
     static constexpr uint32_t kFramePreparationGuardInterval = 1500;
 
-    void InitFrameRequestAhead(void);
     void RescheduleCslTx(void);
 
     uint32_t GetNextCslTransmissionDelay(const Child &aChild, uint32_t &aDelayFromLastRx, uint32_t aAheadUs) const;

src/lib/spinel/radio_spinel.cpp

@@ -78,6 +78,7 @@ RadioSpinel::RadioSpinel(void)
     , mPanId(0xffff)
     , mChannel(0)
     , mRxSensitivity(0)
+    , mBusLatency(0)
     , mState(kStateDisabled)
     , mIsPromiscuous(false)
     , mRxOnWhenIdle(true)
@@ -1903,6 +1904,10 @@ uint64_t RadioSpinel::GetNow(void) { return (mIsTimeSynced) ? (otPlatTimeGet() +
 
 uint32_t RadioSpinel::GetBusSpeed(void) const { return GetSpinelDriver().GetSpinelInterface()->GetBusSpeed(); }
 
+uint32_t RadioSpinel::GetBusLatency(void) const { return mBusLatency; }
+
+void RadioSpinel::SetBusLatency(uint32_t aLatency) { mBusLatency = aLatency; }
+
 void RadioSpinel::HandleRcpUnexpectedReset(spinel_status_t aStatus)
 {
     OT_UNUSED_VARIABLE(aStatus);

src/lib/spinel/radio_spinel.hpp

@@ -857,6 +857,22 @@ class RadioSpinel : private Logger
      */
     uint32_t GetBusSpeed(void) const;
 
+    /**
+     * Returns the bus latency between the host and the radio.
+     *
+     * @returns   Bus latency in microseconds.
+     *
+     */
+    uint32_t GetBusLatency(void) const;
+
+    /**
+     * Sets the bus latency between the host and the radio.
+     *
+     * @param[in]   aLatency  Bus latency in microseconds.
+     *
+     */
+    void SetBusLatency(uint32_t aLatency);
+
     /**
      * Returns the co-processor sw version string.
      *
@@ -1254,6 +1270,8 @@ class RadioSpinel : private Logger
     static otExtAddress sIeeeEui64;
     static otRadioCaps  sRadioCaps;
 
+    uint32_t mBusLatency;
+
     State mState;
     bool  mIsPromiscuous : 1; ///< Promiscuous mode.
     bool  mRxOnWhenIdle : 1;  ///< RxOnWhenIdle mode.

src/posix/platform/radio.cpp

@@ -36,6 +36,7 @@
 #include <string.h>
 
 #include <openthread/logging.h>
+#include <openthread/thread_ftd.h>
 #include <openthread/platform/diag.h>
 
 #include "common/code_utils.hpp"
@@ -130,6 +131,13 @@ void Radio::ProcessRadioUrl(const RadioUrl &aRadioUrl)
         SuccessOrDie(otPlatRadioSetRegion(gInstance, regionCode));
     }
 
+    if (aRadioUrl.HasParam("bus-latency"))
+    {
+        uint32_t busLatency;
+        SuccessOrDie(aRadioUrl.ParseUint32("bus-latency", busLatency));
+        mRadioSpinel.SetBusLatency(busLatency);
+    }
+
     ProcessMaxPowerTable(aRadioUrl);
 
 #if OPENTHREAD_CONFIG_PLATFORM_RADIO_COEX_ENABLE
@@ -900,6 +908,22 @@ uint32_t otPlatRadioGetBusSpeed(otInstance *aInstance)
     return GetRadioSpinel().GetBusSpeed();
 }
 
+uint32_t otPlatRadioGetBusLatency(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    return GetRadioSpinel().GetBusLatency();
+}
+
+void otPlatRadioSetBusLatency(otInstance *aInstance, uint32_t aLatency)
+{
+    GetRadioSpinel().SetBusLatency(aLatency);
+#if OPENTHREAD_FTD && OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
+    otThreaUpdateFrameRequestAhead(aInstance);
+#else
+    OT_UNUSED_VARIABLE(aInstance);
+#endif
+}
+
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE || OPENTHREAD_CONFIG_MAC_CSL_TRANSMITTER_ENABLE
 uint8_t otPlatRadioGetCslAccuracy(otInstance *aInstance)
 {

src/posix/platform/radio_url.cpp

@@ -121,6 +121,7 @@ const char *otSysGetRadioUrlHelpString(void)
            "    fem-lnagain[=dbm]             Set the Rx LNA gain in dBm of the external FEM.\n"
            "    no-reset                      Do not send Spinel reset command to RCP on initialization.\n"
            "    skip-rcp-compatibility-check  Skip checking RCP API version and capabilities during initialization.\n"
+           "    bus-latency[=usec]            Communication latency in usec, default is 0.\n"
 #if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
            "    iid                           Set the Spinel Interface ID for this process. Valid values are 0-3.\n"
            "    iid-list                      List of IIDs a host can subscribe to receive spinel frames other than \n"