1 /*

     2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Declaration of the TDataBuffer and the RFrameXferBlock class.

    15 *

    16 */

    17 

    18 /*

    19 * %version: 25 %

    20 */

    21 

    22 #ifndef FRAMEXFERBLOCK_H

    23 #define FRAMEXFERBLOCK_H

    24 

    25 #include "802dot11.h"

    26 #include "umac_types.h"

    27 #include "pack.h"

    28 #include "wllddcircularbuffer.h"

    29 

    30 /** Max number of completed Rx buffers */

    31 static const TUint KMaxCompletedRxBufs = 300;

    32 

    33 /** Max number of to be completed Rx buffers */

    34 static const TUint KMaxToBeCompletedRxBufs = KMaxCompletedRxBufs;

    35 

    36 /** 

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

    38 * by the used WLAN vendor implementation. 

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

    40 * time, we use this value when doing that.

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

    42 * to submit a close to maximum length frame for transmit

    43 */

    44 static const TUint KVendorTxHdrMax = 200;

    45 

    46 /** 

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

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

    49 * buffer length divisible by four

    50 */

    51 static const TUint KSpaceForAlignment = 4;

    52 

    53 /** 

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

    55 * required by the used WLAN vendor implementation.

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

    57 */

    58 static const TUint KVendorTxTrailerMax = 4;

    59 

    60 /** 

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

    62 */

    63 static const TUint KMgmtSideTxBufferLength =                 // 2576

    64     KVendorTxHdrMax +                                        //  200

    65     KMaxDot11TxMpduLength +                                  // 2368

    66     KSpaceForAlignment +                                     //    4

    67     KVendorTxTrailerMax;                                     //    4

    68 

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

    70 

    71 static const TUint KVoiceTxQueueLen = 4;

    72 static const TUint KVideoTxQueueLen = 8;

    73 static const TUint KBestEffortTxQueueLen = 24;

    74 static const TUint KBackgroundTxQueueLen = 4;

    75 

    76 /** 

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

    78  * memory pool size 

    79  */

    80 

    81 static const TUint KEthernetVoiceTxFrameLenEstimate = 256;

    82 static const TUint KEthernetVideoTxFrameLenEstimate = 1024;

    83 static const TUint KEthernetBestEffortTxFrameLenEstimate = 

    84                        KMaxEthernetFrameLength;

    85 static const TUint KEthernetBackgroundTxFrameLenEstimate = 

    86                        KMaxEthernetFrameLength;

    87 

    88 static const TUint KVendorTxHdrLenEstimate = 64;

    89 static const TUint KVendorTxTrailerLenEstimate = 4;

    90 

    91 static const TUint KProtocolStackSideFrameLenOverhead = 

    92     KVendorTxHdrLenEstimate +

    93     KHtQoSMacHeaderLength +  

    94     KMaxDot11SecurityEncapsulationLength +

    95     sizeof( SSnapHeader ) +

    96     KSpaceForAlignment +

    97     KVendorTxTrailerLenEstimate;

    98 

    99 /** 

   100 * Protocol stack side Tx memory pool size in packets

   101 */

   102 static const TUint KTxPoolSizeInPackets = 

   103     KVoiceTxQueueLen +

   104     KVideoTxQueueLen +

   105     KBestEffortTxQueueLen +

   106     KBackgroundTxQueueLen;

   107 

   108 /** 

   109 * Protocol stack side Tx data chunk size in bytes

   110 * Note! Needs to be divisible by 4

   111 */

   112 static const TUint KProtocolStackSideTxDataChunkSize = 

   113     KVoiceTxQueueLen * ( KEthernetVoiceTxFrameLenEstimate + 

   114                          KProtocolStackSideFrameLenOverhead ) +

   115     KVideoTxQueueLen * ( KEthernetVideoTxFrameLenEstimate + 

   116                          KProtocolStackSideFrameLenOverhead ) +

   117     KBestEffortTxQueueLen * ( KEthernetBestEffortTxFrameLenEstimate +

   118                               KProtocolStackSideFrameLenOverhead ) +

   119     KBackgroundTxQueueLen * ( KEthernetBackgroundTxFrameLenEstimate + 

   120                               KProtocolStackSideFrameLenOverhead );                        

   121     

   122 /**

   123 *  Meta header for Rx and Tx frames

   124 *

   125 *  @since S60 v3.1

   126 */

   127 #pragma pack( 1 )

   128 class TDataBuffer 

   129     {

   130     friend class RFrameXferBlock; 

   131     friend class RFrameXferBlockProtocolStack; // because of SetLength()

   132 

   133 public:

   134 

   135     typedef TUint32 TFrameType;

   136 

   137     /** ethernet II frame */

   138     static const TFrameType KEthernetFrame      = 0;

   139     /** complete 802.11 frame */

   140     static const TFrameType KDot11Frame         = 1;

   141     /** frame beginning with a SNAP header */

   142     static const TFrameType KSnapFrame          = 2;

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

   144     static const TFrameType KEthernetTestFrame  = 3;

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

   146     static const TFrameType KFrameTypeMax       = 4;

   147 

   148     typedef TUint32 TFlag;

   149     

   150     /** 

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

   152     * when releasing this meta header 

   153     */

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

   155     /** 

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

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

   158     * frame may be encrypted if a valid key exists

   159     */

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

   161     

   162 public:

   163 

   164     /**

   165     * Appends data to Tx Buffer

   166     * @param aData data to be apended

   167     * @param aLength length of data in bytes

   168     * @return KErrNone on success,

   169     *         KErrOverflow if aLength is greater than the available space in

   170     *         the buffer

   171     */

   172     inline TInt AppendBuffer( 

   173         const TUint8* aData, 

   174         TUint32 aLength );

   175 

   176     /**

   177     * Gets length of the data in the buffer

   178     *

   179     * @since S60 3.1

   180     * @return length of the data in the buffer

   181     */

   182     inline TUint32 GetLength() const;

   183 

   184     /**

   185     * Gets the begin of the buffer

   186     *

   187     * @since S60 3.1

   188     * @return beginning of the buffer

   189     */

   190     inline const TUint8* GetBuffer() const;

   191 

   192     /**

   193     * Gets the beginning of the buffer

   194     *

   195     * @since S60 3.1

   196     * @return begin of the buffer

   197     */

   198     inline TUint8* GetBuffer();

   199 

   200     /**

   201     * Gets the frame type in the buffer

   202     *

   203     * @since S60 3.1

   204     * @return frame type in the buffer

   205     */

   206     inline TFrameType FrameType() const;

   207 

   208     /**

   209     * Sets the frame type in the buffer

   210     *

   211     * @since S60 3.1

   212     */

   213     inline void FrameType( TFrameType aFrameType );

   214 

   215     /**

   216     * Sets the 802.1D User Priority of the frame

   217     *

   218     * @since S60 3.2

   219     * @param aUp UP value to be set

   220     */

   221     inline void SetUserPriority( TUint8 aUp );

   222 

   223     /**

   224     * Gets the 802.1D User Priority of the frame

   225     *

   226     * @since S60 3.2

   227     * @return UP value

   228     */

   229     inline TUint8 UserPriority() const;

   230 

   231     /**

   232     * Gets the RCPI value of a received frame

   233     *

   234     * @since S60 3.2

   235     * @return RCPI value

   236     */

   237     inline TUint8 Rcpi() const;

   238 

   239     

   240     //////////////////////////////////////////////////////////////////////////

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

   242     //////////////////////////////////////////////////////////////////////////

   243 

   244     /**

   245     * Gets the beginning of the data buffer

   246     * NOTE: to be used only by the device driver

   247     *

   248     * @return Buffer beginning

   249     */

   250     inline TUint8* KeGetBufferStart() const;

   251     

   252     /**

   253     * Sets the specified flag(s)

   254     * NOTE: to be used only by the device driver

   255     *

   256     * @param aFlag The flag(s) to set

   257     */

   258     inline void KeSetFlags( TFlag aFlags );

   259 

   260     /**

   261     * Returns the flags set in this object

   262     * NOTE: to be used only by the device driver

   263     *

   264     * @return Flags set in this object

   265     */

   266     inline TFlag KeFlags() const;

   267     

   268     /**

   269     * Clears the specified flag(s)

   270     * NOTE: to be used only by the device driver

   271     *

   272     * @param aFlag The flag(s) to clear

   273     */

   274     inline void KeClearFlags( TFlag aFlags );

   275 

   276 

   277 #ifdef __KERNEL_MODE__ /* Kernel mode */

   278     

   279     /**

   280     * Sets the RCPI value of a received frame

   281     * NOTE: to be used only by the device driver

   282     *

   283     * @since S60 3.2

   284     * @param aRcpi RCPI value to be set

   285     */

   286     inline void KeSetRcpi( TUint8 aRcpi );

   287 

   288    /**

   289     * Gets the Destination Address of the frame to be transmitted

   290     * NOTE: to be used only by the device driver

   291     *

   292     * @return Destination Address

   293     */

   294     inline const TMacAddress& KeDestinationAddress() const;

   295 

   296     /**

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

   298     * NOTE: to be used only by the device driver

   299     *

   300     * @param aOffset Offset to frame beginning

   301     */

   302     inline void KeSetOffsetToFrameBeginning( TUint32 aOffset );

   303 

   304     /**

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

   306     * NOTE: to be used only by the device driver

   307     *

   308     * @return Offset to frame beginning

   309     */

   310     inline TUint32 KeOffsetToFrameBeginning() const;

   311 

   312     /**

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

   314     * buffer start address

   315     * NOTE: to be used only by the device driver

   316     *

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

   318     *        negative.

   319     */

   320     inline void KeSetBufferOffset( TInt32 aOffset );

   321     

   322     /**

   323     * Sets the length field

   324     * NOTE: to be used only by the device driver

   325     *

   326     * @since S60 3.1

   327     * @param aLength length to be set

   328     */

   329     inline void KeSetLength( TUint32 aLength )

   330         {

   331         iLength = aLength;

   332         };

   333 

   334 #endif /* Kernel mode end */

   335     

   336 private:

   337 

   338     /** Default Ctor */

   339     TDataBuffer() :

   340         iFrameType( KEthernetFrame ), 

   341         iLength( 0 ), 

   342         iUp( 0 ), 

   343         iRcpi( 0 ),

   344         iDestinationAddress( KZeroMacAddr ),

   345         iBufLength( 0 ),

   346         iOffsetToFrameBeginning( 0 ),

   347         iBufferOffsetAddr( sizeof( TDataBuffer ) ),

   348         iFlags( 0 )

   349         {};

   350 

   351     /**

   352     * Adds a value to the length field

   353     * @param aValue length to be set

   354     */

   355     inline void IncrementLength( TUint32 aValue );

   356 

   357     /**

   358     * Appends data to Buffer

   359     * @param aData data to be apended

   360     * @param aLength length of data in BYTEs

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

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

   363     */

   364     inline void AppendBuffer( 

   365         const TUint8* aData, 

   366         TUint32 aLength,

   367         TUint32 aOffsetToFrameBeginning );

   368 

   369     /**

   370     * Sets the length field

   371     * @param aLength length to be set

   372     */

   373     inline void SetLength( TUint32 aLength );

   374 

   375     /**

   376     * Sets the length of the attached data buffer

   377     * @param aBufLength length to be set

   378     */

   379     inline void SetBufLength( TUint16 aBufLength );

   380 

   381     /**

   382     * Sets the Destination Address of the frame to be transmitted

   383     *

   384     * @param aDa Destination Address to be set

   385     */

   386     inline void SetDestinationAddress( const TMacAddress& aDa );

   387 

   388     /** Prohibit copy constructor */

   389     TDataBuffer( const TDataBuffer& );

   390     /** Prohibit assigment operator */

   391     TDataBuffer& operator= ( const TDataBuffer& );

   392 

   393 private:    // Data

   394 

   395     /** type of the frame in buffer */

   396     TFrameType iFrameType;

   397         

   398     /** length of the data in buffer */

   399     TUint32 iLength;

   400     

   401     /** 

   402     * 802.1D User Priority of the frame

   403     * stored as a 32-bit value to keep the length of this object 32-bit

   404     * aligned

   405     */

   406     TUint32 iUp;

   407 

   408     /** 

   409     * RCPI of the received frame; range: [0..250]

   410     * stored as a 32-bit value to keep the length of this object 32-bit

   411     * aligned

   412     */

   413     TUint32 iRcpi;

   414 

   415     /** 

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

   417     * the address cannot be determined from the frame content  

   418     */

   419     TMacAddress iDestinationAddress;

   420     

   421     /** 

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

   423     * Stack Side client Tx frames 

   424     */

   425     TUint16 iBufLength;

   426     

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

   428     TUint32 iOffsetToFrameBeginning;

   429 

   430     /** 

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

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

   433     */

   434     TInt32 iBufferOffsetAddr;

   435 

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

   437     TFlag iFlags;

   438     

   439     /** 

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

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

   442     */

   443     } __PACKED;

   444 #pragma pack()

   445 

   446 // ---------------------------------------------------------------------------

   447 // 

   448 // ---------------------------------------------------------------------------

   449 //

   450 inline TInt TDataBuffer::AppendBuffer( 

   451     const TUint8* aData, 

   452     TUint32 aLength )

   453     {

   454     if ( aLength <= iBufLength - iLength )

   455         {

   456         os_memcpy( 

   457             KeGetBufferStart() + iOffsetToFrameBeginning + iLength, 

   458             aData, 

   459             aLength );

   460         IncrementLength( aLength );

   461         

   462         return KErrNone;

   463         }

   464     else

   465         {

   466         return KErrOverflow;

   467         }

   468     }

   469 

   470 // ---------------------------------------------------------------------------

   471 // 

   472 // ---------------------------------------------------------------------------

   473 //

   474 inline TUint32 TDataBuffer::GetLength() const

   475     {

   476     return iLength;

   477     }

   478 

   479 // ---------------------------------------------------------------------------

   480 // 

   481 // ---------------------------------------------------------------------------

   482 //

   483 inline const TUint8* TDataBuffer::GetBuffer() const

   484     {

   485     return KeGetBufferStart() + iOffsetToFrameBeginning;

   486     }

   487 

   488 // ---------------------------------------------------------------------------

   489 // 

   490 // ---------------------------------------------------------------------------

   491 //

   492 inline TUint8* TDataBuffer::GetBuffer()

   493     {

   494     return KeGetBufferStart() + iOffsetToFrameBeginning;

   495     }

   496 

   497 // ---------------------------------------------------------------------------

   498 // 

   499 // ---------------------------------------------------------------------------

   500 //

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

   502     {

   503     return iFrameType;

   504     }

   505 

   506 // ---------------------------------------------------------------------------

   507 // 

   508 // ---------------------------------------------------------------------------

   509 //

   510 inline void TDataBuffer::FrameType( TFrameType aFrameType )

   511     {

   512     iFrameType = aFrameType;

   513     }

   514 

   515 // ---------------------------------------------------------------------------

   516 // 

   517 // ---------------------------------------------------------------------------

   518 //

   519 inline void TDataBuffer::SetLength( TUint32 aLength )

   520     {

   521     iLength = aLength;

   522     }

   523 

   524 // ---------------------------------------------------------------------------

   525 // 

   526 // ---------------------------------------------------------------------------

   527 //

   528 inline void TDataBuffer::SetBufLength( TUint16 aBufLength )

   529     {

   530     iBufLength = aBufLength;

   531     }

   532 

   533 // ---------------------------------------------------------------------------

   534 // 

   535 // ---------------------------------------------------------------------------

   536 //

   537 inline void TDataBuffer::IncrementLength( TUint32 aValue )

   538     {

   539     iLength += aValue;

   540     }

   541 

   542 // ---------------------------------------------------------------------------

   543 // 

   544 // ---------------------------------------------------------------------------

   545 //

   546 inline void TDataBuffer::AppendBuffer( 

   547     const TUint8* aData, 

   548     TUint32 aLength,

   549     TUint32 aOffsetToFrameBeginning )

   550     {

   551     iOffsetToFrameBeginning = aOffsetToFrameBeginning;

   552     os_memcpy( 

   553         KeGetBufferStart() + aOffsetToFrameBeginning + iLength, 

   554         aData, 

   555         aLength );

   556     IncrementLength( aLength );

   557     }

   558 

   559 // ---------------------------------------------------------------------------

   560 // 

   561 // ---------------------------------------------------------------------------

   562 //

   563 inline void TDataBuffer::SetUserPriority( TUint8 aUp )

   564     {

   565     iUp = aUp;

   566     }

   567 

   568 // ---------------------------------------------------------------------------

   569 // return as a TUint8 value as the range of User Priority is [0..7]

   570 // ---------------------------------------------------------------------------

   571 //

   572 inline TUint8 TDataBuffer::UserPriority() const

   573     {

   574     return static_cast<TUint8>(iUp);

   575     }

   576 

   577 // ---------------------------------------------------------------------------

   578 // return as a TUint8 value as the range of RCPI is [0..250]

   579 // ---------------------------------------------------------------------------

   580 //

   581 inline TUint8 TDataBuffer::Rcpi() const

   582     {

   583     return static_cast<TUint8>(iRcpi);

   584     }

   585 

   586 // ---------------------------------------------------------------------------

   587 // 

   588 // ---------------------------------------------------------------------------

   589 //

   590 inline void TDataBuffer::SetDestinationAddress( const TMacAddress& aDa )

   591     {

   592     iDestinationAddress = aDa;

   593     }

   594 

   595 // ---------------------------------------------------------------------------

   596 // 

   597 // ---------------------------------------------------------------------------

   598 //

   599 inline TUint8* TDataBuffer::KeGetBufferStart() const

   600     {

   601     return reinterpret_cast<TUint8*>(

   602         const_cast<TDataBuffer*>(this)) 

   603         + iBufferOffsetAddr;

   604     }

   605 

   606 // ---------------------------------------------------------------------------

   607 // 

   608 // ---------------------------------------------------------------------------

   609 //

   610 inline void TDataBuffer::KeSetFlags( TFlag aFlags )

   611     {

   612     iFlags |= aFlags;

   613     }

   614 

   615 // ---------------------------------------------------------------------------

   616 // 

   617 // ---------------------------------------------------------------------------

   618 //

   619 inline TDataBuffer::TFlag TDataBuffer::KeFlags() const

   620     {

   621     return iFlags;

   622     }

   623 

   624 // ---------------------------------------------------------------------------

   625 // 

   626 // ---------------------------------------------------------------------------

   627 //

   628 inline void TDataBuffer::KeClearFlags( TFlag aFlags )

   629     {

   630     iFlags &= ~aFlags;    

   631     }

   632 

   633 #ifdef __KERNEL_MODE__ /* Kernel mode */

   634     

   635 // ---------------------------------------------------------------------------

   636 // 

   637 // ---------------------------------------------------------------------------

   638 //

   639 inline void TDataBuffer::KeSetRcpi( TUint8 aRcpi )

   640     {

   641     iRcpi = aRcpi;

   642     }

   643 

   644 // ---------------------------------------------------------------------------

   645 // 

   646 // ---------------------------------------------------------------------------

   647 //

   648 inline const TMacAddress& TDataBuffer::KeDestinationAddress() const

   649     {

   650     return iDestinationAddress;

   651     }

   652 

   653 // ---------------------------------------------------------------------------

   654 // 

   655 // ---------------------------------------------------------------------------

   656 //

   657 inline void TDataBuffer::KeSetOffsetToFrameBeginning( TUint32 aOffset )

   658     {

   659     iOffsetToFrameBeginning = aOffset;

   660     }

   661 

   662 // ---------------------------------------------------------------------------

   663 // 

   664 // ---------------------------------------------------------------------------

   665 //

   666 inline TUint32 TDataBuffer::KeOffsetToFrameBeginning() const

   667     {

   668     return iOffsetToFrameBeginning;

   669     }

   670 

   671 // ---------------------------------------------------------------------------

   672 // 

   673 // ---------------------------------------------------------------------------

   674 //

   675 inline void TDataBuffer::KeSetBufferOffset( TInt32 aOffset )

   676     {

   677     iBufferOffsetAddr = aOffset;

   678     }

   679 

   680 #endif /* Kernel mode end */

   681 

   682 /**

   683 * Ethernet frame transfer context block base class between user and 

   684 * kernel space

   685 */

   686 class RFrameXferBlockBase

   687     {

   688 

   689 public:

   690 

   691 #ifndef __KERNEL_MODE__ /* User mode */

   692     

   693     /**

   694     * Gets next Rx-data buffer that has data to be read

   695     *

   696     * @since S60 3.1

   697     * @param aBuf OUT parameter where Rx-data buffers address that is to

   698     * be read is copied

   699     * @return ETrue Rx-data exists after this call still to read,

   700     * otherwise EFalse

   701     */

   702     inline TBool GetNextRxDataBuffer( TDataBuffer*& aBuf );

   703 

   704     //////////////////////////////////////////////////////////////////////////

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

   706     //////////////////////////////////////////////////////////////////////////

   707 

   708     /**

   709     * Set data chunk address

   710     *

   711     * Note! This method is executed in user mode context by the user mode

   712     * client interface, i.e. not the client itself!

   713     * @since S60 3.1

   714     * @param aUserAddr user address of the buffer

   715     */

   716     inline void SetRxDataChunkField( TLinAddr aUserAddr );

   717 

   718 #endif /* User mode end */

   719 

   720 #ifdef __KERNEL_MODE__ /* Kernel mode */

   721     

   722     /**

   723     * Completes Rx buffers to user space

   724     *

   725     * @since S60 3.1

   726     * @param aRxCompletionBuffersArray Rx buffer addresses as offsets from

   727     *        Rx memory pool beginning

   728     * @param aNumOfCompleted number of buffers

   729     */

   730     void KeRxComplete( 

   731         const TUint32* aRxCompletionBuffersArray, 

   732         TUint32 aNumOfCompleted );

   733 

   734     /**

   735     * Gets the array of Rx buffers (their offset addresses) which have already

   736     * been handled by the user space client

   737     *

   738     * @since S60 5.0

   739     * @param aRxHandledBuffersArray Pointer to the beginning of the array

   740     * @param aNumOfHandled Number of buffers (offset addresses) on the array

   741     */

   742     void KeGetHandledRxBuffers( 

   743         const TUint32*& aRxHandledBuffersArray, 

   744         TUint32& aNumOfHandled );

   745 

   746     /**

   747     * Notes, that all Rx buffers, which were completed to user space

   748     * the previous time, are now free.

   749     *

   750     * @since S60 5.0

   751     */

   752     void KeAllUserSideRxBuffersFreed();

   753 

   754     /**

   755     * Sets the Tx offset for every frame type which can be transmitted

   756     *

   757     * @since S60 5.0

   758     * @param aEthernetFrameTxOffset Tx offset for Ethernet frames and Ethernet

   759     *        Test frames

   760     * @param aDot11FrameTxOffset Tx offset for 802.11 frames

   761     * @param aSnapFrameTxOffset Tx offset for SNAP frames

   762     */

   763     void KeSetTxOffsets( 

   764         TUint32 aEthernetFrameTxOffset,

   765         TUint32 aDot11FrameTxOffset,

   766         TUint32 aSnapFrameTxOffset );    

   767 

   768 protected:

   769     

   770     /**

   771     * Initialises the buffer.

   772     *

   773     * @since S60 3.1

   774     */

   775     void KeInitialize();

   776     

   777 #endif /* Kernel mode end */    

   778     

   779 private:

   780 

   781     /** Prohibit default constructor */

   782     RFrameXferBlockBase();

   783 

   784     /** Prohibit copy constructor */

   785     RFrameXferBlockBase( const RFrameXferBlockBase& );

   786     /** Prohibit assigment operator */

   787     RFrameXferBlockBase& operator= ( const RFrameXferBlockBase& );

   788     

   789 protected:    // Data

   790 

   791     /** the beginning of the Rx data area in user address space */

   792     TUint8*         iRxDataChunk;

   793 

   794     /**

   795     * number of Rx-data buffers that were completed by the device driver

   796     */

   797     TUint32         iNumOfCompleted;

   798 

   799     /**

   800     * index to iRxCompletedBuffers denoting the Rx buffer that is to be

   801     * extracted next by the user application

   802     */

   803     TUint32         iCurrentRxBuffer;

   804 

   805     /** 

   806     * index of the first Rx buffer in iRxCompletedBuffers array

   807     * - which the user side client has already handled and

   808     *   which can therefore be freed & re-used AND

   809     * - which hasn't been freed yet

   810     */

   811     TUint32         iFirstRxBufferToFree;

   812     

   813     /** 

   814     * defines a Tx offset for every frame type which can be transmitted

   815     */

   816     TUint32         iTxOffset[TDataBuffer::KFrameTypeMax];

   817 

   818     /** 

   819     * array of TDataBuffer offset addresses from the memory pool start address,

   820     * denoting Rx buffers which are ready to be read

   821     */

   822     TUint32         iRxCompletedBuffers[KMaxCompletedRxBufs];

   823     

   824     /**

   825     * Note! The length of this object needs to be divisible by 4 to make

   826     * the objects following it to be aligned correctly

   827     */

   828     };

   829 

   830 #ifndef __KERNEL_MODE__ /* User mode */

   831 

   832 // ---------------------------------------------------------------------------

   833 // 

   834 // ---------------------------------------------------------------------------

   835 //

   836 inline TBool RFrameXferBlockBase::GetNextRxDataBuffer( TDataBuffer*& aBuf )

   837     {

   838     TBool ret( EFalse );

   839 

   840     if ( iNumOfCompleted )

   841         {

   842         --iNumOfCompleted;

   843         aBuf = reinterpret_cast<TDataBuffer*>(

   844                 // Rx memory pool user mode start address

   845                 iRxDataChunk + 

   846                 // offset from the memory pool start address

   847                 iRxCompletedBuffers[iCurrentRxBuffer]);

   848                 

   849         ++iCurrentRxBuffer;

   850         ret = ETrue;

   851         }

   852 

   853     return ret;

   854     }

   855 

   856 // ---------------------------------------------------------------------------

   857 // 

   858 // ---------------------------------------------------------------------------

   859 //

   860 inline void RFrameXferBlockBase::SetRxDataChunkField( TLinAddr aUserAddr )

   861     {

   862     iRxDataChunk = reinterpret_cast<TUint8*>(aUserAddr); 

   863     }

   864 

   865 #endif /* User mode end */

   866 

   867 

   868 /**

   869 * Ethernet frame transfer context block between user and kernel space

   870 * for the Management Client

   871 */

   872 class RFrameXferBlock : public RFrameXferBlockBase

   873     {

   874 

   875 public:

   876 

   877 #ifndef __KERNEL_MODE__ /* User mode */

   878     

   879     /**

   880     * Appends data to iTxDataBuffer

   881     *

   882     * @since S60 3.1

   883     * @param aData data to be apended

   884     * @param aLength length of data in BYTEs

   885     * @param aFrameType frame type idenitifier

   886     * @param aUserPriority 802.1D User Priority of the frame

   887     * @param aMustNotBeEncrypted If EFalse it is allowed to encrypt the frame

   888     *        if a valid encryption key exists. This is the default behavior.

   889     *        If ETrue, the frame must not be encrypted even if a valid 

   890     *        encryption key existed. 

   891     * @param aDestinationAddress If not NULL, specifies the destination MAC

   892     *        address for the frame to be transmitted

   893     * @return KErrNone on success,

   894     *         KErrOverflow if aLength is greater than the available space in

   895     *         the Tx buffer

   896     */

   897     inline TInt AppendTxDataBuffer( 

   898         const TUint8* aData, 

   899         TUint32 aLength,

   900         TDataBuffer::TFrameType aFrameType = TDataBuffer::KEthernetFrame,

   901         TUint8 aUserPriority = 0,

   902         TBool aMustNotBeEncrypted = EFalse,

   903         const TMacAddress* aDestinationAddress = NULL );

   904 

   905     /**

   906     * Clears TxDataBuffer, makes it zero length size

   907     *

   908     * @since S60 3.1

   909     */

   910     inline void ClearTxDataBuffer();

   911     

   912     /**

   913     * Set data buffer address

   914     *

   915     * Note! This method is executed in user mode context by the user mode

   916     * client interface, i.e. not the client itself!

   917     * @since S60 3.1

   918     * @param aUserAddr user address of the buffer

   919     */

   920     inline void SetTxDataBufferField( TLinAddr aUserAddr );

   921 

   922 #endif /* User mode end*/    

   923 

   924 #ifdef __KERNEL_MODE__ /* Kernel mode */

   925     

   926     /**

   927     * Initialises the buffer.

   928     *

   929     *  @param aTxBufLength

   930     */

   931     inline void Initialize( TUint32 aTxBufLength );

   932     

   933 #endif /* Kernel mode end */

   934     

   935 private:

   936 

   937     /** Prohibit default constructor */

   938     RFrameXferBlock();

   939 

   940     /** Prohibit copy constructor */

   941     RFrameXferBlock( const RFrameXferBlock& );

   942     /** Prohibit assigment operator */

   943     RFrameXferBlock& operator= ( const RFrameXferBlock& );

   944     

   945 private: // data

   946 

   947     /** Tx-data buffer */

   948     TDataBuffer*    iTxDataBuffer;

   949 

   950     /** 

   951     * stores the total capacity (length) of the Tx buffer (iTxDataBuffer) 

   952     * associated with this object instance

   953     */

   954     TUint32         iTxBufLength;

   955     };

   956 

   957 #ifndef __KERNEL_MODE__ /* User mode */

   958 

   959 // ---------------------------------------------------------------------------

   960 // 

   961 // ---------------------------------------------------------------------------

   962 //

   963 inline TInt RFrameXferBlock::AppendTxDataBuffer( 

   964     const TUint8* aData, 

   965     TUint32 aLength,

   966     TDataBuffer::TFrameType aFrameType,

   967     TUint8 aUserPriority,

   968     TBool aMustNotBeEncrypted,

   969     const TMacAddress* aDestinationAddress )

   970     {

   971     if ( aLength <= 

   972         iTxBufLength - 

   973         iTxOffset[aFrameType] - 

   974         iTxDataBuffer->GetLength() )

   975         {

   976         // provided data fits into buffer

   977         

   978         iTxDataBuffer->FrameType( aFrameType );

   979         iTxDataBuffer->AppendBuffer( aData, aLength, iTxOffset[aFrameType] );

   980         iTxDataBuffer->SetUserPriority( aUserPriority );

   981 

   982         if ( aMustNotBeEncrypted )

   983             {

   984             iTxDataBuffer->KeSetFlags( 

   985                 TDataBuffer::KTxFrameMustNotBeEncrypted );

   986             }

   987         else

   988             {

   989             iTxDataBuffer->KeClearFlags( 

   990                 TDataBuffer::KTxFrameMustNotBeEncrypted );

   991             }

   992 

   993         if ( aDestinationAddress )

   994             {

   995             iTxDataBuffer->SetDestinationAddress( *aDestinationAddress );

   996             }

   997         

   998         return KErrNone;

   999         }

  1000     else

  1001         {

  1002         return KErrOverflow;        

  1003         }    

  1004     }

  1005 

  1006 // ---------------------------------------------------------------------------

  1007 // 

  1008 // ---------------------------------------------------------------------------

  1009 //

  1010 inline void RFrameXferBlock::ClearTxDataBuffer()

  1011     {

  1012     iTxDataBuffer->SetLength( 0 );

  1013     }

  1014 

  1015 // ---------------------------------------------------------------------------

  1016 // 

  1017 // ---------------------------------------------------------------------------

  1018 //

  1019 inline void RFrameXferBlock::SetTxDataBufferField( TLinAddr aUserAddr )

  1020     {

  1021     iTxDataBuffer = reinterpret_cast<TDataBuffer*>(aUserAddr);

  1022     }

  1023 

  1024 #endif /* User mode end */

  1025 

  1026 #ifdef __KERNEL_MODE__ /* Kernel mode */

  1027 

  1028 // ---------------------------------------------------------------------------

  1029 // 

  1030 // ---------------------------------------------------------------------------

  1031 //

  1032 inline void RFrameXferBlock::Initialize( TUint32 aTxBufLength )

  1033     {

  1034     // perform base class initialization first

  1035     KeInitialize();

  1036     

  1037     iTxDataBuffer = NULL;

  1038     iTxBufLength = aTxBufLength;

  1039     }

  1040 

  1041 #endif  /* Kernel mode end */

  1042 

  1043 /**

  1044 * Ethernet frame transfer context block between user and kernel space 

  1045 * for the protocol stack side client 

  1046 * 

  1047 */

  1048 class RFrameXferBlockProtocolStack : public RFrameXferBlock

  1049     {

  1050 

  1051 public:

  1052 

  1053 #ifndef __KERNEL_MODE__ /* User mode */

  1054     

  1055     /** 

  1056      * Initializes TX Data pool, with the address of this in user space.

  1057      * 

  1058      * @param aThisAddrUserSpace Address of this object in user space.

  1059      */

  1060     inline void UserInitialize( TUint32 aThisAddrUserSpace );

  1061     

  1062 #endif /* User mode end */    

  1063 

  1064 #ifdef __KERNEL_MODE__ /* Kernel mode */

  1065     

  1066     /**

  1067      * Initialises Kernel's memory interface to shared memory between User

  1068      * and Kernel Space.

  1069      */ 

  1070     void Initialise();

  1071     

  1072     /**

  1073      * Allocates a Tx buffer from the shared memory.

  1074      * 

  1075      * @param aTxBuf Pointer to the pre-allocated actual Tx buffer.

  1076      * @param aBufLength Length of the Tx buffer.

  1077      * @return Pointer to the meta header attached to the allocated buffer, on

  1078      *         success.

  1079      *         NULL, in case of allocation failure.

  1080      */

  1081     TDataBuffer* AllocTxBuffer( const TUint8* aTxBuf, TUint16 aBufLength );

  1082     

  1083     /**

  1084      * Adds the specified Tx frame (contained in the buffer allocated from the 

  1085      * shared memory) to the relevant Tx queue according to its AC (i.e.

  1086      * priority).

  1087      *  

  1088      * @param aPacketInUserSpace Meta header attached to the frame; as a user

  1089      *        space pointer.

  1090      * @param aPacketInKernSpace If not NULL on return, the frame needs to be 

  1091      *        discarded and this is the kernel space pointer to its meta header.

  1092      *        If NULL on return, the frame must not be discarded. 

  1093      * @param aUserDataTxEnabled ETrue if user data Tx is enabled

  1094      *        EFalse otherwise

  1095      * @return ETrue if the client is allowed to continue calling this method

  1096      *         (i.e. Tx flow is not stopped).

  1097      *         EFalse if the client is not allowed to call this method again

  1098      *         (i.e. Tx flow is stopped) until it is re-allowed.

  1099      */

  1100     TBool AddTxFrame( 

  1101         TDataBuffer* aPacketInUserSpace, 

  1102         TDataBuffer*& aPacketInKernSpace, 

  1103         TBool aUserDataTxEnabled );

  1104     

  1105     /**

  1106      * Gets the frame to be transmitted next from the Tx queues.

  1107      * 

  1108      * @param aWhaTxQueueState State (full / not full) of every WHA transmit 

  1109      *        queue

  1110      * @param aMore On return is ETrue if another frame is also ready to be 

  1111      *        transmitted, EFalse otherwise

  1112      * @return Pointer to the meta header of the frame to be transmitted, on

  1113      *         success

  1114      *         NULL, if there's no frame that could be transmitted, given the

  1115      *         current status of the WHA Tx queues

  1116      */ 

  1117     TDataBuffer* GetTxFrame( 

  1118         const TWhaTxQueueState& aWhaTxQueueState,

  1119         TBool& aMore );

  1120     

  1121     /**

  1122      * Deallocates a Tx packet.

  1123      * 

  1124      * All Tx packets allocated with AllocTxBuffer() must be deallocated using

  1125      * this method.

  1126      * 

  1127      * @param aPacket Meta header of the packet to the deallocated

  1128      */ 

  1129     inline void FreeTxPacket( TDataBuffer*& aPacket );

  1130     

  1131     /** 

  1132      * Determines if Tx from protocol stack side client should be resumed

  1133      * 

  1134      * @param aUserDataTxEnabled ETrue if user data Tx is enabled