// Copyright (c) 2005-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 MPAGER_H

#define MPAGER_H

#include "mmu.h"

#include <kern_priv.h>

/**

Maximum number of pages to attempt to clean in one go.

If a paging device sets a preferred write size greater than this then it will fail to install with

KErrArgument.

*/

const TUint KMaxPagesToClean = 16;

struct SVMCacheInfo;

class DMemModelThread;

class DMemoryMappingBase;

class DPager

	{

public:

	DPager();

	void InitCache();

	void Init3();

	FORCE_INLINE TBool CacheInitialised()

		{

		return iYoungOldRatio && iMinimumPageLimit;

		}

	FORCE_INLINE TUint NumberOfFreePages()

		{

		return iNumberOfFreePages;

		}

	FORCE_INLINE TUint NumberOfDirtyPages()

		{

		TUint ret;

		MmuLock::Lock();

		ret = iNumberOfDirtyPages;

		MmuLock::Unlock();

		return ret;

		}

	FORCE_INLINE TUint MinimumPageCount()

		{

		return iMinimumPageCount;

		}

	FORCE_INLINE void SetWritable(SPageInfo& aPageInfo)

		{

		if (!aPageInfo.IsDirty())

			{// This is the first mapping to write to the page so increase the 

			// dirty page count.

			iNumberOfDirtyPages++;

			}

		aPageInfo.SetWritable();

		}

	FORCE_INLINE void SetClean(SPageInfo& aPageInfo)

		{

		__NK_ASSERT_DEBUG(iNumberOfDirtyPages);

		__NK_ASSERT_DEBUG(aPageInfo.IsDirty());

		aPageInfo.SetClean();

		iNumberOfDirtyPages--;

		}

	/**

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

	(Free them.)

	This is called by class Mmu when it requires more free RAM to meet an

	allocation request.

	@param	aNumPages The number of pages to free up.

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

	@pre	RamAlloc mutex held.

	*/

	TBool GetFreePages(TInt aNumPages);

	/**

	Attempts to rejuvenate or page in the page to the mapping that took the page fault.

	@param aPc					Address of instruction causing the fault.

	@param aFaultAddress		Address of memory access which faulted.

	@param aFaultAsid			The asid of the faulting thread's process.

	@param aAccessPermissions	Bitmask of values from enum TAccessPermissions, which

								indicates the permissions required by faulting memory access.

	@param aMapInstanceCount	The instance count of the mapping when it took the page fault.

	@param aThread				The thread that took the page fault.

	@param aExceptionInfo		The processor specific exception info.

	@return KErrNone if the page is now accessable, otherwise one of the system wide error codes.

	*/

	TInt HandlePageFault(	TLinAddr aPc, TLinAddr aFaultAddress, TUint aFaultAsid, TUint aFaultIndex,

							TUint aAccessPermissions, DMemoryObject* aMemory, DMemoryMapping* aMapping,

							TUint aMapInstanceCount, DThread* aThread, TAny* aExceptionInfo);

	/**

	Fault enumeration

	*/

	enum TFault

		{

		};

	/**

	Fault the system.

	*/

	static void Fault(TFault aFault);

	/**

	Get state of live page list.

	*/

	void GetLiveListInfo(SVMCacheInfo& aInfo);

	/**

	Resize the live page list.

	*/

	TInt ResizeLiveList(TUint aMinimumPageCount, TUint aMaximumPageCount);

	/**

	Recalculate live list size.

	*/

	TInt ResizeLiveList();

	/**

	Flush (unmap) all memory which is demand paged.

	This reduces the live page list to a minimum.

	*/

	void FlushAll();

	/**

	Flush demand paged pages in a specified region.

	The memory must reside in a single memory object.

	@param aProcess The process containing the pages to flush.

	@param aStart   The start address of the region.

	@param aSize    The size of the region in bytes.

	@return KErrBadDescriptor If the memory region is invalid or spans more than one memory object,

	                          otherwise KErrNone.

	*/

	TInt FlushRegion(DMemModelProcess* aProcess, TLinAddr aStartAddress, TUint aSize);

	/**

	Give pages to paging system for managing.

	*/

	void DonatePages(TUint aCount, TPhysAddr* aPages);

	/**

	Reclaim pages from paging system which were previously donated with DonatePages.

	@param aCount Number of pages.

	@param aPages Array of pages (as stored in an RPageArray).

	@return KErrNone if successful.

			KErrNoMemory if paging system doesn't have enough spare pages. This will leave some or all of the pages still managed by the pager.

			KErrNotFound if some of the pages were not actually being managed by the pager.

	*/

	TInt ReclaimPages(TUint aCount, TPhysAddr* aPages);

	/**

	Called by class Mmu whenever a page of RAM is freed. The page state will be EUnused.

	If the page was being used by the pager then this gives it the opportunity to update

	any internal state. If the pager wishes to retain ownership of the page the it must

	return the result KErrNone, any other value will cause the page to be returned to the

	systems free pool.

	*/

	TInt PageFreed(SPageInfo* aPageInfo);

	//

	// following public members for use by memory managers...

	//

	/**

	Allocate a number of RAM pages to store demand paged content.

	These pages are obtained from...

	1. An unused page in the live page list.

	2. The systems free pool.

	3. The oldest page from the live page list.

	*/

	TInt PageInAllocPages(TPhysAddr* aPages, TUint aCount, Mmu::TRamAllocFlags aAllocFlags);

	/**

	Free a number of RAM pages allocated by PageInAllocPages.

	*/

	void PageInFreePages(TPhysAddr* aPages, TUint aCount);

	/**

	Called to add a new page to the live list after a fault has occurred.

	@param aPageInfo		The page.

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	void PagedIn(SPageInfo* aPageInfo);

	/**

	@param aPageInfo		The page.

	@param aPinArgs			Owner of a replacement page which will be used to substitute for the pinned page.

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	void PagedInPinned(SPageInfo* aPageInfo, TPinArgs& aPinArgs);

	/**

	@pre MmuLock held

	@post MmuLock left unchanged.

	*/

	void PagedInUnneeded(SPageInfo* aPageInfo);

	/**

	@param aPageInfo		The page to unpin.

	@param aPinArgs			The resources used for pinning. The replacement pages allocated

							to this will be increased for each page which was became completely

							unpinned.

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	void Unpin(SPageInfo* aPageInfo, TPinArgs& aPinArgs);

	/**

	@param aPageInfo		The page to pin. Must be page being demand paged.

	@param aPinArgs			Owner of a replacement page which will be used to substitute for the pinned page.

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	void Pin(SPageInfo* aPageInfo, TPinArgs& aPinArgs);

	/**

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	void RejuvenatePageTable(TPte* aPt);

	/**

	*/

	TBool ReservePages(TUint aRequiredCount, TUint& aCount);

	/**

	*/

	void UnreservePages(TUint& aCount);

	/**

	Indicates whether there are any dirty pages available to be cleaned by #CleanSomePages.

	This is called by the page cleaner to work out whether it has any work to do.

	@return Whether there are any dirty pages in the oldest section of the live list.

	*/

	TBool HasPagesToClean();

	/**

	Attempt to clean one or more dirty pages in one go.

	Called by the page cleaner to clean pages and by PageInAllocPage when needs to steal a page from

	the live list, but the oldest clean list is empty.

	May or may not succeed in acually cleaning any pages.

	@param aBackground Whether the activity should be ignored when determining whether the paging

	                   device is busy.  This is used by the page cleaner.

	@return The number of pages this method attempted to clean.  If it returns zero, there were no

	        pages eligible to be cleaned.

	*/

	TInt CleanSomePages(TBool aBackground);

	/**

	Enumeration of instrumented paging events which only require the

	SPageInfo object as an argument. 

	*/

	enum TEventSimple

		{

		EEventPageInNew,

		EEventPageInAgain,

		EEventPageInUnneeded,

		EEventPageInFree,

		EEventPageOut,

		EEventPageAged,

		EEventPagePin,

		EEventPageUnpin,

		EEventPageDonate,

		EEventPageReclaim,

		EEventPageAgedClean,

		EEventPageAgedDirty,

		EEventPagePageTableAlloc

		};

	/**

	Signal the occurrence of an event of type TEventSimple.

	*/

	void Event(TEventSimple aEvent, SPageInfo* aPageInfo);

	/**

	Enumeration of instrumented paging events which require the faulting address

	and program counter as arguments. 

	*/

	enum TEventWithAddresses

		{

		EEventPageInStart,

		EEventPageRejuvenate

		};

	/**

	Signal the occurrence of an event of type TEventWithAddresses.

	*/

	void Event(TEventWithAddresses aEvent, SPageInfo* aPageInfo, TLinAddr aPc, TLinAddr aFaultAddress, TUint aAccessPermissions);

	/**

	Get the pager's event info data.

	*/

	void GetEventInfo(SVMEventInfo& aInfoOut);

	/**

	Reset the pager's event info data.

	*/

	void ResetEventInfo();

	/**

	Attempt to discard the specified page.

	@param aOldPageInfo	The page info of the page to discard.

	@param aBlockZoneId	The ID of the RAM zone not to allocate any required new page into.

	@param aMoveDisFlags 	Flags that control the discarding of the page, should be a mask of 

							values from M::TMoveDiscardFlags

	*/

	TInt DiscardPage(SPageInfo* aOldPageInfo, TUint aBlockZoneId, TUint aMoveDisFlags);

	/**

	Attempt to discard the specified page and then allocate a page of type aPageType

	in its place.

	Note - This will always attempt to move dirty pages rather than write them to swap.

	@param aPageInfo	The page info of the page to discard.

	@param aPageType 	The new page type to allocate into aPageInfo's physical address.

	*/

	TInt DiscardAndAllocPage(SPageInfo* aPageInfo, TZonePageType aPageType);

	/**

	Update any live list links to replace the old page with the new page.

	This is to be used when a page has been moved.

	@param aOldPageInfo	The page info of the page to replace.

	@param aNewPageInfo	The page info of the page to be used instead of the old page.

	*/

	void ReplacePage(SPageInfo& aOldPageInfo, SPageInfo& aNewPageInfo);

	//

	// following public members for use by TPinArgs...

	//

	/**

	*/

	TBool AllocPinReplacementPages(TUint aNumPages);

	/**

	*/

	void FreePinReplacementPages(TUint aNumPages);

	//

	// following public members for use by DDataPagedMemoryManager...

	//

	/**

	Called by the data paged memory manager to set the number of pages the pager should attempt to

	clean at once.

	This also adjusts the maximum size of the oldest list if it is too small to contain the

	specified number of pages.

	@param aPagesToClean     Number of pages the pager should attempt to clean in one go

	*/

	void SetPagesToClean(TUint aPagesToClean);

	/**

	Get the number of pages the pager attempts to clean at once.

	*/

	TUint PagesToClean();

	/**

	Called by the data paged memory manager to set whether pages cleaned must have sequential page

	colour.

	@param aCleanInSequence  Whether pages must have sequential page colour

	*/

	void SetCleanInSequence(TBool aCleanInSequence);

private:

	/**

	Add a page to the head of the live page list. I.e. make it the 'youngest' page.

	@pre MmuLock held

	@post MmuLock left unchanged.

	*/

	void AddAsYoungestPage(SPageInfo* aPageInfo);

	/**

	Mark a page as type EUnused and add it to the end of the live page list.

	I.e. make it the 'oldest' page, so that it is the first page to be reused.

	@pre MmuLock held

	@post MmuLock left unchanged.

	*/

	void AddAsFreePage(SPageInfo* aPageInfo);

	/**

	Remove a page from live page list.

	It paged state is set to EUnpaged.

	@pre MmuLock held

	@post MmuLock left unchanged.

	*/

	void RemovePage(SPageInfo* aPageInfo);

	/**

	Get a page, either by stealing one from the live list or allocating one from the system.

	If the oldest page is an oldest dirty page, this may attempt to clean multiple pages by calling

	#CleanSomePages.

	If the oldest page is on any other list (i.e. is an old or young page) this will steal it,

	aquiring the page cleaning mutex first if it is dirty.

	Called from #PageInAllocPage, #TryReturnOldestPageToSystem, #AllowAddFreePage and 

	#AllowAddFreePages.

	@param aAllowAlloc Indicates whether the method should try to allocate a page from the system

	@return KErrNone on success, KErrInUse if stealing failed or 1 to indicate the the oldest page

	was dirty and the PageCleaning mutex was not held.

	@pre MmuLock held

	@post MmuLock left unchanged.

	*/

	SPageInfo* StealOrAllocPage(TBool aAllowAlloc, Mmu::TRamAllocFlags aAllocFlags);

	/**

	Steal a page from the memory object (if any) which is using the page.

	If successful the returned page will be in the EUnknown state and the

	cache state for the page is indeterminate. This is the same state as

	if the page had been allocated by Mmu::AllocRam.

	@pre RamAlloc mutex held

	@pre If the page is dirty the PageCleaning lock must be held.

	@pre MmuLock held

	@post MmuLock held (but may have been released by this function)

	*/

	TInt StealPage(SPageInfo* aPageInfo);

	/**

	Restrict the access permissions for a page.

	@param aPageInfo	The page.

	@param aRestriction	The restriction type to apply.

	*/

	TInt RestrictPage(SPageInfo* aPageInfo, TRestrictPagesType aRestriction);

	/**

	Get a RAM page from the system's free pool and add it to the live list as a free page.

	@return False if out of memory;

			true otherwise, though new free page may still have already been used.

	@pre MmuLock held