// Copyright (c) 1998-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:

// eka\include\kernel\cache.h

// 

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef __CACHE_H__

#define __CACHE_H__

#include <e32err.h>

#include <nk_cpu.h>

/**

Cache Thresholds container used to Set/Get cache thresholds from/to Kernel.

@see Cache::GetThresholds

@see Cache::SetThresholds

*/

struct TCacheThresholds

	{

	TUint32 iPurge; /**< Invalidate threshold in bytes*/

	TUint32 iClean; /**< Clean threshold in bytes*/

	TUint32 iFlush; /**< Clean and invalidate threshold in bytes*/

	};

const TUint KCacheSelectI=1; 		/**<Specifies instruction cache.*/ 

const TUint KCacheSelectD=2;		/**<Specifies data cache to the point of coherency.*/

const TUint KCacheSelectAltD=4;		/**<Specifies alternative cache. @deprecated*/

const TUint KCacheSelectD_IMB=8;	/**<Specifies data cache to the point of unification.*/

const TUint KCacheSelect_L2=0x10;	/**<Specifies external cache.*/

/**

A set of Kernel APIs for cache utility functions.

*/

class Cache

	{

public:

	/**

	Synchronises cache(s) for instruction execution in the specified address range.

	The function performs the cache/memory synchronisation required to guarantee

	correct execution of code in the specified virtual address range.

	@param aBase The start of the virtual address range.

	@param aSize The size of the address range.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	*/

	IMPORT_C static void IMB_Range(TLinAddr aBase, TUint aSize);

	/**

	Synchronises cache(s) prior to a DMA write (memory to HW DMA transfer) operation.

	It is assumed that the memory region is fully cached.

	The purpose of SyncMemoryBeforeDmaWrite is to ensure that the main memory is

	synchronised with the content of cache memory before the start of DMA write transfer.

	@param aBase The start of the virtual address range.

	@param aSize The size of the address range.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	*/

	IMPORT_C static void SyncMemoryBeforeDmaWrite(TLinAddr aBase, TUint aSize);

	/**

	Synchronises cache(s) prior to a DMA read (HW to memory DMA transfer) operation.

	It is assumed that the memory region is fully cached.

	The purpose of SyncMemoryBeforeDmaRead is to make sure that the content of memory

	(that is about to be DMA-ed) won't be destroyed by interaction between cache

	and the main memory. (E.g. by cache eviction or remaining content of write buffers.) 

	@param aBase The start of the virtual address range.

	@param aSize The size of the address range.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	*/

	IMPORT_C static void SyncMemoryBeforeDmaRead(TLinAddr aBase, TUint aSize);

	/**

	Synchronises cache(s) after a DMA read (HW to memory DMA transfer) operation.

	It is assumed that the memory region is fully cached.

	The purpose of SyncMemoryAfterDmaRead is to make sure that CPU won't read

	old data from cache instead of DMA-ed data from the main memory.

	@param aBase The start of the virtual address range.

	@param aSize The size of the address range.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	*/

	IMPORT_C static void SyncMemoryAfterDmaRead(TLinAddr aBase, TUint aSize);

	/**

	Synchronises cache(s) with main memory prior to power off or reboot.

	It ensures the content of cache is copied down to the main memory. It doesn't necessarily

	invalidates the content of cache(s).

	On SMP platforms, it only maintains internal cache of the CPU that executes the call.

	Cache memory common to the all cores (like external cache controllers) are also synchronised.

	@pre Interrupts must be disabled.

	*/

	IMPORT_C static void AtomicSyncMemory();

	/**

	Synchronises cache(s) prior to a DMA write (memory to HW DMA transfer) operation.

	The purpose of SyncMemoryBeforeDmaWrite is to make sure that the main memory is synchronised 

	with the content of cache memory before DMA transfer from main memory starts.

	@param aBase    The start of the virtual address range.

	@param aSize    The size of the address range.

	@param aMapAttr The mapping attributes with which the address range has been mapped.

	                This is a value constructed from the bit masks in the enumeration

	                TMappingAttributes.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	@see TMappingAttributes

	*/

	IMPORT_C static void SyncMemoryBeforeDmaWrite(TLinAddr aBase, TUint aSize, TUint32 aMapAttr);

	/**

	Synchronises cache(s) prior to a DMA read ((HW to memory DMA transfer) operation.

	The purpose of SyncMemoryBeforeDmaRead is to make sure that the content of memory

	(that is about to be DMA-ed) won't be destroyed by interaction between cache

	and the main memory. (E.g. by write buffers' flushing or cache eviction.) 

	@param aBase    The start of the virtual address range.

	@param aSize    The size of the address range.

	@param aMapAttr The mapping attributes with which the address range has been mapped.

	                This is a value constructed from the bit masks in the enumeration

	                TMappingAttributes.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	@see TMappingAttributes

	*/

	IMPORT_C static void SyncMemoryBeforeDmaRead(TLinAddr aBase, TUint aSize, TUint32 aMapAttr);

	/**

	Synchronises cache(s) after a DMA read (HW to memory DMA transfer) operation.

	The purpose of SyncMemoryAfterDmaRead is to make sure that CPU won't read

	old data from cache instead of DMA-ed data from the main memory.

	@param aBase The start of the virtual address range.

	@param aSize The size of the address range.

	@param aMapAttr The mapping attributes with which the address range has been mapped.

	                This is a value constructed from the bit masks in the enumeration

	                TMappingAttributes.

	@pre Call in a thread context.

	@pre No fast mutex can be held.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	@see TMappingAttributes

	*/

	IMPORT_C static void SyncMemoryAfterDmaRead(TLinAddr aBase, TUint aSize, TUint32 aMapAttr);

	/**

	Prepares physical memory for DMA writing (memory to H/W DMA copy). If the physical memory is the

	subject of RAM defragmentation framework (e.g. if it is mapped in user side space) the driver

	should make sure it is pinned (@see Kern::PinPhysicalMemory) before calling this Kernel service.

	Kern::PinPhysicalMemory also generates input parameters aPages and aColour for this Kernel service.

	@param	aPages		Pointer to the the list of physical memory pages to be prepared for DMA write.

						The exact portion of physical memory to be prepared is defined by aOffset and

						aSize parameters. For example, if aOffset is 0x1800 and aSize is 0x2000, the method

						will sync the last 0x800 bytes of the second page in the list, the whole third page

						and the first 0x800  bytes of the fourth page. (0x1000 page size is assumed).

	@param	aColour		The mapping colour of the first physical page in the list. 

	@param	aOffset		Offset in memory list where DMA transfer should start.

	@param	aSize		The size of the memory in bytes to be sync'ed.

	@param	aMapAttr	Mapping attributes of the the existing mapping. The value is either:

						  - Formed by ORing together values from the TMappingAttributes enumeration as

						    returned by Kern::ChunkCreate interface, or

						  - TMappingAttributes2 object.

						For user memory (always fully cached), EMapAttrCachedMax enum value can be passed.

						KErrNone, on flexible memory model.

	@pre Interrupts must be enabled.

	@pre Kernel must be unlocked.

	@pre No fast mutex can be held.

	@pre Call in a thread context.

	@pre Can be used in a device driver.

	*/

	IMPORT_C static TInt SyncPhysicalMemoryBeforeDmaWrite(TPhysAddr* aPages, TUint aColour, TUint aOffset, TUint aSize, TUint32 aMapAttr);

	/**

	Prepares physical memory for DMA read (H/W to memory DMA copy).

	For all the details @see Cache::SyncPhysicalMemoryBeforeDmaWrite

	*/

	IMPORT_C static TInt SyncPhysicalMemoryBeforeDmaRead (TPhysAddr* aPages, TUint aColour, TUint aOffset, TUint aSize, TUint32 aMapAttr);

	/**

	Maintains physical memory after DMA read (H/W to memory DMA copy).

	For all the details @see Cache::SyncPhysicalMemoryBeforeDmaWrite

	*/

	IMPORT_C static TInt SyncPhysicalMemoryAfterDmaRead  (TPhysAddr* aPages, TUint aColour, TUint aOffset, TUint aSize, TUint32 aMapAttr);

/*

 * Gets threshold values for the specified cache.

 * 

 * When Kernel is about to perform cache maintenance operation, the size of the region to act

 * against is compared to the corresponding threshold value:

 *  - When invalidating memory region:

 * 		@code

 * 			if (invalidate region > invalidate threshold)

 * 				clean and invalidate entire cache

 * 			else

 * 				invalidate the specified region

 * 		@endcode

 * 

 *	- When cleaning memory region:

 * 		@code

 * 			if (clean region > clean threshold)

 * 				clean entire cache

 * 			else

 * 				clean the specified region

 * 		@endcode

 * 

 *	- When invalidating and cleaning memory region:

 * 		@code

 * 			if (invalidate and clean region > invalidate and clean threshold)

 * 				invalidate and clean entire cache

 * 			else

 * 				invalidate and clean the specified region

 * 		@endcode

 * 

 * This function returns the current threshold values for the specified type of cache. Threshold

 * values could be changed by Cache::SetThresholds.

 * 

 * @param aCacheType 	Specifies which type of cache the thresholds belong to:

 * 		- KCacheSelectI 		Instruction Cache

 *		- KCacheSelectD 		Data Cache. For ARMv7 platforms, it specifies Point-of-Coherency thresholds.

 * 								These threshold are relevant for DMA related cache maintenance.

 * 		- KCacheSelectD_IMB 	Data Cache for the Point-of-Unification.

 * 								These threshold are relevant for Instruction Memory Barrier (IMB).

 * 		- KCacheSelectAltD 		Alternative Data Cache. This type of cache is depricated on today's platforms.

 * 		- KCacheSelect_L2		External Cache, such as L210, L220 or PL310.

 * @param aThresholds 	If KErrNone is returned, holds thresholds values(in bytes) for the specified cache.

 * 

 * @return 						KErrNone if successfull or KErrNotSupported if aCacheType is not valid on the

 * 								running platform.

 * 

 * @see Cache::SetThresholds

 * @see TCacheThresholds

 * @released 9.3

 */

	IMPORT_C static TInt GetThresholds(TCacheThresholds& aThresholds, TUint aCacheType);

/*

 * Sets threshold values for the specified cache. @See GetThresholds for details.

 * 

 * @param aCacheType 	Specifies which type of cache the thresholds belong to:

 * 		- KCacheSelectI 		Instruction Cache

 *		- KCacheSelectD 		Data Cache. For ARMv7 platforms, it specifies Point-of-Coherency thresholds.

 * 								These threshold are relevant for DMA related cache maintenance.

 * 		- KCacheSelectD_IMB 	Data Cache for the Point-of-Unification.

 * 								These threshold are relevant for Instruction Memory Barrier (IMB).

 * 		- KCacheSelectAltD 		Alternative Data Cache. This type of cache is depricated on today's platforms.

 * 		- KCacheSelect_L2		External Cache, such as L210, L220 or PL310.

 * @param aThresholds 			New threshold values (in bytes) for the cache..

 * 

 * @return 						KErrNone if successfull or KErrNotSupported if aCacheType is not valid on the

 * 								running platform.

 * 

 * @see Cache::GetThresholds

 * @see TCacheThresholds

 * @released 9.3

 */

	IMPORT_C static TInt SetThresholds(const TCacheThresholds& aThresholds, TUint aCacheType);

/*

 * Returns the required alignment for fully cached memory buffer used in DMA transfer.

 * Use this value to separate DMA from non-DMA memory.

 * 

 * Note that a single DMA transfer can still start/stop from any memory location. However,

 * the content of memory just before (if start address is unaligned) or after (if end address

 * is unaligned) DMA buffer may be corrupted.

 * 

 * Here is an example of code that allocates DMA buffer from the heap.

 * 

 * @code

 * 	class DMABufferAlloc

 *		{

 * 	public:

 * 		DMABufferAlloc():iPtr(NULL){};

 * 

 * 		//Return value is guaranteed to be aligned.

 *		TAny* Alloc(TInt aSize)

 * 			{

 * 			TInt alignmentMask = Cache::DmaBufferAlignment()-1;

 * 			NKern::ThreadEnterCS();

 * 

 * 			// Assume that the return value of Kern::Alloc is unaligned.

 *			// Allocate sufficient memory to cover the worst case, for example:

 *			// Alignment = 32, aSize = 2. If (iPtr==31) 64 bytes are required   

 *			iPtr = Kern::Alloc( (aSize+2*alignmentMask) & ~alignmentMask);

 * 

 * 			NKern::ThreadLeaveCS();

 * 

 *			//Return the first aligned location in the allocated buffer.

 *			return (TAny*)(((TInt)iPtr + alignmentMask) & ~alignmentMask);

 *			}

 * 

 *		void Free()

 *			{

 *			NKern::ThreadEnterCS();

 *			Kern::Free(iPtr);

 *			iPtr = NULL;

 *			NKern::ThreadLeaveCS();

 *			}

 *

 * 		~DMABufferAlloc()

 * 			{

 *			if (iPtr)

 *			Free();

 *			};

 * 

 *	private:

 *		TAny* iPtr;

 * 		};

 *	@codeend

 */

	IMPORT_C static TUint DmaBufferAlignment();

	};

#endif // def __CACHE_H__