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

#define MOBJECT_H

#include "mrefcntobj.h"

#include "mmappinglist.h"

#include "mpagearray.h"

class DMemoryManager;

class DCoarseMapping;

/**

Base class for memory objects.

A memory object is a sparse array of memory pages (#iPages) to which memory

mappings may be attached (#iMappings). All pages in the array are managed

in the same way (#iManager).

*/

class DMemoryObject : public DReferenceCountedObject

	{

public:

	virtual ~DMemoryObject();

	/**

	Claim ownership of memory originally allocated by the bootstrap.

	This is used during system boot to initialise this object's memory to contain

	the pages which are already mapped at a given region of virtual addresses.

	For coarse memory objects, this function also takes ownership of the page tables

	being used to map the memory.

	@param aBase				Starting virtual address of memory to claim.

	@param aSize				Size, in bytes, of memory region to claim.

	@param aPermissions			The access permissions which the memory region

								is mapped. As well as being required for correct object

								initialisation this also enables the function to check

								that the bootstrap code mapped the memory in manner

								consistent with the flexible memory model implementation.

	@param aAllowGaps			True if the memory region may have gaps (unmapped pages) in it.

								If false, the function faults if the region is not fully

								populated with mapped pages.

	@param aAllowNonRamPages	True if the memory region contains memory pages which are

								not RAM pages known to the kernel. I.e. are not

								contained in the list of RAM banks supplied by the bootstrap.

								Any such memory cannot be never be subsequently freed from the

								memory object because the kernel can't handle this memory.

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

	*/

	virtual TInt ClaimInitialPages(TLinAddr aBase, TUint aSize, TMappingPermissions aPermissions, TBool aAllowGaps=false, TBool aAllowNonRamPages=false) = 0;

	/**

	Update the page table entries for all attached mappings to add entries for

	a specified set of memory pages.

	This method is called by this object's manager whenever new pages of memory are added.

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

								in this memory object.

								Only array entries which have state RPageArray::ECommitted

								should be mapped into a mapping's page tables.

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

	*/

	virtual TInt MapPages(RPageArray::TIter aPages);

	/**

	Update the page table entries for all attached mappings to add new entry for

	a specified memory page.

	This method is called by this object's manager whenever the page is moved.

	@param aPageArray			The page array entry of the page in this memory object.

								Only array entries which have state RPageArray::ECommitted

								should be mapped into a mapping's page tables.

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

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

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

	*/

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

	/**

	Update the page table entries for all attached mappings to remove entries for

	a specified set of memory pages.

	This method is called this object's manager whenever pages of memory are removed.

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

								in this memory object.

								Only array entries which return true for

								RPageArray::TargetStateIsDecommitted should be unmapped

								from a mapping's page tables.

	@param aDecommitting		True if memory is being permanently decommitted from

								the memory object. False if the memory pages are only

								temporarily being unmapped due to a demand paging 'page out'

								operation.

	*/

	virtual void UnmapPages(RPageArray::TIter aPages, TBool aDecommitting);

	/**

	Update the page table entries for all attached mappings to apply access restrictions

	to a specified set of memory pages.

	This method is called by this object's manager whenever pages of memory are restricted.

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

								in this memory object.

								Only array entries which return true for

								RPageArray::TargetStateIsDecommitted should be unmapped

								from a mapping's page tables.

	@param aRestriction			A value from enum #TRestrictPagesType indicating the

								kind of restriction to apply.

	*/

	virtual void RestrictPages(RPageArray::TIter aPages, TRestrictPagesType aRestriction);

	/**

	Add a memory mapping to this memory object.

	This is only intended for use by #DMemoryMappingBase::Attach.

	After verifying that the mapping is permitted (using #CheckNewMapping)

	the mapping is linked into this objects list of mappings #iMappings.

	@param aMapping The mapping to add.

	@return KErrNone if successful,

			otherwise KErrAccessDenied to indicate that the mapping is not allowed.

	*/

	virtual TInt AddMapping(DMemoryMappingBase* aMapping);

	/**

	Remove a memory mapping from this memory object.

	This is only intended for use by #DMemoryMappingBase::Detach.

	This unlinks the mapping from the list of mappings #iMappings.

	@param aMapping The mapping to remove.

	*/

	virtual void RemoveMapping(DMemoryMappingBase* aMapping);

	/**

	Attempt to set the memory object read only.  This will only succeed if

	there are no writable mappings to the memory object.

	NOTE - This can't be undone, page moving will break if a memory object 

	is made writable again.

	@return KErrNone on success, KErrInUse if writable mappings are found.

	*/

	virtual TInt SetReadOnly();

	/**

	Create a mapping object to map this memory.

	This is only intended for use by #MM::MappingNew.

	The base class creates a #DFineMapping object.  It is overridden by #DCoarseMemory to create a

	#DCoarseMapping in appropriate circumstances.

	@param aIndex 		The index of the start of the mapping into this memory object.

	@oaram aCount		The size in pages of the mapping.

	*/

	virtual DMemoryMapping* CreateMapping(TUint aIndex, TUint aCount);

	/**

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

	Depending on how the memory is being managed the physical addresses returned

	may become invalid due to various reasons, e.g.

	- memory being decommitted from the memory object

	- ram defragmentation moving the memory contents to a different physical page

	- paging out of demand paged memory

	This function should therefore only be used where it is know that these

	possibilities can't occur, e.g. this is used safely by DPhysicalPinMapping::PhysAddr.

	@param aIndex			Page index, within the memory, for the 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.

	*/

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

	/**

	Check specified region lies entirely within this memory object, and that it

	is page aligned.

	*/

	TBool CheckRegion(TUint aIndex, TUint aCount);

	/**

	Clip the specified region to lie within the memory object,

	*/

	void ClipRegion(TUint& aIndex, TUint& aCount);

	/**

	Set the mutex used to lock operations on this memory object

	*/

	void SetLock(DMutex* aLock);

	/**

	Prevents any further mappings being added to this memory object.

	*/

	void DenyMappings();

	/**

	Return the memory attributes for this object's memory.

	*/

	FORCE_INLINE TMemoryAttributes Attributes()

		{

		return (TMemoryAttributes)iAttributes;

		}

	/**

	Value for initialising SPageInfo::iFlags when allocating pages.

	*/

	FORCE_INLINE TUint8 PageInfoFlags()

		{

		return iAttributes;

		}

	/**

	Value for #Mmu::TRamAllocFlags to use when allocating pages.

	*/

	FORCE_INLINE Mmu::TRamAllocFlags RamAllocFlags()

		{

		return (Mmu::TRamAllocFlags)iRamAllocFlags;

		}

	/**

	Return true if this object is an instance of #DCoarseMemory.

	*/

	FORCE_INLINE TBool IsCoarse()

		{

		return iFlags&ECoarseObject;

		}

	/**

	Return true if this object contains memory which is being demand paged.

	*/

	FORCE_INLINE TBool IsDemandPaged()

		{

		return iFlags&EDemandPaged;

		}

	/**

	Return true if writeable mappings of the memory are not allowed.

	*/

	FORCE_INLINE TBool IsReadOnly()

		{

		return iFlags&EDenyWriteMappings;

		}

	/**

	Return true if executable mappings allowed on this memory object.

	*/

	FORCE_INLINE TBool IsExecutable()

		{

		return !(iFlags&EDenyExecuteMappings);

		}

	/**

	Clear the flag that indicates that a mapping has been added.

	*/

	FORCE_INLINE void ClearMappingAddedFlag()

		{

		__NK_ASSERT_DEBUG(iMappings.LockIsHeld());

		__e32_atomic_and_ord8(&iFlags, (TUint8)~EMappingAdded);

		}

	/**

	Set the flag to indicate that a mapping has been added.

	*/

	FORCE_INLINE void SetMappingAddedFlag()

		{

		__NK_ASSERT_DEBUG(iMappings.LockIsHeld());

		__NK_ASSERT_DEBUG(MmuLock::IsHeld());

		__e32_atomic_ior_ord8(&iFlags, (TUint8)EMappingAdded);

		}

	/**

	Get the value of the mappings added flags

	@return ETrue if a mapping has been added, EFalse otherwise.

	*/

	FORCE_INLINE TBool MappingAddedFlag()

		{

		__NK_ASSERT_DEBUG(MmuLock::IsHeld());

		return iFlags & (TUint8)EMappingAdded;

		}

	enum

		{

		/**

		Maximum number of bits which can be stored in an array entry by SetPagingManagerData.

		*/

		KPagingManagerDataBits = RPageArray::KPagingManagerDataBits

		};

	enum

		{

		/**

		Maximum value which can be stored in an array entry by SetPagingManagerData.

		*/

		KMaxPagingManagerData = RPageArray::KMaxPagingManagerData

		};

	/**

	Write \a aValue to the paging manager data for page index \a aIndex.

	The value must not exceed KMaxPagingManagerData.

	This must only be used for demand paged memory objects.

	*/

	void SetPagingManagerData(TUint aIndex, TUint aValue);

	/**

	Return the paging manager data for page index \a aIndex.

	This must only be used for demand paged memory objects.

	@see SetPagingManagerData

	*/

	TUint PagingManagerData(TUint aIndex);

	/**

	Check that a given memory mapping is allowed to be attached to this memory object.

	@param aMapping	The mapping to check.

	@return KErrNone if successful,

			otherwise KErrAccessDenied to indicate that the mapping is not allowed.

	*/

	TInt CheckNewMapping(DMemoryMappingBase* aMapping);

	/**

	Emit BTrace traces identifying the initial attributes of this object.

	*/

	void BTraceCreate();

protected:

	/**

	@param aManager		The manager object for this memory.

	@param aFlags		Initial value for #iFlags.

	@param aSizeInPages	Size of the memory object, in number of pages.

	@param aAttributes	Bitmask of values from enum #TMemoryAttributes.

	@param aCreateFlags	Bitmask of option flags from enum #TMemoryCreateFlags.

	*/

	DMemoryObject(DMemoryManager* aManager, TUint aFlags, TUint aSizeInPages, TMemoryAttributes aAttributes, TMemoryCreateFlags aCreateFlags);

	/**

	Second phase constructor.

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

	*/

	TInt Construct();

public:

	/**

	The manager of this memory object.

	*/

	DMemoryManager*	iManager;

	/**

	For use by this object's manager (iManager) to store any memory objects specific state

	it requires to keep track of.

	*/

	TAny*			iManagerData;

	/**

	For use by DMemoryManager::QueueCleanup to link objects which require a cleanup operation.

	Access to this is protected by #DMemoryManager::iCleanupLock.

	*/

	DMemoryObject*	iCleanupNext;

	/**

	For use by DMemoryManager::QueueCleanup to store flags representing each pending cleanup operation.

	Access to this is protected by #DMemoryManager::iCleanupLock.

	*/

	TUint32			iCleanupFlags;

	/**

	Bit flags stored in #iFlags giving various state and attributes of the object.

	*/

	enum TFlags

		{

		/**

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

		class #DCoarseMemory.

		*/

		ECoarseObject			= 1<<0,

		/**

		Flag set during object construction to indicate that the memory for this object

		is being demand paged in some manner.

		*/

		EDemandPaged			= 1<<1,

		/**

		Flag set during object construction to indicate that all resources for this

		object are to be reserved during construction; excluding memory pages owned by

		object. Objects constructed in this way will not require additional memory

		allocation when committing memory to them (other than allocating the memory

		pages being committed.)

		*/

		EReserveResources		= 1<<2,

		/**

		Flag set during object construction to indicate that pinned memory mappings

		are not allowed to be attached to this object.

		*/

		EDenyPinning			= 1<<3,

		/**

		Flag set by DenyMappings to indicate that no additional memory mappings

		are allowed to be attached to this object.

		*/

		EDenyMappings			= 1<<4,

		/**

		Flag set during object construction, or by SetReadOnly, to indicate that

		the memory object is read-only and no writable mappings are allowed

		to be attached to this object.

		*/

		EDenyWriteMappings		= 1<<5,

		/**

		Flag set during object construction to indicate that executable memory mappings

		are not allowed to be attached to this object.

		This is mainly an optimisation to allow demand paging to avoid instruction cache

		maintenance operations during page fault handling.

		*/

		EDenyExecuteMappings	= 1<<6,

		/**

		Flag set whenever a new mapping is added to a memory object.

		The object's mappings lock and MmuLock protects this flag when it is set

		and the mappings lock protects when it is cleared.

		*/

		EMappingAdded			= 1<<7,

		};

	/**

	Bitmask of TFlags

	*/

	TUint8 iFlags;

	/**

	Value from TMemoryAttributes indicating type of memory in object.

	*/

	TUint8 iAttributes;

	/**

	#Mmu::TRamAllocFlags value to use when allocating RAM for this memory object.

	*/

	TUint16 iRamAllocFlags;

	/**

	List of mappings currently attached to this object.

	*/

	TMappingList iMappings;

	/**

	Size, in page units, of this memory object.

	*/

	TUint iSizeInPages;

	/**

	Lock currently being used to serialise explicit memory operations.

	This is assigned using #MemoryObjectLock.

	*/

	DMutex* iLock;

	/**

	The array of memory pages assigned to this memory object.

	*/

	RPageArray iPages;

	};

/**

A memory object which has a size that is an exact multiple