1 // Copyright (c) 2006-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 // e32\include\memmodel\epoc\mmubase\ramcache.h

    15 // 

    16 //

    17 

    18 #ifndef RAMCACHE_H

    19 #define RAMCACHE_H

    20 

    21 #ifndef __MEMMODEL_FLEXIBLE__

    22 #include <memmodel/epoc/mmubase/mmubase.h>

    23 #else

    24 class MmuBase;

    25 #endif

    26 

    27 /**

    28 Base class for the ram caching or demand paging implementation.

    29 

    30 This provides an interface between class Mmu and the implementation

    31 of any form of dynamic use of the system's free memory, e.g. demand paging.

    32 The chief functionality of this interface is for transferring ownership of

    33 physical pages of RAM.

    34 

    35 @internalComponent

    36 */

    37 class RamCacheBase

    38 	{

    39 public:

    40 	/**

    41 	Constructor

    42 	*/

    43 	RamCacheBase();

    44 

    45 	/**

    46 	Intialisation called during MmuBase:Init2.

    47 	*/

    48 	virtual void Init2();

    49 

    50 	/**

    51 	Initialisation called from M::DemandPagingInit.

    52 	*/

    53 	virtual TInt Init3()=0;

    54 

    55 	/**

    56 	Remove RAM pages from the cache and return them to the system's free pool.

    57 	(Free them.)

    58 

    59 	This is called by MmuBase when it requires more free RAM to meet an

    60 	allocation request.

    61 

    62 	@param	aNumPages The number of pages to free up.

    63 	@return	True if all pages could be freed, false otherwise

    64 	@pre	RamAlloc mutex held.

    65 	*/

    66 	virtual TBool GetFreePages(TInt aNumPages)=0;

    67 

    68 	/**

    69 	Give a RAM page to the cache system for managing.

    70 	This page of RAM may be reused for any purpose.

    71 	If the page has already been donated then no action is taken.

    72 

    73 	@param aPageInfo The page info for the donated page.

    74 

    75 	@see ReclaimRamCachePage.

    76 

    77 	@pre System Lock held

    78 	@post System Lock left unchanged.

    79 	*/

    80 	virtual void DonateRamCachePage(SPageInfo* aPageInfo)=0;

    81 

    82 	/**

    83 	Attempt to reclaim a RAM page given to the cache system with #DonateRamCachePage.

    84 	If the RAM page has not been reused for other purposes then the page is

    85 	removed from the cache system's management.

    86 	If the page has not previousely been donated then no action is taken.

    87 

    88 	@param aPageInfo The page info for the page to reclaim.

    89 

    90 	@return True if page successfuly reclaimed, false otherwise.

    91 

    92 	@pre System Lock held

    93 	@post System Lock left unchanged.

    94 	*/

    95 	virtual TBool ReclaimRamCachePage(SPageInfo* aPageInfo)=0;

    96 

    97 	/**

    98 	Called by MMU class when a page is unmapped from a chunk.

    99 

   100 	@param aPageInfo The page info for the page being unmapped.

   101 

   102 	@return True is cache system doesn't claim ownership of this page, false if it does.

   103 	*/

   104 	virtual TBool PageUnmapped(SPageInfo* aPageInfo)=0;

   105 

   106 	/**

   107 	Check whether the specified page can be discarded by the RAM cache.

   108 

   109 	@param aPageInfo The page info of the page being queried.

   110 	@return ETrue when the page can be discarded, EFalse otherwise.

   111 	@pre System lock held.

   112 	@post System lock held.

   113 	*/

   114 	virtual TBool IsPageDiscardable(SPageInfo& aPageInfo) = 0;

   115 

   116 	/**

   117 	Discard the specified page.

   118 	Should only be called on a page if a previous call to IsPageDiscardable()

   119 	returned ETrue and the system lock hasn't been released between the calls.

   120 	If necessary a new page may be allocated to replace the one being

   121 	discarded, however the new page should not be allocated into the RAM

   122 	zone of ID==aBlockedZoneId.

   123 	

   124 	@param aPageInfo The page info of the page to be discarded

   125 	@param aBlockZoneId The ID of the RAM zone that shouldn't be allocated into.

   126 	@param aBlockRest Set to ETrue to stop allocation as soon as aBlockedZoneId is reached 

   127 	in preference ordering.  EFalse otherwise.

   128 	@return ETrue if the page could be discarded, EFalse otherwise.

   129 	

   130 	@pre System lock held.

   131 	@post System lock held.

   132 	*/

   133 	virtual TBool DoDiscardPage(SPageInfo& aPageInfo, TUint aBlockedZoneId, TBool aBlockRest) = 0;

   134 

   135 

   136 	/**

   137 	First stage in discarding a list of pages.

   138 

   139 	Must ensure that the pages will still be discardable even if system lock 

   140 	is released after this method has completed.

   141 	To be used in conjunction with RamCacheBase::DoDiscardPages1().

   142 

   143 	@param aPageList A NULL terminated list of the pages to be discarded

   144 	@return KErrNone on success.

   145 

   146 	@pre System lock held

   147 	@post System lock held

   148 	*/

   149 	virtual TInt DoDiscardPages0(SPageInfo** aPageList) = 0;

   150 

   151 

   152 	/**

   153 	Final stage in discarding a list of page

   154 	Finish discarding the pages previously removed by RamCacheBase::DoDiscardPages0().

   155 

   156 	@param aPageList A NULL terminated list of the pages to be discarded

   157 	@return KErrNone on success.

   158 

   159 	@pre System lock held

   160 	@post System lock held

   161 	*/

   162 	virtual TInt DoDiscardPages1(SPageInfo** aPageList) = 0;

   163 

   164 

   165 	/**

   166 	Flush (unmap) all the free memory which is currently cached.

   167 	*/

   168 	virtual void FlushAll() = 0;

   169 

   170 	/**

   171 	Attempt to allocate the required contiguous region of pages, freeing

   172 	RAM cache pages if required.

   173 

   174 	@param	aNumPages The number of pages to free up.

   175 	@param	aAlign The alignment of the region to free-up, (a power-of-2).

   176 	@param aBlockZoneId The ID of a zone that shouldn't be allocated into, when set to 

   177 	KRamZoneInvalidId it will have no effect.

   178 	@param aBlockRest Set to ETrue to stop allocation as soon as aBlockedZoneId is reached 

   179 	in preference ordering.  EFalse otherwise.

   180 

   181 	@return	KErrNone on success, KErrNoMemory otherwise

   182 	@pre	RamAlloc mutex held.

   183 	*/

   184 	TInt AllocFreeContiguousPages(TInt aNumPages, TInt aAlign, TZonePageType aType, TPhysAddr& aPhysAddr, TUint aBlockedZoneId, TBool aBlockRest);

   185 

   186 	/**

   187 	Return the maximum number of RAM pages which could be obtained with #GetFreePages.

   188 	This value is used in the calculation of the 'free' RAM in the system.

   189 

   190 	@return Number of free RAM pages.

   191 	*/

   192 	inline TInt NumberOfFreePages() { return iNumberOfFreePages; }

   193 

   194 	/**

   195 	Put a page back on the system's free pool.

   196 

   197 	@pre RamAlloc mutex held.

   198 	*/

   199 	void ReturnToSystem(SPageInfo* aPageInfo);

   200 

   201 	/**

   202 	Get a RAM page from the system's free pool.

   203 	

   204 	@param aBlockZoneId The ID of a zone that shouldn't be allocated into, when set to 

   205 	KRamZoneInvalidId it will have no effect.

   206 	@param aBlockRest Set to ETrue to stop allocation as soon as aBlockedZoneId is reached 

   207 	in preference ordering.  EFalse otherwise.

   208 

   209  	@pre	RamAlloc mutex held.

   210 

   211 	@return The page or NULL if no page is available.

   212 	*/

   213 	SPageInfo* GetPageFromSystem(TUint aBlockedZone=KRamZoneInvalidId, TBool aBlockRest=EFalse);

   214 

   215 

   216 

   217 public:

   218 	MmuBase* iMmu;				/**< Copy of MmuBase::TheMmu */

   219 	TInt iNumberOfFreePages;	/**< Number of pages which could be freed by GetFreePages.

   220 									 This value is protected by the RamAlloc mutex. */

   221 	static RamCacheBase* TheRamCache;

   222 	};

   223 

   224 

   225 class RamCache : public RamCacheBase

   226 	{

   227 public:

   228 	// from RamCacheBase

   229 	virtual void Init2();

   230 	virtual TInt Init3();

   231 	virtual TBool GetFreePages(TInt aNumPages);

   232 	virtual void DonateRamCachePage(SPageInfo* aPageInfo);

   233 	virtual TBool ReclaimRamCachePage(SPageInfo* aPageInfo);

   234 	virtual TBool PageUnmapped(SPageInfo* aPageInfo);

   235 	virtual TBool IsPageDiscardable(SPageInfo& aPageInfo);

   236 	virtual TBool DoDiscardPage(SPageInfo& aPageInfo, TUint aBlockZoneId, TBool aBlockRest);

   237 	virtual TInt DoDiscardPages0(SPageInfo** aPageList);

   238 	virtual TInt DoDiscardPages1(SPageInfo** aPageList);

   239 	virtual void FlushAll();

   240 	// new

   241 	virtual void SetFree(SPageInfo* aPageInfo);

   242 	enum TFault

   243 		{

   244 		EUnexpectedPageType = 3,	/**< A page in the live page list had an unexpected type (SPageInfo::Attribs) */

   245 		};

   246 	static void Panic(TFault aFault);

   247 	void RemovePage(SPageInfo& aPageInfo);

   248 private:

   249 	SDblQue iPageList;

   250 	};

   251 

   252 #endif