// Copyright (c) 2007-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 MMAPPING_H

 #define MMAPPING_H

 #include "mrefcntobj.h"

 #include "mmappinglist.h"

 #include "mpagearray.h"

 /**

 Base class for memory mappings.

 This provides the methods for linking a mapping to a memory object

 as well as the interface for updating the MMU page tables associated

 with a mapping when the memory state changes.

 */

 class DMemoryMappingBase : public DReferenceCountedObject

 	{

 private:

 	/**

 	Memory object to which this mapping is currently attached.

 	Updates to the are protected by the MmuLock.

 	*/

 	DMemoryObject*	 iMemory;

 public:

 	/**

 	Link used to maintain list of mappings attached to a memory object.

 	*/

 	TMappingListLink iLink;

 	/**

 	Offset, in page units, within the memory object's memory for start of this mapping.

 	*/

 	TUint			 iStartIndex;

 	/**

 	Size of this mapping, in page units.

 	*/

 	TUint			 iSizeInPages;

 private:

 	/**

 	Instance count which is incremented every time a mapping is attached to a memory object.

 	When code is manipulating mappings, the instance count is used to detect that a

 	mapping has been reused and that the operation it is performing is no long needed.

 	*/

 	TUint			 iMapInstanceCount;

 public:

 	/**

 	Bit flags stored in #Flags giving various state and attributes of the mapping.

 	*/

 	enum TFlags

 		{

 		/**

 		Flag set during object construction to indicate that this mapping is of

 		class #DCoarseMapping.

 		*/

 		ECoarseMapping			= 1<<0,

 		/**

 		Flag set during object construction to indicate that this mapping will pin

 		any memory pages it maps. This may not be used with coarse memory mappings.

 		*/

 		EPinned					= 1<<1,

 		/**

 		Pages have already been reserved for pinning, so when this mapping is attached

 		to a memory object no additional pages need to be reserved. Pre-reserving pages

 		is used to prevent the possibility of failing to pin due to an out of memory

 		condition. It is essential that the users of these mappings ensure that there

 		are enough reserved pages in the paging pool to meet the maximum mapping size

 		used.

 		*/

 		EPinningPagesReserved	= 1<<2,

 		/**

 		Pages have been successfully pinned by this mapping. This is set after demand

 		paged memory has been succeeded pinned and is used to indicate that the pages

 		need unpinning again when the mapping is later unmapped.

 		*/

 		EPagesPinned			= 1<<3,

 		/**

 		Flag set during object construction to indicate that MMU page tables are to

 		be permanently allocated for use by this mapping. Normally, page tables are

 		allocated as needed to map memory which can result in out-of-memory errors

 		when mapping memory pages.

 		*/

 		EPermanentPageTables	= 1<<4,

 		/**

 		Permanent page tables have been successfully been allocated for this mapping.

 		This flag is used to track allocation so they can be released when the mapping

 		is destroyed.

 		*/

 		EPageTablesAllocated	= 1<<5,

 		/**

 		For pinned mappings (EPinned) this flag is set whenever the mapping prevents

 		any pages of memory from being fully decommitted from a memory object. When a

 		mapping is finally unmapped from the memory object this flag is checked, and,

 		if set, further cleanup of the decommitted pages triggered.

 		*/

 		EPageUnmapVetoed		= 1<<6,

 		/**

 		Mapping is being, or has been, detached from a memory object.

 		When set, operations on the mapping should act as though the mapping is no

 		longer attached to a memory object. Specifically, no further pages of memory

 		should be mapped into this mapping.

 		This flag is only set when the MmuLock is held.

 		*/

 		EDetaching				= 1<<7,

 		/**

 		This mapping is a physical pinning mapping.  The pages it pins

 		cannot be paged out or moved.

 		This flag is set when DPhysicalPinMapping objects are created.

 		*/

 		EPhysicalPinningMapping = 1<<8,

 		/**

 		Flag set during object construction to indicate that this mapping is of

 		class #DLargeMapping.

 		Note that #DLargeMapping is derived from #DCoarseMapping, therefore presence of this flag

 		implies presence of #ECoarseMapping as well.

 		*/

 		ELargeMapping			= 1<<9,

 		};

 	/**

 	Bitmask of values from enum #TPteType which will be used to calculate

 	the correct attributes for any page table entries this mapping uses.

 	*/

 	FORCE_INLINE TUint8& PteType()

 		{ return iLink.iSpare1; }

 	/**

 	Bitmask of values from enum #TFlags.

 	The flags 16 bits and are stored in iLink.iSpare2 and iLink.iSpare3.

 	*/

 	FORCE_INLINE TUint16& Flags()

 		{ return (TUint16&)iLink.iSpare2; }

 public:

 	/**

 	Return the memory object to which this mapping is currently attached.

 	@pre MmuLock is held. (If aNoCheck==false)

 	*/

 	FORCE_INLINE DMemoryObject* Memory(TBool aNoCheck=false)

 		{

 		if(!aNoCheck)

 			__NK_ASSERT_DEBUG(MmuLock::IsHeld());

 		return iMemory;

 		}

 	/**

 	Return true if the mapping is currently attached to a memory object.

 	*/

 	FORCE_INLINE TBool IsAttached()

 		{ return iLink.IsLinked(); }

 	/**

 	Return true if the mapping is being, or has been, detached from a memory object.

 	The mapping may or may not still be attached to a memory object, i.e. #IsAttached

 	is indeterminate.

 	*/

 	FORCE_INLINE TBool BeingDetached()

 		{ return Flags()&EDetaching; }

 	/**

 	Return the mapping instance count.

 	@see #iMapInstanceCount.

 	*/

 	FORCE_INLINE TUint MapInstanceCount()

 		{ return iMapInstanceCount; }

 	/**

 	Return true if this mapping provides read only access to memory.

 	*/

 	FORCE_INLINE TBool IsReadOnly()

 		{ return !(PteType()&EPteTypeWritable); }

 #ifdef MMU_SUPPORTS_EXECUTE_NEVER

 	/**

 	Return true if this mapping provides access to memory which allows

 	code to be executed from it.

 	*/

 	FORCE_INLINE TBool IsExecutable()

 		{ return (PteType()&EPteTypeExecutable); }

 #endif

 	/**

 	Return true if this is a coarse mapping, in other words it is an instance of #DCoarseMapping or

 	#DLargeMapping.

 	*/

 	FORCE_INLINE TBool IsCoarse()

 		{ return Flags()&ECoarseMapping; }

 	/**

 	Return true if this mapping is a large mapping, in other words an instance of #DLargeMapping.

 	Note that all large mappings are also coarse mappings.

 	*/

 	FORCE_INLINE TBool IsLarge()

 		{ return Flags()&ELargeMapping; }

 	/**

 	Return true if this mapping pins the memory it maps.

 	*/

 	FORCE_INLINE TBool IsPinned()

 		{ return Flags()&EPinned; }

 	/**

 	Return true if this mapping physically pins the memory it maps.

 	*/

 	FORCE_INLINE TBool IsPhysicalPinning()

 		{ return Flags()&EPhysicalPinningMapping; }

 	/**

 	Return the access permissions which this mapping uses to maps memory.

 	*/

 	FORCE_INLINE TMappingPermissions Permissions()

 		{ return Mmu::PermissionsFromPteType(PteType()); }

 	/**

 	Link this mapping to a memory object.

 	This is called by the memory object during processing of #Attach.

 	@param aMemory		The memory object the mapping is being attached to.

 	@param aMappingList	The list to add this mapping to.

 	@pre MmuLock is held.

 	@pre Mapping list lock is held.

 	*/

 	void LinkToMemory(DMemoryObject* aMemory, TMappingList& aMappingList);

 	/**

 	Unlink this mapping from the memory object it was previously linked to with

 	#LinkToMemory.

 	This is called by the memory object during processing of #Detach.

 	@param aMappingList	The list that the mapping appears on.

 	*/

 	void UnlinkFromMemory(TMappingList& aMappingList);

 	/**

 	Get the physical address(es) for a region of pages in this mapping.

 	@param aIndex			Page index, within the mapping, for start of the region.

 	@param aCount			Number of pages in the region.

 	@param aPhysicalAddress	On success, this value is set to one of two values.

 							If the specified region is physically contiguous,

 							the value is the physical address of the first page

 							in the region. If the region is discontiguous, the

 							value is set to KPhysAddrInvalid.

 	@param aPhysicalPageList If not zero, this points to an array of TPhysAddr

 							objects. On success, this array will be filled

 							with the addresses of the physical pages which

 							contain the specified region. If aPageList is

 							zero, then the function will fail with

 							KErrNotFound if the specified region is not

 							physically contiguous.

 	@return 0 if successful and the whole region is physically contiguous.

 			1 if successful but the region isn't physically contiguous.

 			KErrNotFound, if any page in the region is not present,

 			otherwise one of the system wide error codes.

 	@pre This mapping must have been attached to a memory object with #Pin.

 	*/

 	TInt PhysAddr(TUint aIndex, TUint aCount, TPhysAddr& aPhysicalAddress, TPhysAddr* aPhysicalPageList);

 protected:

 	/**

 	@param aType Initial value for #Flags.

 	*/

 	DMemoryMappingBase(TUint aType);

 	/**

 	Attach this mapping to a memory object so that it maps a specified region of its memory.

 	@param aMemory	The memory object.

 	@param aIndex	The page index of the first page of memory to be mapped by the mapping.

 	@param aCount	The number of pages of memory to be mapped by the mapping.

 	@return KErrNone if successful, otherwise one of the system wide error codes.

 	*/

 	TInt Attach(DMemoryObject* aMemory, TUint aIndex, TUint aCount);

 	/**

 	Remove this mapping from the memory object it was previously attached to by #Attach.

 	*/

 	void Detach();

 public:

 	/**

 	Update the page table entries corresponding to this mapping to add entries for

 	a specified set of memory pages.

 	This method is called by DMemoryObject::MapPages to update each mapping attached

 	to a memory object whenever new pages of memory are added. However, it won't be

 	called for any mapping with the #EPinned attribute as such mappings are unchanging.

 	@param aPages				An RPageArray::TIter which refers to a range of pages

 								in a memory object. This has been clipped to fit within

 								the range of pages mapped by this mapping.

 								Only array entries which have state RPageArray::ECommitted

 								should be mapped into the mapping's page tables.

 	@param aMapInstanceCount	The instance of this mapping which is to be updated.

 								Whenever this no longer matches the current #MapInstanceCount

 								the function must not update any more of the mapping's

 								page table entries, (but must still return KErrNone).

 	@return KErrNone if successful, otherwise one of the system wide error codes.	

 	*/

 	virtual TInt MapPages(RPageArray::TIter aPages, TUint aMapInstanceCount) =0;

 	/**

 	Update the page table entries corresponding to this mapping to remove entries for

 	a specified set of memory pages.

 	This method is called by DMemoryObject::UnmapPages to update each mapping attached

 	to a memory object whenever pages of memory are removed.

 	@param aPages				An RPageArray::TIter which refers to a range of pages

 								in a memory object. This has been clipped to fit within

 								the range of pages mapped by this mapping.

 								Only array entries which return true for

 								RPageArray::TargetStateIsDecommitted should be unmapped

 								from the mapping's page tables.

 	@param aMapInstanceCount	The instance of this mapping which is to be updated.

 								Whenever this no longer matches the current #MapInstanceCount

 								the function must not update any more of the mapping's

 								page table entries.

 	*/

 	virtual void UnmapPages(RPageArray::TIter aPages, TUint aMapInstanceCount) =0;

 	/**

 	Update the page table entry corresponding to this mapping to update an entry for a specified

 	page that has just been moved or shadowed.

 	@param aPages				The page array entry of the page in a memory object. 

 								Only array entries which have a target state of 

 								RPageArray::ECommitted should be mapped into the 

 								mapping's page tables.

 	@param aIndex				The index of the page in the memory object.

 	@param aMapInstanceCount	The instance of this mapping which is to be updated.

 								Whenever this no longer matches the current #MapInstanceCount

 								the function must not update any more of the mapping's

 								page table entries, (but must still return KErrNone).

 	@param	aInvalidateTLB		Set to ETrue when the TLB entries associated with this page

 								should be invalidated.  This must be done when there is 

 								already a valid pte for this page, i.e. if the page is still 

 								mapped.

 	*/

 	virtual void RemapPage(TPhysAddr& aPageArray, TUint aIndex, TUint aMapInstanceCount, TBool aInvalidateTLB)=0;

 	/**

 	Update the page table entries corresponding to this mapping to apply access restrictions

 	to a specified set of memory pages.

 	This method is called by DMemoryObject::RestrictPages to update each mapping attached

 	to a memory object whenever pages of memory are restricted.

 	@param aPages				An RPageArray::TIter which refers to a range of pages

 								in a memory object. This has been clipped to fit within

 								the range of pages mapped by this mapping.

 								Only array entries which return true for

 								RPageArray::TargetStateIsDecommitted should be unmapped

 								from the mapping's page tables.

 	@param aMapInstanceCount	The instance of this mapping which is to be updated.

 								Whenever this no longer matches the current #MapInstanceCount

 								the function must not update any more of the mapping's

 								page table entries.

 	*/

 	virtual void RestrictPagesNA(RPageArray::TIter aPages, TUint aMapInstanceCount) =0;

 	/**

 	Update the page table entries corresponding to this mapping to add entries for

 	a specified set of demand paged memory pages following a 'page in' or memory

 	pinning operation.

 	@param aPages				An RPageArray::TIter which refers to a range of pages

 								in a memory object. This will be within the range of pages

 								mapped by this mapping.

 								Only array entries which have state RPageArray::ECommitted

 								should be mapped into the mapping's page tables.

 	@param aPinArgs				The resources required to pin any page tables the mapping uses.

 								Page table must be pinned if \a aPinArgs.iPinnedPageTables is

 								not the null pointer, in which case this the virtual address

 								of the pinned must be stored in the array this points to.

 								\a aPinArgs.iReadOnly is true if write access permissions

 								are not needed.

 	@return KErrNone if successful, otherwise one of the system wide error codes.	

 	*/

 	virtual TInt PageIn(RPageArray::TIter aPages, TPinArgs& aPinArgs, TUint aMapInstanceCount) =0;

 	/**

 	Update the page table entry corresponding to this mapping to add an entry for

 	a specified page which is in the process of being moved.

 	@param aPageArrayPtr		The page array entry for the page to be mapped which must be

 								within this mapping range of pages.

 								Only array entries which have a target state of

 								RPageArray::ECommitted should be mapped into the mapping's 

 								page tables.

 	@param	aIndex				The index of the page.

 	@return ETrue if successful, EFalse otherwise.

 	*/

 	virtual TBool MovingPageIn(TPhysAddr& aPageArrayPtr, TUint aIndex)=0;

 	/**

 	In debug builds, dump information about this mapping to the kernel trace port.

 	*/

 	virtual void Dump();

 private:

 	/**

 	Update this mapping's MMU data structures to map all pages of memory

 	currently committed to the memory object (#iMemory) in the region covered

 	by this mapping.

 	This method is called by #Attach after the mapping has been linked

 	into the memory object.

 	@return KErrNone if successful, otherwise one of the system wide error codes.

 	*/

 	virtual TInt DoMap() =0;

 	/**

 	Update this mapping's MMU data structures to unmap all pages of memory.

 	This method is called by #Detach before the mapping has been unlinked

 	from the memory object but after the #EDetaching flag has been set.

 	*/

 	virtual void DoUnmap() =0;

 protected:

 	/**

 	For pinned mapping, this virtual method is called by #Attach in order to pin

 	pages of memory if required. This is called after the mapping has been linked

 	into the memory object but before #DoMap.

 	The default implementation of this method simply calls DMemoryManager::Pin.

 	@param aPinArgs	The resources to use for pinning. This has sufficient replacement

 					pages allocated to pin every page the mapping covers, and the

 					value of \a aPinArgs.iReadOnly has been set to correspond to the

 					mappings access permissions.

 	@return KErrNone if successful, otherwise one of the system wide error codes.

 	*/

 	virtual TInt DoPin(TPinArgs& aPinArgs);

 	/**

 	For pinned mapping, this virtual method is called by #Detach in order to unpin

 	pages of memory if required. This is called before the mapping has been unlinked

 	from the memory object but after #DoUnmap.

 	The default implementation of this method simply calls DMemoryManager::Unpin.

 	@param aPinArgs	The resources used for pinning. The replacement pages allocated

 					to this will be increased for each page which was became completely

 					unpinned.

 	*/

 	virtual void DoUnpin(TPinArgs& aPinArgs);

 	};

 /**

 Base class for memory mappings which map memory contents into a address space.

 This provides methods for allocating virtual memory and holds the attributes needed

 for MMU page table entries.

 */

 class DMemoryMapping : public DMemoryMappingBase

 	{

 protected:

 	/**

 	The page directory entry (PDE) value for use when mapping this mapping's page tables.

 	This value has the physical address component being zero, so a page table's physical

 	address can be simply ORed in.

 	This could potentially be removed (see DMemoryMapping::PdeType()).

 	*/

 	TPde			iBlankPde;

 	/**

 	The page table entry (PTE) value for use when mapping pages into this mapping.

 	This value has the physical address component being zero, so a page's physical

 	address can be simply ORed in.

 	*/

 	TPte			iBlankPte;

 	/**

 	Start of the virtual address region allocated for use by this mapping

 	ORed with the OS ASID of the address space this lies in.

 	Note, the address at which memory is mapped (#iLinAddrAndOsAsid) may be different

 	to this allocated address due to page colouring restrictions.

 	@see iAllocatedSize

 	*/

 	TLinAddr		iAllocatedLinAddrAndOsAsid;

 	/**

 	Size of virtual address region memory allocated for use by this mapping.

 	@see iAllocatedLinAddrAndOsAsid

 	*/

 	TUint			iAllocatedSize;

 private:

 	/**

 	Start of the virtual address region that this mapping is currently

 	mapping memory at, ORed with the OS ASID of the address space this lies in.

 	This value is set by #Map which is called from #Attach when the mapping

 	is attached to a memory object. The address used may be different to

 	#iAllocatedLinAddrAndOsAsid due to page colouring restrictions.

 	The size of the region mapped is #iSizeInPages.

 	Note, access to this value is through #Base() and #OsAsid().

 	*/

 	TLinAddr		iLinAddrAndOsAsid;

 public:

 	/**

 	Second phase constructor.

 	The main function of this is to allocate a virtual address region for the mapping

 	and to add it to an address space.

 	@param aAttributes		The attributes of the memory which this mapping is intended to map.

 							This is only needed to setup #PdeType which is required for correct

 							virtual address allocation so in practice the only relevant attribute

 							is to set EMemoryAttributeUseECC if required, else use

 							EMemoryAttributeStandard.

 	@param aFlags			A combination of the options from enum TMappingCreateFlags.

 	@param aOsAsid			The OS ASID of the address space the mapping is to be added to.

 	@param aAddr			The virtual address to use for the mapping, or zero if this is

 							to be allocated by this function.

 	@param aSize			The maximum size of memory, in bytes, this mapping will be used to

 							map. This determines the size of the virtual address region the

 							mapping will use.

 	@param aColourOffset	The byte offset within a memory object's memory which this mapping

 							is to start. This is used to adjust virtual memory allocation to

 							meet page colouring restrictions. If this value is not known leave

 							this argument unspecified; however, it must be specified if \a aAddr

 							is specified.

 	@return KErrNone if successful, otherwise one of the system wide error codes.	

 	*/

 	TInt Construct(TMemoryAttributes aAttributes, TMappingCreateFlags aFlags, TInt aOsAsid, TLinAddr aAddr, TUint aSize, TLinAddr aColourOffset=~(TLinAddr)0);

 	/**

 	Add this mapping to a memory object so that it maps a specified region of its memory.

 	Most of the action of this method is performed by #Attach.

 	@param aMemory		The memory object.

 	@param aIndex		The page index of the first page of memory to be mapped by the mapping.

 	@param aCount		The number of pages of memory to be mapped by the mapping.

 	@param aPermissions	The memory access permissions to apply to the mapping.

 	@return KErrNone if successful, otherwise one of the system wide error codes.

 	*/

 	TInt Map(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TMappingPermissions aPermissions);

 	/**

 	Remove this mapping from the memory object it was previously added to by #Map.

 	Most of the action of this method is performed by #Detach.

 	*/

 	void Unmap();

 	/**

 	Return the OS ASID for the address space that this mapping is currently mapping memory in.

 	*/

 	FORCE_INLINE TInt OsAsid()

 		{

 		__NK_ASSERT_DEBUG(iLinAddrAndOsAsid); // check mapping has been added to an address space

 		return iLinAddrAndOsAsid&KPageMask;

 		}

 	/**

 	Return starting virtual address that this mapping is currently mapping memory at.

 	The size of the region mapped is #iSizeInPages.

 	*/

 	FORCE_INLINE TLinAddr Base()

 		{

 		__NK_ASSERT_DEBUG(iLinAddrAndOsAsid); // check mapping has been added to an address space

 		return iLinAddrAndOsAsid&~KPageMask;

 		}

 	/**

 	Return #Base()|#OsAsid()

 	*/

 	FORCE_INLINE TLinAddr LinAddrAndOsAsid()

 		{

 		__NK_ASSERT_DEBUG(iLinAddrAndOsAsid); // check mapping has been added to an address space

 		return iLinAddrAndOsAsid;

 		}

 	FORCE_INLINE TBool IsUserMapping()

 		{

 		// Note: must be usable before the mapping has been added to an address space

 		return (PteType() & (EPteTypeUserAccess|EPteTypeGlobal)) == EPteTypeUserAccess;

 		}

 	/**

 	Return #iBlankPde.

 	*/

 	FORCE_INLINE TPde BlankPde()

 		{

 		return iBlankPde;

 		}

 	/**

 	Emit BTrace traces identifying this mappings virtual address usage.

 	*/

 	void BTraceCreate();

 	/**

 	In debug builds, dump information about this mapping to the kernel trace port.

 	*/

 	virtual void Dump();

 	/**

 	Function to return a page table pointer for the specified linear address and

 	index to this mapping.

 	This is called by #Epoc::MovePhysicalPage when moving page table or page table info pages.

 	@param aLinAddr		The linear address to find the page table entry for.

 	@param aMemoryIndex	The memory object index of the page to find the page 

 						table entry for.

 	@return A pointer to the page table entry, if the page table entry couldn't 

 			be found this will be NULL

 	*/

 	virtual TPte* FindPageTable(TLinAddr aLinAddr, TUint aMemoryIndex)=0;

 protected:

 	/**

 	@param aType Initial value for #Flags.

 	*/

 	DMemoryMapping(TUint aType);

 	/**

 	This destructor removes the mapping from any address space it was added to and

 	frees any virtual addresses allocated to it.

 	*/

 	~DMemoryMapping();

 	/**

 	Free any resources owned by this mapping, i.e. allow Construct() to be used

 	on this mapping at a new address etc.

 	*/

 	void Destruct();

 	/**

 	Allocatate virtual addresses for this mapping to use.

 	This is called from #Construct and the arguments to this function are the same.

 	On success, iAllocatedLinAddrAndOsAsid and iAllocatedSize will be initialised.

 	*/

 	virtual TInt AllocateVirtualMemory(TMappingCreateFlags aFlags, TInt aOsAsid, TLinAddr aAddr, TUint aSize, TLinAddr aColourOffset);

 	/**

 	Free the virtual addresses allocated to this mapping with AllocateVirtualMemory.

 	*/

 	virtual void FreeVirtualMemory();

 	};

 /**

 A memory mapping to map a 'chunk' aligned region of a DCoarseMemory object into

 an address space. A 'chunk' is the size of memory mapped by a whole MMU page table

 and is #KChunkSize bytes.

 These mappings make use of page tables owned by a DCoarseMemory and when

 they are attached to a memory object they are linked into

 DCoarseMemory::DPageTables::iMappings not DCoarseMemory::iMappings.

 */

 class DCoarseMapping : public DMemoryMapping

 	{

 public:

 	DCoarseMapping();

 	~DCoarseMapping();

 protected:

 	DCoarseMapping(TUint aFlags);

 protected:

 	// from DMemoryMappingBase...

 	virtual TInt MapPages(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Not implemented. Faults in debug builds.

 	virtual void UnmapPages(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Not implemented. Faults in debug builds.

 	virtual void RemapPage(TPhysAddr& aPageArray, TUint aIndex, TUint aMapInstanceCount, TBool aInvalidateTLB); ///< Not implemented. Faults in debug builds.

 	virtual void RestrictPagesNA(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Not implemented. Faults in debug builds.

 	virtual TInt PageIn(RPageArray::TIter aPages, TPinArgs& aPinArgs, TUint aMapInstanceCount);

 	virtual TBool MovingPageIn(TPhysAddr& aPageArrayPtr, TUint aIndex);

 	virtual TInt DoMap();

 	virtual void DoUnmap();

 	// from DMemoryMapping...

 	virtual TPte* FindPageTable(TLinAddr aLinAddr, TUint aMemoryIndex);

 	};

 /**

 A memory mapping to map a page aligned region of a memory object into

 an address space. The may be used with any memory object: DFineMemory or DCoarseMemory.

 */

 class DFineMapping : public DMemoryMapping

 	{

 public:

 	DFineMapping();

 	~DFineMapping();

 private:

 	// from DMemoryMappingBase...

 	virtual TInt MapPages(RPageArray::TIter aPages, TUint aMapInstanceCount);

 	virtual void UnmapPages(RPageArray::TIter aPages, TUint aMapInstanceCount);

 	virtual void RemapPage(TPhysAddr& aPageArray, TUint aIndex, TUint aMapInstanceCount, TBool aInvalidateTLB);

 	virtual void RestrictPagesNA(RPageArray::TIter aPages, TUint aMapInstanceCount);

 	virtual TInt PageIn(RPageArray::TIter aPages, TPinArgs& aPinArgs, TUint aMapInstanceCount);

 	virtual TBool MovingPageIn(TPhysAddr& aPageArrayPtr, TUint aIndex);

 	virtual TInt DoMap();

 	virtual void DoUnmap();

 	// from DMemoryMapping...

 	/**

 	Allocatate virtual addresses for this mapping to use.

 	In addition to performing the action of DMemoryMapping::AllocateVirtualMemory

 	this will also allocate all permanent page tables for the mapping if it has attribute

 	#EPermanentPageTables.

 	*/

 	virtual TInt AllocateVirtualMemory(TMappingCreateFlags aFlags, TInt aOsAsid, TLinAddr aAddr, TUint aSize, TLinAddr aColourOffset);

 	/**

 	Free the virtual addresses and permanent page tables allocated to this mapping with

 	AllocateVirtualMemory.

 	*/

 	virtual void FreeVirtualMemory();

 	virtual TPte* FindPageTable(TLinAddr aLinAddr, TUint aMemoryIndex);

 	// new...

 	/**

 	Allocate all the page tables required for this mapping. This is called by

 	AllocateVirtualMemory if the #EPermanentPageTables attribute is set.

 	Each page table for the virtual address region used by the mapping is

 	allocated if not already present. The permanence count of any page table

 	(SPageTableInfo::iPermanenceCount) is then incremented so that it is not

 	freed even when it no longer maps any pages.

 	If successful, the #EPageTablesAllocated flag in #Flags will be set.

 	@return KErrNone if successful, otherwise one of the system wide error codes.

 	*/

 	TInt AllocatePermanentPageTables();

 	/**

 	Free all permanent page tables allocated to this mapping.

 	This reverses the action of #AllocatePermanentPageTables by decrementing

 	the permanence count for each page table and freeing it if is no longer in use.

 	*/

 	void FreePermanentPageTables();

 	/**

 	Free a range of permanent page tables.

 	This is an implementation factor for FreePermanentPageTables and

 	AllocatePermanentPageTables. It decrements the permanence count

 	for each page table and frees it if is no longer in use

 	@param aFirstPde	The address of the page directory entry which refers to

 						the first page table to be freed.

 	@param aLastPde		The address of the page directory entry which refers to

 						the last page table to be freed.

 	*/

 	void FreePermanentPageTables(TPde* aFirstPde, TPde* aLastPde);

 #ifdef _DEBUG

 	/**

 	Validate the contents of the page table are valid.

 	@param aPt	The page table to validate.

 	*/

 	void ValidatePageTable(TPte* aPt, TLinAddr aAddr);

 #endif

 	/**

 	Get the page table being used to map a specified virtual address if it exists.

 	@param aAddr	A virtual address in the region allocated to this mapping.

 	@return The virtual address of the page table mapping \a aAddr,

 			or the null pointer if one wasn't found.

 	*/

 	TPte* GetPageTable(TLinAddr aAddr);

 	/**

 	Get the page table being used to map a specified virtual address; allocating

 	a new one if it didn't previously exist.

 	@param aAddr	A virtual address in the region allocated to this mapping.

 	@return The virtual address of the page table mapping \a aAddr,

 			or the null pointer if one wasn't found and couldn't be allocated.

 	*/

 	TPte* GetOrAllocatePageTable(TLinAddr aAddr);

 	/**

 	Get and pin the page table being used to map a specified virtual address;

 	allocating a new one if it didn't previously exist.

 	@param aAddr	A virtual address in the region allocated to this mapping.

 	@param aPinArgs	The resources required to pin the page table.

 					On success, the page table will have been appended to

 					\a aPinArgs.iPinnedPageTables.

 	@return The virtual address of the page table mapping \a aAddr,

 			or the null pointer if one wasn't found and couldn't be allocated.

 	*/

 	TPte* GetOrAllocatePageTable(TLinAddr aAddr, TPinArgs& aPinArgs);

 	/**

 	Allocate a single page table.

 	@param aAddr		The virtual address the page table will be used to map.

 	@param aPdeAddress	Address of the page directory entry which is to map

 						the newly allocated page table.

 	@param aPermanent	True, if the page table's permanence count is to be incremented.

 	@return The virtual address of the page table if it was successfully allocated,

 			otherwise the null pointer.

 	*/

 	TPte* AllocatePageTable(TLinAddr aAddr, TPde* aPdeAddress, TBool aPermanent=false);

 	/**

 	Free a single page table if it is unused.

 	@param aPdeAddress	Address of the page directory entry (PDE) which maps the page table.

 						If the page table is freed, this PDE will be set to an 'unallocated' value.

 	*/

 	void FreePageTable(TPde* aPdeAddress);

 	};

 /**

 A mapping which maps any memory into the kernel address space and provides access to 

 the physical address used by a memory object.

 These mappings are always of the 'pinned' type to prevent the obtained physical addresses

 from becoming invalid.

 */

 class DKernelPinMapping : public DFineMapping

 	{

 public:

 	DKernelPinMapping();

 	TInt Construct(TUint aReserveSize);

 	TInt MapAndPin(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TMappingPermissions aPermissions);

 	void UnmapAndUnpin();

 public:

 	TInt iReservePages;		///< The number of pages this mapping is able to map with its reserved resources(page tables etc).

 	};

 /**

 A mapping which provides access to the physical address used by a memory object

 without mapping these at any virtual address accessible to software.

 These mappings are always of the 'pinned' type to prevent the obtained physical addresses

 from becoming invalid.

 */

 class DPhysicalPinMapping : public DMemoryMappingBase

 	{

 public:

 	DPhysicalPinMapping();

 	/**

 	Attach this mapping to a memory object so that it pins a specified region of its memory.

 	Most of the action of this method is performed by #Attach.

 	@param aMemory		The memory object.

 	@param aIndex		The page index of the first page of memory to be pinned by the mapping.

 	@param aCount		The number of pages of memory to be pinned by the mapping.

 	@param aPermissions	The memory access permissions appropriate to the intended use

 						of the physical addresses. E.g. if the memory contents will be

 						changes, use EReadWrite. These permissions are used for error

 						checking, e.g. detecting attempted writes to read-only memory.

 						They are also used for optimising access to demand paged memory;

 						which is more efficient if only read-only access is required.

 	@return KErrNone if successful,

 			KErrNotFound if any part of the memory to be pinned was not present,

 			KErrNoMemory if there was insufficient memory,

 			otherwise one of the system wide error codes.

 	*/

 	TInt Pin(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TMappingPermissions aPermissions);

 	/**

 	Remove this mapping from the memory object it was previously added to by #Pin.

 	Most of the action of this method is performed by #Detach.

 	*/

 	virtual void Unpin();

 private:

 	// from DMemoryMappingBase...

 	virtual TInt MapPages(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Not implemented. Faults in debug builds.

 	virtual void UnmapPages(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Does nothing

 	virtual void RemapPage(TPhysAddr& aPageArray, TUint aIndex, TUint aMapInstanceCount, TBool aInvalidateTLB); ///< Not implemented. Faults in debug builds.

 	virtual void RestrictPagesNA(RPageArray::TIter aPages, TUint aMapInstanceCount); ///< Does nothing

 	virtual TInt PageIn(RPageArray::TIter aPages, TPinArgs& aPinArgs, TUint aMapInstanceCount); ///< Does nothing

 	virtual TBool MovingPageIn(TPhysAddr& aPageArrayPtr, TUint aIndex);///< Not implemented. Faults in debug builds.

 	virtual TInt DoMap(); ///< Does nothing

 	virtual void DoUnmap(); ///< Does nothing

 	}; 

 /**

 A mapping which pins memory in order to prevent demand paging related

 page faults from occurring.

 */

 class DVirtualPinMapping : public DPhysicalPinMapping

 	{

 public:

 	DVirtualPinMapping();

 	~DVirtualPinMapping();

 	/**

 	Create a new DVirtualPinMapping object suitable for pinning a specified number of pages.

 	If no maximum is specified (\a aMaxCount==0) then this object may be used to pin

 	any number of pages, however this will require dynamic allocation of storage for

 	page table references.

 	@param aMaxCount The maximum number of pages which can be pinned, or zero for no maximum.

 	@return The newly created DVirtualPinMapping or the null pointer if there was

 			insufficient memory.

 	*/

 	static DVirtualPinMapping* New(TUint aMaxCount);

 	/**

 	Attach this mapping to a memory object so that it pins a specified region of its memory.

 	Additionally, pin the page tables in a specified mapping (\a aMapping) which

 	are being used to map these pages.

 	The result of this function is that access to the pinned memory through the virtual

 	addresses used by \a aMapping will not generate any demand paging related page faults.

 	@param aMemory		The memory object.

 	@param aIndex		The page index of the first page of memory to be pinned by the mapping.

 	@param aCount		The number of pages of memory to be pinned by the mapping.

 	@param aPermissions	The memory access permissions appropriate to the intended use

 						of the physical addresses. E.g. if the memory contents will be

 						changes, use EReadWrite. These permissions are used for error

 						checking, e.g. detecting attempted writes to read-only memory.

 						They are also used for optimising access to demand paged memory;

 						which is more efficient if only read-only access is required.

 	@param aMapping		The mapping whose page tables are to be pinned. This must be

 						currently mapping the specified region of memory pages.

 	@param aMapInstanceCount	The instance count of the mapping who's page tables are to be pinned.

 	@return KErrNone if successful,

 			KErrNotFound if any part of the memory to be pinned was not present,

 			KErrNoMemory if there was insufficient memory,

 			otherwise one of the system wide error codes.

 	*/

 	TInt Pin(	DMemoryObject* aMemory, TUint aIndex, TUint aCount, TMappingPermissions aPermissions, 

 				DMemoryMappingBase* aMapping, TUint aMapInstanceCount);

 	/**

 	Remove this mapping from the memory object it was previously added to by #Pin.

 	This will unpin any memory pages and pages tables that were pinned.

 	*/

 	void Unpin();

 	/**

 	Return the maximum number of page tables which could be required to map

 	\a aPageCount pages. This is used by various resource reserving calculations.

 	*/

 	static TUint MaxPageTables(TUint aPageCount);

 	/**

 	In debug builds, dump information about this mapping to the kernel trace port.

 	*/

 	virtual void Dump();

 private:

 	// from DMemoryMappingBase...

 	virtual void RemapPage(TPhysAddr& aPageArray, TUint aIndex, TUint aMapInstanceCount, TBool aInvalidateTLB); ///< Does nothing.

 	virtual TInt PageIn(RPageArray::TIter aPages, TPinArgs& aPinArgs, TUint aMapInstanceCount);

 	virtual TBool MovingPageIn(TPhysAddr& aPageArrayPtr, TUint aIndex);///< Not implemented. Faults in debug builds.

 	virtual TInt DoPin(TPinArgs& aPinArgs);

 	virtual void DoUnpin(TPinArgs& aPinArgs);

 private:

 	/**

 	Allocate memory to store pointers to all the page table which map

 	\a aCount pages of memory. The pointer to the allocated memory

 	is stored at iAllocatedPinnedPageTables.

 	If iSmallPinnedPageTablesArray is large enough, this function doesn't

 	allocate any memory.

 	@return KErrNone if successful, otherwise KErrNoMemory.

 	*/

 	TInt AllocPageTableArray(TUint aCount);

 	/**

 	Delete iAllocatedPinnedPageTables.

 	*/

 	void FreePageTableArray();

 	/**

 	Return the address of the array storing pinned page tables.

 	This is either iSmallPinnedPageTablesArray or iAllocatedPinnedPageTables.

 	*/

 	TPte** PageTableArray();

 	/**

 	Unpin all the page tables which have been pinned by this mapping.

 	@param aPinArgs	The resources used for pinning. The replacement pages allocated

 					to this will be increased for each page which was became completely

 					unpinned.

 	*/

 	void UnpinPageTables(TPinArgs& aPinArgs);

 private:

 	/**

 	Temporary store for the mapping passed to #Pin

 	*/

 	DMemoryMappingBase* iPinVirtualMapping;

 	/**

 	Temporary store for the mapping instance count passed to #Pin

 	*/

 	TUint iPinVirtualMapInstanceCount;

 	/**

 	The number of page tables which are currently being pinned by this mapping.

 	This is the number of valid entries stored at PageTableArray.

 	*/

 	TUint iNumPinnedPageTables;

 	/**

 	The maximum number of pages which can be pinned by this mapping.

 	If this is zero, there is no maximum.

 	*/

 	TUint iMaxCount;

 	/**

 	The memory allocated by this object for storing pointer to the page tables

 	it has pinned.

 	*/

 	TPte** iAllocatedPinnedPageTables;

 	enum

 		{

 		KSmallPinnedPageTableCount = 2 ///< Number of entries in iSmallPinnedPageTablesArray

 		};

 	/**

 	A small array to use for storing pinned page tables.

 	This is an optimisation used for the typical case of pinning a small number of pages

 	to avoid dynamic allocation of memory.

 	*/

 	TPte* iSmallPinnedPageTablesArray[KSmallPinnedPageTableCount];

 	}; 

 #endif