--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/wlan_bearer/wlanldd/wlan_symbian/wlanldd_symbian/inc/EthernetFrameMemMngr.h Tue Feb 02 02:03:13 2010 +0200
@@ -0,0 +1,455 @@
+/*
+* 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 DEthernetFrameMemMngr class.
+*
+*/
+
+/*
+* %version: 17 %
+*/
+
+#ifndef DETHERNETFRAMEMEMMNGR_H
+#define DETHERNETFRAMEMEMMNGR_H
+
+#include "FrameXferBlock.h"
+#include "WlanLogicalChannel.h"
+
+class RFrameXferBlock;
+class DThread;
+class TDataBuffer;
+
+class TSharedChunkInfo;
+class WlanChunk;
+
+/**
+* Manager object for frame Tx and Rx memory
+*
+* Consumed count of Rx-buffers =
+* nbr of Rx buffers currently under processing in user mode
+* + nbr of Rx buffers given to wlanpdd
+* + nbr of Rx buffers waiting for completion to user mode
+*
+* @since S60 v3.1
+*/
+class DEthernetFrameMemMngr
+ {
+
+public:
+
+ /** Dtor */
+ virtual ~DEthernetFrameMemMngr();
+
+ /**
+ * Memory intilisation method.
+ * Allocates a shared memory chunk, if relevant, and opens a handle to it
+ * for the user mode client.
+ *
+ * @since S60 3.1
+ * @param aThread calling processes DThread object
+ * @param aSharedChunkInfo After successful return contains the handle to the
+ * chunk
+ * @param aVendorTxHdrLen Amount of free space (bytes) that the WLAN vendor
+ * implementation requires to exist in a Tx buffer before the 802.11
+ * MPDU to be sent
+ * @param aVendorTxTrailerLen Amount of free space (bytes) that the WLAN
+ * vendor implementation requires to exist in a Tx buffer after the
+ * 802.11 MPDU to be sent
+ * @return system wide error code, KErrNone upon success
+ */
+ TInt OnInitialiseMemory(
+ DThread& aThread,
+ TSharedChunkInfo* aSharedChunkInfo,
+ TUint aVendorTxHdrLen,
+ TUint aVendorTxTrailerLen );
+
+ /**
+ * Checks if the memory is in use, i.e. is it allocated and attached to the
+ * address space of the user mode client process
+ * @return the state of the memory: in use (ETrue), or not (EFalse)
+ */
+ TBool IsMemInUse() const { return iInUse; }
+
+ /**
+ * Memory finalization method.
+ * Deallocates the shared memory chunk, if relevant
+ *
+ * @since S60 3.1
+ */
+ virtual void OnReleaseMemory();
+
+ /**
+ * Gets a memory block that can be used for tx frame write
+ *
+ * @since S60 3.1
+ * @return memory block that can be used for tx frame write,
+ * NULL upon failure
+ */
+ TDataBuffer* OnWriteEthernetFrame() const;
+
+ /**
+ * Gets a memory block that can be used as rx frame buffer
+ *
+ * @since S60 3.1
+ * @param aLengthinBytes Requested buffer length
+ * @return memory block that can be used as rx frame buffer
+ * NULL upon failure
+ */
+ TUint8* OnGetEthernetFrameRxBuffer( TUint aLengthinBytes );
+
+ /**
+ * Gets a memory block for storing Rx frame meta header
+ *
+ * @return memory block for storing Rx frame meta header on success
+ * NULL upon failure
+ */
+ TDataBuffer* GetRxFrameMetaHeader();
+
+ /**
+ * Deallocates Rx frame meta header
+ * @param aMetaHeader Meta header to deallocate
+ */
+ void FreeRxFrameMetaHeader( TDataBuffer* aMetaHeader );
+
+ /**
+ * To be called when rx frame read cycle has ended.
+ *
+ * @since S60 3.1
+ * @param aBufferStart first element of the array that holds pointers to
+ * Rx frame meta headers
+ * @param aNumOfBuffers number of meta header pointers in the array
+ * @return ETrue if a pending user mode frame read request exists
+ * and callee should complete it,
+ * EFalse otherwise
+ */
+ TBool OnEthernetFrameRxComplete(
+ const TDataBuffer*& aBufferStart,
+ TUint32 aNumOfBuffers );
+
+ /**
+ * To be called when user mode issues a rx frame read request
+ *
+ * @since S60 3.1
+ * @return ETrue if callee should complete the request immediadly
+ * as their exist data to be completed, EFalse otherwise
+ */
+ TBool OnReadRequest();
+
+ /**
+ * Frees the specified Rx frame buffer
+ *
+ * @since S60 3.1
+ * @param aBufferToFree The buffer to free
+ */
+ virtual void DoMarkRxBufFree( TUint8* aBufferToFree );
+
+ /**
+ * Allocates a Tx packet from the shared memory.
+ *
+ * @param aLength Length of the requested Tx buffer in bytes
+ * @return Pointer to the meta header attached to the allocated packet, on
+ * success.
+ * NULL, in case of failure.
+ */
+ virtual TDataBuffer* AllocTxBuffer( TUint aLength );
+
+ /**
+ * Adds the specified Tx frame (contained in the buffer allocated from the
+ * shared memory) to the relevant Tx queue according to its AC (i.e.
+ * priority).
+ *
+ * @param aPacketInUserSpace Meta header attached to the frame; as a user
+ * space pointer.
+ * @param aPacketInKernSpace If not NULL on return, the frame needs to be
+ * discarded and this is the kernel space pointer to its meta header.
+ * If NULL on return, the frame must not be discarded.
+ * @param aUserDataTxEnabled ETrue if user data Tx is enabled
+ * EFalse otherwise
+ * @return ETrue if the client is allowed to continue calling this method
+ * (i.e. Tx flow is not stopped).
+ * EFalse if the client is not allowed to call this method again
+ * (i.e. Tx flow is stopped) until it is re-allowed.
+ */
+ TBool AddTxFrame(
+ TDataBuffer* aPacketInUserSpace,
+ TDataBuffer*& aPacketInKernSpace,
+ TBool aUserDataTxEnabled );
+
+ /**
+ * Gets the frame to be transmitted next from the Tx queues.
+ *
+ * @param aWhaTxQueueState State (full / not full) of every WHA transmit
+ * queue
+ * @param aMore On return is ETrue if another frame is also ready to be
+ * transmitted, EFalse otherwise
+ * @return Pointer to the meta header of the frame to be transmitted, on
+ * success
+ * NULL, if there's no frame that could be transmitted, given the
+ * current status of the WHA Tx queues
+ */
+ TDataBuffer* GetTxFrame(
+ const TWhaTxQueueState& aTxQueueState,
+ TBool& aMore );
+
+ /**
+ * Deallocates a Tx packet.
+ *
+ * All Tx packets allocated with AllocTxBuffer() must be deallocated using
+ * this method.
+ *
+ * @param aPacket Meta header of the packet to the deallocated
+ */
+ virtual void FreeTxPacket( TDataBuffer*& aPacket );
+
+ /**
+ * Determines if Tx from protocol stack side client should be resumed
+ *
+ * @param aUserDataTxEnabled ETrue if user data Tx is enabled
+ * EFalse otherwise
+ * @return ETrue if Tx should be resumed
+ * EFalse otherwise
+ */
+ TBool ResumeClientTx( TBool aUserDataTxEnabled ) const;
+
+ /**
+ * Determines if all protocol stack side client's Tx queues are empty
+ *
+ * @return ETrue if all Tx queues are empty
+ * EFalse otherwise
+ */
+ TBool AllTxQueuesEmpty() const;
+
+ /**
+ * Static creator of the class instance
+ * @param aUnit identifier of the type of object to be created
+ * @param aParent
+ * @param aRxFrameMemoryPool
+ * @param aUseCachedMemory ETrue if cached frame transfer memory shall be
+ * used,
+ * EFalse otherwise
+ * @param aFrameBufAllocationUnit size of the Rx/Tx frame buffer allocation
+ * unit in bytes
+ * @return DEthernetFrameMemMngr object or NULL upon failure
+ *
+ * @since S60 3.1
+ */
+ static DEthernetFrameMemMngr* Init(
+ TInt aUnit,
+ DWlanLogicalChannel& aParent,
+ WlanChunk*& aRxFrameMemoryPool,
+ TBool aUseCachedMemory,
+ TInt aFrameBufAllocationUnit );
+
+ /**
+ * Sets the Tx offset for every frame type which can be transmitted
+ *
+ * @param aEthernetFrameTxOffset Tx offset for Ethernet frames and Ethernet
+ * Test frames
+ * @param aDot11FrameTxOffset Tx offset for 802.11 frames
+ * @param aSnapFrameTxOffset Tx offset for SNAP frames
+ */
+ void SetTxOffsets(
+ TUint32 aEthernetFrameTxOffset,
+ TUint32 aDot11FrameTxOffset,
+ TUint32 aSnapFrameTxOffset );
+
+
+protected:
+
+ /** Ctor */
+ DEthernetFrameMemMngr(
+ DWlanLogicalChannel& aParent,
+ WlanChunk*& aRxFrameMemoryPool ) :
+ iReadStatus( ENotPending ),
+ iFrameXferBlock( NULL ),
+ iCountCompleted( 0 ),
+ iCountTobeCompleted( 0 ),
+ iTxDataBuffer( NULL ),
+ iRxDataChunk( NULL ),
+ iParent( aParent ),
+ iRxFrameMemoryPool( aRxFrameMemoryPool ),
+ iRxBufAlignmentPadding( 0 ),
+ iVendorTxHdrLen( 0 ),
+ iVendorTxTrailerLen( 0 ),
+ iInUse( EFalse )
+ {};
+
+ /**
+ * Allocates a shared memory chunk for frame transfer between user
+ * and kernel address spaces
+ *
+ * @since S60 3.1
+ * @param aSharedMemoryChunk The shared memory chunk
+ * @return system wide error code, KErrNone upon success
+ */
+ virtual TInt DoAllocate( DChunk*& aSharedMemoryChunk );
+
+ /**
+ * Opens a handle for user mode client to the shared memory chunk
+ * allocated for frame transfer between user and kernel address spaces
+ *
+ * @since S60 3.1
+ * @param aThread The user mode client thread
+ * @param aSharedChunkInfo After successful return contains the handle to the
+ * chunk
+ * @param aSharedMemoryChunk The shared memory chunk
+ * @return system wide error code, KErrNone upon success
+ */
+ virtual TInt DoOpenHandle(
+ DThread& aThread,
+ TSharedChunkInfo& aSharedChunkInfo,
+ DChunk* aSharedMemoryChunk ) = 0;
+
+ /**
+ * Gets a free rx buffer
+ *
+ * @since S60 3.1
+ * @param aLengthinBytes Requested buffer length
+ * @return buffer for Rx data upon success
+ * NULL otherwise
+ */
+ virtual TUint8* DoGetNextFreeRxBuffer( TUint aLengthinBytes );
+
+ /**
+ * Gets called when rx frame read cycle has ended.
+ *
+ * @since S60 3.1
+ * @param aBufferStart first element of the array that holds pointers to
+ * Rx frame meta headers
+ * @param aNumOfBuffers number of meta header pointers in the array
+ * @return ETrue if a pending user mode frame read request exists
+ * and callee should complete it,
+ * EFalse otherwise
+ */
+ virtual TBool DoEthernetFrameRxComplete(
+ const TDataBuffer*& aBufferStart,
+ TUint32 aNumOfBuffers ) = 0;
+
+ /**
+ * Gets start address of Rx buffers (their offset addresses)
+ * that are waiting for completion to user mode
+ *
+ * @since S60 3.1
+ * @return see above statement
+ */
+ virtual TUint32* DoGetTobeCompletedBuffersStart() = 0;
+
+ /**
+ * Gets start address of Rx buffers (their offset addresses)
+ * that have been completed to user mode
+ *
+ * @since S60 3.1
+ * @return see above statement
+ */
+ virtual TUint32* DoGetCompletedBuffersStart() = 0;
+
+ /**
+ * Gets called when user mode client issues a frame receive request
+ * and Rx buffers have been completed to it. The completed Rx frame
+ * buffers are freed.
+ *
+ * @since S60 3.1
+ */
+ virtual void DoFreeRxBuffers() = 0;
+
+ /**
+ * Marks memory as not in use, meaning that it is not allocated
+ * and attached to calling process'es address space
+ */
+ void MarkMemFree() { iInUse = EFalse; }
+
+private:
+
+ /**
+ * Marks memory as in use, meaning that is it allocated
+ * and attached to calling processes address space
+ */
+ void MarkMemInUSe() { iInUse = ETrue; }
+
+ // Prohibit copy constructor.
+ DEthernetFrameMemMngr( const DEthernetFrameMemMngr& );
+ // Prohibit assigment operator.
+ DEthernetFrameMemMngr& operator= ( const DEthernetFrameMemMngr& );
+
+protected: // Data
+
+ enum TFrameReadState
+ {
+ /** there is no rx frame read request pending in kernel-mode */
+ ENotPending,
+ /**
+ * there is rx frame read request waiting
+ * to be completed in kernel-mode
+ */
+ EPending
+ };
+
+ /** state of the rx frame read request */
+ TFrameReadState iReadStatus;
+
+ /** kernel address of xfer block */
+ RFrameXferBlock* iFrameXferBlock;
+
+ /**
+ * amount of rx frame buffers that are
+ * currently under processing in user mode
+ */
+ TUint32 iCountCompleted;
+
+ /**
+ * amount of rx frame buffers waiting completion to user mode
+ */
+ TUint32 iCountTobeCompleted;
+
+ /** kernel address of Tx-data buffer */
+ TDataBuffer* iTxDataBuffer;
+
+ /** pointer to Rx area start in the kernel address space */
+ TUint8* iRxDataChunk;
+
+ /**
+ * reference to logical channel object instance owning this object
+ * instance
+ */
+ DWlanLogicalChannel& iParent;
+
+ /**
+ * reference to Rx frame memory pool manager
+ */
+ WlanChunk*& iRxFrameMemoryPool;
+
+ /**
+ * number of extra bytes required to align Rx buffer start address
+ * to be returned to WHA layer to allocation unit boundary
+ */
+ TInt iRxBufAlignmentPadding;
+
+ /**
+ * amount of free space (bytes) that the WLAN vendor implementation
+ * requires to exist in a Tx buffer before the 802.11 MPDU to be sent
+ */
+ TUint iVendorTxHdrLen;
+
+ /**
+ * amount of free space (bytes) that the WLAN vendor implementation
+ * requires to exist in a Tx buffer after the 802.11 MPDU to be sent
+ */
+ TUint iVendorTxTrailerLen;
+
+private: // Data
+
+ /** is memory in use or not */
+ TBool iInUse;
+ };
+
+#endif // DETHERNETFRAMEMEMMNGR_H