[low-power] add csl debug option (#5455)

This commit adds a option to debug CSL feature. When the option is
turned on, a CSL receiver wouldn't actually sleep so that it could
receive all packets from its parent and know the tx time.

etc/cmake/options.cmake

@@ -107,6 +107,11 @@ if(OT_CSL_RECEIVER)
     target_compile_definitions(ot-config INTERFACE "OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE=1")
 endif()
 
+option(OT_CSL_DEBUG "enable csl debug")
+if(OT_CSL_DEBUG)
+    target_compile_definitions(ot-config INTERFACE "OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE=1")
+endif()
+
 option(OT_DHCP6_CLIENT "enable DHCP6 client support")
 if(OT_DHCP6_CLIENT)
     target_compile_definitions(ot-config INTERFACE "OPENTHREAD_CONFIG_DHCP6_CLIENT_ENABLE=1")

examples/common-switches.mk

@@ -134,6 +134,10 @@ ifeq ($(CSL_RECEIVER),1)
 COMMONCFLAGS                   += -DOPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE=1
 endif
 
+ifeq ($(CSL_DEBUG),1)
+COMMONCFLAGS                   += -DOPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE=1
+endif
+
 ifeq ($(DEBUG),1)
 configure_OPTIONS              += --enable-debug --disable-optimization
 endif

src/core/config/mac.h

@@ -324,8 +324,6 @@
 #define OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE 0
 #endif
 
-#if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
-
 /**
  * @def OPENTHREAD_CONFIG_MAC_CSL_MIN_PERIOD
  *
@@ -366,6 +364,15 @@
 #define OPENTHREAD_CONFIG_CSL_SAMPLE_WINDOW 5
 #endif
 
-#endif // OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
+/**
+ * @def OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+ *
+ * CSL receiver debug option. When this option is enabled, a CSL receiver wouldn't actually sleep in CSL state so it
+ * can still receive packets from the CSL transmitter.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+#define OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE 0
+#endif
 
 #endif // CONFIG_MAC_H_

src/core/config/openthread-core-config-check.h

@@ -517,6 +517,12 @@
 #endif
 #endif // OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
 
+#if OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+#if !OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
+#error "OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE is required for OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE"
+#endif
+#endif
+
 #if OPENTHREAD_CONFIG_DUA_ENABLE && (OPENTHREAD_CONFIG_THREAD_VERSION < OT_THREAD_VERSION_1_2)
 #error "Thread 1.2 or higher version is required for OPENTHREAD_CONFIG_DUA_ENABLE"
 #endif

src/core/mac/sub_mac.cpp

@@ -217,7 +217,9 @@ otError SubMac::CslSample(void)
         error = Get<Radio>().Receive(mCslChannel);
         break;
     case kCslSleep:
-        error = Get<Radio>().Sleep();
+#if !OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+        error = Get<Radio>().Sleep(); // Don't actually sleep for debugging
+#endif
         break;
     case kCslIdle:
         ExitNow(error = OT_ERROR_INVALID_STATE);
@@ -248,6 +250,16 @@ void SubMac::HandleReceiveDone(RxFrame *aFrame, otError aError)
         UpdateFrameCounter(aFrame->mInfo.mRxInfo.mAckFrameCounter);
     }
 
+#if OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+    if (aFrame != nullptr && aError == OT_ERROR_NONE)
+    {
+        otLogDebgMac(
+            "Received frame in state (SubMac %s, CSL %d), timestamp %lu, target sample start time %u, time drift %d",
+            StateToString(mState), mCslState, aFrame->mInfo.mRxInfo.mTimestamp, mCslSampleTime.GetValue(),
+            static_cast<uint32_t>(aFrame->mInfo.mRxInfo.mTimestamp) - mCslSampleTime.GetValue());
+    }
+#endif
+
     mCallbacks.ReceiveDone(aFrame, aError);
 }
 
@@ -905,7 +917,9 @@ void SubMac::HandleCslTimer(void)
         mCslTimer.StartAt(mCslSampleTime, mCslPeriod * kUsPerTenSymbols - kUsPerTenSymbols);
         if (mState == kStateCslSample)
         {
-            IgnoreError(Get<Radio>().Sleep());
+#if !OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
+            IgnoreError(Get<Radio>().Sleep()); // Don't actually sleep for debugging
+#endif
             otLogDebgMac("CSL sleep %u", mCslTimer.GetNow().GetValue());
         }
         break;
@@ -921,7 +935,7 @@ void SubMac::HandleCslTimer(void)
         if (mState == kStateCslSample)
         {
             IgnoreError(Get<Radio>().Receive(mCslChannel));
-            otLogDebgMac("CSL Sample %u", mCslTimer.GetNow().GetValue());
+            otLogDebgMac("CSL sample %u", mCslTimer.GetNow().GetValue());
         }
         break;