1 // Copyright (c) 1998-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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // e32\include\memmodel\epoc\platform.h
15 // Public header file for device drivers
17 // WARNING: This file contains some APIs which are internal and are subject
18 // to change without notice. Such APIs should therefore not be used
19 // outside the Kernel and Hardware Services package.
24 #include <kernel/kernel.h>
25 #include <kernel/kernboot.h>
30 class TRomImageHeader;
35 /********************************************
36 * Hardware chunk abstraction
37 ********************************************/
40 The list of memory types (aka cache attributes) in Kernel on ARMv6K, ARMv7 and later platforms.
41 Types 0-3 can be used on all platforms. Types 4-7 can be used only on the platforms with memory type remapping.
42 @see TMappingAttributes2
48 EMemAttStronglyOrdered = 0, /**< Strongly Ordered memory.*/
49 EMemAttDevice = 1, /**< Device memory.*/
50 EMemAttNormalUncached = 2, /**< Uncached Normal memory. Writes may combine.*/
51 EMemAttNormalCached = 3, /**< Fully cached (Write-Back, Read/Write Allocate, Normal memory).*/
52 EMemAttKernelInternal4 = 4, /**< @internalComponent. Not to be used by device drivers.*/
53 EMemAttPlatformSpecific5= 5, /**< Defined by Baseport - H/W independent.*/
54 EMemAttPlatformSpecific6= 6, /**< Defined by Baseport - H/W specific - see ARM core's document for the details.*/
55 EMemAttPlatformSpecific7= 7 /**< Defined by Baseport - H/W independent.*/
58 const TUint KMemoryTypeShift = 3; /**< @internalComponent. The number of bits in a TMemoryType value.*/
59 const TUint KMemoryTypeMask = (1<<KMemoryTypeShift)-1; /**< @internalComponent. Mask value for extracting a TMemoryType value from a bitfield.*/
62 Memory mapping permissions and attributes.
65 @see Kern::ChunkCreate
66 @see DSharedIoBuffer::New
67 @see DPlatChunkHw::New
68 @see Kern::ChunkPhysicalAddress
69 @see Cache::SyncMemoryBeforeDmaWrite
70 @see Cache::SyncMemoryBeforeDmaRead
71 @see Cache::SyncMemoryBeforeDmaWrite
76 enum TMappingAttributes
78 // access permissions for read
79 EMapAttrReadNoone=0x0, /**< Sets the memory as not readable in any mode */
80 EMapAttrReadSup=0x1, /**< Sets the memory as readable only from Kernel (Supervisor) mode */
81 EMapAttrReadUser=0x4, /**< Sets the memory as readable for user, hence it can be read in both user and supervisor mode*/
82 EMapAttrReadMask=0xF, /**< Used for masking read attributes*/
84 // access permissions for write
85 EMapAttrWriteNoone=0x00, /**< Sets the memory as not writable in any mode */
86 EMapAttrWriteSup=0x10, /**< Sets the memory as writable only from Kernel (Supervisor) mode */
87 EMapAttrWriteUser=0x40, /**< Sets the memory as writable for user, hence it can be written in both user and supervisor mode*/
88 EMapAttrWriteMask=0xF0, /**< Used for masking write attributes*/
90 // access permissions for execute
91 EMapAttrExecNoone=0x000, /**< Sets the memory as not executable in any mode */
92 EMapAttrExecSup=0x100, /**< Sets the memory as executable only from Kernel (Supervisor) mode */
93 EMapAttrExecUser=0x400, /**< Sets the memory as executable for user, hence it can be executed in both user and supervisor mode*/
94 EMapAttrExecMask=0xF00, /**< Used for masking execute attributes*/
96 // access permissions - popular combinations
97 EMapAttrSupRo=0x01, /**< Supervisor has read only and user has no access permissions*/
98 EMapAttrSupRw=0x11, /**< Supervisor has read/write and user has no access permissions*/
99 EMapAttrSupRwx=0x111, /**< Supervisor has read/write/execute and user has no access permissions*/
100 EMapAttrUserRo=0x14, /**< Supervisor has read/write and user has read only permissions*/
101 EMapAttrUserRw=0x44, /**< Supervisor and user both have read/write permissions*/
102 EMapAttrUserRwx=0x444, /**< Supervisor and user both have read/write/execute permissions*/
103 EMapAttrAccessMask=0xFFF, /**< Used for masking access permissions attribute for popular combination */
105 // Level 1 cache/buffer attributes
106 EMapAttrFullyBlocking=0x0000, /**< Level 1 cache/buffer attributes sets the memory as uncached, unbuffered (may not be L2 cached)*/
107 EMapAttrBufferedNC=0x1000, /**< Level 1 cache/buffer attributes sets the memory as uncached, buffered, writes do not coalesce (may not be L2 cached)*/
108 EMapAttrBufferedC=0x2000, /**< Level 1 cache/buffer attributes sets the memory as uncached, buffered, writes may coalesce (may not be L2 cached)*/
109 EMapAttrL1Uncached=0x3000, /**< Level 1 cache/buffer attributes sets the memory as uncached, buffered, writes may coalesce (may be L2 cached)*/
110 EMapAttrCachedWTRA=0x4000, /**< Level 1 cache/buffer attributes sets the memory as write-through cached, read allocate*/
111 EMapAttrCachedWTWA=0x5000, /**< Level 1 cache/buffer attributes sets the memory as write-through cached, read/write allocate*/
112 EMapAttrCachedWBRA=0x6000, /**< Level 1 cache/buffer attributes sets the memory as write-back cached, read allocate*/
113 EMapAttrCachedWBWA=0x7000, /**< Level 1 cache/buffer attributes sets memory as write-back cached, read/write allocate*/
114 EMapAttrAltCacheWTRA=0x8000, /**< Level 1 cache/buffer attributes sets memory as write-through cached, read allocate, use alternate cache*/
115 EMapAttrAltCacheWTWA=0x9000, /**< Level 1 cache/buffer attributes sets memory as write-through cached, read/write allocate, use alternate cache*/
116 EMapAttrAltCacheWBRA=0xA000, /**< Level 1 cache/buffer attributes sets memory as write-back cached, read allocate, use alternate cache*/
117 EMapAttrAltCacheWBWA=0xB000, /**< Level 1 cache/buffer attributes write-back cached, read/write allocate, use alternate cache*/
118 EMapAttrL1CachedMax=0xF000, /**< Used to make memory maximally cached in L1 cache*/
119 EMapAttrL1CacheMask=0xF000, /**< Used for masking L1 cache attributes*/
121 // Level 2 cache attributes
122 EMapAttrL2Uncached=0x00000, /**< Level 2 cache attributes used to set memory as uncached at level 2 */
123 EMapAttrL2CachedWTRA=0x40000, /**< Level 2 cache attributes sets memory as write-through cached, read allocate*/
124 EMapAttrL2CachedWTWA=0x50000, /**< Level 2 cache attributes sets memory as write-through cached, read/write allocate*/
125 EMapAttrL2CachedWBRA=0x60000, /**< Level 2 cache attributes sets memory as write-back cached, read allocate*/
126 EMapAttrL2CachedWBWA=0x70000, /**< Level 2 cache attributes sets memory as write-back cached, read/write allocate*/
127 EMapAttrL2CachedMax=0xF0000, /**< Used to make memory maximally cached in L2 cache*/
128 EMapAttrL2CacheMask=0xF0000, /**< Used for masking L2 cache attributes*/
131 EMapAttrCachedMax=0xFF000, /**< Used to set memory as maximally cached for system (fully cached in L1&L2 cache)*/
132 EMapAttrShared=0x100000, /**< Used to set the memory as shared with other processors*/
133 EMapAttrUseECC=0x200000, /**< Used for error correcting code*/
137 Container class for memory region's attributes.
138 It is intended for ARM platforms with memory type and access permission remapping
139 (arm11mpcore, arm1176, cortex_a8 and later), but could be used on any previous platform as well.
141 The object of this type can replace TMappingAttributes bit mask whereever it is in use. For example:
143 TChunkCreateInfo chunkInfo;
145 new (&chunkInfo.iMapAttr) TMappingAttributes2(EMemAttStronglyOrdered,EFalse,ETrue);
146 r = Kern::ChunkCreate(chunkInfo, ...);
150 @see TMappingAttributes
151 @see TChunkCreateInfo
152 @see Kern::ChunkCreate
153 @see DSharedIoBuffer::New
154 @see DPlatChunkHw::New
155 @see Kern::ChunkPhysicalAddress
156 @see Cache::SyncMemoryBeforeDmaWrite
157 @see Cache::SyncMemoryBeforeDmaRead
158 @see Cache::SyncMemoryBeforeDmaWrite
163 class TMappingAttributes2
168 Memory is always readable by Kernel. Other attributes are defined by input parameters, as follows:
169 @param aType Type (aka cache attributes) of the memory.
170 @param aUserAccess True if memory is also accessed from user code, false if it is only accessible from kernel.
171 @param aWritable True if memory is writable, false if this is read only memory.
172 @param aExecutable True if memory contains code or data, false if it only contains data.
173 Default argument value is false.
174 @param aShared Shared attribute of the mapping:
175 <0 Default value for the platform, e.g. Shareable for SMP, Unshareable for uni-processor.
176 ==0 Unshareable memory
178 To ensure future compatibility, use the value <0 except when absolutely neccessary.
179 Default argument value is -1.
180 @param aParity Parity error attribute of the mapping:
181 <0 Default value for the platform (which is off on all platforms so far).
182 ==0 Parity error doesn't generate external abort.
183 >0 Parity error generates external abort.
184 To ensure future compatibility, use the value <0 except when absolutely neccessary.
185 Default argument value is -1.
189 IMPORT_C TMappingAttributes2(TMemoryType aType ,
192 TBool aExecutable = EFalse,
196 TMappingAttributes2(TUint aMapAttr);/**< @internalComponent*/
197 TMemoryType Type(); /**< @internalComponent @return Type of the memory (aka cache attributes).*/
198 TBool UserAccess(); /**< @internalComponent @return True if memory can be accessed from user code.*/
199 TBool Writable(); /**< @internalComponent @return True if memory can be written into, false if this is reaad only memory.*/
200 TBool Executable(); /**< @internalComponent @return True if memory can contain code and data, false if it can only contain data.*/
201 TBool Shared(); /**< @internalComponent @return True if memory is shared, false if not.*/
202 TBool Parity(); /**< @internalComponent @return True if parity error generates external abort, false if not.*/
203 TBool ObjectType2();/**< @internalComponent @return True if the object is TMappingAttributes2, false if it is TMappingAttributes bitmask.*/
205 static void Panic(TInt aPanic); /**< @internalComponent*/
207 TUint32 iAttributes; /**< @internalComponent*/
213 inline TBool ComparePermissions(TInt aActual, TInt aRequired)
215 return ((aActual&EMapAttrReadMask)>=(aRequired&EMapAttrReadMask)) &&
216 ((aActual&EMapAttrWriteMask)>=(aRequired&EMapAttrWriteMask)) &&
217 ((aActual&EMapAttrExecMask)>=(aRequired&EMapAttrExecMask));
221 /** Hardware Chunk class
222 Class representing a global mapping of I/O or global memory buffers
227 class DPlatChunkHw : public DObject
230 IMPORT_C static TInt New(DPlatChunkHw*& aChunk, TPhysAddr anAddr, TInt aSize, TUint aAttribs);
231 inline TLinAddr LinearAddress() {return iLinAddr;}
232 inline TPhysAddr PhysicalAddress() {return iPhysAddr;}
234 /** @internalComponent */
235 static TInt DoNew(DPlatChunkHw*& aChunk, TPhysAddr anAddr, TInt aSize, TUint aAttribs);
237 TPhysAddr iPhysAddr; /**< @internalComponent */
238 TLinAddr iLinAddr; /**< @internalComponent */
239 TInt iSize; /**< @internalComponent */
240 TUint iAttribs; /**< @internalComponent */ // mapping attributes
243 /********************************************
244 * Exports from layer 2 or below of the kernel
245 * which are not available to layer 1
246 ********************************************/
249 Specifies the operation performed by the TRamZoneCallback function.
250 @see TRamZoneCallback
256 /** Informs the variant that a specified RAM zone is not currently
257 being used and therefore it may be possible to save power by not refreshing
258 this zone or, if the rest of the its RAM IC's zones are also empty, powering
261 The TRamZoneCallback parameter aParam1 is the ID of the zone.
262 The TRamZoneCallback parameter aParam2 is a pointer to const array of TUints
263 that are the bit masks of the zones' power status.
265 ERamZoneOp_PowerDown=0,
267 /** Informs the variant that a specified RAM zone is now required for use
268 and therefore it must be ready.
269 The variant should ensure the zone is refreshed, if required, and that the
270 RAM IC is powered and fully initialised.
272 The TRamZoneCallback parameter aParam1 is the ID of the zone.
273 The TRamZoneCallback parameter aParam2 is a pointer to const array of TUints
274 that are the bit masks of the zones' power status.
276 ERamZoneOp_PowerUp=1,
278 /** Operation that informs the variant of the RAM zones that have been used
279 during the initial stages of the boot process. Any RAM zones that are not
280 in use may be powered down or not refreshed to save power.
281 This will be the first operation requested of the variant and it is only
284 The TRamZoneCallback parameter aParam1 is unused by this operation.
285 The TRamZoneCallback parameter aParam2 is a pointer to const array of TUints
286 that are the bit masks of the zones' power status.
293 Call back function that is invoked by the kernel when its RAM allocator determines
294 that an operation can be performed on a particular RAM zone.
299 @param aOp Type of operation to perform; a value of TRamZoneOp
300 @param aParam1 A value whose use is defined by the TRamZoneOp to be performed
301 @param aParam2 A value whose use is defined by the TRamZoneOp to be performed
302 The data pointed to by aParam2 is const and therefore should not be modified
304 @return KErrNone if successful, otherwise one of the system wide error codes
308 typedef TInt (*TRamZoneCallback) (TRamZoneOp aOp, TAny* aParam1, const TAny* aParam2);
311 Holds the number of each page type within a RAM zone.
313 @see Epoc::GetRamZonePageCount()
318 struct SRamZonePageCount
320 TUint iFreePages; /**< The number of free pages in the RAM zone*/
321 TUint iUnknownPages; /**< The number of unknown pages in the RAM zone*/
322 TUint iFixedPages; /**< The number of fixed pages in the RAM zone*/
323 TUint iMovablePages; /**< The number of movable pages in the RAM zone*/
324 TUint iDiscardablePages;/**< The number of discardable pages in the RAM zone*/
325 TUint iReserved[4]; /**<@internalComponent reserved for internal use only*/
336 The types of RAM defragmentation operations.
341 ERamDefrag_DefragRam,
342 ERamDefrag_EmptyRamZone,
343 ERamDefrag_ClaimRamZone,
347 The type of page to move with Epoc::MovePhysicalPage().
350 enum TRamDefragPageToMove
353 Move the physical page aOld.
355 ERamDefragPage_Physical,
357 Move the page table page that maps the linear address in the
358 current thread at aOld.
360 ERamDefragPage_PageTable,
362 Move the page table info page of the page table that maps the linear
363 address in the current thread at aOld.
365 ERamDefragPage_PageTableInfo,
369 IMPORT_C static void SetMonitorEntryPoint(TDfcFn aFunction); /**< @internalComponent */
370 IMPORT_C static void SetMonitorExceptionHandler(TLinAddr aHandler); /**< @internalComponent */
371 IMPORT_C static TAny* ExceptionInfo(); /**< @internalComponent */
372 IMPORT_C static const TRomHeader& RomHeader();
373 IMPORT_C static TInt AllocShadowPage(TLinAddr aRomAddr);
374 IMPORT_C static TInt CopyToShadowMemory(TLinAddr aDest, TLinAddr aSrc, TUint32 aLength);
375 IMPORT_C static TInt FreeShadowPage(TLinAddr aRomAddr);
376 IMPORT_C static TInt FreezeShadowPage(TLinAddr aRomAddr);
377 IMPORT_C static TInt AllocPhysicalRam(TInt aSize, TPhysAddr& aPhysAddr, TInt aAlign=0);
378 IMPORT_C static TInt ZoneAllocPhysicalRam(TUint aZoneId, TInt aSize, TPhysAddr& aPhysAddr, TInt aAlign=0);
379 IMPORT_C static TInt ZoneAllocPhysicalRam(TUint* aZoneIdList, TUint aZoneIdCount, TInt aSize, TPhysAddr& aPhysAddr, TInt aAlign=0);
380 IMPORT_C static TInt AllocPhysicalRam(TInt aNumPages, TPhysAddr* aPageList);
381 IMPORT_C static TInt ZoneAllocPhysicalRam(TUint aZoneId, TInt aNumPages, TPhysAddr* aPageList);
382 IMPORT_C static TInt ZoneAllocPhysicalRam(TUint* aZoneIdList, TUint aZoneIdCount, TInt aNumPages, TPhysAddr* aPageList);
383 IMPORT_C static TInt FreePhysicalRam(TPhysAddr aPhysAddr, TInt aSize);
384 IMPORT_C static TInt FreePhysicalRam(TInt aNumPages, TPhysAddr* aPageList);
385 IMPORT_C static TInt ClaimPhysicalRam(TPhysAddr aPhysAddr, TInt aSize);
386 IMPORT_C static TPhysAddr LinearToPhysical(TLinAddr aLinAddr);
387 IMPORT_C static void RomProcessInfo(TProcessCreateInfo& aInfo, const TRomImageHeader& aRomImageHeader); /**< @internalComponent */
388 #ifdef BTRACE_KERNEL_MEMORY
389 static TInt DriverAllocdPhysRam; // the number of bytes allocated by Epoc::AllocPhysicalRam and Epoc::FreePhysicalRam
390 static TInt KernelMiscPages; // the number of bytes of 'miscelaneous' kernel memory allocated
392 IMPORT_C static TInt MovePhysicalPage(TPhysAddr aOld, TPhysAddr& aNew, TRamDefragPageToMove aPageToMove=ERamDefragPage_Physical); /**< @internalComponent */
393 IMPORT_C static TInt SetRamZoneConfig(const SRamZone* aZones, TRamZoneCallback aCallback);
394 IMPORT_C static TInt GetRamZonePageCount(TUint aId, SRamZonePageCount& aPageData);
395 IMPORT_C static TInt ModifyRamZoneFlags(TUint aId, TUint aClearMask, TUint aSetMask);
406 /** Bitmask values representing different breakpoint types. */
409 EBreakpointGlobal = 1<<0, /**< Breakpoint appears in all processes */
410 EBreakpointLocal = 1<<1, /**< Breakpoint appears in the specified process only. */
413 IMPORT_C static TInt InitialiseCodeModifier(TUint& aCapabilities, TInt aMinBreakpoints);
414 IMPORT_C static void CloseCodeModifier();
415 IMPORT_C static TInt ModifyCode(DThread* aThread, TLinAddr aAddress, TInt aSize, TUint aValue, TUint aType);
416 IMPORT_C static TInt RestoreCode(DThread* aThread, TLinAddr aAddress);
422 IMPORT_C static void TerminateProcess(DProcess* aProcess, const TInt aReason);
426 #ifdef __DEBUGGER_SUPPORT__
430 class CodeModifier : public DBase
434 /** Values for panic values in category 'CodeModifier'. */
437 EPanicNotInitialised = 0,
438 EPanicInvalidSizeOrAlignment = 1,
441 /** Defines the type/size of the breakpoint - see TBreakpoint::iSize*/
444 EEmpty =0, //The slot is unused
445 EByte =1, //Jazelle breakpoint
446 EHalfword =2, //Thumb breakpoint
447 EWord =4 //ARM breakpoint
450 TInt static CreateAndInitialise(TInt aMinBreakpoints);
453 TInt Modify(DThread* aThread, TLinAddr aAddress, TInt aSize, TUint aValue);
454 TInt Restore(DThread* aThread, TLinAddr aAddress);
455 static void CodeSegRemoved(DCodeSeg* aCodeSeg, DProcess* aProcess);
456 static DMutex& Mutex() {return *Kern::CodeSegLock();}
457 static void Fault(TPanic aPanic);
461 /**Desribes a breakpoint slot in the pool*/
464 TUint iProcessId; //Id of the process associated to this breakpoint.
465 TUint iAddress; //The virtual address of the breakpoint
466 TUint32 iOldValue; //Will hold the original content of iAddress
467 TInt16 iSize; //Could be one of TBrkType. 0 means empty/unused, otherwise it indicates the size of the breakpoint in bytes.
468 TInt16 iPageIndex; //If iSize!=0 identifies corresponding shadowed page, or -1 if it is non-XIP page.
471 /** Desribes a page slot in the pool. Used for pages that are shadowed or need to be locked (for demand paging). */
474 TLinAddr iAddress; //Base address of the page.
475 TInt32 iCounter; //The number of breakpoints associated with this page. 0 indicates empty slot.
476 TBool iWasShadowed; //True if the page had been already shadowed before the first breakpoint was applied,
477 //false otherwise. If true, it won't be un-shadowed after all breakpoints are removed.
478 #ifdef __DEMAND_PAGING__
479 /// If set, points to the deamnd paging lock object used to lock this page. Only applies to
481 DDemandPagingLock* iPagingLock;
485 TBreakpoint* FindBreakpoint(DThread* aThread, TLinAddr aAddress, TInt aSize, TBool& aOverlap);
486 TBreakpoint* FindEmptyBrk();
487 TInt FindEmptyPageInfo();
488 TInt FindPageInfo(TLinAddr aAddress);
489 TInt IsRom(TLinAddr aAddress);
490 TInt WriteCode(TLinAddr aAddress, TInt aSize, TUint aValue, void* aOldValue);
491 DProcess* Process(TUint aProcessId);
492 TInt SafeWriteCode(DProcess* aProcess, TLinAddr aAddress, TInt aSize, TUint aValue, void* aOldValue);
493 void RestorePage(TInt aPageIndex);
494 void DoCodeSegRemoved(DCodeSeg* aCodeSeg, DProcess* aProcess);
498 TBreakpoint* iBreakpoints; //Breakpoint pool with iPoolSize slots
499 TPageInfo* iPages; //The pool of the shadowed/locked pages with iPoolSize slots
504 GLREF_D CodeModifier* TheCodeModifier;
505 #endif //__DEBUGGER_SUPPORT__
511 inline const TRomEntry &RomEntry(TLinAddr anAddr)
512 {return(*((const TRomEntry *)anAddr));}
517 inline const TRomImageHeader& RomImageHeader(TLinAddr anAddr)
518 {return(*((const TRomImageHeader*)anAddr));}
521 TRamDefragRequest is intended to be used by device drivers to request that RAM defragmentation
522 operations are performed.
524 All RAM defragmentation operations can be invoked synchronously or asynchronously.
525 The asynchronous RAM defragmentation operations can use either a TDfc or a NFastSemaphore
526 to signal to the caller that the operation has completed.
533 class TRamDefragRequest : protected TAsyncRequest
536 IMPORT_C TRamDefragRequest();
537 IMPORT_C TInt DefragRam(TInt aPriority, TInt aMaxPages=0);
538 IMPORT_C TInt DefragRam(NFastSemaphore* aSem, TInt aPriority, TInt aMaxPages=0);
539 IMPORT_C TInt DefragRam(TDfc* aDfc, TInt aPriority, TInt aMaxPages=0);
540 IMPORT_C TInt EmptyRamZone(TUint aId, TInt aPriority);
541 IMPORT_C TInt EmptyRamZone(TUint aId, NFastSemaphore* aSem, TInt aPriority);
542 IMPORT_C TInt EmptyRamZone(TUint aId, TDfc* aDfc, TInt aPriority);
543 IMPORT_C TInt ClaimRamZone(TUint aId, TPhysAddr& aPhysAddr, TInt aPriority);
544 IMPORT_C TInt ClaimRamZone(TUint aId, TPhysAddr& aPhysAddr, NFastSemaphore* aSem, TInt aPriority);
545 IMPORT_C TInt ClaimRamZone(TUint aId, TPhysAddr& aPhysAddr, TDfc* aDfc, TInt aPriority);
546 IMPORT_C TInt Result();
547 IMPORT_C void Cancel();
550 Values that can be specified to control which thread priority
551 the RAM defragmentation operations are run with.
553 enum TPrioritySpecial
556 The RAM defragmentation operation will use the same thread priority as
559 KInheritPriority = -1,
563 void SetupPriority(TInt aPriority);
566 Epoc::TRamDefragOp iOp;
569 TInt iThreadPriority;
570 TPhysAddr* iPhysAddr;