/*

* 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 TDataBuffer and the RFrameXferBlock class.

*

*/

/*

*/

#ifndef FRAMEXFERBLOCK_H

#define FRAMEXFERBLOCK_H

#include "802dot11.h"

#include "umac_types.h"

#include "pack.h"

#include "wllddcircularbuffer.h"

/** 

* This value (bytes) should be at least as large as the Tx offset required

* by the used WLAN vendor implementation. 

* As we need to decide the max size of the Tx buffers already at compile

* time, we use this value when doing that.

* If the value is too small, WLAN Mgmt client may receive an error when trying 

* to submit a close to maximum length frame for transmit

*/

static const TUint KVendorTxHdrMax = 200;

/** 

* Extra space to enable us to align the start of a 802.11 MAC Tx frame on four 

* byte boundary, if it isn't aligned already. Shall also make the total

* buffer length divisible by four

*/

static const TUint KSpaceForAlignment = 4;

/** 

* This value (bytes) should be at least as large as the Tx trailer space 

* required by the used WLAN vendor implementation.

* The other comments for KVendorTxHdrMax (above) apply also to this value.

*/

static const TUint KVendorTxTrailerMax = 4;

/** 

* The length (in bytes) of the only WLAN Mgmt client Tx buffer

*/

static const TUint KMgmtSideTxBufferLength =                 // 2576

    KVendorTxHdrMax +                                        //  200

    KMaxDot11TxMpduLength +                                  // 2368

    KSpaceForAlignment +                                     //    4

    KVendorTxTrailerMax;                                     //    4

/** Protocol Stack Side client's Tx queue max lengths in packets */

static const TUint KVoiceTxQueueLen = 4;

static const TUint KVideoTxQueueLen = 8;

static const TUint KBestEffortTxQueueLen = 24;

static const TUint KBackgroundTxQueueLen = 4;

/** 

 * Estimates used for calculating the total Protocol Stack Side client Tx 

 * memory pool size 

 */

static const TUint KEthernetVoiceTxFrameLenEstimate = 256;

static const TUint KEthernetVideoTxFrameLenEstimate = 1024;

static const TUint KEthernetBestEffortTxFrameLenEstimate = 

                       KMaxEthernetFrameLength;

static const TUint KEthernetBackgroundTxFrameLenEstimate = 

                       KMaxEthernetFrameLength;

static const TUint KVendorTxHdrLenEstimate = 64;

static const TUint KVendorTxTrailerLenEstimate = 4;

static const TUint KProtocolStackSideFrameLenOverhead = 

    KVendorTxHdrLenEstimate +

    KHtQoSMacHeaderLength +  

    KMaxDot11SecurityEncapsulationLength +

    sizeof( SSnapHeader ) +

    KSpaceForAlignment +

    KVendorTxTrailerLenEstimate;

/** 

* Protocol stack side Tx memory pool size in packets

*/

static const TUint KTxPoolSizeInPackets = 

    KVoiceTxQueueLen +

    KVideoTxQueueLen +

    KBestEffortTxQueueLen +

    KBackgroundTxQueueLen;

/** 

* Protocol stack side Tx data chunk size in bytes

* Note! Needs to be divisible by 4

*/

static const TUint KProtocolStackSideTxDataChunkSize = 

    KVoiceTxQueueLen * ( KEthernetVoiceTxFrameLenEstimate + 

                         KProtocolStackSideFrameLenOverhead ) +

    KVideoTxQueueLen * ( KEthernetVideoTxFrameLenEstimate + 

                         KProtocolStackSideFrameLenOverhead ) +

    KBestEffortTxQueueLen * ( KEthernetBestEffortTxFrameLenEstimate +

                              KProtocolStackSideFrameLenOverhead ) +

    KBackgroundTxQueueLen * ( KEthernetBackgroundTxFrameLenEstimate + 

                              KProtocolStackSideFrameLenOverhead );                        

/**

*  Meta header for Rx and Tx frames

*

*  @since S60 v3.1

*/

#pragma pack( 1 )

class TDataBuffer 

    {

    friend class RFrameXferBlock; 

    friend class RFrameXferBlockProtocolStack; // because of SetLength()

public:

    /** ethernet II frame */

    static const TFrameType KEthernetFrame      = 0;

    /** complete 802.11 frame */

    static const TFrameType KDot11Frame         = 1;

    /** frame beginning with a SNAP header */

    static const TFrameType KSnapFrame          = 2;

    /** ethernet II frame used to test an AP */

    static const TFrameType KEthernetTestFrame  = 3;

    /** upper bound, so not a real type */

    static const TFrameType KFrameTypeMax       = 4;

    typedef TUint32 TFlag;

    /** 

    * flag indicating that the associated Rx buffer shall not be released 

    * when releasing this meta header 

    */

    static const TFlag KDontReleaseBuffer = ( 1 << 0 );

    /** 

    * flag indicating that the Tx frame in the associated buffer shall not 

    * be encrypted even if a valid encryption key existed. If not set, the

    * frame may be encrypted if a valid key exists

    */

    static const TFlag KTxFrameMustNotBeEncrypted = ( 1 << 1 );

public:

    /**

    * Appends data to Tx Buffer

    * @param aData data to be apended

    * @param aLength length of data in bytes

    * @return KErrNone on success,

    *         KErrOverflow if aLength is greater than the available space in

    *         the buffer

    */

    inline TInt AppendBuffer( 

        const TUint8* aData, 

        TUint32 aLength );

    /**

    * Gets length of the data in the buffer

    *

    * @since S60 3.1

    * @return length of the data in the buffer

    */

    inline TUint32 GetLength() const;

    /**

    * Gets the begin of the buffer

    *

    * @since S60 3.1

    * @return beginning of the buffer

    */

    inline const TUint8* GetBuffer() const;

    /**

    * Gets the beginning of the buffer

    *

    * @since S60 3.1

    * @return begin of the buffer

    */

    inline TUint8* GetBuffer();

    /**

    * Gets the frame type in the buffer

    *

    * @since S60 3.1

    * @return frame type in the buffer

    */

    inline TFrameType FrameType() const;

    /**

    * Sets the frame type in the buffer

    *

    * @since S60 3.1

    */

    inline void FrameType( TFrameType aFrameType );

    /**

    * Sets the 802.1D User Priority of the frame

    *

    * @since S60 3.2

    * @param aUp UP value to be set

    */

    inline void SetUserPriority( TUint8 aUp );

    /**

    * Gets the 802.1D User Priority of the frame

    *

    * @since S60 3.2

    * @return UP value

    */

    inline TUint8 UserPriority() const;

    /**

    *

    * @since S60 3.2

    * @return RCPI value

    */

    inline TUint8 Rcpi() const;

    //////////////////////////////////////////////////////////////////////////

    // Rest of the methods are meant to be used only in the device driver code

    //////////////////////////////////////////////////////////////////////////

    /**

    * Gets the beginning of the data buffer

    * NOTE: to be used only by the device driver

    *

    * @return Buffer beginning

    */

    inline TUint8* KeGetBufferStart() const;

    /**

    * Sets the specified flag(s)

    * NOTE: to be used only by the device driver

    *

    * @param aFlag The flag(s) to set

    */

    inline void KeSetFlags( TFlag aFlags );

    /**

    * Returns the flags set in this object

    * NOTE: to be used only by the device driver

    *

    * @return Flags set in this object

    */

    inline TFlag KeFlags() const;

    /**

    * Clears the specified flag(s)

    * NOTE: to be used only by the device driver

    *

    * @param aFlag The flag(s) to clear

    */

    inline void KeClearFlags( TFlag aFlags );

#ifdef __KERNEL_MODE__ /* Kernel mode */

    /**

    * Sets the RCPI value of a received frame

    * NOTE: to be used only by the device driver

    *

    * @since S60 3.2

    * @param aRcpi RCPI value to be set

    */

    inline void KeSetRcpi( TUint8 aRcpi );

   /**

    * Gets the Destination Address of the frame to be transmitted

    * NOTE: to be used only by the device driver

    *

    * @return Destination Address

    */

    inline const TMacAddress& KeDestinationAddress() const;

    /**

    * Sets the offset to actual frame beginning within the data buffer

    * NOTE: to be used only by the device driver

    *

    * @param aOffset Offset to frame beginning

    */

    inline void KeSetOffsetToFrameBeginning( TUint32 aOffset );

    /**

    * Returns the offset to actual frame beginning within the data buffer

    * NOTE: to be used only by the device driver

    *

    * @return Offset to frame beginning

    */

    inline TUint32 KeOffsetToFrameBeginning() const;

    /**

    * Sets the offset from the start address of this object to the actual data 

    * buffer start address

    * NOTE: to be used only by the device driver

    *

    * @param aOffset Offset to data buffer start address. May be positive or 

    *        negative.

    */

    inline void KeSetBufferOffset( TInt32 aOffset );

    /**

    * Sets the length field

    * NOTE: to be used only by the device driver

    *

    * @since S60 3.1

    * @param aLength length to be set

    */

    inline void KeSetLength( TUint32 aLength )

        {

        iLength = aLength;

        };

#endif /* Kernel mode end */

private:

    /** Default Ctor */

    TDataBuffer() :

        iFrameType( KEthernetFrame ), 

        iUp( 0 ), 

        iRcpi( 0 ),

        iDestinationAddress( KZeroMacAddr ),

        iBufLength( 0 ),

        iOffsetToFrameBeginning( 0 ),

        iBufferOffsetAddr( sizeof( TDataBuffer ) ),

        {};

    /**

    * Adds a value to the length field

    * @param aValue length to be set

    */

    inline void IncrementLength( TUint32 aValue );

    /**

    * Appends data to Buffer

    * @param aData data to be apended

    * @param aLength length of data in BYTEs

    * @param aOffsetToFrameBeginning Amount of empty space to leave in the

    *        beginning of the buffer, i.e. before the frame beginning

    */

    inline void AppendBuffer( 

        const TUint8* aData, 

        TUint32 aLength,

        TUint32 aOffsetToFrameBeginning );

    /**

    * Sets the length field

    * @param aLength length to be set

    */

    inline void SetLength( TUint32 aLength );

    /**

    * Sets the length of the attached data buffer

    * @param aBufLength length to be set

    */

    inline void SetBufLength( TUint16 aBufLength );

    /**

    * Sets the Destination Address of the frame to be transmitted

    *

    * @param aDa Destination Address to be set

    */

    inline void SetDestinationAddress( const TMacAddress& aDa );

    /** Prohibit copy constructor */

    TDataBuffer( const TDataBuffer& );

    /** Prohibit assigment operator */

    TDataBuffer& operator= ( const TDataBuffer& );

private:    // Data

    /** type of the frame in buffer */

    TFrameType iFrameType;

    /** length of the data in buffer */

    TUint32 iLength;

    /** 

    * Destination address of the frame to be transmitted. Used only when

    * the address cannot be determined from the frame content  

    */

    TMacAddress iDestinationAddress;

    /** 

    * Length of the attached data buffer. Currently used only for Protocol

    * Stack Side client Tx frames 

    */

    TUint16 iBufLength;

    /** the offset to actual frame beginning within the data buffer */

    TUint32 iOffsetToFrameBeginning;

    /** 

    * the offset from the start address of this object to the start address 

    * of the data buffer. May be positive or negative.

    */

    TInt32 iBufferOffsetAddr;

    /** may contain a combination of the flags defined for this class */

    TFlag iFlags;

    /** 

    * Note! The total length of this object needs to be divisible by four

    * to enable the items following it to be correctly aligned. 

    */

    } __PACKED;

#pragma pack()

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline TInt TDataBuffer::AppendBuffer( 

    const TUint8* aData, 

    TUint32 aLength )

    {

    if ( aLength <= iBufLength - iLength )

        {

        os_memcpy( 

            KeGetBufferStart() + iOffsetToFrameBeginning + iLength, 

            aData, 

            aLength );

        IncrementLength( aLength );

        return KErrNone;

        }

    else

        {

        return KErrOverflow;

        }

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline TUint32 TDataBuffer::GetLength() const

    {

    return iLength;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline const TUint8* TDataBuffer::GetBuffer() const

    {

    return KeGetBufferStart() + iOffsetToFrameBeginning;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline TUint8* TDataBuffer::GetBuffer()

    {

    return KeGetBufferStart() + iOffsetToFrameBeginning;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline TDataBuffer::TFrameType TDataBuffer::FrameType() const

    {

    return iFrameType;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline void TDataBuffer::FrameType( TFrameType aFrameType )

    {

    iFrameType = aFrameType;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline void TDataBuffer::SetLength( TUint32 aLength )

    {

    iLength = aLength;

    }

// ---------------------------------------------------------------------------

// 

// ---------------------------------------------------------------------------

//

inline void TDataBuffer::SetBufLength( TUint16 aBufLength )

    {

    iBufLength = aBufLength;

    }