// Copyright (c) 1998-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:

//

/**

 @file

 @internalComponent

*/

#ifndef __MMU_H__

#define __MMU_H__

#define _USE_OLDEST_LISTS

#include "mm.h"

#include "mmboot.h"

#include <mmtypes.h>

#include <kern_priv.h>

class DCoarseMemory;

class DMemoryObject;

class DMemoryMapping;

/**

A page information structure giving the current use and state for a

RAM page being managed by the kernel.

Any modification to the contents of any SPageInfo structure requires the

#MmuLock to be held. The exceptions to this is when a page is unused (#Type()==#EUnused),

in this case only the #RamAllocLock is required to use #SetAllocated(), #SetUncached(),

and #CacheInvalidateCounter().

These structures are stored in an array at the virtual address #KPageInfoLinearBase

which is indexed by the physical address of the page they are associated with, divided

by #KPageSize. The memory for this array is allocated by the bootstrap and it has

unallocated regions where no memory is required to store SPageInfo structures.

These unallocated memory regions are indicated by zeros in the bitmap stored at

#KPageInfoMap.

*/

struct SPageInfo

	{

	/**

	Enumeration for the usage of a RAM page. This is stored in #iType.

	*/

	enum TType

		{

		/**

		No physical RAM exists for this page.

		This represents memory which doesn't exist or is not part of the physical

		address range being managed by the kernel.

		*/

		EInvalid,

		/**

		RAM fixed at boot time.

		This is for memory which was allocated by the bootstrap and which

		the kernel does not actively manage.

		*/

		EFixed,

		/**

		Page is unused.

		The page is either free memory in Mmu::iRamPageAllocator or the demand

		paging 'live' list.

		To change from or to this type the #RamAllocLock must be held.

		*/

		EUnused,

		/**

		Page is in an indeterminate state.

		A page is placed into this state by Mmu::PagesAllocated when it is

		allocated (ceases to be #EUnused). Once the page

		*/

		EUnknown,

		/**

		Page was allocated with Mmu::AllocPhysicalRam, Mmu::ClaimPhysicalRam

		or is part of a reserved RAM bank set at system boot.

		*/

		EPhysAlloc,

		/**

		Page is owned by a memory object.

		#iOwner will point to the owning memory object and #iIndex will

		be the page index into its memory for this page.

		*/

		EManaged,

		/**

		Page is being used as a shadow page.

		@see DShadowPage.

		*/

		EShadow

		};

	/**

	Flags stored in #iFlags.

	The least significant bits of these flags are used for the #TMemoryAttributes

	value for the page.

	*/

	enum TFlags

		{

		// lower bits hold TMemoryAttribute value for this page

		/**

		Flag set to indicate that the page has writable mappings.

		(This is to facilitate demand paged memory.)

		*/

		EWritable			= 1<<(EMemoryAttributeShift),

		/**

		Flag set to indicate that the memory page contents may be different

		to those previously saved to backing store (contents are 'dirty').

		This is set whenever a page gains a writeable mapping and only every

		cleared once a demand paging memory manager 'cleans' the page.

		*/

		EDirty				= 1<<(EMemoryAttributeShift+1)

		};

	/**

	State for the page when being used to contain demand paged content.

	*/

	enum TPagedState

		{

		/**

		Page is not being managed for demand paging purposes, is has been transiently

		removed from the demand paging live list.

		*/

		EUnpaged 			= 0x0,

		/**

		Page is in the live list as a young page.

		*/

		EPagedYoung 		= 0x1,

		/**

		Page is in the live list as an old page.

		*/

		EPagedOld 			= 0x2,

		/**

		Page was pinned but it has been moved but not yet freed.

		*/

		EPagedPinnedMoved	= 0x3,

		/**

		Page has been removed from live list to prevent contents being paged-out.

		*/

		// NOTE - This must be the same value as EStatePagedLocked as defined in mmubase.h

		EPagedPinned 		= 0x4,

#ifdef _USE_OLDEST_LISTS

		/**

		Page is in the live list as one of oldest pages that is clean.

		*/

		EPagedOldestClean	= 0x5,

		/**

		Page is in the live list as one of oldest pages that is dirty.

		*/

		EPagedOldestDirty 	= 0x6

#endif

		};

	/**

	Additional flags, stored in #iFlags2.

	*/

	enum TFlags2

		{

		/**

		When #iPagedState==#EPagedPinned this indicates the page is a 'reserved' page

		and is does not increase free page count when returned to the live list.

		*/

		EPinnedReserve	= 1<<0,

		};

private:

	/**

	Value from enum #TType, returned by #Type().

	*/

	TUint8 iType;

	/**

	Bitmask of values from #TFlags, returned by #Flags().

	*/

	TUint8 iFlags;

	/**

	Value from enum #TPagedState, returned by #PagedState().

	*/

	TUint8 iPagedState;

	/**

	Bitmask of values from #TFlags2.

	*/

	TUint8 iFlags2;

	union

		{

		/**

		The memory object which owns this page.

		Used for always set for #EManaged pages and can be set for #PhysAlloc pages.

		*/

		DMemoryObject* iOwner;

		/**

		A pointer to the SPageInfo of the page that is being shadowed.

		For use with #EShadow pages only.

		*/

		SPageInfo* iOriginalPageInfo;

		};

	/**

	The index for this page within within the owning object's (#iOwner) memory.

	*/

	TUint32 iIndex;

	/**

	Pointer identifying the current modifier of the page. See #SetModifier.

	*/

	TAny* iModifier;

	/**

	Storage location for data specific to the memory manager object handling this page.

	See #SetPagingManagerData.

	*/

	TUint32 iPagingManagerData;

	/**

	Union of values which vary depending of the current value of #iType.

	*/

	union

		{

		/**

		When #iType==#EPhysAlloc, this stores a count of the number of memory objects

		this page has been added to.

		*/

		TUint32 iUseCount;

		/**

		When #iType==#EUnused, this stores the value of Mmu::iCacheInvalidateCounter

		at the time the page was freed. This is used for some cache maintenance optimisations.

		*/

		TUint32 iCacheInvalidateCounter;

		/**

		When #iType==#EManaged, this holds the count of the number of times the page was pinned.

		This will only be non-zero for demand paged memory.

		*/

		TUint32 iPinCount;

		};

public:

	/**

	Used for placing page into linked lists. E.g. the various demand paging live lists.

	*/

	SDblQueLink iLink;

public:

	/**

	Return the SPageInfo for a given page of physical RAM.

	*/

	static SPageInfo* FromPhysAddr(TPhysAddr aAddress);

	/**

	Return physical address of the RAM page which this SPageInfo object is associated.

	If the address has no SPageInfo, then a null pointer is returned.

	*/

	static SPageInfo* SafeFromPhysAddr(TPhysAddr aAddress);

	/**

	Return physical address of the RAM page which this SPageInfo object is associated.

	*/

	FORCE_INLINE TPhysAddr PhysAddr();

	/**

	Return a SPageInfo by conversion from the address of its embedded link member #iLink.

	*/

	FORCE_INLINE static SPageInfo* FromLink(SDblQueLink* aLink)

		{

		return (SPageInfo*)((TInt)aLink-_FOFF(SPageInfo,iLink));

		}

	//

	// Getters...

	//

	/**

	Return the current #TType value stored in #iType.

	@pre #MmuLock held.

	*/

	FORCE_INLINE TType Type()

		{

		CheckAccess("Type");

		return (TType)iType;

		}

	/**

	Return the current value of #iFlags.

	@pre #MmuLock held (if \a aNoCheck false).

	*/

	FORCE_INLINE TUint Flags(TBool aNoCheck=false)

		{

		if(!aNoCheck)

			CheckAccess("Flags");

		return iFlags;

		}

	/**

	Return the current value of #iPagedState.

	@pre #MmuLock held.

	*/

	FORCE_INLINE TPagedState PagedState()

		{

		CheckAccess("PagedState");

		return (TPagedState)iPagedState;

		}

	/**

	Return the current value of #iOwner.

	@pre #MmuLock held.

	*/

	FORCE_INLINE DMemoryObject* Owner()

		{

		CheckAccess("Owner");

		return iOwner;

		}

	/**

	Return the current value of #iIndex.

	@pre #MmuLock held (if \a aNoCheck false).

	*/

	FORCE_INLINE TUint32 Index(TBool aNoCheck=false)

		{

		if(!aNoCheck)

			CheckAccess("Index");

		return iIndex;

		}

	/**

	Return the current value of #iModifier.

	@pre #MmuLock held (if \a aNoCheck false).

	*/

	FORCE_INLINE TAny* Modifier()

		{

		CheckAccess("Modifier");

		return iModifier;

		}

	//

	// Setters..

	//

	/**

	Set this page as type #EFixed.

	This is only used during boot by Mmu::Init2Common.

	*/

	inline void SetFixed(TUint32 aIndex=0)

		{

		CheckAccess("SetFixed");

		Set(EFixed,0,aIndex);

		}

	/**

	Set this page as type #EUnused.

	@pre #MmuLock held.

	@pre #RamAllocLock held if previous page type != #EUnknown.

	@post #iModifier==0 to indicate that page usage has changed.

	*/

	inline void SetUnused()

		{

		CheckAccess("SetUnused",ECheckNotUnused|((iType!=EUnknown)?(TInt)ECheckRamAllocLock:0));

		iType = EUnused;

		iModifier = 0;

		// do not modify iFlags or iIndex in this function because page allocating cache cleaning operations rely on using this value

		}

	/**

	Set this page as type #EUnknown.

	This is only used by Mmu::PagesAllocated.

	@pre #RamAllocLock held.

	@post #iModifier==0 to indicate that page usage has changed.

	*/

	inline void SetAllocated()

		{

		CheckAccess("SetAllocated",ECheckUnused|ECheckRamAllocLock|ENoCheckMmuLock);

		iType = EUnknown;

		iModifier = 0;

		// do not modify iFlags or iIndex in this function because cache cleaning operations rely on using this value

		}

	/**

	Set this page as type #EPhysAlloc.

	@param aOwner	 Optional value for #iOwner.

	@param aIndex	 Optional value for #iIndex.

	@pre #MmuLock held.

	@post #iModifier==0 to indicate that page usage has changed.

	*/

	inline void SetPhysAlloc(DMemoryObject* aOwner=0, TUint32 aIndex=0)

		{

		CheckAccess("SetPhysAlloc");

		Set(EPhysAlloc,aOwner,aIndex);

		iUseCount = 0;

		}

	/**

	Set this page as type #EManaged.

	@param aOwner	Value for #iOwner.

	@param aIndex 	Value for #iIndex.

	@param aFlags 	Value for #iFlags (aOwner->PageInfoFlags()).

	@pre #MmuLock held.

	@post #iModifier==0 to indicate that page usage has changed.

	*/

	inline void SetManaged(DMemoryObject* aOwner, TUint32 aIndex, TUint8 aFlags)

		{

		CheckAccess("SetManaged");

		Set(EManaged,aOwner,aIndex);

		iFlags = aFlags;

		iPinCount = 0;

		}

	/**

	Set this page as type #EShadow.

	This is for use by #DShadowPage.

	@param aIndex 	Value for #iIndex.

	@param aFlags 	Value for #iFlags.

	@pre #MmuLock held.

	@post #iModifier==0 to indicate that page usage has changed.

	*/

	inline void SetShadow(TUint32 aIndex, TUint8 aFlags)

		{

		CheckAccess("SetShadow");

		Set(EShadow,0,aIndex);

		iFlags = aFlags;

		}

	/**

	Store a pointer to the SPageInfo of the page that this page is shadowing.

	@param aOrigPageInfo	Pointer to the SPageInfo that this page is shadowing

	@pre #MmuLock held.

	*/

	inline void SetOriginalPage(SPageInfo* aOrigPageInfo)

		{

		CheckAccess("SetOriginalPage");

		__NK_ASSERT_DEBUG(iType == EShadow);

		__NK_ASSERT_DEBUG(!iOriginalPageInfo);

		iOriginalPageInfo = aOrigPageInfo;

		}

	/**

	Reutrns a pointer to the SPageInfo of the page that this page is shadowing.

	@return	A pointer to the SPageInfo that this page is shadowing

	@pre #MmuLock held.

	*/

	inline SPageInfo* GetOriginalPage()

		{

		CheckAccess("GetOriginalPage");

		__NK_ASSERT_DEBUG(iType == EShadow);

		__NK_ASSERT_DEBUG(iOriginalPageInfo);

		return iOriginalPageInfo;

		}

private:

	/** Internal implementation factor for methods which set page type. */

	FORCE_INLINE void Set(TType aType, DMemoryObject* aOwner, TUint32 aIndex)

		{

		CheckAccess("Set",ECheckNotAllocated|ECheckNotPaged);

		(TUint32&)iType = aType; // also clears iFlags, iFlags2 and iPagedState

		iOwner = aOwner;

		iIndex = aIndex;

		iModifier = 0;

		}

public:

	//

	//

	//

	/**

	Set #iFlags to indicate that the contents of this page have been removed from

	any caches.

	@pre #MmuLock held if #iType!=#EUnused, #RamAllocLock held if #iType==#EUnused.

	*/