1 /*
2  *  Copyright (c) 2024, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  *   This file implements the CSL receiver of the subset of IEEE 802.15.4 MAC primitives.
32  */
33 
34 #include "sub_mac.hpp"
35 
36 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
37 
38 #include "instance/instance.hpp"
39 
40 namespace ot {
41 namespace Mac {
42 
43 RegisterLogModule("SubMac");
44 
CslInit(void)45 void SubMac::CslInit(void)
46 {
47     mCslPeriod     = 0;
48     mCslChannel    = 0;
49     mCslPeerShort  = 0;
50     mIsCslSampling = false;
51     mCslSampleTime = TimeMicro{0};
52     mCslLastSync   = TimeMicro{0};
53     mCslTimer.Stop();
54 }
55 
UpdateCslLastSyncTimestamp(TxFrame & aFrame,RxFrame * aAckFrame)56 void SubMac::UpdateCslLastSyncTimestamp(TxFrame &aFrame, RxFrame *aAckFrame)
57 {
58     // Actual synchronization timestamp should be from the sent frame instead of the current time.
59     // Assuming the error here since it is bounded and has very small effect on the final window duration.
60     if (aAckFrame != nullptr && aFrame.HasCslIe())
61     {
62         mCslLastSync = TimeMicro(GetLocalTime());
63     }
64 }
65 
UpdateCslLastSyncTimestamp(RxFrame * aFrame,Error aError)66 void SubMac::UpdateCslLastSyncTimestamp(RxFrame *aFrame, Error aError)
67 {
68     VerifyOrExit(aFrame != nullptr && aError == kErrorNone);
69 
70 #if OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
71     LogReceived(aFrame);
72 #endif
73 
74     // Assuming the risk of the parent missing the Enh-ACK in favor of smaller CSL receive window
75     if ((mCslPeriod > 0) && aFrame->mInfo.mRxInfo.mAckedWithSecEnhAck)
76     {
77 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_LOCAL_TIME_SYNC
78         mCslLastSync = TimerMicro::GetNow();
79 #else
80         mCslLastSync = TimeMicro(static_cast<uint32_t>(aFrame->mInfo.mRxInfo.mTimestamp));
81 #endif
82     }
83 
84 exit:
85     return;
86 }
87 
CslSample(void)88 void SubMac::CslSample(void)
89 {
90 #if OPENTHREAD_CONFIG_MAC_FILTER_ENABLE
91     VerifyOrExit(!mRadioFilterEnabled, IgnoreError(Get<Radio>().Sleep()));
92 #endif
93 
94     SetState(kStateCslSample);
95 
96     if (mIsCslSampling && !RadioSupportsReceiveTiming())
97     {
98         IgnoreError(Get<Radio>().Receive(mCslChannel));
99         ExitNow();
100     }
101 
102 #if !OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
103     IgnoreError(Get<Radio>().Sleep()); // Don't actually sleep for debugging
104 #endif
105 
106 exit:
107     return;
108 }
109 
UpdateCsl(uint16_t aPeriod,uint8_t aChannel,otShortAddress aShortAddr,const otExtAddress * aExtAddr)110 bool SubMac::UpdateCsl(uint16_t aPeriod, uint8_t aChannel, otShortAddress aShortAddr, const otExtAddress *aExtAddr)
111 {
112     bool diffPeriod  = aPeriod != mCslPeriod;
113     bool diffChannel = aChannel != mCslChannel;
114     bool diffPeer    = aShortAddr != mCslPeerShort;
115     bool retval      = diffPeriod || diffChannel || diffPeer;
116 
117     VerifyOrExit(retval);
118     mCslChannel = aChannel;
119 
120     VerifyOrExit(diffPeriod || diffPeer);
121     mCslPeriod    = aPeriod;
122     mCslPeerShort = aShortAddr;
123     IgnoreError(Get<Radio>().EnableCsl(aPeriod, aShortAddr, aExtAddr));
124 
125     mCslTimer.Stop();
126     if (mCslPeriod > 0)
127     {
128         mCslSampleTime = TimeMicro(static_cast<uint32_t>(Get<Radio>().GetNow()));
129         mIsCslSampling = false;
130         HandleCslTimer();
131     }
132 
133 exit:
134     return retval;
135 }
136 
HandleCslTimer(Timer & aTimer)137 void SubMac::HandleCslTimer(Timer &aTimer) { aTimer.Get<SubMac>().HandleCslTimer(); }
138 
HandleCslTimer(void)139 void SubMac::HandleCslTimer(void)
140 {
141     /*
142      * CSL sample timing diagram
143      *    |<---------------------------------Sample--------------------------------->|<--------Sleep--------->|
144      *    |                                                                          |                        |
145      *    |<--Ahead-->|<--UnCert-->|<--Drift-->|<--Drift-->|<--UnCert-->|<--MinWin-->|                        |
146      *    |           |            |           |           |            |            |                        |
147      * ---|-----------|------------|-----------|-----------|------------|------------|----------//------------|---
148      * -timeAhead                           CslPhase                             +timeAfter             -timeAhead
149      *
150      * The handler works in different ways when the radio supports receive-timing and doesn't.
151      *
152      * When the radio supports receive-timing:
153      *   The handler will be called once per CSL period. When the handler is called, it will set the timer to
154      *   fire at the next CSL sample time and call `Radio::ReceiveAt` to start sampling for the current CSL period.
155      *   The timer fires some time before the actual sample time. After `Radio::ReceiveAt` is called, the radio will
156      *   remain in sleep state until the actual sample time.
157      *   Note that it never call `Radio::Sleep` explicitly. The radio will fall into sleep after `ReceiveAt` ends. This
158      *   will be done by the platform as part of the `otPlatRadioReceiveAt` API.
159      *
160      *   Timer fires                                         Timer fires
161      *       ^                                                    ^
162      *       x-|------------|-------------------------------------x-|------------|---------------------------------------|
163      *            sample                   sleep                        sample                    sleep
164      *
165      * When the radio doesn't support receive-timing:
166      *   The handler will be called twice per CSL period: at the beginning of sample and sleep. When the handler is
167      *   called, it will explicitly change the radio state due to the current state by calling `Radio::Receive` or
168      *   `Radio::Sleep`.
169      *
170      *   Timer fires  Timer fires                            Timer fires  Timer fires
171      *       ^            ^                                       ^            ^
172      *       |------------|---------------------------------------|------------|---------------------------------------|
173      *          sample                   sleep                        sample                    sleep
174      */
175     uint32_t periodUs = mCslPeriod * kUsPerTenSymbols;
176     uint32_t timeAhead, timeAfter, winStart, winDuration;
177 
178     GetCslWindowEdges(timeAhead, timeAfter);
179 
180     if (mIsCslSampling)
181     {
182         mIsCslSampling = false;
183         mCslTimer.FireAt(mCslSampleTime - timeAhead);
184         if (mState == kStateCslSample)
185         {
186 #if !OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
187             IgnoreError(Get<Radio>().Sleep()); // Don't actually sleep for debugging
188 #endif
189             LogDebg("CSL sleep %lu", ToUlong(mCslTimer.GetNow().GetValue()));
190         }
191     }
192     else
193     {
194         if (RadioSupportsReceiveTiming())
195         {
196             mCslTimer.FireAt(mCslSampleTime - timeAhead + periodUs);
197             timeAhead -= kCslReceiveTimeAhead;
198             winStart = mCslSampleTime.GetValue() - timeAhead;
199         }
200         else
201         {
202             mCslTimer.FireAt(mCslSampleTime + timeAfter);
203             mIsCslSampling = true;
204             winStart       = ot::TimerMicro::GetNow().GetValue();
205         }
206 
207         winDuration = timeAhead + timeAfter;
208         mCslSampleTime += periodUs;
209 
210         Get<Radio>().UpdateCslSampleTime(mCslSampleTime.GetValue());
211 
212         // Schedule reception window for any state except RX - so that CSL RX Window has lower priority
213         // than scanning or RX after the data poll.
214         if (RadioSupportsReceiveTiming() && (mState != kStateDisabled) && (mState != kStateReceive))
215         {
216             IgnoreError(Get<Radio>().ReceiveAt(mCslChannel, winStart, winDuration));
217         }
218         else if (mState == kStateCslSample)
219         {
220             IgnoreError(Get<Radio>().Receive(mCslChannel));
221         }
222 
223         LogDebg("CSL window start %lu, duration %lu", ToUlong(winStart), ToUlong(winDuration));
224     }
225 }
226 
GetCslWindowEdges(uint32_t & aAhead,uint32_t & aAfter)227 void SubMac::GetCslWindowEdges(uint32_t &aAhead, uint32_t &aAfter)
228 {
229     uint32_t semiPeriod = mCslPeriod * kUsPerTenSymbols / 2;
230     uint32_t curTime, elapsed, semiWindow;
231 
232     curTime = GetLocalTime();
233     elapsed = curTime - mCslLastSync.GetValue();
234 
235     semiWindow =
236         static_cast<uint32_t>(static_cast<uint64_t>(elapsed) *
237                               (Get<Radio>().GetCslAccuracy() + mCslParentAccuracy.GetClockAccuracy()) / 1000000);
238     semiWindow += mCslParentAccuracy.GetUncertaintyInMicrosec() + Get<Radio>().GetCslUncertainty() * 10;
239 
240     aAhead = Min(semiPeriod, semiWindow + kMinReceiveOnAhead + kCslReceiveTimeAhead);
241     aAfter = Min(semiPeriod, semiWindow + kMinReceiveOnAfter);
242 }
243 
GetLocalTime(void)244 uint32_t SubMac::GetLocalTime(void)
245 {
246     uint32_t now;
247 
248 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_LOCAL_TIME_SYNC
249     now = TimerMicro::GetNow().GetValue();
250 #else
251     now = static_cast<uint32_t>(Get<Radio>().GetNow());
252 #endif
253 
254     return now;
255 }
256 
257 #if OPENTHREAD_CONFIG_MAC_CSL_DEBUG_ENABLE
LogReceived(RxFrame * aFrame)258 void SubMac::LogReceived(RxFrame *aFrame)
259 {
260     static constexpr uint8_t kLogStringSize = 72;
261 
262     String<kLogStringSize> logString;
263     Address                dst;
264     int32_t                deviation;
265     uint32_t               sampleTime, ahead, after;
266 
267     IgnoreError(aFrame->GetDstAddr(dst));
268 
269     VerifyOrExit((dst.GetType() == Address::kTypeShort && dst.GetShort() == GetShortAddress()) ||
270                  (dst.GetType() == Address::kTypeExtended && dst.GetExtended() == GetExtAddress()));
271 
272     LogDebg("Received frame in state (SubMac %s, CSL %s), timestamp %lu", StateToString(mState),
273             mIsCslSampling ? "CslSample" : "CslSleep",
274             ToUlong(static_cast<uint32_t>(aFrame->mInfo.mRxInfo.mTimestamp)));
275 
276     VerifyOrExit(mState == kStateCslSample);
277 
278     GetCslWindowEdges(ahead, after);
279     ahead -= kMinReceiveOnAhead + kCslReceiveTimeAhead;
280 
281     sampleTime = mCslSampleTime.GetValue() - mCslPeriod * kUsPerTenSymbols;
282     deviation  = aFrame->mInfo.mRxInfo.mTimestamp + kRadioHeaderPhrDuration - sampleTime;
283 
284     // This logs three values (all in microseconds):
285     // - Absolute sample time in which the CSL receiver expected the MHR of the received frame.
286     // - Allowed margin around that time accounting for accuracy and uncertainty from both devices.
287     // - Real deviation on the reception of the MHR with regards to expected sample time. This can
288     //   be due to clocks drift and/or CSL Phase rounding error.
289     // This means that a deviation absolute value greater than the margin would result in the frame
290     // not being received out of the debug mode.
291     logString.Append("Expected sample time %lu, margin ±%lu, deviation %ld", ToUlong(sampleTime), ToUlong(ahead),
292                      static_cast<long>(deviation));
293 
294     // Treat as a warning when the deviation is not within the margins. Neither kCslReceiveTimeAhead
295     // or kMinReceiveOnAhead/kMinReceiveOnAfter are considered for the margin since they have no
296     // impact on understanding possible deviation errors between transmitter and receiver. So in this
297     // case only `ahead` is used, as an allowable max deviation in both +/- directions.
298     if ((deviation + ahead > 0) && (deviation < static_cast<int32_t>(ahead)))
299     {
300         LogDebg("%s", logString.AsCString());
301     }
302     else
303     {
304         LogWarn("%s", logString.AsCString());
305     }
306 
307 exit:
308     return;
309 }
310 #endif
311 
312 } // namespace Mac
313 } // namespace ot
314 
315 #endif // OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
316