1 /* 2 * Copyright (c) 2019, 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 radio selector (for multi radio links). 32 */ 33 34 #ifndef RADIO_SELECTOR_HPP_ 35 #define RADIO_SELECTOR_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_CONFIG_MULTI_RADIO 40 41 #include <openthread/multi_radio.h> 42 43 #include "common/locator.hpp" 44 #include "common/log.hpp" 45 #include "common/message.hpp" 46 #include "mac/mac_frame.hpp" 47 #include "mac/mac_links.hpp" 48 #include "mac/mac_types.hpp" 49 50 namespace ot { 51 52 /** 53 * @addtogroup core-radio-selector 54 * 55 * @brief 56 * This module includes definition for radio selector (for multi radio links). 57 * 58 * @{ 59 */ 60 61 class Neighbor; 62 63 class RadioSelector : InstanceLocator 64 { 65 public: 66 /** 67 * Defines all the neighbor info required for multi radio link and radio selection. 68 * 69 * `Neighbor` class publicly inherits from this class. 70 */ 71 class NeighborInfo 72 { 73 friend class RadioSelector; 74 75 public: 76 /** 77 * Represents multi radio information associated with a neighbor. 78 */ 79 typedef otMultiRadioNeighborInfo MultiRadioInfo; 80 81 /** 82 * Returns the supported radio types by the neighbor. 83 * 84 * @returns The supported radio types set. 85 */ GetSupportedRadioTypes(void) const86 Mac::RadioTypes GetSupportedRadioTypes(void) const { return mSupportedRadioTypes; } 87 88 /** 89 * Retrieves the multi radio information `otMultiRadioNeighborInfo` associated with the neighbor. 90 * 91 * @param[out] aInfo A reference to `MultiRadioInfo` to populate with neighbor info. 92 */ 93 void PopulateMultiRadioInfo(MultiRadioInfo &aInfo); 94 95 private: AddSupportedRadioType(Mac::RadioType aType)96 void AddSupportedRadioType(Mac::RadioType aType) { mSupportedRadioTypes.Add(aType); } RemoveSupportedRadioType(Mac::RadioType aType)97 void RemoveSupportedRadioType(Mac::RadioType aType) { mSupportedRadioTypes.Remove(aType); } ClearSupportedRadioType(void)98 void ClearSupportedRadioType(void) { mSupportedRadioTypes.Clear(); } 99 GetRadioPreference(Mac::RadioType aType) const100 uint8_t GetRadioPreference(Mac::RadioType aType) const { return mRadioPreference[aType]; } SetRadioPreference(Mac::RadioType aType,uint8_t aValue)101 void SetRadioPreference(Mac::RadioType aType, uint8_t aValue) { mRadioPreference[aType] = aValue; } 102 103 Mac::RadioTypes mSupportedRadioTypes; 104 uint8_t mRadioPreference[Mac::kNumRadioTypes]; 105 }; 106 107 /** 108 * Initializes the RadioSelector object. 109 * 110 * @param[in] aInstance A reference to the OpenThread instance. 111 */ 112 explicit RadioSelector(Instance &aInstance); 113 114 /** 115 * Updates the neighbor info (for multi radio support) on a received frame event. 116 * 117 * Notifies `RadioSelector` of a received secure frame/message on a radio link type for neighbor. If 118 * the frame/message happens to be received earlier on another radio link, the `aIsDuplicate` is set to `true`. 119 * A duplicate frame/message should have passed the security check (i.e., tag/MIC should be valid). 120 * 121 * @param[in] aNeighbor The neighbor for which a frame/message was received. 122 * @param[in] aRadioType The radio link type on which the frame/message was received. 123 * @param[in] aIsDuplicate Indicates whether the received frame/message is a duplicate or not. 124 */ 125 void UpdateOnReceive(Neighbor &aNeighbor, Mac::RadioType aRadioType, bool aIsDuplicate); 126 127 /** 128 * Updates the neighbor info (for multi radio support) on a send done event. 129 * 130 * Notifies `RadioSelector` the status of frame transmission on a radio link type. The radio link 131 * type is provided by the `aFrame` itself. 132 * 133 * @param[in] aFrame A transmitted frame. 134 * @param[in] aTxError The transmission error. 135 */ 136 void UpdateOnSendDone(Mac::TxFrame &aFrame, Error aTxError); 137 138 #if OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE 139 /** 140 * Updates the neighbor info (for multi radio support) on a deferred ack event. 141 * 142 * The deferred ack model is used by TREL radio link. 143 * 144 * @param[in] aNeighbor The neighbor from which ack was expected 145 * @param[in] aError The deferred ack status (`kErrorNone` indicates ack was received). 146 * @param[out] aAllowNeighborRemove Boolean variable to output whether the neighbor is allowed to be removed. 147 */ 148 void UpdateOnDeferredAck(Neighbor &aNeighbor, Error aTxError, bool &aAllowNeighborRemove); 149 #endif 150 151 /** 152 * Selects the radio link type for sending a data poll frame to a given parent neighbor. 153 * 154 * @param[in] aParent The parent to which the data poll frame will be sent. 155 * 156 * @returns The radio type on which the data poll frame should be sent. 157 */ 158 Mac::RadioType SelectPollFrameRadio(const Neighbor &aParent); 159 160 /** 161 * Selects the radio link for sending a given message to a specified MAC destination. 162 * 163 * The `aMessage` will be updated to store the selected radio type (please see `Message::GetRadioType()`). 164 * The `aTxFrames` will also be updated to indicate which radio links are to be used. 165 * 166 * @param[in,out] aMessage The message to send. 167 * @param[in] aMacDest The MAC destination address. 168 * @param[in,out] aTxFrames The set of TxFrames for all radio links. 169 * 170 * @returns A reference to `mTxFrame` to use when preparing the frame for tx. 171 */ 172 Mac::TxFrame &SelectRadio(Message &aMessage, const Mac::Address &aMacDest, Mac::TxFrames &aTxFrames); 173 174 private: 175 static constexpr int16_t kPreferenceChangeOnTxError = -35; // Change on a tx error on a radio link. 176 static constexpr int16_t kPreferenceChangeOnTxSuccess = 25; // Change on tx success on a radio link. 177 static constexpr int16_t kPreferenceChangeOnDeferredAckSuccess = 25; // Change on deferred ack success. 178 static constexpr int16_t kPreferenceChangeOnDeferredAckTimeout = -100; // Change on deferred ack timeout. 179 static constexpr int16_t kPreferenceChangeOnRx = 15; // Change on new (secure) rx. 180 static constexpr int16_t kPreferenceChangeOnRxDuplicate = 15; // Change on new (secure) duplicate rx. 181 182 static constexpr uint8_t kMinPreference = 0; // Minimum preference value. 183 static constexpr uint8_t kMaxPreference = 255; // Maximum preference value. 184 static constexpr uint8_t kInitPreference = 200; // Initial preference value 185 static constexpr uint8_t kHighPreference = 220; // High preference. 186 187 static constexpr uint8_t kTrelProbeProbability = 25; // Probability percentage to probe on TREL link 188 189 static constexpr uint16_t kRadioPreferenceStringSize = 75; 190 191 LogLevel UpdatePreference(Neighbor &aNeighbor, Mac::RadioType aRadioType, int16_t aDifference); 192 Mac::RadioType Select(Mac::RadioTypes aRadioOptions, const Neighbor &aNeighbor); 193 void Log(LogLevel aLogLevel, const char *aActionText, Mac::RadioType aType, const Neighbor &aNeighbor); 194 195 static const Mac::RadioType sRadioSelectionOrder[Mac::kNumRadioTypes]; 196 }; 197 198 /** 199 * @} 200 */ 201 202 } // namespace ot 203 204 #endif // #if OPENTHREAD_CONFIG_MULTI_RADIO 205 206 #endif // RADIO_SELECTOR_HPP_ 207
