From 41f051d69b9962a6a45f02b5a7a937434f9a118c Mon Sep 17 00:00:00 2001 From: Li Cao Date: Fri, 17 Mar 2023 00:27:31 +0800 Subject: [PATCH] [csl] add code comment & explanation for `HandleCslTimer` (#8867) --- src/core/mac/sub_mac.cpp | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/core/mac/sub_mac.cpp b/src/core/mac/sub_mac.cpp index 194647023..fb8b6e820 100644 --- a/src/core/mac/sub_mac.cpp +++ b/src/core/mac/sub_mac.cpp @@ -1098,6 +1098,32 @@ void SubMac::HandleCslTimer(void) * | | | | | | | | * ---|-----------|------------|-----------|-----------|------------|------------|----------//------------|--- * -timeAhead CslPhase +timeAfter -timeAhead + * + * The handler works in different ways when the radio supports receive-timing and doesn't. + * + * When the radio supports receive-timing: + * The handler will be called once per CSL period. When the handler is called, it will set the timer to + * fire at the next CSL sample time and call `Radio::ReceiveAt` to start sampling for the current CSL period. + * The timer fires some time before the actual sample time. After `Radio::ReceiveAt` is called, the radio will + * remain in sleep state until the actual sample time. + * Note that it never call `Radio::Sleep` explicitly. The radio will fall into sleep after `ReceiveAt` ends. This + * will be done by the platform as part of the `otPlatRadioReceiveAt` API. + * + * Timer fires Timer fires + * ^ ^ + * x-|------------|-------------------------------------x-|------------|---------------------------------------| + * sample sleep sample sleep + * + * When the radio doesn't support receive-timing: + * The handler will be called twice per CSL period: at the begining of sample and sleep. When the handler is + * called, it will explicitly change the radio state due to the current state by calling `Radio::Receive` or + * `Radio::Sleep`. + * + * Timer fires Timer fires Timer fires Timer fires + * ^ ^ ^ ^ + * |------------|---------------------------------------|------------|---------------------------------------| + * sample sleep sample sleep + * */ uint32_t periodUs = mCslPeriod * kUsPerTenSymbols; uint32_t timeAhead, timeAfter;