--- /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 <e32shbufcmn.h>
+#include <e32cmn.h>
+
+/**
+ 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