1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @internalComponent

    19 */

    20 

    21 #ifndef MM_H

    22 #define MM_H

    23 

    24 #include <mmtypes.h>

    25 #include <platform.h>

    26 

    27 

    28 class DMemoryObject;

    29 class DMemoryMapping;

    30 class DMemModelThread;

    31 class DPhysicalPinMapping;

    32 

    33 /**

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

    35 contents of a memory object are to be managed.

    36 */

    37 enum TMemoryObjectType

    38 	{

    39 	/**

    40 	Memory object for containing memory mapped hardware devices or special

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

    42 	these type of objects are manipulated with the functions:

    43 	- MM::MemoryAddPages

    44 	- MM::MemoryAddContiguous

    45 	- MM::MemoryRemovePages

    46 	*/

    47 	EMemoryObjectHardware				= 0,

    48 

    49 	/**

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

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

    52 	the functions:

    53 	- MM::MemoryAlloc

    54 	- MM::MemoryAllocContiguous

    55 	- MM::MemoryFree

    56 	*/

    57 	EMemoryObjectUnpaged				= 1,

    58 

    59 	/**

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

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

    62 	RAM defragmentation activity may substituted physical RAM pages with others and

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

    64 	for most kernel-side usage.

    65 

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

    67 	- MM::MemoryAlloc

    68 	- MM::MemoryAllocContiguous

    69 	- MM::MemoryFree

    70 	*/

    71 	EMemoryObjectMovable				= 2,

    72 

    73 	/**

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

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

    76 	with the functions.

    77 	- MM::MemoryAlloc

    78 	- MM::MemoryFree

    79 	*/

    80 	EMemoryObjectPaged					= 3,

    81 

    82 	/**

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

    84 	EMemoryObjectMovable but with the additional option of marking pages as

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

    86 	any time, this state is controlled using the functions:

    87 	- MM::MemoryAllowDiscard

    88 	- MM::MemoryDisallowDiscard

    89 	*/

    90 	EMemoryObjectDiscardable			= 4

    91 	};

    92 

    93 

    94 /**

    95 Bitmask of flags to specify options to MM:MemoryNew.

    96 */

    97 enum TMemoryCreateFlags

    98 	{

    99 	/**

   100 	Default value which has all flags false.

   101 	*/

   102 	EMemoryCreateDefault				= 0,

   103 

   104 	/**

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

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

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

   108 	be read by any process without TCB capability.

   109 	*/

   110 	EMemoryCreateNoWipe					= 1<<0,

   111 

   112 	/**

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

   114 	@see EMemoryCreateUseCustomWipeByte

   115 	*/

   116 	EMemoryCreateUseCustomWipeByte		= 1<<1,

   117 

   118 	/**

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

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

   121 	allocation of memory pages for use as the objects contents.

   122 	*/

   123 	EMemoryCreateReserveAllResources	= 1<<2,

   124 

   125 	/**

   126 	Memory object contents are not allowed to be pinned.

   127 	*/

   128 	EMemoryCreateDisallowPinning		= 1<<3,

   129 

   130 	/**

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

   132 	not allowed.

   133 	*/

   134 	EMemoryCreateReadOnly				= 1<<4,

   135 

   136 	/**

   137 	Memory object contents may be executed. Mappings with execute permissions

   138 	are allowed.

   139 	*/

   140 	EMemoryCreateAllowExecution			= 1<<5,

   141 

   142 	/**

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

   144 	wiping newly allocated memory.

   145 	@see EMemoryCreateUseCustomWipeByte

   146 	@see EMemoryCreateNoWipe

   147 	*/

   148 	EMemoryCreateWipeByteShift			= 8,

   149 

   150 	// for selected internal use only...

   151 

   152 	/**

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

   154 	*/

   155 	EMemoryCreateCustomManager			= 1<<30,

   156 

   157 	/**

   158 	Memory object contents are to be demand paged. 

   159 	*/

   160 	EMemoryCreateDemandPaged			= 1<<31

   161 	};

   162 

   163 

   164 /**

   165 Attributes that the memory in a memory object has.

   166 

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

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

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

   170 

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

   172 - 'Shareable' attribute.

   173 */

   174 enum TMemoryAttributes

   175 	{

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

   177 

   178 	EMemoryAttributeStronglyOrdered 	= EMemAttStronglyOrdered,

   179 	EMemoryAttributeDevice 				= EMemAttDevice,

   180 	EMemoryAttributeNormalUncached 		= EMemAttNormalUncached,

   181 	EMemoryAttributeNormalCached 		= EMemAttNormalCached,

   182 	EMemoryAttributeKernelInternal4 	= EMemAttKernelInternal4,

   183 	EMemoryAttributePlatformSpecific5 	= EMemAttPlatformSpecific5,

   184 	EMemoryAttributePlatformSpecific6	= EMemAttPlatformSpecific6,

   185 	EMemoryAttributePlatformSpecific7	= EMemAttPlatformSpecific7,

   186 

   187 	/**

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

   189 	@code

   190 	TMemoryAttributes attr;

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

   192 	@endcode

   193 	*/

   194 	EMemoryAttributeTypeMask			= KMemoryTypeMask,

   195 

   196 	/**

   197 	Set if memory is Shareable.

   198 	*/

   199 	EMemoryAttributeShareable			= 0x08,

   200 

   201 	/**

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

   203 	*/

   204 	EMemoryAttributeUseECC				= 0x10,

   205 

   206 

   207 	/**

   208 	Number of bits required to store memory attribute value.

   209 	@internalComponent

   210 	*/

   211 	EMemoryAttributeShift				= 5,

   212 

   213 	/**

   214 	Bitmask for all significant attribute bits.

   215 	@internalComponent

   216 	*/

   217 	EMemoryAttributeMask				= (1<<EMemoryAttributeShift)-1,

   218 

   219 	// pseudo attributes...

   220 

   221 	/**

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

   223 	See macro __CPU_USE_SHARED_MEMORY

   224 	*/

   225 	EMemoryAttributeDefaultShareable	= 0x80000000,

   226 

   227 	// popular combinations...

   228 

   229 	/**

   230 	Normal program memory for use by software.

   231 	*/

   232 	EMemoryAttributeStandard			= EMemoryAttributeNormalCached|EMemoryAttributeDefaultShareable

   233 	};

   234 

   235 

   236 /**

   237 Access permissions applied to Memory Mappings.

   238 */

   239 enum TMappingPermissions

   240 	{

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

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

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

   244 

   245 	// popular combinations...

   246 	EUserReadOnly = EUser,

   247 	EUserReadWrite = EUser|EReadWrite,

   248 	EUserExecute = EUser|EExecute,

   249 	ESupervisorReadOnly = 0,

   250 	ESupervisorReadWrite = EReadWrite,

   251 	ESupervisorExecute = EExecute

   252 	};

   253 

   254 

   255 /**

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

   257 */

   258 enum TMappingCreateFlags

   259 	{

   260 	/**

   261 	Default value which has all flags false.

   262 	*/

   263 	EMappingCreateDefault				= 0,

   264 

   265 	/**

   266 	Allocate the specified virtual address.

   267 	*/

   268 	EMappingCreateExactVirtual			= 1<<0,

   269 

   270 	/**

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

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

   273 	*/

   274 	EMappingCreateReserveAllResources	= 1<<1,

   275 

   276 	// for selected internal use only...

   277 

   278 	/**

   279 	Flag memory as being demand paged.

   280 	Exclusive with EMappingCreatePinning and EMappingCreateReserveAllResources.

   281 	@internalTechnology

   282 	*/

   283 	EMappingCreateDemandPaged			= 1<<27,

   284 

   285 	/**

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

   287 	implies EMappingCreateExactVirtual.

   288 	@internalTechnology

   289 	*/

   290 	EMappingCreateCommonVirtual			= 1<<28,

   291 

   292 	/**

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

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

   295 	@internalTechnology

   296 	*/

   297 	EMappingCreateUserGlobalVirtual		= 1<<29,

   298 

   299 	/**

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

   301 	address and assume ownership of this.

   302 	@internalTechnology

   303 	*/

   304 	EMappingCreateAdoptVirtual			= 1<<30,

   305 

   306 	/**

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

   308 	specified address.

   309 	@internalTechnology

   310 	*/

   311 	EMappingCreateFixedVirtual	= 1<<31

   312 	};

   313 

   314 

   315 class DMemModelChunk;

   316 class TPagedCodeInfo;

   317 

   318 /**

   319 Static interface to the Flexible Memory Model implementation

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

   321 */

   322 class MM

   323 	{

   324 public:

   325 	//

   326 	// Memory Object functions

   327 	//

   328 

   329 	/**

   330 	Create a new memory object.

   331 

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

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

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

   335 

   336 	On creation it contains no pages.

   337 

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

   339 						of the created memory object.

   340 	@param aType		Value from TMemoryObjectType which indicates how the

   341 						contents of the memory object are to be managed.

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

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

   344 	@param aAttributes	Bitmask of values from enum TMemoryAttributes.

   345 

   346 	@return KErrNone, if successful;

   347 			otherwise another of the system wide error codes.

   348 	*/

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

   350 

   351 	/**

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

   353 	specified memory object.

   354 

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

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

   357 	#KMutexOrdMemoryObject.

   358 

   359 	@see MemoryObjectLock.

   360 	*/

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

   362 

   363 	/**

   364 	Wait on the specified memory object's lock mutex.

   365 	*/

   366 	static void MemoryLock(DMemoryObject* aMemory);

   367 

   368 	/**

   369 	Signal the specified memory object's lock mutex.

   370 	*/

   371 	static void MemoryUnlock(DMemoryObject* aMemory);

   372 

   373 	/**

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

   375 

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

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

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

   379 	delayed indefinitely.

   380 

   381 	This function acquires and releases the memory objects lock.

   382 	See MM::MemorySetLock.

   383 

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

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

   386 					No action is performed if the reference was already the

   387 					null-pointer on entry to this function.

   388 	*/

   389 	static void MemoryDestroy(DMemoryObject*& aMemory);

   390 

   391 	/**

   392 	Allocate memory for a specified region within a memory object.

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

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

   395 	backing store.

   396 

   397 	This function acquires and releases the memory objects lock.

   398 	See MM::MemorySetLock.

   399 

   400 	Supported for memory object types:

   401 	- EMemoryObjectUnpaged

   402 	- EMemoryObjectMovable

   403 	- EMemoryObjectPaged

   404 	- EMemoryObjectDiscardable

   405 

   406 	@param aMemory	The memory object.

   407 	@param aIndex	Page index for start of the region.

   408 	@param aCount	Number of pages in the region.

   409 

   410 	@return KErrNone, if successful;

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

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

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

   414 			otherwise another of the system wide error codes.

   415 	*/

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

   417 

   418 	/**

   419 	Allocate memory for a specified region within a memory object.

   420 	The allocated memory will have contiguous physical addresses.

   421 

   422 	This function acquires and releases the memory objects lock.

   423 	See MM::MemorySetLock.

   424 

   425 	Important note, this function can unexpectedly fail with KErrAlreadyExists

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

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

   428 	use.

   429 

   430 	Supported for memory object types:

   431 	- EMemoryObjectUnpaged

   432 	- EMemoryObjectDiscardable

   433 

   434 	@param aMemory	The memory object.

   435 	@param aIndex	Page index for start of the region.

   436 	@param aCount	Number of pages in the region.

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

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

   439 

   440 	@return KErrNone, if successful;

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

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

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

   444 			otherwise another of the system wide error codes.

   445 	*/

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

   447 

   448 	/**

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

   450 	This is the inverse operation to MemoryAlloc and MemoryAllocContiguous.

   451 

   452 	This function acquires and releases the memory objects lock.

   453 	See MM::MemorySetLock.

   454 

   455 	Supported for memory object types:

   456 	- EMemoryObjectUnpaged

   457 	- EMemoryObjectMovable

   458 	- EMemoryObjectPaged

   459 	- EMemoryObjectDiscardable

   460 

   461 	@param aMemory	The memory object.

   462 	@param aIndex	Page index for start of the region.

   463 	@param aCount	Number of pages in the region.

   464 	*/

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

   466 

   467 	/**

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

   469 

   470 	This function acquires and releases the memory objects lock.

   471 	See MM::MemorySetLock.

   472 

   473 	Supported for memory object types:

   474 	- EMemoryObjectHardware

   475 

   476 	@param aMemory	The memory object.

   477 	@param aIndex	Page index for start of the region.

   478 	@param aCount	Number of pages in the region.

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

   480 					number of physical page addresses which are page aligned.

   481 

   482 	@return KErrNone, if successful;

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

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

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

   486 			otherwise another of the system wide error codes.

   487 	*/

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

   489 

   490 	/**

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

   492 

   493 	This function acquires and releases the memory objects lock.

   494 	See MM::MemorySetLock.

   495 

   496 	Supported for memory object types:

   497 	- EMemoryObjectHardware

   498 

   499 	@param aMemory		The memory object.

   500 	@param aIndex		Page index for start of the region.

   501 	@param aCount		Number of pages in the region.

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

   503 

   504 	@return KErrNone, if successful;

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

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

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

   508 			otherwise another of the system wide error codes.

   509 	*/

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

   511 

   512 	/**

   513 	Remove pages from a region in a memory object.

   514 

   515 	This is the inverse operation to MemoryAdd and MemoryAddContiguous.

   516 

   517 	This function acquires and releases the memory objects lock.

   518 	See MM::MemorySetLock.

   519 

   520 	Supported for memory object types:

   521 	- EMemoryObjectHardware

   522 

   523 	@param aMemory		The memory object.

   524 	@param aIndex		Page index for start of the region.

   525 	@param aCount		Number of pages in the region.

   526 	@param[out] aPages	Pointer to an array of physical addresses which has a

   527 						length of \a aCount. The contents of this will be set to

   528 						the addresses of the pages which were removed by this

   529 						function. The number of valid entries in this array is

   530 						given by the return value of this function.

   531 						aPages may be the null-pointer, to indicate that these

   532 						page addresses aren't required by the caller.

   533 

   534 	@return The number of pages successfully removed from the memory object.

   535 			This gives the number of valid entries in the array \a aPages and is

   536 			less-than or equal to \a aCount.

   537 	*/

   538 	static TUint MemoryRemovePages(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TPhysAddr* aPages);

   539 

   540 	/**

   541 	Mark a region in a memory object as discardable.

   542 

   543 	The system may remove discardable pages from the memory object at any time,

   544 	to be reused for other purposes.

   545 

   546 	This function acquires and releases the memory objects lock.

   547 	See MM::MemorySetLock.

   548 

   549 	Supported for memory object types:

   550 	- EMemoryObjectDiscardable

   551 

   552 	@see MemoryDisallowDiscard

   553 

   554 	@param aMemory	The memory object.

   555 	@param aIndex	Page index for start of the region.

   556 	@param aCount	Number of pages in the region.

   557 

   558 	@return KErrNone, if successful;

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

   560 			otherwise another of the system wide error codes.

   561 

   562 	*/

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

   564 

   565 	/**

   566 	Mark a region in a memory object as no longer discardable.

   567 	This undoes the operation of MemoryAllowDiscard.

   568 

   569 	If any pages in the region are no longer present, then the operation will

   570 	fail with KErrNotFound. In this case, the state of the pages in the region

   571 	is indeterminate; they may be either still discardable, not discardable, or

   572 	not present.

   573 

   574 	Supported for memory object types:

   575 	- EMemoryObjectDiscardable

   576 

   577 	@see MemoryAllowDiscard

   578 

   579 	@param aMemory	The memory object.

   580 	@param aIndex	Page index for start of the region.

   581 	@param aCount	Number of pages in the region.

   582 

   583 	@return KErrNone, if successful;

   584 			KErrNotFound, if any page in the region was no longer present;

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

   586 			otherwise another of the system wide error codes.

   587 	*/

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

   589 

   590 	/**

   591 	This function only exists to support DMemModelChunk::PhysicalAddress and may be removed.

   592 	DO NOT USE.

   593 	*/

   594 	static TInt MemoryPhysAddr(DMemoryObject* aMemory, TUint aIndex, TUint aCount, TPhysAddr& aPhysicalAddress, TPhysAddr* aPhysicalPageList);

   595 

   596 	/**

   597 	Prime BTrace for a memory object - internal use only.

   598 	*/

   599 	static void MemoryBTracePrime(DMemoryObject* aMemory);

   600 

   601 	/**

   602 	Close a memory object.

   603 

   604 	This should be called on the memory object returned by #MappingGetAndOpenMemory.

   605 	*/

   606 	static void MemoryClose(DMemoryObject* aMemory);

   607 

   608 	/**

   609 	Return true if aMemory has any mappings associated with it.

   610 	*/

   611 	static TBool MemoryIsNotMapped(DMemoryObject* aMemory);

   612 

   613 	/**

   614 	Wipe the entire memory contents of the memory object so they are in the

   615 	same state as if the memory had been newly allocated with #MemoryAlloc.

   616 

   617 	This is useful for situations where a memory object is being re-purposed and

   618 	confidentiality requires that the old memory contents are not disclosed.

   619 	For this reason, the function asserts that the memory object has no mappings.

   620 

   621 	@see EMemoryCreateUseCustomWipeByte

   622 	@see EMemoryCreateNoWipe

   623 

   624 	@return KErrNone, if successful;

   625 			otherwise KErrNotSupported, to indicate the memory object doesn't support this operation.

   626 	*/

   627 	static TInt MemoryWipe(DMemoryObject* aMemory);

   628 

   629 	/**

   630 	Set the memory object to be read only, i.e. to no longer allow writable mappings.

   631 

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

   633 	writable again.

   634 

   635 	@param aMemory	The memory object to update.

   636 	@return KErrNone on success, KErrInUse if the memory object has writable mappings

   637 			KErrNotSupported if the objects manager doesn't support this.

   638 	*/

   639 	static TInt MemorySetReadOnly(DMemoryObject* aMemory);

   640 

   641 	/**

   642 	Pins physical memory associated with the memory object and returns the physical

   643 	memory characteristics, e.g. address, map attributes and colour

   644 

   645 	@param aMemory	        The memory object.

   646 	@param aPinObject	    The physical pin mapping.

   647 	@param aIndex	        Page index for start of the region.

   648 	@param aCount   	    Number of pages in the region.

   649 	@param aReadOnly   	    Indicates whether memory should be pinned as read only.

   650 	@param aAddress[out]	The value is the physical address of the first page

   651 						    in the region.

   652 	@param aPages[out]      If not zero, this points to an array of TPhysAddr

   653 	                        objects. On success, this array will be filled

   654 						    with the addresses of the physical pages which

   655 						    contain the specified region. If aPages is

   656 						    zero, then the function will fail with

   657 						    KErrNotFound if the specified region is not

   658 						    physically contiguous.

   659 	@param aMapAttr[out]    Memory attributes defined by TMappingAttributes2.

   660 	@param aColour[out]     The mapping colour of the first physical page.

   661 

   662 

   663 	@return The number of pages successfully removed from the memory object.

   664 			This gives the number of entries in the array aPages and is

   665 			less-than or equal to aCount.

   666 	*/

   667 

   668 	static TInt PinPhysicalMemory(DMemoryObject* aMemory, DPhysicalPinMapping* aPinObject, TUint aIndex,

   669 								  TUint aCount, TBool aReadOnly, TPhysAddr& aAddress, TPhysAddr* aPages,

   670 								  TUint32& aMapAttr, TUint& aColour);

   671 

   672 	//

   673 	// Memory Mapping functions

   674 	//

   675 

   676 	/**

   677 	Create a new memory mapping for a specific memory object.

   678 

   679 	A memory mapping represents the MMU resources required to make a region of a

   680 	memory object accessible to software within a single address space (process).

   681 	Each mapping has an associated set of access permissions (see

   682 	#TMappingPermissions).

   683 

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

   685 						of the created memory mapping.

   686 	@param aMemory		The memory object with which the mapping is associated.

   687 	@param aPermissions	Bitmask of values from enum #TMappingPermissions which

   688 						give the access permissions for this mapping.

   689 	@param aOsAsid		The identifier for the address space in which this

   690 						mapping is to appear.

   691 	@param aFlags		Bitmask of option flags from enum #TMappingCreateFlags

   692 	@param aAddr		Optional virtual address at which the memory mapped

   693 						by this mapping is to appear within the specified

   694 						address space.

   695 	@param aIndex		Optional start page index within \a aMemory for this

   696 						mapping.

   697 	@param aCount		Optional page count for size of mapping. A value of

   698 						the maximum integer indicates that the mapping is to

   699 						extend to the end of the memory object.

   700 

   701 	@return KErrNone, if successful;

   702 			otherwise another of the system wide error codes.

   703 	*/

   704 	static TInt MappingNew(DMemoryMapping*& aMapping, DMemoryObject* aMemory, TMappingPermissions aPermissions, TInt aOsAsid, TMappingCreateFlags aFlags=EMappingCreateDefault, TLinAddr aAddr=0, TUint aIndex=0, TUint aCount=~0u);

   705 

   706 	/**

   707 	Create a new memory mapping with is not associated with any memory object.

   708 

   709 	This mapping may be used and reused with different memory objects by using

   710 	the #MappingMap and #MappingUnmap methods.

   711 

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

   713 							of the created memory mapping.

   714 	@param aCount			Page count for size of mapping.

   715 	@param aOsAsid			The identifier for the address space in which this

   716 							mapping is to appear.

   717 	@param aFlags			Bitmask of option flags from enum #TMappingCreateFlags

   718 	@param aAddr			Optional virtual address at which the mapping is to

   719 							appear within the specified address space.

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

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

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

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

   724 							is specified.

   725 

   726 	@return KErrNone, if successful;

   727 			otherwise another of the system wide error codes.

   728 	*/

   729 	static TInt MappingNew(DMemoryMapping*& aMapping, TUint aCount, TInt aOsAsid, TMappingCreateFlags aFlags=EMappingCreateDefault, TLinAddr aAddr=0, TLinAddr aColourOffset=~0);

   730 

   731 	/**

   732 	Apply a memory mapping to a memory object.

   733 

   734 	@param aMapping		The memory mapping to be used to map \a aMemory.

   735 	@param aPermissions	Bitmask of values from enum #TMappingPermissions which

   736 						give the access permissions for this mapping.

   737 	@param aMemory		The memory object with which the mapping is to be associated.

   738 	@param aIndex		Optional start page index within aMemory for this

   739 						mapping.

   740 	@param aCount		Optional page count for size of mapping. A value of

   741 						the maximum integer indicates that the mapping is to

   742 						extend to the end of the memory object.

   743 

   744 	@return KErrNone, if successful;

   745 			otherwise another of the system wide error codes.

   746 	*/

   747 	static TInt MappingMap(DMemoryMapping* aMapping, TMappingPermissions aPermissions, DMemoryObject* aMemory, TUint aIndex=0, TUint aCount=~0u);

   748 

   749 	/**

   750 	Remove a mapping from the memory object with which it is associated.

   751 	*/

   752 	static void MappingUnmap(DMemoryMapping* aMapping);

   753 

   754 	/**

   755 	Remove a memory mapping from its associated address space and close a

   756 	reference on it.

   757 

   758 	If there are no longer any other references, this will result in the memory

   759 	object being destroyed,

   760 

   761 	@param aMapping	Pointer reference to memory mapping to be destroyed.

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

   763 					No action is performed if the reference was already the

   764 					null-pointer on entry to this function.

   765 	*/

   766 	static void MappingDestroy(DMemoryMapping*& aMapping);

   767 

   768 	/**

   769 	Remove a memory mapping from its associated address space and close a

   770 	reference on it.

   771 

   772 	The mapping is found based on the virtual address region within which it

   773 	maps memory. The caller must that such a mapping exists and that it will not

   774 	be unmapped by another thread.

   775 

   776 	@param aAddr	Virtual address which lies within the region covered by the

   777 					memory mapping.

   778 	@param aOsAsid	Address space in which the mapping appears.

   779 	*/

   780 	static void MappingDestroy(TLinAddr aAddr, TInt aOsAsid);

   781 

   782 	/**

   783 	Perform the action of #MappingDestroy on a memory mapping then #MemoryDestroy

   784 	on its associated memory object.

   785 

   786 	This function acquires and releases the memory objects lock.

   787 	See MM::MemorySetLock.

   788 

   789 	NOTE - This should not be used on mappings that are reused as the mapping's 

   790 	instance count is not checked.

   791 

   792 	@param aMapping	Pointer reference to memory mapping to be destroyed.

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

   794 					No action is performed if the reference was already the

   795 					null-pointer on entry to this function.

   796 	*/

   797 	static void MappingAndMemoryDestroy(DMemoryMapping*& aMapping);

   798 

   799 	/**

   800 	Perform the action of #MappingDestroy on a memory mapping then #MemoryDestroy

   801 	on its associated memory object.

   802 

   803 	The mapping is found based on the virtual address region within which it

   804 	maps memory. The caller must that such a mapping exists and that it will not

   805 	be unmapped by another thread.

   806 

   807 	This function acquires and releases the memory objects lock.

   808 	See MM::MemorySetLock.

   809 

   810 	NOTE - This should not be used on mappings that are reused as the mapping's 

   811 	instance count is not checked.

   812 

   813 	@param aAddr	Virtual address which lies within the region covered by the

   814 					memory mapping.

   815 	@param aOsAsid	Address space in which the mapping appears.

   816 	*/

   817 	static void MappingAndMemoryDestroy(TLinAddr aAddr, TInt aOsAsid);

   818 

   819 	/**

   820 	Return the virtual address at which the memory mapped by a memory mapping

   821 	starts.

   822 

   823 	@param aMapping	A memory mapping.

   824 

   825 	@return The base address.

   826 	*/

   827 	static TLinAddr MappingBase(DMemoryMapping* aMapping);

   828 

   829 	/**

   830 	Return the OS Address Space ID (OS ASID) of the address space the mapping is within.

   831 

   832 	@param aMapping	A memory mapping.

   833 

   834 	@return OS Address Space ID (OS ASID).

   835 	*/

   836 	static TInt MappingOsAsid(DMemoryMapping* aMapping);

   837 

   838 	/**

   839 	Open the memory object mapped by a mapping and return it.

   840 

   841 	The memory object can be closed again by calling #MemoryClose.

   842 

   843 	NOTE - This should not be used on mappings that are reused as the mapping's 

   844 	instance count is not checked.

   845 

   846 	@param aMapping			A memory mapping.

   847 

   848 	@return The memory object, or NULL.

   849 	*/

   850 	static DMemoryObject* MappingGetAndOpenMemory(DMemoryMapping* aMapping);

   851 

   852 	/**

   853 	Close a mapping

   854 

   855 	@param aMapping	A memory mapping.

   856 	*/

   857 	static void MappingClose(DMemoryMapping* aMapping);

   858 

   859 	/**

   860 	Find and open the mapping that maps a virtual address in the address space of the specified

   861 	thread.

   862 

   863 	The caller must close the mapping when it has finished using it.

   864 

   865 	@param aThread The thread whose address space is to be searched.

   866 	@param aAddr The virtual address for which the mapping is to be found.

   867 	@param aSize The size, in bytes, of the region at aAddr.

   868 	@param aOffsetInMapping A reference which is set to the offset, in bytes, into the

   869 							mapping of the start address.

   870 	@param aInstanceCount	The instance count of the found mapping.

   871 

   872 	@return The mapping, or NULL if no mapping was found.

   873 

   874 	@pre Calling thread must be in a critical section.

   875 	*/

   876 	static DMemoryMapping* FindMappingInThread(	DMemModelThread* aThread, TLinAddr aAddr, TUint aSize, 

   877 												TUint& aOffsetInMapping, TUint& aInstanceCount);

   878 

   879 	/**

   880 	Find and open the mapping that maps a virtual address in the address space of the specified

   881 	process.

   882 

   883 	The caller must close the mapping when it has finished using it.  The caller must ensure that

   884 	the process can't be destroyed while calling this method.

   885 

   886 	@param aOsAsid The identifier for the address space in which the mapping appears.

   887 	@param aAddr The virtual address for which the mapping is to be found.

   888 	@param aSize The size, in bytes, of the region at aAddr.

   889 	@param aOffsetInMapping A reference which is set to the offset, in bytes, into the

   890 							mapping of the start address.

   891 	@param aInstanceCount	The instance count of the found mapping.

   892 

   893 	@return The mapping, or NULL if no mapping was found.

   894 

   895 	@pre Calling thread must be in a critical section.

   896 	*/

   897 	static DMemoryMapping* FindMappingInAddressSpace(	TUint aOsAsid, TLinAddr aAddr, TUint aSize, 

   898 														TUint& aOffsetInMapping, TUint& aInstanceCount);

   899 

   900 

   901 	//

   902 	// Conversion utilities

   903 	//

   904 

   905 	/**

   906 	Round a size in bytes up to the next integer multiple of the page size.

   907 

   908 	@param aSize A size in bytes.

   909 

   910 	@return The rounded size.

   911 	*/

   912 	static TUint RoundToPageSize(TUint aSize);

   913 

   914 	/**

   915 	Round a size in bytes up to the next integer multiple of the page size

   916 	then convert it into a page count by dividing it by the page size.

   917 

   918 	@param aSize A size in bytes.

   919 

   920 	@return The rounded page count.

   921 	*/

   922 	static TUint RoundToPageCount(TUint aSize);

   923 

   924 	/**

   925 	Round a bit shift value representing the log2 of a size in bytes, up to

   926 	a shift value representing the log2 of a size in pages.

   927 

   928 	@param aShift log2 of a size in bytes.

   929 

   930 	@return aShift-KPageShift, or zero if aShift<=KPageShift.

   931 	*/

   932 	static TUint RoundToPageShift(TUint aShift);

   933 

   934 	/**

   935 	Convert a size in bytes to a size in pages.

   936 

   937 	@param aBytes A size in bytes.

   938 

   939 	@return aBytes/KPageSize.

   940 

   941 	@panic MemModel #EBadBytesToPages if aBytes is not an integer multiple of

   942 		   the page size.

   943 	*/

   944 	static TUint BytesToPages(TUint aBytes);

   945 

   946 	/**

   947 	Construct a #TMappingPermissions value base on individual permission flags.

   948 

   949 	@param aUser	True to allow unprivileged (user mode) access.

   950 	@param aWrite	True to allow memory contents to be modified.

   951 	@param aExecute	True to allow memory contents to be executed as code.

   952 

   953 	@return Permissions expressed as an #TMappingPermissions value.

   954 	*/

   955 	static TMappingPermissions MappingPermissions(TBool aUser, TBool aWrite, TBool aExecute);

   956 

   957 	/**

   958 	Extract the mapping permissions from a TMappingAttributes2

   959 	(or TMappingAttributes) value.

   960 

   961 	@param[out] aPermissions	If successful, mapping permissions extracted from aLegacyAttributes.

   962 	@param aLegacyAttributes	A legacy combined permission/attribute value.

   963 

   964 	@return KErrNone, if successful;

   965 			otherwise another of the system wide error codes.

   966 	*/

   967 	static TInt MappingPermissions(TMappingPermissions& aPermissions, TMappingAttributes2 aLegacyAttributes);

   968 

   969 	/**

   970 	Extract the memory attributes from a TMappingAttributes2

   971 	(or TMappingAttributes) value.

   972 

   973 	@param[out] aAttributes		If successful, memory attributes extracted from \a aLegacyAttributes.

   974 	@param aLegacyAttributes	A legacy combined permission/attribute value.

   975 

   976 	@return KErrNone, if successful;

   977 			otherwise another of the system wide error codes.

   978 	*/

   979 	static TInt MemoryAttributes(TMemoryAttributes& aAttributes, TMappingAttributes2 aLegacyAttributes);

   980 

   981 	/**

   982 	Construct a legacy combined permission/memory-type value based on a

   983 	#TMemoryAttributes and #TMappingPermissions value.

   984 

   985 	@param aAttributes	A memory attributes value.

   986 	@param aPermissions	A mapping permissions value.

   987 

   988 	@return A TMappingAttributes2 value combining \a aAttributes and \a aPermissions.

   989 	*/

   990 	static TMappingAttributes2 LegacyMappingAttributes(TMemoryAttributes aAttributes, TMappingPermissions aPermissions);

   991 

   992 	//

   993 	// Code paging

   994 	//

   995 

   996 	/**

   997 	Create a new memory object which will contain demand paged code.

   998 

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

  1000 						of the created memory object.

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

  1002 	@param aInfo		Pointer reference which on success it set to a #TPagedCodeInfo

  1003 						object which should be initialised with information required

  1004 						for demand paging the code. (Call #PagedCodeLoaded when this is done.)

  1005 

  1006 	@return KErrNone, if successful;

  1007 			otherwise another of the system wide error codes.

  1008 	*/

  1009 	static TInt PagedCodeNew(DMemoryObject*& aMemory, TUint aPageCount, TPagedCodeInfo*& aInfo);

  1010 

  1011 	/**

  1012 	Call this to indicate that a memory object created with #PagedCodeNew has had its

  1013 	#TPagedCodeInfo object initialised.

  1014 

  1015 	@param aMemory		The memory object.

  1016 	@param aLoadAddress	An address at which \a aMemory is mapped with write permissions.

  1017 	*/

  1018 	static void PagedCodeLoaded(DMemoryObject* aMemory, TLinAddr aLoadAddress);

  1019 

  1020 	//

  1021 	// Misc

  1022 	//

  1023 

  1024 	// Initialisation...

  1025 	static void Init1();

  1026 	static void Init2();

  1027 	static void Init3();

  1028 	static TInt InitFixedKernelMemory(DMemoryObject*& aMemory, TLinAddr aStart, TLinAddr aEnd, TUint aInitSize, TMemoryObjectType aType, TMemoryCreateFlags aMemoryCreateFlags, TMemoryAttributes aMemoryAttributes, TMappingCreateFlags aMappingCreateFlags);

  1029 	static TInt MemoryClaimInitialPages(DMemoryObject* aMemory, TLinAddr aBase, TUint aSize, TMappingPermissions aPermissions, TBool aAllowGaps=false, TBool aAllowNonRamPages=false);

  1030 

  1031 	// IPC helpers...

  1032 	static void ValidateLocalIpcAddress(TLinAddr aAddr, TUint aSize, TBool aWrite);

  1033 #ifndef __SMP__

  1034 	static void IpcAliasPde(TPde*& aPdePtr, TUint aOsAsid);

  1035 #endif

  1036 	static void UserPermissionFault(TLinAddr aAddr, TBool aWrite);

  1037 

  1038 	// Address space...

  1039 	static TInt AddressSpaceAlloc(TPhysAddr& aPageDirectory);

  1040 	static void AddressSpaceFree(TUint aOsAsid);

  1041 	static void AsyncAddressSpaceFree(TUint aOsAsid);

  1042 	static TInt VirtualAllocCommon(TLinAddr& aLinAddr, TUint aSize, TBool aDemandPaged);

  1043 	static void VirtualFreeCommon(TLinAddr aLinAddr, TUint aSize);

  1044 	static TInt VirtualAlloc(TInt aOsAsid, TLinAddr& aLinAddr, TUint aSize, TBool aDemandPaged);

  1045 	static void VirtualFree(TInt aOsAsid, TLinAddr aLinAddr, TUint aSize);

  1046 

  1047 	/**

  1048 	Enumeration of panic values for category "MemModel".

  1049 	*/

  1050 	enum TMemModelPanic

  1051 		{

  1052 		EFsRegisterThread,

  1053 		EProcessDestructChunksRemaining,

  1054 		ECommitInvalidDllDataAddress,

  1055 		ECodeSegLoadedNotCreator,

  1056 		ETempMappingAlreadyInUse,

  1057 		EUnsupportedOperation,

  1058 		EBadBytesToPages,

  1059 		ECodeSegSetReadOnlyFailure,

  1060 		EProcessDestructOsAsidRemaining,

  1061 		};

  1062 	static void Panic(TMemModelPanic aPanic);

  1063 	};

  1064 

  1065 

  1066 

  1067 template <class T>

  1068 FORCE_INLINE void FlagSet(T& a,const T b)

  1069 	{ a = (T)(a|b); }

  1070 

  1071 template <class T>

  1072 FORCE_INLINE void FlagSet(T& a,const T b,const T c)

  1073 	{ a = (T)(a|b|c); }

  1074 

  1075 template <class T>

  1076 FORCE_INLINE void FlagSet(T& a,const T b,const T c,const T d)

  1077 	{ a = (T)(a|b|c|d); }

  1078 

  1079 template <class T>

  1080 FORCE_INLINE void FlagClear(T& a,const T b)

  1081 	{ a = (T)(a&~b); }

  1082 

  1083 template <class T>

  1084 FORCE_INLINE void FlagClear(T& a,const T b,const T c)

  1085 	{ a = (T)(a&~b&~c); }

  1086 

  1087 template <class T>

  1088 FORCE_INLINE void FlagClear(T& a,const T b,const T c,const T d)

  1089 	{ a = (T)(a&~b&~c&~d); }

  1090 

  1091 

  1092 #include <memmodel/epoc/mmubase/kblockmap.h>

  1093 

  1094 /**

  1095 Structure containing the information about a demand paged code segment

  1096 which is required to load and fixup its code section.

  1097 */

  1098 class TPagedCodeInfo

  1099 	{

  1100 public:

  1101 	~TPagedCodeInfo();

  1102 	TInt ReadBlockMap(const TCodeSegCreateInfo& aInfo);

  1103 	TInt ReadFixupTables(const TCodeSegCreateInfo& aInfo);

  1104 	void ApplyFixups(TLinAddr aBuffer, TUint iIndex);

  1105 public:

  1106 	TBool iLoaded;						///< True once initial loading has finished and paging should start applying fixups.

  1107 	TUint iCodeRelocTableSize;			///< Size, in bytes, of #iCodeRelocTable.

  1108 	TUint8* iCodeRelocTable;			///< Code relocation information.

  1109 	TUint iImportFixupTableSize;		///< Size, in bytes, of #iImportFixupTable.

  1110 	TUint8* iImportFixupTable;			///< Import fixup information.

  1111 	TUint32 iCodeDelta;					///< Delta to apply to relocate words referring to the code section.

  1112 	TUint32 iDataDelta;					///< Delta to apply to relocate words referring to the data section.

  1113 

  1114 	TUint iCodeSize;					///< Size, in bytes, of the code section.

  1115 	TUint32 iCompressionType;			///< Compression scheme in use, (KUidCompressionBytePair or KFormatNotCompressed).

  1116 	TInt32* iCodePageOffsets;			///< Array of compressed page offsets within the file.

  1117 	TInt iCodeLocalDrive;				///< Local drive number.

  1118 	TInt iCodeStartInFile;				///< Offset of (possibly compressed) code from start of file.

  1119 	TBlockMap iBlockMap;				///< Kernel-side representation of block map.

  1120 	};

  1121 

  1122 

  1123 

  1124 /**

  1125 A pool of DMutex objects that can be dynamically assigned for use.

  1126 

  1127 This is intended as a memory saving alternative to having each object in a class of objects

  1128 owning their own mutex for locking purposes and provides a concurrency improvement over using

  1129 a single global lock.

  1130 */

  1131 class DMutexPool : public DBase

  1132 	{

  1133 public:

  1134 	/**