/*
* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Declaration of the WlanTxRateAdaptation class
*
*/
/*
* %version: 18 %
*/
#ifndef WLANTXRATEADAPTATION_H
#define WLANTXRATEADAPTATION_H
#ifndef RD_WLAN_DDK
#include <wha_types.h>
#else
#include <wlanwha_types.h>
#endif
class WlanContextImpl;
/**
* Implements dynamic transmit rate adaptation.
*
* @lib wlanumac.lib
* @since S60 v3.1
*/
class WlanTxRateAdaptation
{
public:
/**
* C++ default constructor.
*/
WlanTxRateAdaptation();
/**
* Destructor.
*/
virtual ~WlanTxRateAdaptation() {};
/**
* Sets the rate adaptation object
* @since S60 3.1
* @param aPolicyId id of the Tx rate policy for which the rates
* are set
* @param aRateBitmask contains the rates to be set
*/
TBool SetRates( TUint8 aPolicyId, WHA::TRate aRateBitmask );
/**
* Defines which Tx rate policy should be used when sending via
* the specified queue
*
* @since S60 3.1
* @param aQueueId id of the Tx queue
* @param aPolicyId id of the Tx rate policy
*/
void SetPolicy( WHA::TQueueId aQueueId, TUint8 aPolicyId );
/**
* Sets the current max Tx rate which should be initially used when sending
* frames using the specified Tx rate policy.
* If this rate is not present in the specified rate policy, or if
* it is not supported either by the nw or by WHA layer, the next possible
* lower rate will be used instead.
* However, if the specified rate is lower that any rate in the specified
* rate policy, the lowest rate in the policy will be used.
*
* @since S60 3.1
* @param aPolicyId id of the Tx rate policy
* @param aRate initial max Tx rate
*/
void SetCurrentMaxTxRate( TUint8 aPolicyId, WHA::TRate aRate );
/**
* Sets the Tx rate adaptation algorithm parameters
*
* @since S60 3.1
* @param aMinStepUpCheckpoint minimum and initial rate increase
* checkpoint in units of frames
* Range: [aStepDownCheckpoint,aMaxStepUpCheckpoint]
* @param aMaxStepUpCheckpoint maximum rate increase checkpoint in units
* of frames
* Range: [aStepDownCheckpoint,UCHAR_MAX]
* @param aStepUpCheckpointFactor StepUpCheckpoint is multiplied with this
* value if sending a probe frame fails
* Range: [1,aMaxStepUpCheckpoint]
* @param aStepDownCheckpoint after this many frames the need to decrease
* the rate is checked
* Range: [2,UCHAR_MAX]
* @param aMinStepUpThreshold minimum and initial StepUpThreshold
* percentage
* Range: [1,aMaxStepUpThreshold]
* @param aMaxStepUpThreshold maximum StepUpThreshold percentage
* Range: [1,100]
* @param aStepUpThresholdIncrement StepUpThreshold is incremented by this
* value if sending a probe frame fails
* Range: [0,aMaxStepUpThreshold]
* @param aStepDownThreshold if the percentage of frames which failed to
* be transmitted at the originally requested rate is at least
* aStepDownThreshold at the aStepDownCheckpoint, the rate will
* be decreased
* Range: [1,100]
* @param aDisableProbeHandling if EFalse, the rate adaptation algorithm
* handles the first frame transmitted after a rate increase in a
* special way. Otherwise the special handling is disabled
*/
void SetAlgorithmParameters(
TUint8 aMinStepUpCheckpoint,
TUint8 aMaxStepUpCheckpoint,
TUint8 aStepUpCheckpointFactor,
TUint8 aStepDownCheckpoint,
TUint8 aMinStepUpThreshold,
TUint8 aMaxStepUpThreshold,
TUint8 aStepUpThresholdIncrement,
TUint8 aStepDownThreshold,
TBool aDisableProbeHandling );
/**
* Gets the current transmit rate & rate policy class to use when sending
* via the specified Tx queue
*
* @since S60 3.1
* @param aCtxImpl Global statemachine context
* @param aQueueId ID of the Tx queue
* @param aUseSpecialRatePolicy ETrue if use of the special Tx rate
* policy is requested for this frame Tx
* @param aRate Rate to use. Note that this value is not relevant if
* autonomous rate adaptation is being used
* @param aPolicyId id of the Tx rate policy
*/
void RatePolicy(
const WlanContextImpl& aCtxImpl,
WHA::TQueueId aQueueId,
TBool aUseSpecialRatePolicy,
WHA::TRate& aRate,
TUint8& aPolicyId ) const;
/**
* Called upon Tx operation complete
*
* @since S60 3.1
* @param aRate the rate which was used to transmit the frame (if success)
* @param aSuccess did the send succeed
* @param aQueueId id of the queue via which the frame was transmitted
* @param aRequestedRate Tx rate that was originally requested
*/
void OnTxCompleted(
WHA::TRate aRate,
TBool aSuccess,
WHA::TQueueId aQueueId,
WHA::TRate aRequestedRate );
/**
* Resets the state of the whole Tx rate adaptation object
*/
void Reset();
private:
struct SBitRate
{
/*
* rates are in ascending order the lowest rate being the first
*/
WHA::TRate iBitRate;
// number of rates
SBitRate* iNext;
SBitRate* iPrev;
};
enum TRateStep
{
EKeepCurrent,
EStepDown,
EStepUp
};
struct SAlgorithmParams
{
/*
* minimum and initial rate increase checkpoint in units of frames
*/
TUint8 iMinStepUpCheckpoint;
/*
* maximum rate increase checkpoint in units of frames
*/
TUint8 iMaxStepUpCheckpoint;
/*
* iStepUpCheckpoint is multiplied with this value if sending a probe
* frame fails
*/
TUint8 iStepUpCheckpointFactor;
/*
* after this many frames the need to decrease the rate is checked
*/
TUint8 iStepDownCheckpoint;
/*
* minimum and initial StepUpThreshold percentage
*/
TUint8 iMinStepUpThreshold;
/*
* maximum iStepUpThreshold percentage value
*/
TUint8 iMaxStepUpThreshold;
/*
* iStepUpThreshold is incremented by this value if sending a probe
* frame fails
*/
TUint8 iStepUpThresholdIncrement;
/*
* if the percentage of frames which failed to be transmitted at the
* originally requested rate is at least iStepDownThreshold at the
* iStepDownCheckpoint, the rate will be decreased
*/
TUint8 iStepDownThreshold;
/*
* if EFalse, the rate adaptation algorithm handles the first frame
* transmitted after a rate increase in a special way. Otherwise the
* special handling is disabled
*/
TBool iDisableProbeHandling;
};
struct SPolicy
{
/** current Tx rate */
SBitRate* iCurrentTxRate;
// first rate
SBitRate* iHead;
// last rate
SBitRate* iTail;
/** number of rate entrys */
TUint iNumOfRates;
/** ETrue for a probe frame */
TBool iProbe;
TUint iTxCount;
TUint iTxFailCount;
TUint iStepUpCheckpoint;
TUint iStepUpThreshold;
};
/**
* Resets the state related to the specified rate policy
* @param aPolicy the policy to reset
*/
void Reset( SPolicy& aPolicy ) const;
/**
* Appends a rate to rate list
* @param aPolicyIndex index of the Tx rate policy to which to append
* @param aRate rate to append
*/
TBool AppendRate( TUint8 aPolicyIndex, WHA::TRate aRate );
/**
* Inserts a rate to rate list
* @param aPolicyIndex index of the Tx rate policy to which to insert
* @param aBlock rate list item to insert
*/
void InsertRate( TUint8 aPolicyIndex, SBitRate* aBlock ) const;
/**
* Decrements Tx rate for the specified Tx rate policy
* @param aPolicy the policy
*/
void RateStepDown( SPolicy& aPolicy ) const;
/**
* Increments Tx rate for the specified Tx rate policy
* @param aPolicy the policy
* @return ETrue if the operation succeeded
* EFalse if already using the highest rate
*/
TBool RateStepUp( SPolicy& aPolicy ) const;
/**
* Called upon Tx operation complete
* @param aSuccess did the send succeed using the rate origianlly requested
* @param aPolicy policy which was used when transmitting the related frame
*/
TRateStep OnTxCompleted(
TBool aSuccess,
SPolicy& aPolicy ) const;
// Prohibit copy constructor.
WlanTxRateAdaptation( const WlanTxRateAdaptation& );
// Prohibit assigment operator.
WlanTxRateAdaptation& operator=
( const WlanTxRateAdaptation& );
private: // Data
SAlgorithmParams iAlgorithmParam;
/**
* maps every Tx queue to a Tx policy
*/
TUint8 iQueue2Policy[WHA::EQueueIdMax];
/**
* maximum number of rate policies in use concurrently.
* We will use two policies, one for voice priority (voice AC) data
* and another for everything else, if possible. Otherwise only one policy
* is used. Parameters for policy 1 are at index 0, for policy 2 at index 1
* and so on
*/
enum { KMaxRatePolicyCount = 2 };
SPolicy iPolicy[KMaxRatePolicyCount];
};
#endif // WLANTXRATEADAPTATION_H