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

#define MM_H

#include <mmtypes.h>

#include <platform.h>

class DMemoryObject;

class DMemoryMapping;

class DMemModelThread;

class DPhysicalPinMapping;

/**

Memory object types for MM::MemoryNew which indicates how the

contents of a memory object are to be managed.

*/

enum TMemoryObjectType

	{

	/**

	Memory object for containing memory mapped hardware devices or special

	purpose memory for which the physical addresses are fixed. The contents of

	these type of objects are manipulated with the functions:

	- MM::MemoryAddPages

	- MM::MemoryAddContiguous

	- MM::MemoryRemovePages

	*/

	EMemoryObjectHardware				= 0,

	/**

	Memory object containing normal program memory (RAM) which is allocated from a

	system wide pool. The contents of these type of objects are manipulated with

	the functions:

	- MM::MemoryAlloc

	- MM::MemoryAllocContiguous

	- MM::MemoryFree

	*/

	EMemoryObjectUnpaged				= 1,

	/**

	Memory object containing normal program memory (RAM) which is allocated from a

	system wide pool. This is the same basic management as EMemoryObjectUnpaged however

	RAM defragmentation activity may substituted physical RAM pages with others and

	this process may cause transient page faults which make this memory not suitable

	for most kernel-side usage.

	The contents of these type of objects are manipulated with the functions:

	- MM::MemoryAlloc

	- MM::MemoryAllocContiguous

	- MM::MemoryFree

	*/

	EMemoryObjectMovable				= 2,

	/**

	Memory object containing normal program memory (RAM) which is demand paged

	from a backing store. The contents of these type of objects are manipulated

	with the functions.

	- MM::MemoryAlloc

	- MM::MemoryFree

	*/

	EMemoryObjectPaged					= 3,

	/**

	Memory object containing normal program memory (RAM) in the same way as

	EMemoryObjectMovable but with the additional option of marking pages as

	'discardable'. Discardable pages may be reclaimed (remove) by the system at

	any time, this state is controlled using the functions:

	- MM::MemoryAlloc

	- MM::MemoryAllocContiguous

	- MM::MemoryFree

	- MM::MemoryAllowDiscard

	- MM::MemoryDisallowDiscard

	*/

	EMemoryObjectDiscardable			= 4

	};

/**

Bitmask of flags to specify options to MM:MemoryNew.

*/

enum TMemoryCreateFlags

	{

	/**

	Default value which has all flags false.

	*/

	EMemoryCreateDefault				= 0,

	/**

	Memory allocated for the memory object contents does not need wiping.

	IMPORTANT, memory is normally wiped for security purposes, this attribute

	should only be used when the old contents of any memory allocated can not

	be read by any process without TCB capability.

	*/

	EMemoryCreateNoWipe					= 1<<0,

	/**

	Use the custom wipe byte value when wiping memory, rather than the default value.

	@see EMemoryCreateUseCustomWipeByte

	*/

	EMemoryCreateUseCustomWipeByte		= 1<<1,

	/**

	Pre-create all resources the memory object needs so that operations on it

	can not fail due to low memory conditions. This excludes any explicit

	allocation of memory pages for use as the objects contents.

	*/

	EMemoryCreateReserveAllResources	= 1<<2,

	/**

	Memory object contents are not allowed to be pinned.

	*/

	EMemoryCreateDisallowPinning		= 1<<3,

	/**

	Memory object contents are read-only. Mappings with write permissions are

	not allowed.

	*/

	EMemoryCreateReadOnly				= 1<<4,

	/**

	Memory object contents may be executed. Mappings with execute permissions

	are allowed.

	*/

	EMemoryCreateAllowExecution			= 1<<5,

	/**

	Bit position for the least significant bit of an 8 bit value to use for

	wiping newly allocated memory.

	@see EMemoryCreateUseCustomWipeByte

	@see EMemoryCreateNoWipe

	*/

	EMemoryCreateWipeByteShift			= 8,

	// for selected internal use only...

	/**

	The TMemoryObjectType specified is actually a pointer to the DMemoryManager to use.

	*/

	EMemoryCreateCustomManager			= 1<<30,

	/**

	Memory object contents are to be demand paged. 

	*/

	};

/**

Attributes that the memory in a memory object has.

These govern how the MMU and caching systems treat the memory. The following

terms have meanings as specified in the ARM Architecture Reference Manual - see

the section 'Memory types and attributes and the Memory order model'.

- Memory types 'normal', 'device' and 'strongly-ordered'.

- 'Shareable' attribute.

*/

enum TMemoryAttributes

	{

	// memory types (copy of TMemoryType)...

	EMemoryAttributeStronglyOrdered 	= EMemAttStronglyOrdered,

	EMemoryAttributeDevice 				= EMemAttDevice,

	EMemoryAttributeNormalUncached 		= EMemAttNormalUncached,

	EMemoryAttributeNormalCached 		= EMemAttNormalCached,

	EMemoryAttributeKernelInternal4 	= EMemAttKernelInternal4,

	EMemoryAttributePlatformSpecific5 	= EMemAttPlatformSpecific5,

	EMemoryAttributePlatformSpecific6	= EMemAttPlatformSpecific6,

	EMemoryAttributePlatformSpecific7	= EMemAttPlatformSpecific7,

	/**

	Bitmask to extract TMemoryType value from this enum. E.g.

	@code

	TMemoryAttributes attr;

	TMemoryType type = (TMemoryType)(attr&EMemoryAttributeTypeMask);

	@endcode

	*/

	EMemoryAttributeTypeMask			= KMemoryTypeMask,

	/**

	Set if memory is Shareable.

	*/

	EMemoryAttributeShareable			= 0x08,

	/**

	Legacy (and little-used/unused?) ARM attribute.

	*/

	EMemoryAttributeUseECC				= 0x10,

	/**

	Number of bits required to store memory attribute value.

	@internalComponent

	*/

	EMemoryAttributeShift				= 5,

	/**

	Bitmask for all significant attribute bits.

	@internalComponent

	*/

	EMemoryAttributeMask				= (1<<EMemoryAttributeShift)-1,

	// pseudo attributes...

	/**

	Indicates the Shareable attribute should be the default value for the system.

	See macro __CPU_USE_SHARED_MEMORY

	*/

	EMemoryAttributeDefaultShareable	= 0x80000000,

	// popular combinations...

	/**

	Normal program memory for use by software.

	*/

	EMemoryAttributeStandard			= EMemoryAttributeNormalCached|EMemoryAttributeDefaultShareable

	};

/**

Access permissions applied to Memory Mappings.

*/

enum TMappingPermissions

	{

	EUser	    = 1<<0, ///< Unprivileged (user mode) access allowed.

	EReadWrite  = 1<<1, ///< Memory contents may be modified

	EExecute	= 1<<2, ///< Memory contents may be executed as code.

	// popular combinations...

	EUserReadOnly = EUser,

	EUserReadWrite = EUser|EReadWrite,

	EUserExecute = EUser|EExecute,

	ESupervisorReadOnly = 0,

	ESupervisorReadWrite = EReadWrite,

	ESupervisorExecute = EExecute

	};

/**

Bitmask of flags to specify options to MM::MappingNew.

*/

enum TMappingCreateFlags

	{

	/**

	Default value which has all flags false.

	*/

	EMappingCreateDefault				= 0,

	/**

	Allocate the specified virtual address.

	*/

	EMappingCreateExactVirtual			= 1<<0,

	/**

	Pre-create all resources (like page tables) that the memory mapping

	needs so that operations on it can not fail due to low memory conditions.

	*/

	EMappingCreateReserveAllResources	= 1<<1,

	// for selected internal use only...

	/**

	Flag memory as being demand paged.

	Exclusive with EMappingCreatePinning and EMappingCreateReserveAllResources.

	@internalTechnology

	*/

	EMappingCreateDemandPaged			= 1<<27,

	/**

	Flag memory as requiring a common address across all address spaces, also

	implies EMappingCreateExactVirtual.

	@internalTechnology

	*/

	EMappingCreateCommonVirtual			= 1<<28,

	/**

	Allocate virtual address in the global region which it to be used for

	user-mode access. (KGlobalMemoryBase<=address<KUserMemoryLimit).

	@internalTechnology

	*/

	EMappingCreateUserGlobalVirtual		= 1<<29,

	/**

	Don't allocate any virtual memory in the address space, use the specified

	address and assume ownership of this.

	@internalTechnology

	*/

	EMappingCreateAdoptVirtual			= 1<<30,

	/**

	Don't allocate any virtual memory in the address space, just used the

	specified address.

	@internalTechnology

	*/

	};

class DMemModelChunk;

class TPagedCodeInfo;

/**

Static interface to the Flexible Memory Model implementation

for use by the Symbian OS aware part of the memory model codebase.

*/

class MM

	{

public:

	//

	// Memory Object functions

	//

	/**

	Create a new memory object.

	A memory object is a sparse array of memory pages to which memory mappings

	may be attached. All pages in the array are managed using the same methods

	(see TMemoryObjectType) and have the same attributes (see TMemoryAttributes).

	On creation it contains no pages.

	@param[out] aMemory	Pointer reference which on success is set to the address

						of the created memory object.

	@param aType		Value from TMemoryObjectType which indicates how the

						contents of the memory object are to be managed.

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

	@param aCreateFlags	Bitmask of option flags from enum TMemoryCreateFlags.

	@param aAttributes	Bitmask of values from enum TMemoryAttributes.

	@return KErrNone, if successful;

			otherwise another of the system wide error codes.

	*/

	static TInt MemoryNew(DMemoryObject*& aMemory, TMemoryObjectType aType, TUint aPageCount, TMemoryCreateFlags aCreateFlags=EMemoryCreateDefault, TMemoryAttributes aAttributes=EMemoryAttributeStandard);

	/**

	Assign a mutex which will be used to serialise explicit modifications to the

	specified memory object.

	If a lock hasn't been specified for a particular object, it will make use of

	one allocated dynamically allocated from a shared pool; this mutex will be of 'order'

	#KMutexOrdMemoryObject.

	@see MemoryObjectLock.

	*/

	static void MemorySetLock(DMemoryObject* aMemory, DMutex* aLock);

	/**

	Wait on the specified memory object's lock mutex.

	*/

	static void MemoryLock(DMemoryObject* aMemory);

	/**

	Signal the specified memory object's lock mutex.

	*/

	static void MemoryUnlock(DMemoryObject* aMemory);

	/**

	Remove all memory from a memory object and close a reference on it.

	If there are no longer any mappings to the memory, or other references,

	this will result in the memory object being destroyed. However whilst

	other references exist, cleanup of memory and other resources may be

	delayed indefinitely.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	@param aMemory	Pointer reference to memory object to be destroyed.

					On return from the function this is set to the null-pointer.

					No action is performed if the reference was already the

					null-pointer on entry to this function.

	*/

	static void MemoryDestroy(DMemoryObject*& aMemory);

	/**

	Allocate memory for a specified region within a memory object.

	Memory is allocated as appropriate for the object type, e.g.

	For Unpaged objects, from the system RAM pool; for Paged objects, in the

	backing store.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Supported for memory object types:

	- EMemoryObjectUnpaged

	- EMemoryObjectMovable

	- EMemoryObjectPaged

	- EMemoryObjectDiscardable

	@param aMemory	The memory object.

	@param aIndex	Page index for start of the region.

	@param aCount	Number of pages in the region.

	@return KErrNone, if successful;

			KErrAlreadyExists, if any part of the region was already allocated;

			KErrArgument, if the region exceeds the bounds of the memory object;

			KErrNotSupported, if the memory object doesn't support this operation;

			otherwise another of the system wide error codes.

	*/

	static TInt MemoryAlloc(DMemoryObject* aMemory, TUint aIndex, TUint aCount);

	/**

	Allocate memory for a specified region within a memory object.

	The allocated memory will have contiguous physical addresses.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Important note, this function can unexpectedly fail with KErrAlreadyExists

	if any part of the the region previously contained allocated memory which

	had been freed but which was pinned. It is therefore not suitable for general

	use.

	Supported for memory object types:

	- EMemoryObjectUnpaged

	- EMemoryObjectDiscardable

	@param aMemory	The memory object.

	@param aIndex	Page index for start of the region.

	@param aCount	Number of pages in the region.

	@param aAlign	Log2 of the alignment (in bytes) that the address of the allocated physical RAM must have.

	@param[out] aPhysAddr	On success, this is set to the start address of the allocated physical RAM.

	@return KErrNone, if successful;

			KErrAlreadyExists, if any part of the region was already allocated;

			KErrArgument, if the region exceeds the bounds of the memory object;

			KErrNotSupported, if the memory object doesn't support this operation;

			otherwise another of the system wide error codes.

	*/

	static TInt MemoryAllocContiguous(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TUint aAlign, TPhysAddr& aPhysAddr);

	/**

	Free (unallocate) memory for a specified region within a memory object.

	This is the inverse operation to MemoryAlloc and MemoryAllocContiguous.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Supported for memory object types:

	- EMemoryObjectUnpaged

	- EMemoryObjectMovable

	- EMemoryObjectPaged

	- EMemoryObjectDiscardable

	@param aMemory	The memory object.

	@param aIndex	Page index for start of the region.

	@param aCount	Number of pages in the region.

	*/

	static void MemoryFree(DMemoryObject* aMemory, TUint aIndex, TUint aCount);

	/**

	Add the specified pages to a region in a memory object.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Supported for memory object types:

	- EMemoryObjectHardware

	@param aMemory	The memory object.

	@param aIndex	Page index for start of the region.

	@param aCount	Number of pages in the region.

	@param aPages	Pointer to array of pages to add. This must contain \a aCount

					number of physical page addresses which are page aligned.

	@return KErrNone, if successful;

			KErrAlreadyExists, if any part of the region already contains pages;

			KErrArgument, if the region exceeds the bounds of the memory object;

			KErrNotSupported, if the memory object doesn't support this operation;

			otherwise another of the system wide error codes.

	*/

	static TInt MemoryAddPages(DMemoryObject* aMemory, TUint aIndex, TUint aCount, const TPhysAddr* aPages);

	/**

	Add a contiguous range of pages to a region in a memory object.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Supported for memory object types:

	- EMemoryObjectHardware

	@param aMemory		The memory object.

	@param aIndex		Page index for start of the region.

	@param aCount		Number of pages in the region.

	@param aPhysAddr	The page aligned start address of the pages to be added.

	@return KErrNone, if successful;

			KErrAlreadyExists, if any part of the region already contains pages;

			KErrArgument, if the region exceeds the bounds of the memory object;

			KErrNotSupported, if the memory object doesn't support this operation;

			otherwise another of the system wide error codes.

	*/

	static TInt MemoryAddContiguous(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TPhysAddr aPhysAddr);

	/**

	Remove pages from a region in a memory object.

	This is the inverse operation to MemoryAdd and MemoryAddContiguous.

	This function acquires and releases the memory objects lock.

	See MM::MemorySetLock.

	Supported for memory object types:

	- EMemoryObjectHardware

	@param aMemory		The memory object.