// 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.