sl@0: // Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32/include/e32shbuf.h
sl@0: // Shareable Data Buffers
sl@0: 
sl@0: /**
sl@0: 	@file
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: 
sl@0: #ifndef E32SHBUF_H
sl@0: #define E32SHBUF_H
sl@0: 
sl@0: #include <e32shbufcmn.h>
sl@0: #include <e32cmn.h>
sl@0: 
sl@0: /**
sl@0: 	Specifies characteristics of the pool to be created.
sl@0: 
sl@0: 	@see RShPool::Create()
sl@0: 
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: 
sl@0: class TShPoolCreateInfo
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Enumeration type to create a pool with page-aligned buffers.
sl@0: 
sl@0: 	The buffers in the pool will be at least the size of an MMU page,
sl@0: 	aligned to an MMU page, and may be mapped in and out of a process's
sl@0: 	address space independently.
sl@0: 	*/
sl@0: 	enum TShPoolPageAlignedBuffers
sl@0: 		{
sl@0: 		EPageAlignedBuffer = EShPoolPageAlignedBuffer,
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	Enumeration type to create a pool with non-page-aligned buffers.
sl@0: 
sl@0: 	The buffers in the pool do not have any size or alignment restrictions beyond
sl@0: 	the iAlignment specified in TShPoolInfo.
sl@0: 
sl@0: 	The whole pool will always mapped into a process's address space.
sl@0: 	*/
sl@0: 	enum TShPoolNonPageAlignedBuffers
sl@0: 		{
sl@0: 		ENonPageAlignedBuffer = EShPoolNonPageAlignedBuffer,
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the buffer size and initial number of committed buffers for a pool
sl@0: 	with page-aligned buffers.
sl@0: 
sl@0: 	@param aFlag			Page-aligned buffers
sl@0: 	@param aBufSize			Size in bytes of each buffer within the pool
sl@0: 	@param aInitialBufs		Initial number of buffers allocated to the pool
sl@0: 	*/
sl@0: 	IMPORT_C TShPoolCreateInfo(TShPoolPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs);
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the buffer size, initial number of committed buffers, and buffer
sl@0: 	alignment for a pool with non-page-aligned buffers.
sl@0: 
sl@0: 	@param aFlag			Non-page aligned buffers
sl@0: 	@param aBufSize			Size in bytes of each buffer within the pool
sl@0: 	@param aInitialBufs		Initial number of buffers allocated to the pool
sl@0: 	@param aAlignment		Alignment of the start of each buffer in the pool (shift/log2 value)
sl@0: 	*/
sl@0: 	IMPORT_C TShPoolCreateInfo(TShPoolNonPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs, TUint aAlignment);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the sizing attributes for the pool, allowing it to grow and
sl@0: 	shrink automatically.
sl@0: 
sl@0: 	If either aGrowTriggerRatio or aGrowByRatio is 0, no automatic growing or
sl@0: 	shrinking will be performed.
sl@0: 
sl@0: 	@param aMaxBufs					The maximum number of buffers that the pool
sl@0: 									can grow to.  This value must not be less than
sl@0: 									aInitialBufs.
sl@0: 
sl@0: 	@param aGrowTriggerRatio		This specifies when to grow the pool.  When the
sl@0: 									proportion of free buffers in the pool drops below
sl@0: 									this value, the pool will be grown.  This value is
sl@0: 									expressed as a 32-bit fixed-point number, where
sl@0: 									the binary point is defined to be between bits
sl@0: 									7 and 8 (where the least-significant bit is defined
sl@0: 									as bit 0).  (This format is also known as a Q8, or
sl@0: 									fx24.8 number, or alternatively as the value * 256.)
sl@0: 									It must represent a value < 1 (i.e. must be < 256).
sl@0: 
sl@0: 	@param aGrowByRatio				The proportion to grow the pool by each time,
sl@0: 									expressed as a 32-bit fx24.8 fixed-point number, in
sl@0: 									the same way as aGrowTriggerRatio.
sl@0: 
sl@0: 	@param aShrinkHysteresisRatio	The hysteresis value to ensure that a pool is not
sl@0: 									automatically shrunk immediately after it is grown.
sl@0: 									Automatic shrinking will only happen when there are
sl@0: 									(aGrowTriggerRatio + aGrowByRatio) * aShrinkHysteresisRatio *
sl@0: 									(total buffers in the pool) free buffers left in the pool.
sl@0: 									This is a 32-bit fx24.8 fixed-point number in the
sl@0: 									same way as aGrowTriggerRatio and aGrowByRatio.
sl@0: 									It must represent a value > 1 (i.e. must be > 256).
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetSizingAttributes(TUint aMaxBufs, TUint aGrowTriggerRatio,
sl@0: 										TUint aGrowByRatio, TUint aShrinkHysteresisRatio);
sl@0: 
sl@0: 	/**
sl@0: 	Ensures that each buffer is mapped into at most one process address space
sl@0: 	at a time.
sl@0: 
sl@0: 	If this is set for a non-page-aligned pool, the pool creation will fail.
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetExclusive();
sl@0: 
sl@0: 	/**
sl@0: 	Specifies that unmapped guard pages are inserted between each buffer in a process's
sl@0: 	address space.
sl@0: 
sl@0: 	If this is set for a non-page-aligned pool, the pool creation will fail.
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetGuardPages();
sl@0: 
sl@0: private:
sl@0: 	friend class RShPool;
sl@0: 	TShPoolCreateInfo();		// hide the default constructor
sl@0: 
sl@0: 	TShPoolInfo iInfo;
sl@0: };
sl@0: 
sl@0: 
sl@0: /**
sl@0: A handle to a pool of buffers.
sl@0: 
sl@0: Pools can be created by either user-side or kernel-side components.
sl@0: 
sl@0: Upon receiving a pool handle the recipient must map either whole or part of the pool
sl@0: memory into its address space.
sl@0: 
sl@0: When finished with the pool, the recipient must Close() it: this invalidates the handle.
sl@0: Any further attempt to use it will panic the thread.
sl@0: 
sl@0: All pools are reference-counted and will only disappear after all users have closed them.
sl@0: 
sl@0: These handles are process-relative.
sl@0: 
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: class RShPool : public RHandleBase
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C RShPool();
sl@0: 
sl@0: 	/**
sl@0: 	Creates a pool of buffers with the required attributes and maps the memory to this process.
sl@0: 	The RShPool object is changed by this call (iHandle is set).
sl@0: 
sl@0: 	@param aBufInfo		A structure describing the parameters of the pool to be created.
sl@0: 						See TShPoolCreateInfo.
sl@0: 
sl@0: 	@param aFlags		Flags to modify the behaviour of the handle.  This should be a bit-wise
sl@0: 						OR of values from TShPoolHandleFlags.
sl@0: 
sl@0: 	@return the handle (>= 0) if successful, otherwise one of the system-wide error codes.
sl@0: 
sl@0: 	@see TShPoolCreateInfo
sl@0: 	@see TShPoolClientFlags
sl@0: 	*/
sl@0: 	IMPORT_C TInt Create(const TShPoolCreateInfo& aBufInfo, TUint aFlags);
sl@0: 
sl@0: 	/**
sl@0: 	Retrieves information about the pool.
sl@0: 
sl@0: 	@param aInfo returns pool info.
sl@0: 	*/
sl@0: 	IMPORT_C void GetInfo(TShPoolInfo& aInfo) const;
sl@0: 
sl@0: 	/**
sl@0: 	Specifies how many buffers of a page-aligned pool this process will require
sl@0: 	concurrent access to.
sl@0: 
sl@0: 	This determines how much of the process's address space will be allocated for
sl@0: 	buffers of this pool.
sl@0: 
sl@0: 	@param aCount		Specifies the number of buffers to map into the process's virtual address space
sl@0: 						(-1 specifies that all buffers will be mapped).
sl@0: 
sl@0: 	@param aAutoMap		ETrue specifies that an allocated or received buffer
sl@0: 	                    will be automatically mapped into the process's address space.
sl@0: 
sl@0: 	@pre the pool's buffers must be page-aligned
sl@0: 
sl@0: 	@return KErrNone if successful, otherwise one of the system-wide error codes.
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetBufferWindow(TInt aCount, TBool aAutoMap);
sl@0: 
sl@0: 	/**
sl@0: 	@return the number of free buffers in the pool
sl@0: 	*/
sl@0: 	IMPORT_C TUint FreeCount() const;
sl@0: 
sl@0: 	/**
sl@0: 	Requests a notification when the number of free buffers in the pool falls to the
sl@0: 	level specified.
sl@0: 
sl@0: 	@param aFreeBuffers	Specifies the number of free buffers that will trigger completion of the notification.
sl@0: 	@param aStatus		Status request to be completed when the condition is met.
sl@0: 	*/
sl@0: 	IMPORT_C void RequestLowSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);
sl@0: 
sl@0: 	/**
sl@0: 	Requests a notification when the number of free buffers in the pool rises to the
sl@0: 	level specified.
sl@0: 
sl@0: 	@param aFreeBuffers	Specifies the number of free buffers that will trigger completion of the notification.
sl@0: 	@param aStatus		Status request to be completed when the condition is met.
sl@0: 	*/
sl@0: 	IMPORT_C void RequestFreeSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);
sl@0: 
sl@0: 	/**
sl@0: 	Cancels a low space notification request.
sl@0: 
sl@0: 	The status request completes with KErrCancel.
sl@0: 
sl@0: 	@param aStatus		The status request whose notification is to be cancelled.
sl@0: 	*/
sl@0: 	IMPORT_C void CancelLowSpaceNotification(TRequestStatus& aStatus);
sl@0: 
sl@0: 	/**
sl@0: 	Cancels a free space notification request.
sl@0: 
sl@0: 	The status request completes with KErrCancel.
sl@0: 
sl@0: 	@param aStatus		The status request whose notification is to be cancelled.
sl@0: 	*/
sl@0: 	IMPORT_C void CancelFreeSpaceNotification(TRequestStatus& aStatus);
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: A handle to a shared buffer within a pool.
sl@0: 
sl@0: A user-side or kernel-side component allocates the buffer and then passes the
sl@0: handle to the recipient.
sl@0: 
sl@0: Upon receiving a buffer handle. the recipient may map the buffer memory into its address space if not already done so.
sl@0: 
sl@0: When finished with the buffer, the recipient must Close() the handle.  This
sl@0: invalidates the handle; any further attempt to use it will panic the thread.
sl@0: 
sl@0: Buffers are reference-counted and will only be freed and returned to the pool
sl@0: when all users have closed them.
sl@0: 
sl@0: These handles are process-relative.
sl@0: 
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: class RShBuf  : public RHandleBase
sl@0: 	{
sl@0: public:
sl@0: 	inline RShBuf() : iBase(0), iSize(0) {};
sl@0: 
sl@0: 	IMPORT_C void Close();
sl@0: 
sl@0: 	/**
sl@0: 	Allocates a shared data buffer.
sl@0: 
sl@0: 	By default this method will return immediately with KErrNoMemory if no buffer is
sl@0: 	available on the pool's free list, even if the pool could grow automatically.
sl@0: 
sl@0: 	By default it will also map the allocated buffer into the calling process's address space.
sl@0: 
sl@0: 	Setting EShPoolAllocCanWait in the flags indicates that the caller is prepared to
sl@0: 	wait while the pool is grown if a buffer is not immediately available on the free list.
sl@0: 
sl@0: 	Setting EShPoolAllocNoMap in the flags indicates that the caller does not want the
sl@0: 	buffer to be automatically mapped into its address space.  This can improve performance
sl@0: 	on buffers from page-aligned pools if the caller will not need to access the data in the
sl@0: 	buffer (e.g. if it will just be passing it on to another component).  This only prevents
sl@0: 	mapping if the pool is set to not automatically map buffers into processes' address space.
sl@0: 
sl@0: 	@param aPool	Pool handle
sl@0: 	@param aFlags	Bitwise OR of values from TShPoolAllocFlags to specify non-default behaviour.
sl@0: 
sl@0: 	@return KErrNone if successful, otherwise one of the system-wide error codes.
sl@0: 
sl@0: 	@see TShPoolAllocFlags
sl@0: 	*/
sl@0: 	IMPORT_C TInt Alloc(RShPool& aPool, TUint aFlags = 0);
sl@0: 
sl@0: 	/**
sl@0: 	Maps the buffer into the calling process's virtual address space if not already done.
sl@0: 
sl@0: 	It is not necessary to call this method on buffers from non-page-aligned pools, although
sl@0: 	it will cause no harm to do so (and will result in KErrNone being returned).
sl@0: 
sl@0: 	It is not necessary to call this method on buffers from page-aligned pools returned by
sl@0: 	Alloc() unless EShPoolAllocNoMap was specified.
sl@0: 
sl@0: 	@param aReadOnly	Indicates whether the buffer should be mapped as read-only.  The default is
sl@0: 	                    that of pool in the clients address space.
sl@0: 
sl@0: 	@return KErrNone if successful, otherwise one of the system-wide error codes.
sl@0: 	*/
sl@0: 	IMPORT_C TInt Map(TBool aReadOnly = EFalse);
sl@0: 
sl@0: 	/**
sl@0: 	Unmaps the buffer from the calling process's virtual address space.
sl@0: 
sl@0: 	@return KErrNone if successful, otherwise one of the system-wide error codes.
sl@0: 	*/
sl@0: 	IMPORT_C TInt UnMap();
sl@0: 
sl@0: 	/**
sl@0: 	@return The size, in bytes, of this buffer (and every other buffer in the pool).
sl@0: 	*/
sl@0: 	IMPORT_C TUint Size();
sl@0: 
sl@0: 	/**
sl@0: 	@return A pointer to the start of the buffer.
sl@0: 	*/
sl@0: 	IMPORT_C TUint8* Ptr();
sl@0: 
sl@0: private:
sl@0: 	friend class RShPool;
sl@0: 	TLinAddr iBase;
sl@0: 	TUint iSize;
sl@0: 	TUint iSpare1;
sl@0: 	TUint iSpare2;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif	// E32SHBUF_H