329 lines
11 KiB
C++
329 lines
11 KiB
C++
/*
|
|
* 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 <openthread/link_raw.h>
|
|
|
|
#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_
|