/* * Copyright (c) 2016, The OpenThread Authors. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the copyright holder nor the * names of its contributors may be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ /** * @file * This file includes definitions for the Raw Link-Layer class. */ #ifndef LINK_RAW_HPP_ #define LINK_RAW_HPP_ #include "openthread-core-config.h" #if OPENTHREAD_RADIO || OPENTHREAD_CONFIG_LINK_RAW_ENABLE #include #include "common/locator.hpp" #include "common/log.hpp" #include "common/non_copyable.hpp" #include "mac/mac_frame.hpp" #include "mac/sub_mac.hpp" namespace ot { namespace Mac { /** * This class defines the raw link-layer object. * */ class LinkRaw : public InstanceLocator, private NonCopyable { friend class ot::Instance; public: /** * This constructor initializes the object. * * @param[in] aInstance A reference to the OpenThread instance. * */ explicit LinkRaw(Instance &aInstance); /** * This method initializes the states of the raw link-layer. * */ void Init(void); /** * This method returns true if the raw link-layer is enabled. * * @returns true if enabled, false otherwise. * */ bool IsEnabled(void) const { return mReceiveDoneCallback != nullptr; } /** * This method enables/disables the raw link-layer. * * @param[in] aCallback A pointer to a function called on receipt of a IEEE 802.15.4 frame, `nullptr` to disable * raw link-layer. * * * @retval kErrorInvalidState Thread stack is enabled. * @retval kErrorFailed The radio could not be enabled/disabled. * @retval kErrorNone Successfully enabled/disabled raw link. * */ Error SetReceiveDone(otLinkRawReceiveDone aCallback); /** * This method returns the capabilities of the raw link-layer. * * @returns The radio capability bit vector. * */ otRadioCaps GetCaps(void) const { return mSubMac.GetCaps(); } /** * This method starts a (recurring) Receive on the link-layer. * * @retval kErrorNone Successfully transitioned to Receive. * @retval kErrorInvalidState The radio was disabled or transmitting. * */ Error Receive(void); /** * This method invokes the mReceiveDoneCallback, if set. * * @param[in] aFrame A pointer to the received frame or `nullptr` if the receive operation failed. * @param[in] aError kErrorNone when successfully received a frame, * kErrorAbort when reception was aborted and a frame was not received, * kErrorNoBufs when a frame could not be received due to lack of rx buffer space. * */ void InvokeReceiveDone(RxFrame *aFrame, Error aError); /** * This method gets the radio transmit frame. * * @returns The transmit frame. * */ TxFrame &GetTransmitFrame(void) { return mSubMac.GetTransmitFrame(); } /** * This method starts a (single) Transmit on the link-layer. * * @note The callback @p aCallback will not be called if this call does not return kErrorNone. * * @param[in] aCallback A pointer to a function called on completion of the transmission. * * @retval kErrorNone Successfully transitioned to Transmit. * @retval kErrorInvalidState The radio was not in the Receive state. * */ Error Transmit(otLinkRawTransmitDone aCallback); /** * This method invokes the mTransmitDoneCallback, if set. * * @param[in] aFrame The transmitted frame. * @param[in] aAckFrame A pointer to the ACK frame, `nullptr` if no ACK was received. * @param[in] aError kErrorNone when the frame was transmitted, * kErrorNoAck when the frame was transmitted but no ACK was received, * kErrorChannelAccessFailure tx failed due to activity on the channel, * kErrorAbort when transmission was aborted for other reasons. * */ void InvokeTransmitDone(TxFrame &aFrame, RxFrame *aAckFrame, Error aError); /** * This method starts a (single) Energy Scan on the link-layer. * * @param[in] aScanChannel The channel to perform the energy scan on. * @param[in] aScanDuration The duration, in milliseconds, for the channel to be scanned. * @param[in] aCallback A pointer to a function called on completion of a scanned channel. * * @retval kErrorNone Successfully started scanning the channel. * @retval kErrorBusy The radio is performing energy scanning. * @retval kErrorNotImplemented The radio doesn't support energy scanning. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error EnergyScan(uint8_t aScanChannel, uint16_t aScanDuration, otLinkRawEnergyScanDone aCallback); /** * This method invokes the mEnergyScanDoneCallback, if set. * * @param[in] aEnergyScanMaxRssi The max RSSI for energy scan. * */ void InvokeEnergyScanDone(int8_t aEnergyScanMaxRssi); /** * This function returns the short address. * * @returns short address. * */ ShortAddress GetShortAddress(void) const { return mSubMac.GetShortAddress(); } /** * This method updates short address. * * @param[in] aShortAddress The short address. * * @retval kErrorNone If successful. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error SetShortAddress(ShortAddress aShortAddress); /** * This function returns PANID. * * @returns PANID. * */ PanId GetPanId(void) const { return mPanId; } /** * This method updates PANID. * * @param[in] aPanId The PANID. * * @retval kErrorNone If successful. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error SetPanId(PanId aPanId); /** * This method gets the current receiving channel. * * @returns Current receiving channel. * */ uint8_t GetChannel(void) const { return mReceiveChannel; } /** * This method sets the receiving channel. * * @param[in] aChannel The channel to use for receiving. * */ Error SetChannel(uint8_t aChannel); /** * This function returns the extended address. * * @returns A reference to the extended address. * */ const ExtAddress &GetExtAddress(void) const { return mSubMac.GetExtAddress(); } /** * This method updates extended address. * * @param[in] aExtAddress The extended address. * * @retval kErrorNone If successful. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error SetExtAddress(const ExtAddress &aExtAddress); /** * This method updates MAC keys and key index. * * @param[in] aKeyIdMode The key ID mode. * @param[in] aKeyId The key index. * @param[in] aPrevKey The previous MAC key. * @param[in] aCurrKey The current MAC key. * @param[in] aNextKey The next MAC key. * * @retval kErrorNone If successful. * @retval kErrorFailed Platform failed to import key. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error SetMacKey(uint8_t aKeyIdMode, uint8_t aKeyId, const Key &aPrevKey, const Key &aCurrKey, const Key &aNextKey); /** * This method sets the current MAC frame counter value. * * @param[in] aMacFrameCounter The MAC frame counter value. * * @retval kErrorNone If successful. * @retval kErrorInvalidState If the raw link-layer isn't enabled. * */ Error SetMacFrameCounter(uint32_t aMacFrameCounter); #if OT_SHOULD_LOG_AT(OT_LOG_LEVEL_INFO) /** * This method records the status of a frame transmission attempt and is mainly used for logging failures. * * Unlike `HandleTransmitDone` which is called after all transmission attempts of frame to indicate final status * of a frame transmission request, this method is invoked on all frame transmission attempts. * * @param[in] aFrame The transmitted frame. * @param[in] aAckFrame A pointer to the ACK frame, or `nullptr` if no ACK was received. * @param[in] aError kErrorNone when the frame was transmitted successfully, * kErrorNoAck when the frame was transmitted but no ACK was received, * kErrorChannelAccessFailure tx failed due to activity on the channel, * kErrorAbort when transmission was aborted for other reasons. * @param[in] aRetryCount Indicates number of transmission retries for this frame. * @param[in] aWillRetx Indicates whether frame will be retransmitted or not. This is applicable only * when there was an error in transmission (i.e., `aError` is not NONE). * */ void RecordFrameTransmitStatus(const TxFrame &aFrame, const RxFrame *aAckFrame, Error aError, uint8_t aRetryCount, bool aWillRetx); #else void RecordFrameTransmitStatus(const TxFrame &, const RxFrame *, Error, uint8_t, bool) {} #endif private: uint8_t mReceiveChannel; PanId mPanId; otLinkRawReceiveDone mReceiveDoneCallback; otLinkRawTransmitDone mTransmitDoneCallback; otLinkRawEnergyScanDone mEnergyScanDoneCallback; #if OPENTHREAD_RADIO SubMac mSubMac; #elif OPENTHREAD_CONFIG_LINK_RAW_ENABLE SubMac &mSubMac; #endif }; } // namespace Mac } // namespace ot #endif // OPENTHREAD_RADIO || OPENTHREAD_CONFIG_LINK_RAW_ENABLE #endif // LINK_RAW_HPP_