CeFreeAsynchronousBuffer

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This function frees any resources that were allocated by CeAllocAsynchronousBuffer. It performs any required write-back to the source buffer due to out descriptors ARG_IO* or ARG_O*.

For more information about argument descriptors see MarshalledBuffer_t.

Syntax

HRESULT CeFreeAsynchronousBuffer(
  PVOID pDestAsyncMarshalled,
  PVOID pSrcSyncMarshalled,
  DWORD cbSrc,
  DWORD ArgumentDescriptor
);

Parameters

• pDestAsyncMarshalled
  [in] Pointer to the buffer that was allocated by CeAllocAsynchronousBuffer.

• pSrcSyncMarshalled
  [in] Source pointer that was passed to CeAllocAsynchronousBuffer.

• cbSrc
  [in] Buffer size that was passed to CeAllocAsynchronousBuffer.

• ArgumentDescriptor
  [in] Descriptor that was passed to CeAllocAsynchronousBuffer.

  If you are running inside the kernel process and you are using an ARM microprocessor with a virtually tagged cache, you can pass MARSHAL_FORCE_ALIAS as the ArgumentDescriptor. On all other CPUs, inside the kernel process, CeAllocAsynchronousBuffer always creates an alias to the memory with VirtualCopy. On ARM CPUs that use a virtually tagged cache, inside the kernel process, CeAllocAsynchronousBuffer creates a duplicate copy of the memory on the heap by default. On large buffers, creating the duplicate heap can affect performance. To prevent duplication, pass the MARSHAL_FORCE_ALIAS flag to cause CeAllocAsynchronousBuffer to create an alias instead. However, the creation of aliased memory on ARM CPUs that use a virtually tagged cache causes both the source and destination memory to be accessed as uncached, until the alias is destroyed by CeFreeAsynchronousBuffer. This means that the memory accesses become slower at both the source and destination.

  Do not use the MARSHAL_FORCE_ALIAS flag unless you are using buffers greater than 16 KB.

  On all CPUs, inside user-mode processes, CeAllocAsynchronousBuffer always creates a duplicate of the memory, regardless of whether the MARSHAL_FORCE_ALIAS flag is passed. There is no way to force the creation of an alias from user mode.

  If you pass MARSHAL_FORCE_ALIAS to CeAllocAsynchronousBuffer, you should also pass it when you call CeFlushAsynchronousBuffer and CeFreeAsynchronousBuffer. Not passing it can cause the system to become unresponsive or resource leaks.

Return Value

• E_FAIL
  Required write-back could not be performed. If this error occurs, resources are still released, and the marshaled pointer is no longer accessible.

• S_OK
  The allocation and duplication, if necessary, succeeded.

Remarks

This function is protected by __try/__except so that it does not to throw an exception while accessing the input pointer pSrcSyncMarshalled.

Use the SUCCEEDED and FAILED macros to test the return value of this function.

Requirements

See Also

Reference

Kernel Buffer Marshaling Functions
MarshalledBuffer_t
AsynchronousBuffer_t
CeAllocAsynchronousBuffer
CeFlushAsynchronousBuffer

Other Resources

Kernel Migration