1 // Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // e32/include/e32shbuf.h

    15 // Shareable Data Buffers

    16 

    17 /**

    18 	@file

    19 	@publishedPartner

    20 	@prototype

    21 */

    22 

    23 #ifndef E32SHBUF_H

    24 #define E32SHBUF_H

    25 

    26 #include <e32shbufcmn.h>

    27 #include <e32cmn.h>

    28 

    29 /**

    30 	Specifies characteristics of the pool to be created.

    31 

    32 	@see RShPool::Create()

    33 

    34 	@publishedPartner

    35 	@prototype

    36 */

    37 

    38 class TShPoolCreateInfo

    39 	{

    40 public:

    41 	/**

    42 	Enumeration type to create a pool with page-aligned buffers.

    43 

    44 	The buffers in the pool will be at least the size of an MMU page,

    45 	aligned to an MMU page, and may be mapped in and out of a process's

    46 	address space independently.

    47 	*/

    48 	enum TShPoolPageAlignedBuffers

    49 		{

    50 		EPageAlignedBuffer = EShPoolPageAlignedBuffer,

    51 		};

    52 

    53 	/**

    54 	Enumeration type to create a pool with non-page-aligned buffers.

    55 

    56 	The buffers in the pool do not have any size or alignment restrictions beyond

    57 	the iAlignment specified in TShPoolInfo.

    58 

    59 	The whole pool will always mapped into a process's address space.

    60 	*/

    61 	enum TShPoolNonPageAlignedBuffers

    62 		{

    63 		ENonPageAlignedBuffer = EShPoolNonPageAlignedBuffer,

    64 		};

    65 

    66 	/**

    67 	Specifies the buffer size and initial number of committed buffers for a pool

    68 	with page-aligned buffers.

    69 

    70 	@param aFlag			Page-aligned buffers

    71 	@param aBufSize			Size in bytes of each buffer within the pool

    72 	@param aInitialBufs		Initial number of buffers allocated to the pool

    73 	*/

    74 	IMPORT_C TShPoolCreateInfo(TShPoolPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs);

    75 

    76 	/**

    77 	Specifies the buffer size, initial number of committed buffers, and buffer

    78 	alignment for a pool with non-page-aligned buffers.

    79 

    80 	@param aFlag			Non-page aligned buffers

    81 	@param aBufSize			Size in bytes of each buffer within the pool

    82 	@param aInitialBufs		Initial number of buffers allocated to the pool

    83 	@param aAlignment		Alignment of the start of each buffer in the pool (shift/log2 value)

    84 	*/

    85 	IMPORT_C TShPoolCreateInfo(TShPoolNonPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs, TUint aAlignment);

    86 

    87 	/**

    88 	Sets the sizing attributes for the pool, allowing it to grow and

    89 	shrink automatically.

    90 

    91 	If either aGrowTriggerRatio or aGrowByRatio is 0, no automatic growing or

    92 	shrinking will be performed.

    93 

    94 	@param aMaxBufs					The maximum number of buffers that the pool

    95 									can grow to.  This value must not be less than

    96 									aInitialBufs.

    97 

    98 	@param aGrowTriggerRatio		This specifies when to grow the pool.  When the

    99 									proportion of free buffers in the pool drops below

   100 									this value, the pool will be grown.  This value is

   101 									expressed as a 32-bit fixed-point number, where

   102 									the binary point is defined to be between bits

   103 									7 and 8 (where the least-significant bit is defined

   104 									as bit 0).  (This format is also known as a Q8, or

   105 									fx24.8 number, or alternatively as the value * 256.)

   106 									It must represent a value < 1 (i.e. must be < 256).

   107 

   108 	@param aGrowByRatio				The proportion to grow the pool by each time,

   109 									expressed as a 32-bit fx24.8 fixed-point number, in

   110 									the same way as aGrowTriggerRatio.

   111 

   112 	@param aShrinkHysteresisRatio	The hysteresis value to ensure that a pool is not

   113 									automatically shrunk immediately after it is grown.

   114 									Automatic shrinking will only happen when there are

   115 									(aGrowTriggerRatio + aGrowByRatio) * aShrinkHysteresisRatio *

   116 									(total buffers in the pool) free buffers left in the pool.

   117 									This is a 32-bit fx24.8 fixed-point number in the

   118 									same way as aGrowTriggerRatio and aGrowByRatio.

   119 									It must represent a value > 1 (i.e. must be > 256).

   120 	*/

   121 	IMPORT_C TInt SetSizingAttributes(TUint aMaxBufs, TUint aGrowTriggerRatio,

   122 										TUint aGrowByRatio, TUint aShrinkHysteresisRatio);

   123 

   124 	/**

   125 	Ensures that each buffer is mapped into at most one process address space

   126 	at a time.

   127 

   128 	If this is set for a non-page-aligned pool, the pool creation will fail.

   129 	*/

   130 	IMPORT_C TInt SetExclusive();

   131 

   132 	/**

   133 	Specifies that unmapped guard pages are inserted between each buffer in a process's

   134 	address space.

   135 

   136 	If this is set for a non-page-aligned pool, the pool creation will fail.

   137 	*/

   138 	IMPORT_C TInt SetGuardPages();

   139 

   140 private:

   141 	friend class RShPool;

   142 	TShPoolCreateInfo();		// hide the default constructor

   143 

   144 	TShPoolInfo iInfo;

   145 };

   146 

   147 

   148 /**

   149 A handle to a pool of buffers.

   150 

   151 Pools can be created by either user-side or kernel-side components.

   152 

   153 Upon receiving a pool handle the recipient must map either whole or part of the pool

   154 memory into its address space.

   155 

   156 When finished with the pool, the recipient must Close() it: this invalidates the handle.

   157 Any further attempt to use it will panic the thread.

   158 

   159 All pools are reference-counted and will only disappear after all users have closed them.

   160 

   161 These handles are process-relative.

   162 

   163 @publishedPartner

   164 @prototype

   165 */

   166 class RShPool : public RHandleBase

   167 	{

   168 public:

   169 	IMPORT_C RShPool();

   170 

   171 	/**

   172 	Creates a pool of buffers with the required attributes and maps the memory to this process.

   173 	The RShPool object is changed by this call (iHandle is set).

   174 

   175 	@param aBufInfo		A structure describing the parameters of the pool to be created.

   176 						See TShPoolCreateInfo.

   177 

   178 	@param aFlags		Flags to modify the behaviour of the handle.  This should be a bit-wise

   179 						OR of values from TShPoolHandleFlags.

   180 

   181 	@return the handle (>= 0) if successful, otherwise one of the system-wide error codes.

   182 

   183 	@see TShPoolCreateInfo

   184 	@see TShPoolClientFlags

   185 	*/

   186 	IMPORT_C TInt Create(const TShPoolCreateInfo& aBufInfo, TUint aFlags);

   187 

   188 	/**

   189 	Retrieves information about the pool.

   190 

   191 	@param aInfo returns pool info.

   192 	*/

   193 	IMPORT_C void GetInfo(TShPoolInfo& aInfo) const;

   194 

   195 	/**

   196 	Specifies how many buffers of a page-aligned pool this process will require

   197 	concurrent access to.

   198 

   199 	This determines how much of the process's address space will be allocated for

   200 	buffers of this pool.

   201 

   202 	@param aCount		Specifies the number of buffers to map into the process's virtual address space

   203 						(-1 specifies that all buffers will be mapped).

   204 

   205 	@param aAutoMap		ETrue specifies that an allocated or received buffer

   206 	                    will be automatically mapped into the process's address space.

   207 

   208 	@pre the pool's buffers must be page-aligned

   209 

   210 	@return KErrNone if successful, otherwise one of the system-wide error codes.

   211 	*/

   212 	IMPORT_C TInt SetBufferWindow(TInt aCount, TBool aAutoMap);

   213 

   214 	/**

   215 	@return the number of free buffers in the pool

   216 	*/

   217 	IMPORT_C TUint FreeCount() const;

   218 

   219 	/**

   220 	Requests a notification when the number of free buffers in the pool falls to the

   221 	level specified.

   222 

   223 	@param aFreeBuffers	Specifies the number of free buffers that will trigger completion of the notification.

   224 	@param aStatus		Status request to be completed when the condition is met.

   225 	*/

   226 	IMPORT_C void RequestLowSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);

   227 

   228 	/**

   229 	Requests a notification when the number of free buffers in the pool rises to the

   230 	level specified.

   231 

   232 	@param aFreeBuffers	Specifies the number of free buffers that will trigger completion of the notification.

   233 	@param aStatus		Status request to be completed when the condition is met.

   234 	*/

   235 	IMPORT_C void RequestFreeSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);

   236 

   237 	/**

   238 	Cancels a low space notification request.

   239 

   240 	The status request completes with KErrCancel.

   241 

   242 	@param aStatus		The status request whose notification is to be cancelled.

   243 	*/

   244 	IMPORT_C void CancelLowSpaceNotification(TRequestStatus& aStatus);

   245 

   246 	/**

   247 	Cancels a free space notification request.

   248 

   249 	The status request completes with KErrCancel.

   250 

   251 	@param aStatus		The status request whose notification is to be cancelled.

   252 	*/

   253 	IMPORT_C void CancelFreeSpaceNotification(TRequestStatus& aStatus);

   254 	};

   255 

   256 

   257 /**

   258 A handle to a shared buffer within a pool.

   259 

   260 A user-side or kernel-side component allocates the buffer and then passes the

   261 handle to the recipient.

   262 

   263 Upon receiving a buffer handle. the recipient may map the buffer memory into its address space if not already done so.

   264 

   265 When finished with the buffer, the recipient must Close() the handle.  This

   266 invalidates the handle; any further attempt to use it will panic the thread.

   267 

   268 Buffers are reference-counted and will only be freed and returned to the pool

   269 when all users have closed them.

   270 

   271 These handles are process-relative.

   272 

   273 @publishedPartner

   274 @prototype

   275 */

   276 class RShBuf  : public RHandleBase

   277 	{

   278 public:

   279 	inline RShBuf() : iBase(0), iSize(0) {};

   280 

   281 	IMPORT_C void Close();

   282 

   283 	/**

   284 	Allocates a shared data buffer.

   285 

   286 	By default this method will return immediately with KErrNoMemory if no buffer is

   287 	available on the pool's free list, even if the pool could grow automatically.

   288 

   289 	By default it will also map the allocated buffer into the calling process's address space.

   290 

   291 	Setting EShPoolAllocCanWait in the flags indicates that the caller is prepared to

   292 	wait while the pool is grown if a buffer is not immediately available on the free list.

   293 

   294 	Setting EShPoolAllocNoMap in the flags indicates that the caller does not want the

   295 	buffer to be automatically mapped into its address space.  This can improve performance

   296 	on buffers from page-aligned pools if the caller will not need to access the data in the

   297 	buffer (e.g. if it will just be passing it on to another component).  This only prevents

   298 	mapping if the pool is set to not automatically map buffers into processes' address space.

   299 

   300 	@param aPool	Pool handle

   301 	@param aFlags	Bitwise OR of values from TShPoolAllocFlags to specify non-default behaviour.

   302 

   303 	@return KErrNone if successful, otherwise one of the system-wide error codes.

   304 

   305 	@see TShPoolAllocFlags

   306 	*/

   307 	IMPORT_C TInt Alloc(RShPool& aPool, TUint aFlags = 0);

   308 

   309 	/**

   310 	Maps the buffer into the calling process's virtual address space if not already done.

   311 

   312 	It is not necessary to call this method on buffers from non-page-aligned pools, although

   313 	it will cause no harm to do so (and will result in KErrNone being returned).

   314 

   315 	It is not necessary to call this method on buffers from page-aligned pools returned by

   316 	Alloc() unless EShPoolAllocNoMap was specified.

   317 

   318 	@param aReadOnly	Indicates whether the buffer should be mapped as read-only.  The default is

   319 	                    that of pool in the clients address space.

   320 

   321 	@return KErrNone if successful, otherwise one of the system-wide error codes.

   322 	*/

   323 	IMPORT_C TInt Map(TBool aReadOnly = EFalse);

   324 

   325 	/**

   326 	Unmaps the buffer from the calling process's virtual address space.

   327 

   328 	@return KErrNone if successful, otherwise one of the system-wide error codes.

   329 	*/

   330 	IMPORT_C TInt UnMap();

   331 

   332 	/**

   333 	@return The size, in bytes, of this buffer (and every other buffer in the pool).

   334 	*/

   335 	IMPORT_C TUint Size();

   336 

   337 	/**

   338 	@return A pointer to the start of the buffer.

   339 	*/

   340 	IMPORT_C TUint8* Ptr();

   341 

   342 private:

   343 	friend class RShPool;

   344 	TLinAddr iBase;

   345 	TUint iSize;

   346 	TUint iSpare1;

   347 	TUint iSpare2;

   348 	};

   349 

   350 

   351 #endif	// E32SHBUF_H