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 DEthernetFrameMemMngr class.

    15 *

    16 */

    17 

    18 /*

    19 * %version: 17 %

    20 */

    21 

    22 #ifndef DETHERNETFRAMEMEMMNGR_H

    23 #define DETHERNETFRAMEMEMMNGR_H

    24 

    25 #include "FrameXferBlock.h"

    26 #include "WlanLogicalChannel.h"

    27 

    28 class RFrameXferBlock;

    29 class DThread;

    30 class TDataBuffer;

    31 

    32 class TSharedChunkInfo;

    33 class WlanChunk;

    34 

    35 /**

    36 * Manager object for frame Tx and Rx memory

    37 *

    38 * Consumed count of Rx-buffers = 

    39 * nbr of Rx buffers currently under processing in user mode        

    40 * + nbr of Rx buffers given to wlanpdd

    41 * + nbr of Rx buffers waiting for completion to user mode

    42 *

    43 *  @since S60 v3.1

    44 */

    45 class DEthernetFrameMemMngr

    46     {

    47 

    48 public:

    49 

    50     /** Dtor */

    51     virtual ~DEthernetFrameMemMngr();

    52 

    53     /**

    54     * Memory intilisation method.

    55     * Allocates a shared memory chunk, if relevant, and opens a handle to it

    56     * for the user mode client.

    57     *

    58     * @since S60 3.1

    59     * @param aThread calling processes DThread object

    60     * @param aSharedChunkInfo After successful return contains the handle to the

    61     *        chunk

    62     * @param aVendorTxHdrLen Amount of free space (bytes) that the WLAN vendor

    63     *        implementation requires to exist in a Tx buffer before the 802.11

    64     *        MPDU to be sent

    65     * @param aVendorTxTrailerLen Amount of free space (bytes) that the WLAN 

    66     *        vendor implementation requires to exist in a Tx buffer after the

    67     *        802.11 MPDU to be sent 

    68     * @return system wide error code, KErrNone upon success

    69     */

    70     TInt OnInitialiseMemory( 

    71         DThread& aThread,

    72         TSharedChunkInfo* aSharedChunkInfo,

    73         TUint aVendorTxHdrLen,

    74         TUint aVendorTxTrailerLen );

    75 

    76     /**

    77     * Checks if the memory is in use, i.e. is it allocated and attached to the 

    78     * address space of the user mode client process 

    79     * @return the state of the memory: in use (ETrue), or not (EFalse)

    80     */

    81     TBool IsMemInUse() const { return iInUse; }

    82 

    83     /**

    84     * Memory finalization method.

    85     * Deallocates the shared memory chunk, if relevant

    86     *

    87     * @since S60 3.1

    88     */

    89     virtual void OnReleaseMemory();

    90 

    91     /**

    92     * Gets a memory block that can be used for tx frame write

    93     *

    94     * @since S60 3.1

    95     * @return memory block that can be used for tx frame write, 

    96     * NULL upon failure

    97     */

    98     TDataBuffer* OnWriteEthernetFrame() const;

    99 

   100     /**

   101     * Gets a memory block that can be used as rx frame buffer

   102     *

   103     * @since S60 3.1

   104     * @param aLengthinBytes Requested buffer length

   105     * @return memory block that can be used as rx frame buffer

   106     *         NULL upon failure

   107     */

   108     TUint8* OnGetEthernetFrameRxBuffer( TUint aLengthinBytes );

   109 

   110     /**

   111     * Gets a memory block for storing Rx frame meta header

   112     *

   113     * @return memory block for storing Rx frame meta header on success

   114     *         NULL upon failure

   115     */

   116     TDataBuffer* GetRxFrameMetaHeader();

   117 

   118     /**

   119     * Deallocates Rx frame meta header

   120     * @param aMetaHeader Meta header to deallocate

   121     */

   122     void FreeRxFrameMetaHeader( TDataBuffer* aMetaHeader );

   123     

   124     /**

   125     * To be called when rx frame read cycle has ended.

   126     *

   127     * @since S60 3.1

   128     * @param aBufferStart first element of the array that holds pointers to

   129     *        Rx frame meta headers

   130     * @param aNumOfBuffers number of meta header pointers in the array

   131     * @return ETrue if a pending user mode frame read request exists 

   132     *         and callee should complete it, 

   133     *         EFalse otherwise

   134     */

   135     TBool OnEthernetFrameRxComplete( 

   136         const TDataBuffer*& aBufferStart, 

   137         TUint32 aNumOfBuffers );

   138 

   139     /**

   140     * To be called when user mode issues a rx frame read request

   141     *

   142     * @since S60 3.1

   143     * @return ETrue if callee should complete the request immediadly 

   144     * as their exist data to be completed, EFalse otherwise

   145     */

   146     TBool OnReadRequest();

   147 

   148     /**

   149     * Frees the specified Rx frame buffer

   150     *

   151     * @since S60 3.1

   152     * @param aBufferToFree The buffer to free

   153     */

   154     virtual void DoMarkRxBufFree( TUint8* aBufferToFree );

   155 

   156     /**

   157      * Allocates a Tx packet from the shared memory.

   158      * 

   159      * @param aLength Length of the requested Tx buffer in bytes

   160      * @return Pointer to the meta header attached to the allocated packet, on

   161      *         success.

   162      *         NULL, in case of failure.

   163      */

   164     virtual TDataBuffer* AllocTxBuffer( TUint aLength );

   165     

   166     /**

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

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

   169      * priority).

   170      *  

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

   172      *        space pointer.

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

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

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

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

   177      *        EFalse otherwise

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

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

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

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

   182      */

   183     TBool AddTxFrame( 

   184         TDataBuffer* aPacketInUserSpace, 

   185         TDataBuffer*& aPacketInKernSpace,

   186         TBool aUserDataTxEnabled );

   187     

   188     /**

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

   190      * 

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

   192      *        queue

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

   194      *        transmitted, EFalse otherwise

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

   196      *         success

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

   198      *         current status of the WHA Tx queues

   199      */ 

   200     TDataBuffer* GetTxFrame( 

   201         const TWhaTxQueueState& aTxQueueState,

   202         TBool& aMore );

   203     

   204     /**

   205      * Deallocates a Tx packet.

   206      * 

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

   208      * this method.

   209      * 

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

   211      */ 

   212     virtual void FreeTxPacket( TDataBuffer*& aPacket );

   213     

   214     /** 

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

   216      *  

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

   218      *        EFalse otherwise

   219      * @return ETrue if Tx should be resumed

   220      *         EFalse otherwise

   221      */

   222     TBool ResumeClientTx( TBool aUserDataTxEnabled ) const;

   223     

   224     /** 

   225      * Determines if all protocol stack side client's Tx queues are empty

   226      * 

   227      * @return ETrue if all Tx queues are empty

   228      *         EFalse otherwise

   229      */

   230     TBool AllTxQueuesEmpty() const;

   231     

   232     /**

   233     * Static creator of the class instance

   234     * @param aUnit identifier of the type of object to be created

   235     * @param aParent 

   236     * @param aRxFrameMemoryPool 

   237     * @param aUseCachedMemory ETrue if cached frame transfer memory shall be

   238     *        used,

   239     *        EFalse otherwise 

   240     * @param aFrameBufAllocationUnit size of the Rx/Tx frame buffer allocation

   241     *        unit in bytes

   242     * @return DEthernetFrameMemMngr object or NULL upon failure

   243     *

   244     * @since S60 3.1

   245     */

   246     static DEthernetFrameMemMngr* Init( 

   247         TInt aUnit, 

   248         DWlanLogicalChannel& aParent,

   249         WlanChunk*& aRxFrameMemoryPool,

   250         TBool aUseCachedMemory,

   251         TInt aFrameBufAllocationUnit );

   252 

   253     /**

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

   255     *

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

   257     *        Test frames

   258     * @param aDot11FrameTxOffset Tx offset for 802.11 frames

   259     * @param aSnapFrameTxOffset Tx offset for SNAP frames

   260     */

   261     void SetTxOffsets( 

   262         TUint32 aEthernetFrameTxOffset,

   263         TUint32 aDot11FrameTxOffset,

   264         TUint32 aSnapFrameTxOffset );

   265 

   266    

   267 protected: 

   268 

   269     /** Ctor */

   270     DEthernetFrameMemMngr( 

   271         DWlanLogicalChannel& aParent, 

   272         WlanChunk*& aRxFrameMemoryPool ) :

   273         iReadStatus( ENotPending ), 

   274         iFrameXferBlock( NULL ), 

   275         iCountCompleted( 0 ), 

   276         iCountTobeCompleted( 0 ),

   277         iTxDataBuffer( NULL ), 

   278         iRxDataChunk( NULL ),

   279         iParent( aParent ),

   280         iRxFrameMemoryPool( aRxFrameMemoryPool ),

   281         iRxBufAlignmentPadding( 0 ),

   282         iVendorTxHdrLen( 0 ),

   283         iVendorTxTrailerLen( 0 ),

   284         iInUse( EFalse )

   285         {};

   286 

   287     /**

   288     * Allocates a shared memory chunk for frame transfer between user

   289     * and kernel address spaces

   290     *

   291     * @since S60 3.1

   292     * @param aSharedMemoryChunk The shared memory chunk

   293     * @return system wide error code, KErrNone upon success

   294     */

   295     virtual TInt DoAllocate( DChunk*& aSharedMemoryChunk );

   296 

   297     /**

   298     * Opens a handle for user mode client to the shared memory chunk

   299     * allocated for frame transfer between user and kernel address spaces

   300     *

   301     * @since S60 3.1

   302     * @param aThread The user mode client thread

   303     * @param aSharedChunkInfo After successful return contains the handle to the

   304     *        chunk

   305     * @param aSharedMemoryChunk The shared memory chunk

   306     * @return system wide error code, KErrNone upon success

   307     */

   308     virtual TInt DoOpenHandle(

   309         DThread& aThread,

   310         TSharedChunkInfo& aSharedChunkInfo,

   311         DChunk* aSharedMemoryChunk ) = 0;

   312 

   313     /**

   314     * Gets a free rx buffer

   315     *

   316     * @since S60 3.1

   317     * @param aLengthinBytes Requested buffer length

   318     * @return buffer for Rx data upon success

   319     *         NULL otherwise

   320     */

   321     virtual TUint8* DoGetNextFreeRxBuffer( TUint aLengthinBytes );

   322 

   323     /**

   324     * Gets called when rx frame read cycle has ended.

   325     *

   326     * @since S60 3.1

   327     * @param aBufferStart first element of the array that holds pointers to

   328     *        Rx frame meta headers

   329     * @param aNumOfBuffers number of meta header pointers in the array

   330     * @return ETrue if a pending user mode frame read request exists 

   331     *         and callee should complete it, 

   332     *         EFalse otherwise

   333     */

   334     virtual TBool DoEthernetFrameRxComplete( 

   335         const TDataBuffer*& aBufferStart, 

   336         TUint32 aNumOfBuffers ) = 0;

   337 

   338     /**

   339     * Gets start address of Rx buffers (their offset addresses)

   340     * that are waiting for completion to user mode

   341     *

   342     * @since S60 3.1

   343     * @return see above statement

   344     */

   345     virtual TUint32* DoGetTobeCompletedBuffersStart() = 0;

   346 

   347     /**

   348     * Gets start address of Rx buffers (their offset addresses)

   349     * that have been completed to user mode

   350     *

   351     * @since S60 3.1

   352     * @return see above statement

   353     */

   354     virtual TUint32* DoGetCompletedBuffersStart() = 0;        

   355 

   356     /**

   357     * Gets called when user mode client issues a frame receive request 

   358     * and Rx buffers have been completed to it. The completed Rx frame 

   359     * buffers are freed.

   360     *

   361     * @since S60 3.1

   362     */

   363     virtual void DoFreeRxBuffers() = 0;

   364 

   365     /**

   366     * Marks memory as not in use, meaning that it is not allocated 

   367     * and attached to calling process'es address space

   368     */

   369     void MarkMemFree() { iInUse = EFalse; }  

   370     

   371 private:

   372 

   373     /**

   374     * Marks memory as in use, meaning that is it allocated 

   375     * and attached to calling processes address space

   376     */

   377     void MarkMemInUSe() { iInUse = ETrue; }

   378 

   379     // Prohibit copy constructor.

   380     DEthernetFrameMemMngr( const DEthernetFrameMemMngr& );

   381     // Prohibit assigment operator.

   382     DEthernetFrameMemMngr& operator= ( const DEthernetFrameMemMngr& );

   383 

   384 protected:  // Data

   385 

   386     enum TFrameReadState 

   387         { 

   388         /** there is no rx frame read request pending in kernel-mode */

   389         ENotPending, 

   390         /** 

   391         * there is rx frame read request waiting 

   392         * to be completed in kernel-mode 

   393         */

   394 	    EPending

   395         };

   396 

   397     /** state  of the rx frame read request */

   398     TFrameReadState    iReadStatus;

   399 

   400     /** kernel address of xfer block */

   401     RFrameXferBlock*    iFrameXferBlock;

   402 

   403     /**

   404     * amount of rx frame buffers that are 

   405     * currently under processing in user mode

   406     */

   407     TUint32 iCountCompleted;

   408 

   409     /**

   410     * amount of rx frame buffers waiting completion to user mode

   411     */

   412     TUint32 iCountTobeCompleted;

   413 

   414     /** kernel address of Tx-data buffer */

   415     TDataBuffer*        iTxDataBuffer;

   416 

   417     /** pointer to Rx area start in the kernel address space */

   418     TUint8*             iRxDataChunk;

   419 

   420     /** 

   421     * reference to logical channel object instance owning this object 

   422     * instance

   423     */

   424     DWlanLogicalChannel& iParent;

   425     

   426     /** 

   427     * reference to Rx frame memory pool manager

   428     */

   429     WlanChunk*&  iRxFrameMemoryPool;

   430 

   431     /** 

   432     * number of extra bytes required to align Rx buffer start address

   433     * to be returned to WHA layer to allocation unit boundary

   434     */

   435     TInt iRxBufAlignmentPadding;   

   436     

   437     /** 

   438     * amount of free space (bytes) that the WLAN vendor implementation 

   439     * requires to exist in a Tx buffer before the 802.11 MPDU to be sent

   440     */

   441     TUint iVendorTxHdrLen;

   442     

   443     /** 

   444     * amount of free space (bytes) that the WLAN vendor implementation 

   445     * requires to exist in a Tx buffer after the 802.11 MPDU to be sent

   446     */

   447     TUint iVendorTxTrailerLen;

   448     

   449 private:    // Data

   450     

   451     /** is memory in use or not */

   452     TBool               iInUse;

   453     };

   454 

   455 #endif // DETHERNETFRAMEMEMMNGR_H