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 #ifndef WAKEUP_TX_SCHEDULER_HPP_ 30 #define WAKEUP_TX_SCHEDULER_HPP_ 31 32 #include "openthread-core-config.h" 33 34 #if OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE 35 36 #include "common/locator.hpp" 37 #include "common/non_copyable.hpp" 38 #include "common/timer.hpp" 39 #include "mac/mac.hpp" 40 41 namespace ot { 42 43 class Child; 44 45 /** 46 * Implements wake-up sequence TX scheduling functionality. 47 */ 48 class WakeupTxScheduler : public InstanceLocator, private NonCopyable 49 { 50 friend class Mac::Mac; 51 52 public: 53 /** 54 * Initializes the wake-up sequence TX scheduler object. 55 * 56 * @param[in] aInstance A reference to the OpenThread instance. 57 */ 58 explicit WakeupTxScheduler(Instance &aInstance); 59 60 /** 61 * Initiates the wake-up sequence to a Wake-up End Device. 62 * 63 * @param[in] aWedAddress The extended address of the Wake-up End Device. 64 * @param[in] aIntervalUs An interval between consecutive wake-up frames (in microseconds). 65 * @param[in] aDurationMs Duration of the wake-up sequence (in milliseconds). 66 * 67 * @retval kErrorNone Successfully started the wake-up sequence. 68 * @retval kErrorInvalidState This or another device is currently being woken-up. 69 */ 70 Error WakeUp(const Mac::ExtAddress &aWedAddress, uint16_t aIntervalUs, uint16_t aDurationMs); 71 72 /** 73 * Returns the connection window used by this device. 74 * 75 * The connection window is amount of time that this device waits for an initial link establishment message after 76 * sending the last wake-up frame. 77 * 78 * @returns Connection window in the units of microseconds. 79 */ GetConnectionWindowUs(void) const80 uint32_t GetConnectionWindowUs(void) const 81 { 82 return mIntervalUs * kConnectionRetryInterval * kConnectionRetryCount; 83 } 84 85 /** 86 * Returns the end of the wake-up sequence time. 87 * 88 * @returns End of the wake-up sequence time. 89 */ GetTxEndTime(void) const90 TimeMicro GetTxEndTime(void) const { return mTxEndTimeUs; } 91 92 /** 93 * Stops the ongoing wake-up sequence. 94 */ 95 void Stop(void); 96 97 /** 98 * Updates the value of `mTxRequestAheadTimeUs`, based on bus speed, bus latency and `Mac::kCslRequestAhead`. 99 */ 100 void UpdateFrameRequestAhead(void); 101 102 private: 103 constexpr static uint8_t kConnectionRetryInterval = OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_CONNECTION_RETRY_INTERVAL; 104 constexpr static uint8_t kConnectionRetryCount = OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_CONNECTION_RETRY_COUNT; 105 constexpr static uint32_t kWakeupFrameLength = 54; // Includes SHR 106 constexpr static bool kWakeupFrameTxCca = OPENTHREAD_CONFIG_WAKEUP_FRAME_TX_CCA_ENABLE; 107 constexpr static uint32_t kParentRequestLength = 78; // Includes SHR 108 109 // Called by the MAC layer when a wake-up frame transmission is about to be started. 110 Mac::TxFrame *PrepareWakeupFrame(Mac::TxFrames &aTxFrames); 111 112 // Called at the beginning of a wake-up sequence and right after a wake-up frame has been prepared for transmission. 113 void ScheduleTimer(void); 114 115 void RequestWakeupFrameTransmission(void); 116 117 using WakeupTimer = TimerMicroIn<WakeupTxScheduler, &WakeupTxScheduler::RequestWakeupFrameTransmission>; 118 119 Mac::ExtAddress mWedAddress; 120 TimeMicro mTxTimeUs; // Point in time when the next TX occurs. 121 TimeMicro mTxEndTimeUs; // Point in time when the wake-up sequence is over. 122 uint16_t mTxRequestAheadTimeUs; // How much ahead the TX MAC operation needs to be requested. 123 uint16_t mIntervalUs; // Interval between consecutive wake-up frames. 124 WakeupTimer mTimer; 125 bool mIsRunning; 126 }; 127 128 } // namespace ot 129 130 #endif // OPENTHREAD_CONFIG_WAKEUP_COORDINATOR_ENABLE 131 132 #endif // WAKEUP_TX_SCHEDULER_HPP_ 133