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