1 /*
2  *  Copyright (c) 2020, 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 includes definitions for a time ticker.
32  */
33 
34 #ifndef TIME_TICKER_HPP_
35 #define TIME_TICKER_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include "common/locator.hpp"
40 #include "common/non_copyable.hpp"
41 #include "common/numeric_limits.hpp"
42 #include "common/time.hpp"
43 #include "common/timer.hpp"
44 
45 namespace ot {
46 
47 /**
48  * Represents a time ticker.
49  *
50  * The time ticker emits periodic ticks (with 1 second period interval) to a set of registered tick receiver modules.
51  * The tick receivers (OpenThread objects) are identified by the `Receiver` enumeration. The receiver objects
52  * must provide `HandleTimeTick()` method which would be invoked by `TimeTicker` periodically.
53  *
54  */
55 class TimeTicker : public InstanceLocator, private NonCopyable
56 {
57 public:
58     /**
59      * Represents time tick receivers.
60      *
61      * Contains the list of all OpenThread modules that can be registered as time tick receivers.
62      *
63      */
64     enum Receiver : uint8_t
65     {
66         kMeshForwarder,          ///< `MeshForwarder`
67         kMleRouter,              ///< `Mle::MleRouter`
68         kAddressResolver,        ///< `AddressResolver`
69         kChildSupervisor,        ///< `ChildSupervisor`
70         kIp6FragmentReassembler, ///< `Ip6::Ip6` (handling of fragmented messages)
71         kDuaManager,             ///< `DuaManager`
72         kMlrManager,             ///< `MlrManager`
73         kNetworkDataNotifier,    ///< `NetworkData::Notifier`
74         kIp6Mpl,                 ///< `Ip6::Mpl`
75         kBbrLocal,               ///< `BackboneRouter::Local`
76 
77         kNumReceivers, ///< Number of receivers.
78     };
79 
80     /**
81      * Initializes the `TimeTicker` instance.
82      *
83      */
84     explicit TimeTicker(Instance &aInstance);
85 
86     /**
87      * Registers a receiver with `TimeTicker` to receive periodic ticks.
88      *
89      * @param[in] aReceiver   A tick receiver identifier.
90      *
91      */
92     void RegisterReceiver(Receiver aReceiver);
93 
94     /**
95      * Unregisters a receiver with `TimeTicker` to receive periodic ticks.
96      *
97      * @param[in] aReceiver   A tick receiver identifier.
98      *
99      */
100     void UnregisterReceiver(Receiver aReceiver);
101 
102     /**
103      * Indicates whether a receiver is registered with `TimeTicker` to receive periodic ticks.
104      *
105      * @param[in] aReceiver   A tick receiver identifier.
106      *
107      * @retval TRUE   If @p aReceiver is registered with `TimeTicker`.
108      * @retval FALSE  If @p aReceiver is not registered with `TimeTicker`.
109      *
110      */
IsReceiverRegistered(Receiver aReceiver) const111     bool IsReceiverRegistered(Receiver aReceiver) const { return (mReceivers & Mask(aReceiver)) != 0; }
112 
113 private:
114     static constexpr uint32_t kTickInterval  = Time::kOneSecondInMsec;
115     static constexpr uint32_t kRestartJitter = 4; // in msec, jitter added when restarting the timer [-4,+4] ms.
116 
Mask(Receiver aReceiver)117     constexpr static uint32_t Mask(Receiver aReceiver) { return static_cast<uint32_t>(1U) << aReceiver; }
118 
119     void HandleTimer(void);
120 
121     using TickerTimer = TimerMilliIn<TimeTicker, &TimeTicker::HandleTimer>;
122 
123     uint32_t    mReceivers;
124     TickerTimer mTimer;
125 
126     static_assert(kNumReceivers < BitSizeOf(mReceivers), "Too many `Receiver`s - does not fit in a bit mask");
127 };
128 
129 } // namespace ot
130 
131 #endif // TIMER_HPP_
132