CeFlushAsynchronousBuffer (Compact 2013)

  • Article

3/28/2014

This function flushes any changed data between source and destination buffer allocated by CeAllocAsynchronousBuffer.

For more information about argument descriptors see MarshalledBuffer_t.

Syntax

HRESULT CeFlushAsynchronousBuffer(
  PVOID pDestAsyncMarshalled,
  PVOID pSrcSyncMarshalled,
  PVOID pSrcUnmarshalled,
  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.
  • pSrcUnmarshalled
    [in] Source pointer that was passed to CeOpenCallerBuffer, or NULL if the buffer was an API parameter that never came from a kernel mode call to CeOpenCallerBuffer.
  • cbSrc
    [in] Buffer size that was passed to CeAllocAsynchronousBuffer.

  • ArgumentDescriptor
    [in] Descriptor that was passed to CeAllocAsynchronousBuffer. If the descriptor is ARG_O_PTR, this function writes back data from the asynchronous buffer into the source buffer. If the descriptor is ARG_IO_PTR, this function writes back data from the asynchronous buffer into the source buffer without reading from the source buffer. Other descriptor values cause the function to fail with ERROR_NOT_SUPPORTED.

    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, CeAllocAsynchronousBuffer always creates an alias to the memory with VirtualCopy inside the kernel process. 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 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.

    Use the MARSHAL_FORCE_ALIAS flag only if 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 read or write-back could not be performed.
  • ERROR_NOT_SUPPORTED
    Value passed as ArgumentDescriptor not supported.
  • S_OK
    The read or write 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

Header

kernsdk.h

Library

coredll.lib

See Also

Reference

Kernel Buffer Marshaling Functions
MarshalledBuffer_t
AsynchronousBuffer_t
CeOpenCallerBuffer
CeAllocAsynchronousBuffer
CeFreeAsynchronousBuffer