FCL/sf/os/kernelhwsrv: comparison kernel/eka/kernel/sutils.cpp

equal deleted inserted replaced

-:0bf4040442f9
+:46fffbe7b5a7
 	TClientRequest::CallbackFunc(aData, aReason);
 	}
 // Implementation of kernel pin APIs
-/*
+/**
 Create an object which can be used to pin virtual memory.
 @param aPinObject A reference to a pointer which is set to the newly-created object on success.
 @return KErrNone, if successful, otherwise one of the other system-wide error codes.
 @pre Suitable for use in a device driver.
 @see Kern::DestroyVirtualPinObject()
 @prototype
-@internalTechnology
 */
 EXPORT_C TInt Kern::CreateVirtualPinObject(TVirtualPinObject*& aPinObject)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::CreateVirtualPinObject");
 	return M::CreateVirtualPinObject(aPinObject);
 	}
-/*
+/**
 Pin an area of virtual memory.
 The act of pinning virtual memory means that the memory in the specified virtual address range is
 guaranteed to remain in system RAM while it is pinned, unless it is decommited.  The actual physical
 RAM used is not guaranteed to stay the same however, as it could be replaced in the process of RAM
 @pre Can be used in a device driver.
 @see Kern::UnpinVirtualMemory()
 @prototype
-@internalTechnology
 */
 EXPORT_C TInt Kern::PinVirtualMemory(TVirtualPinObject* aPinObject, TLinAddr aStart, TUint aSize, DThread* aThread)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::PinVirtualMemory");
 	if (aThread == NULL)
 	TInt r = M::PinVirtualMemory(aPinObject, aStart, aSize, aThread);
 	NKern::ThreadLeaveCS();
 	return r;
 	}
-/*
+/**
 Pin an area of virtual memory.
 The act of pinning virtual memory means that the memory in the specified virtual address range is
 guaranteed to remain in system RAM while it is pinned, unless it is decommited.  The actual phyiscal
 RAM used is not guaranteed to stay the same however, as it could be replaced in the process of RAM
 client thread, so that when it is accessed from a different thread later on (for example from a DFC
 thread) there is no possibility of taking page faults.
 Note that this operation may fail with KErrNoMemory.
+Note - Instances of TVirtualPinObject are not protected from concurrent operations being performed
+with them by separate threads i.e. it is the responsibility of the creator of a TVirtualPinObject
+instance to ensure that it will not be pinned, unpinned or destroyed by more than one thread at a time.
 @param aPinObject  A virtual pin object previously created by calling Kern::CreateVirtualPinObject().
 @param aDes	       A TClientBuffer object representing a client descriptor to pin.
 @param aThread	   The thread that owns the memory to pin, or NULL to use the current thread.
 @return KErrNone, if successful, otherwse one of the other system-wide error codes.
 @pre Can be used in a device driver.
 @see Kern::UnpinVirtualMemory()
 @prototype
-@internalTechnology
 */
 EXPORT_C TInt Kern::PinVirtualMemory(TVirtualPinObject* aPinObject, const TClientBuffer& aDes, DThread* aThread)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::PinVirtualMemory");
 	if (aThread == NULL)
 	NKern::ThreadEnterCS();
 	TInt r = M::PinVirtualMemory(aPinObject, (TLinAddr)aDes.DataPtr(), length, aThread);
 	NKern::ThreadLeaveCS();
 	return r;
 	}
-/*
+/**
 Create a pin object and then pin an area of virtual memory in the current address space.  If
 an error occurs then no pin object will exist
 The act of pinning virtual memory means that the memory in the specified virtual address range is
 guaranteed to remain in system RAM while it is pinned, unless it is decommited.  The actual physical
 client thread, so that when it is accessed from a different thread later on (for example from a DFC
 thread) there is no possibility of taking page faults.
 Note that this operation may fail with KErrNoMemory.
+Note - Instances of TVirtualPinObject are not protected from concurrent operations being performed
+with them by separate threads i.e. it is the responsibility of the creator of a TVirtualPinObject
+instance to ensure that it will not be pinned, unpinned or destroyed by more than one thread at a time.
 @param aPinObject	A reference to a pointer which is set to the newly-created object on success.
 @param aStart		The start address of the memory to pin.
 @param aSize		The size of the memory to pin in bytes.
 @return KErrNone, if successful, otherwise one of the other system-wide error codes.
 @see Kern::UnpinVirtualMemory()
 @see Kern::DestroyVirtualPinObject()
 @prototype
-@internalTechnology
 */
 EXPORT_C TInt Kern::CreateAndPinVirtualMemory(TVirtualPinObject*& aPinObject, TLinAddr aStart, TUint aSize)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::CreateAndPinVirtualMemory");
 	return M::CreateAndPinVirtualMemory(aPinObject, aStart, aSize);
 	}
-/*
+/**
 Unpin an area of memory previously pinned by calling Kern::PinVirtualMemory().
 @param aPinObject  The virtual pin object used to pin the memory.
 @pre Interrupts must be enabled.
 @pre Can be used in a device driver.
 @see Kern::PinVirtualMemory()
 @prototype
-@internalTechnology
 */
 EXPORT_C void Kern::UnpinVirtualMemory(TVirtualPinObject* aPinObject)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::UnpinVirtualMemory");
 	NKern::ThreadEnterCS();
 	M::UnpinVirtualMemory(aPinObject);
 	NKern::ThreadLeaveCS();
 	}
-/*
+/**
 Dispose of a virtual pin object which is no longer required.
 Any memory pinned by the object is unpinned first.
 @param	aPinObject	A reference to a pointer to the pin object to destroy.
 @pre Suitable for use in a device driver.
 @see Kern::CreateVirtualPinObject()
 @prototype
-@internalTechnology
 */
 EXPORT_C void Kern::DestroyVirtualPinObject(TVirtualPinObject*& aPinObject)
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::DestroyVirtualPinObject");
 	M::DestroyVirtualPinObject(aPinObject);
 	}
 /**
-Creates an object which is used to pin physical memory. Suported by Kernel running flexible memory model.
+Creates an object which is used to pin physical memory. Supported by Kernel running flexible memory model.
+Note - Instances of TPhysicalPinObject are not protected from concurrent operations being performed
+with them by separate threads i.e. it is the responsibility of the creator of a TPhysicalPinObject
+instance to ensure that it will not be pinned, unpinned or destroyed by more than one thread at a time.
 @param aPinObject A reference to a pointer which is set to the newly-created object on success.
 @return KErrNotSupported on memory models other then flexible.
 		KErrNone, if successful, otherwise one of the other system-wide error codes.
 	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::CreatePhysicalPinObject");
 	return M::CreatePhysicalPinObject(aPinObject);
 	}
 /**
-Pins an area of physical memory. Suported by Kernel running flexible memory model.
+Pins an area of physical memory. Supported by Kernel running flexible memory model.
-The physical memory to pin is defined by its existing virtual mapping (by aLinAddr, aSize & aThread parameters).
+The physical memory to pin is defined by its existing virtual mapping (by aStart, aSize & aThread parameters).
-On return, aPhysicalAddress will hold physical address (if memory is mapped contigiously) and aPhysicalPageList
+On return, aAddress will hold physical address (if memory is mapped contigiously) and aPages
 area will be populated with the list of physical pages of the mapping. aColour will hold the mapping colour
 of the first physical page in the mapping.
 This operation is provided to enable device drivers to operate DMA transfers on memory which is not mapped to
 Kernel address space (but to user client's, instead).
 The act of pinning physical memory means that it is guaranteed to be excluded from RAM defragmentation.
-However, it can still be the subject of data paging. Physically pinned memory is also guaranteed not to be
+However, it can still be the subject of demand paging. Physically pinned memory is also guaranteed not to be
 reused for some other purpose - even if the process owning the memory decommits it or terminates.
 Note that this operation may fail with KErrNoMemory.
 @param aPinObject		A physical pin object previously created by calling Kern::CreatePhysicalPinObject().
-@param aLinAddr			Virtual address of memory to pin.
+@param aStart			Virtual address of memory to pin.
 @param aSize			The length (in bytes) of memory to pin.
 @param aThread	   		The thread that owns the memory to pin, or NULL to use the current thread.
 @param aReadOnlyMemory  Set to ETrue if the content of physical memory is not going to change while being
 						pinned, e.g. if it is DMA copied into H/W. Set to EFalse otherwise.
 						Setting this argument to ETrue will improve the performance when/if memory is paged out.
 @pre No fast mutex can be held.
 @pre Call in a thread context.
 @pre Can be used in a device driver.
 @see Kern::UnpinPhysicalMemory()
-@see Cache::SyncPhysicalMemoryBeforeDmaWrite
+@see Cache::SyncPhysicalMemoryBeforeDmaWrite()
-@see Cache::SyncPhysicalMemoryBeforeDmaRead
+@see Cache::SyncPhysicalMemoryBeforeDmaRead()
-@see Cache::SyncPhysicalMemoryAfterDmaRead
+@see Cache::SyncPhysicalMemoryAfterDmaRead()
 @prototype
 */
 EXPORT_C TInt Kern::PinPhysicalMemory(TPhysicalPinObject* aPinObject, TLinAddr aStart, TUint aSize, TBool aReadOnlyMemory,
 				 				TPhysAddr& aAddress, TPhysAddr* aPages, TUint32& aMapAttr, TUint& aColour, DThread* aThread)
 	{
 	M::UnpinPhysicalMemory(aPinObject);
 	NKern::ThreadLeaveCS();
 	return KErrNone;
 	}
-/*
+/**
 Dispose of a physical pin object which is no longer required.
 Any memory pinned by the object is unpinned first.
 @param	aPinObject	A reference to a pointer to the pin object to destroy.
 	{
 	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::DestroyPhysicalPinObject");
 	M::DestroyPhysicalPinObject(aPinObject);
 	return KErrNone;
 	}
+/**
+Creates an object which is used to map user side memory in the kernel address space
+and also physically pin the memory. Supported by Kernel running the flexible memory model.
+When the map object will only be used to map non-demand paged memory aMaxReserveSize can be used
+to pre-reserve the resources that would be required for Kern::MapAndPinMemory().  This will
+prevent Kern::MapAndPinMemory() failing due to low memory and will reduce the time to execute
+Kern::MapAndPinMemory() but only when the mapping object is used to map non-demand paged memory.
+Note - Instances of TKernelMapObject are not protected from concurrent operations being performed
+with them by separate threads i.e. it is the responsibility of the creator of a TKernelMapObject
+instance to ensure that it will not be mapped, unmapped or destroyed by more than one thread at a time.
+@param aMapObject 		A reference to a pointer which is set to the newly created object on success.
+@param aMaxReserveSize	When set to zero (the default) the resources required to map memory will be
+						allocated when Kern::MapAndPinMemory() is invoked with the newly created map
+						object.	 When not set to zero all resources required for the mapping object
+						to map up to aMaxReserveSize bytes will be reserved when creating the mapping
+						object.  When the mapping object is used to map non-demand paged memory,
+						this will prevent Kern::MapAndPinMemory() from returning KErrNoMemory
+						when invoked with the mapping object.  However, it will limit the mapping
+						object to being able to map a maximum of aMaxReserveSize bytes and may also
+						waste resources if it is used to map less than aMaxReserveSize bytes.
+@return KErrNotSupported on memory models other then flexible.
+		KErrNone, if successful, otherwise one of the other system-wide error codes.
+@pre Calling thread must be in a critical section
+@pre Interrupts must be enabled.
+@pre Kernel must be unlocked.
+@pre No fast mutex can be held.
+@pre Call in a thread context.
+@pre Suitable for use in a device driver.
+@see Kern::DestroyKernelMapObject()
+@see Kern::MapAndPinMemory()
+@prototype
+*/
+EXPORT_C TInt Kern::CreateKernelMapObject(TKernelMapObject*& aMapObject, TUint aMaxReserveSize)
+	{
+	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::CreateKernelMapObject");
+	return M::CreateKernelMapObject(aMapObject, aMaxReserveSize);
+	}
+/**
+Maps an area of memory into the kernel address space and physically pins it. Supported by Kernel running
+the flexible memory model.
+The memory to map and pin is defined by its existing virtual mapping (via the aStart, aSize & aThread parameters).
+On return, if aPages is not NULL, aPages will be populated with the list of physical pages mapped.
+This operation is provided to enable device drivers to not only operate DMA transfers on memory which was not
+originally mapped to the kernel address space (but to user client's, instead) but also read or modify the data
+from kernel context, e.g. a DFC.
+The act of mapping the memory means that it is guaranteed to be excluded from RAM defragmentation.  The new mapping
+will also be protected from the effects of demand paging.  Once mapped the memory is also guaranteed not to be reused for
+some other purpose - even if the process owning the memory decommits it or terminates.
+Note that this operation may fail with KErrNoMemory if the kernel mapping object was created with aMaxReserveSize==0
+or the memory to be mapped is demand paged.
+@param aMapObject		A kernel map object previously created by calling Kern::CreateKernelMapObject().
+@param aThread	   		The thread that owns the memory to map, or NULL to use the current thread.
+@param aStart			Virtual address of memory to map.
+@param aSize			The length (in bytes) of memory to map.
+@param aMapAttributes	A bit mask of TKernelMapAttributes attributes for the mapping.
+@param aKernelAddr		Set to the base linear address of the new kernel mapping.  This is the address to use when accessing
+						the memory from kernel side and to pass to cache maintence operations before and after performing
+						DMA operations.
+@param aPages			Points to area of TPhysAddr which will on exit hold the addresses of the physical pages contained
+						in the specified region. The array must be large enough to hold the whole list of pages in the region.
+						Set aPages to NULL if the physical addresses of the pages being mapped are not required.
+@return 				KErrNone, if successful,
+						KErrInUse if aMapObject is already mapping some memory,
+						KErrArgument if aSize is larger than the argument aMaxReserveSize of Kern::CreateKernelMapObject()
+						when creating aMapObject or aMapAttributes has invalid bits set.
+						KErrNotSupported on memory models other then flexible.
+						Otherwise one of the other system-wide error codes.
+@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.
+@see Kern::UnmapAndUnpinMemory()
+@see Cache::SyncMemoryBeforeDmaWrite()
+@see Cache::SyncMemoryBeforeDmaRead()
+@see Cache::SyncMemoryAfterDmaRead()
+@prototype
+*/
+EXPORT_C TInt Kern::MapAndPinMemory(TKernelMapObject* aMapObject, DThread* aThread, TLinAddr aStart, TUint aSize,
+									TUint aMapAttributes, TLinAddr& aKernelAddr, TPhysAddr* aPages)
+	{
+	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::MapAndPinMemory");
+	if (~EKernelMap_ValidMask & aMapAttributes)
+		{// Invalid mapping attribute flags set.
+		return KErrArgument;
+		}
+	if (aThread == NULL)
+		aThread = TheCurrentThread;
+	if (aSize == 0)
+		return KErrNone;
+	NKern::ThreadEnterCS();
+	TInt r = M::MapAndPinMemory(aMapObject, aThread, aStart, aSize, aMapAttributes, aKernelAddr, aPages);
+	NKern::ThreadLeaveCS();
+	return r;
+	}
+/**
+Unmaps and unpins an area of memory previously mapped by calling Kern::MapAndPinMemory().
+@param aMapObject  The kernel mapping object used to map and pin the memory.
+@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.
+@see Kern::MapAndPinMemory()
+@prototype
+*/
+EXPORT_C void Kern::UnmapAndUnpinMemory(TKernelMapObject* aMapObject)
+	{
+	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::UnmapAndUnpinMemory");
+	NKern::ThreadEnterCS();
+	M::UnmapAndUnpinMemory(aMapObject);
+	NKern::ThreadLeaveCS();
+	}
+/**
+Dispose of a kernel mapping object which is no longer required.
+Any memory mapped and pinned by the object is unmapped and unpinned first.
+@param	aMapObject	A reference to a pointer to the mapping object to destroy.
+					This pointer will be set to NULL on return.
+@pre Calling thread must be in a critical section
+@pre Interrupts must be enabled.
+@pre Kernel must be unlocked.
+@pre No fast mutex can be held.
+@pre Call in a thread context.
+@pre Suitable for use in a device driver.
+@see Kern::CreateKernelMapObject()
+@prototype
+*/
+EXPORT_C void Kern::DestroyKernelMapObject(TKernelMapObject*& aMapObject)
+	{
+	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::DestroyKernelMapObject");
+	M::DestroyKernelMapObject(aMapObject);
+	}

changeset 47	46fffbe7b5a7
parent 45	329ab0095843