[low-power] extend EnableCsl API (#6675)

Include the peer's short address together with the extended address
when enabling the CSL link. This removes the need for the platform
to guess it.

examples/platforms/simulation/radio.c

@@ -1165,9 +1165,13 @@ static uint8_t generateAckIeData(uint8_t *aLinkMetricsIeData, uint8_t aLinkMetri
 #endif
 
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
-otError otPlatRadioEnableCsl(otInstance *aInstance, uint32_t aCslPeriod, const otExtAddress *aExtAddr)
+otError otPlatRadioEnableCsl(otInstance *        aInstance,
+                             uint32_t            aCslPeriod,
+                             otShortAddress      aShortAddr,
+                             const otExtAddress *aExtAddr)
 {
     OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aShortAddr);
     OT_UNUSED_VARIABLE(aExtAddr);
 
     otError error = OT_ERROR_NONE;

include/openthread/instance.h

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

include/openthread/platform/radio.h

@@ -979,15 +979,20 @@ otError otPlatRadioGetCoexMetrics(otInstance *aInstance, otRadioCoexMetrics *aCo
  *
  * @param[in]  aInstance     The OpenThread instance structure.
  * @param[in]  aCslPeriod    CSL period, 0 for disabling CSL.
- * @param[in]  aExtAddr      The extended source address of CSL receiver's parent device (when the platforms generate
+ * @param[in]  aShortAddr    The short source address of CSL receiver's peer.
- *                           enhanced ack, platforms may need to know acks to which address should include CSL IE).
+ * @param[in]  aExtAddr      The extended source address of CSL receiver's peer.
  *
- * @retval  OT_ERROR_NOT_SUPPORTED  Radio driver doesn't support CSL.
+ * @note Platforms should use CSL peer addresses to include CSL IE when generating enhanced acks.
- * @retval  OT_ERROR_FAILED         Other platform specific errors.
+ *
- * @retval  OT_ERROR_NONE           Successfully enabled or disabled CSL.
+ * @retval  kErrorNotImplemented Radio driver doesn't support CSL.
+ * @retval  kErrorFailed         Other platform specific errors.
+ * @retval  kErrorNone           Successfully enabled or disabled CSL.
  *
  */
-otError otPlatRadioEnableCsl(otInstance *aInstance, uint32_t aCslPeriod, const otExtAddress *aExtAddr);
+otError otPlatRadioEnableCsl(otInstance *        aInstance,
+                             uint32_t            aCslPeriod,
+                             otShortAddress      aShortAddr,
+                             const otExtAddress *aExtAddr);
 
 /**
  * Update CSL sample time in radio driver.

src/core/mac/mac.cpp

@@ -2462,7 +2462,8 @@ void Mac::SetCslPeriod(uint16_t aPeriod)
 
     if (IsCslEnabled())
     {
-        IgnoreError(Get<Radio>().EnableCsl(GetCslPeriod(), &Get<Mle::Mle>().GetParent().GetExtAddress()));
+        IgnoreError(Get<Radio>().EnableCsl(GetCslPeriod(), Get<Mle::Mle>().GetParent().GetRloc16(),
+                                           &Get<Mle::Mle>().GetParent().GetExtAddress()));
         Get<Mle::Mle>().ScheduleChildUpdateRequest();
     }
 

src/core/radio/radio.hpp

@@ -438,15 +438,17 @@ public:
     /** This method enables CSL sampling in radio.
      *
      * @param[in]  aCslPeriod    CSL period, 0 for disabling CSL.
-     * @param[in]  aExtAddr      The extended source address of CSL receiver's parent device (when the platforms
+     * @param[in]  aShortAddr    The short source address of CSL receiver's peer.
-     * generate enhanced ack, platforms may need to know acks to which address should include CSL IE).
+     * @param[in]  aExtAddr      The extended source address of CSL receiver's peer.
+     *
+     * @note Platforms should use CSL peer addresses to include CSL IE when generating enhanced acks.
      *
      * @retval  kErrorNotImplemented Radio driver doesn't support CSL.
      * @retval  kErrorFailed         Other platform specific errors.
      * @retval  kErrorNone           Successfully enabled or disabled CSL.
      *
      */
-    Error EnableCsl(uint32_t aCslPeriod, const otExtAddress *aExtAddr);
+    Error EnableCsl(uint32_t aCslPeriod, otShortAddress aShortAddr, const otExtAddress *aExtAddr);
 
     /**
      * Get the current accuracy, in units of ± ppm, of the clock used for scheduling CSL operations.
@@ -769,9 +771,9 @@ inline Error Radio::ReceiveAt(uint8_t aChannel, uint32_t aStart, uint32_t aDurat
     return otPlatRadioReceiveAt(GetInstancePtr(), aChannel, aStart, aDuration);
 }
 
-inline Error Radio::EnableCsl(uint32_t aCslPeriod, const otExtAddress *aExtAddr)
+inline Error Radio::EnableCsl(uint32_t aCslPeriod, otShortAddress aShortAddr, const otExtAddress *aExtAddr)
 {
-    return otPlatRadioEnableCsl(GetInstancePtr(), aCslPeriod, aExtAddr);
+    return otPlatRadioEnableCsl(GetInstancePtr(), aCslPeriod, aShortAddr, aExtAddr);
 }
 
 inline uint8_t Radio::GetCslAccuracy()
@@ -927,7 +929,7 @@ inline Error Radio::ReceiveAt(uint8_t, uint32_t, uint32_t)
     return kErrorNone;
 }
 
-inline Error Radio::EnableCsl(uint32_t, const otExtAddress *)
+inline Error Radio::EnableCsl(uint32_t, otShortAddress aShortAddr, const otExtAddress *)
 {
     return kErrorNotImplemented;
 }

src/core/thread/mle.cpp

@@ -694,7 +694,8 @@ void Mle::SetStateChild(uint16_t aRloc16)
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
     if (Get<Mac::Mac>().IsCslEnabled())
     {
-        IgnoreError(Get<Radio>().EnableCsl(Get<Mac::Mac>().GetCslPeriod(), &GetParent().GetExtAddress()));
+        IgnoreError(Get<Radio>().EnableCsl(Get<Mac::Mac>().GetCslPeriod(), GetParent().GetRloc16(),
+                                           &GetParent().GetExtAddress()));
         ScheduleChildUpdateRequest();
     }
 #endif

tests/unit/test_platform.cpp

@@ -607,10 +607,14 @@ uint16_t otPlatTimeGetXtalAccuracy(void)
 #endif
 
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
-otError otPlatRadioEnableCsl(otInstance *aInstance, uint32_t aCslPeriod, const otExtAddress *aExtAddr)
+otError otPlatRadioEnableCsl(otInstance *        aInstance,
+                             uint32_t            aCslPeriod,
+                             otShortAddress      aShortAdd,
+                             const otExtAddress *aExtAddr)
 {
     OT_UNUSED_VARIABLE(aInstance);
     OT_UNUSED_VARIABLE(aCslPeriod);
+    OT_UNUSED_VARIABLE(aShortAdd);
     OT_UNUSED_VARIABLE(aExtAddr);
 
     return OT_ERROR_NONE;