/*
* Copyright (c) 2007-2008 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:   WlanMemoryPool declaration
*
*/

/*
* %version: 6 %
*/

#ifndef WLANMEMORYPOOL_H
#define WLANMEMORYPOOL_H

#include "wlanobject.h"

#include "osaplatformhwchunk.h"
#include "osalist.h"
#include "osahandle.h"

struct SMemHeader;

/**
 *  memory pool for managing memory
 *
 *
 *  @lib wlanosa.lib
 *  @since S60 v3.2
 */
class WlanMemoryPool : public DBase, public WlanObject
    {

    typedef Handle<WlanPlatformHwChunk> HwChunkHandle;

public:

    /**
     * ctor
     * NOTE: call IsValid() member from super class 
     * to validate object after ctor
     *
     * @since S60 v3.2
     * @param aUseCachedMemory ETrue if cached memory shall be used
     *                         EFalse otherwise
     * @param aAllocationUnit allocation unit size for interconnect memory in
     *        bytes
     */
    explicit WlanMemoryPool( TBool aUseCachedMemory, TInt aAllocationUnit );

	/**
	 * Destructor.
	 *
	 * @since S60 v3.2
	 */
    virtual ~WlanMemoryPool();

    /**
     * Memory allocation. 
     * Correct alignment guaranteed
     *
     * @since S60 v3.2
     * @param aOsaMemoryType memory type to be allocated
     * @param aSize size of the buffer to be allocated in bytes. 
     *              Must be positive otherwise the allocation fails
     * @param aZeroStamp zero stamp the memory or not
     * @return begin of the allocated memory, NULL upon failure
     */
    void* Alloc( MWlanOsa::TOsaMemoryType aOsaMemoryType, 
                 TInt aSize, 
                 TBool aZeroStamp );

    /**
     * Releases memory allocated by the Alloc method
     *
     * @since S60 v3.2
     * @param aPtr begin of the buffer to be freed
     */
    void Free( void* aPtr );

private:

    /**
     * Init pool
     *
     * @since S60 v3.2
     * @return ETrue upon success any other for failure
     */
    TBool InitPool();

    /**
     * Appends hw chunk handle to the back of the list
     *
     * @since S60 v3.2
     * @param aHwChunkHandle hw chunk handle to be appended
     * @return ETrue upon success any other for failure
     */
    TBool PushBack( const HwChunkHandle& aHwChunkHandle );

    /**
     * Creates a new hw chunk and allocates memory from it
     *
     * @since S60 v3.2
     * @param aSize size of the buffer to be allocated in bytes. 
     *              Must be positive otherwise the allocation fails 
     * @param aHwChunkId unique chunk identifier used when freeing the memory
     * @param aZeroStamp zero stamp memory or not
     * @return begin of the allocated memory, NULL upon failure
     */
    void* HwChunkAllocWithCreate( const TInt aSize, 
                                  TInt& aHwChunkId, 
                                  TBool aZeroStamp );

    /**
     * Allocates memory from a hw chunk
     *
     * @since S60 v3.2
     * @param aSize size of the buffer to be allocated in bytes. Must be 
     *              positive otherwise the allocation fails 
     * @param aHwChunkId unique chunk identifier used when freeing the memory
     * @param aZeroStamp zero stamp memory or not
     * @return begin of the allocated memory, NULL upon failure
     */
    void* HwChunkAlloc( const TInt aSize, TInt& aHwChunkId, TBool aZeroStamp );

    /**
     * Evaluates is a chunk the initial chunk. 
     * The intial chunk is the one created at object creation time and its 
     * lifetime is equal to the lifetime of this object itself
     *
     * @since S60 v3.2
     * @param aChunk chunk to be evaluated against the intial chunk
     * @return ETrue when aChunk is the intial chunk, any other if not
     */
    inline TBool IsInitialChunk( WlanPlatformHwChunk* aChunk );

    /**
     * Frees memory from a hw chunk
     *
     * @since S60 v3.2
     * @param aMemHeader begin of the buffer to be freed
     */
    void HwChunkFree( SMemHeader& aMemHeader );

    // Prohibit copy constructor.
    WlanMemoryPool( const WlanMemoryPool& );
    // Prohibit assigment operator.
    WlanMemoryPool& operator= ( const WlanMemoryPool& );

private: // data

    typedef list<HwChunkHandle> HwChunkHandleList;

    typedef HwChunkHandleList::iterator iterator;
    typedef HwChunkHandleList::const_iterator const_iterator;
    typedef HwChunkHandleList::size_type size_type;

    /**
     * list of hw chunks
     */
    HwChunkHandleList   iHwChunkHandles;

    /** 
    * ETrue if cached memory shall be used,
    * EFalse otherwise 
    */
    TBool iUseCachedMemory;

    /** 
    * Allocation unit size in bytes 
    */
    TInt iAllocationUnit;
    
    /** 
    * Number of extra bytes required to align interconnect memory buffer 
    * start address returned to the requester to allocation unit boundary
    */
    TInt iExtraPadding;
    };

#endif // WLANMEMORYPOOL_H