AsynchronousBuffer_t (Windows Embedded CE 6.0)

1/6/2010

This class is a wrapper for CeAllocAsynchronousBuffer and CeFreeAsynchronousBuffer. It is meant to be used with pointers already access-checked or marshaled by the kernel that require asynchronous buffer access. It should be used only in kernel mode. For information about how to access a buffer asynchronously in user mode, see CeAllocAsynchronousBuffer.

Methods

AsynchronousBuffer_t();

AsynchronousBuffer_t(
    PVOID pSrcMarshalled, 
    DWORD cbSrc,
    DWORD ArgumentDescriptor
);

AsynchronousBuffer_t(
    PCVOID pSrcMarshalled,
    DWORD cbSrc,
    DWORD ArgumentDescriptor
);

~AsynchronousBuffer_t();

HRESULT Free();

HRESULT Allocate(
    PVOID  pSrcMarshalled,
    DWORD cbSrc,
    DWORD ArgumentDescriptor
);

HRESULT Allocate(
    PCVOID pSrcMarshalled,
    DWORD cbSrc,
    DWORD ArgumentDescriptor
);

HRESULT Flush();

LPVOID ptr() const;

DWORD size() const;

Remarks

You can either call the constructor to allocate the asynchronous buffer or use the default constructor, and then use the Allocate method. If an HRESULT is required, use Allocate. Similarly, you can allow the destructor to release the asynchronous buffer, or use the Free method. If an HRESULT is required, use Free. If Allocate fails, ptr returns NULL, and size returns zero. Otherwise, the asynchronous buffer is accessible with ptr and size.

Once an AsynchronousBuffer is allocated using the constructor or Allocate, it cannot be re-used by calling Allocate until after Free is called. An attempt to do so returns ERROR_ALREADY_EXISTS. If the buffer is not currently allocated, Free fails and returns ERROR_ALREADY_EXISTS. For information about Allocate and Free, see CeAllocAsynchronousBuffer and CeFreeAsynchronousBuffer.

If you are running inside the kernel proces, 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 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, also pass it when you call the CeFlushAsynchronousBuffer and the CeFreeAsynchronousBuffer functions. Not passing it can cause the system to become unresponsive or create resource leaks.

Requirements

See Also

Reference

Kernel Buffer Marshaling Classes
CeAllocAsynchronousBuffer
CeFlushAsynchronousBuffer
CeFreeAsynchronousBuffer

Other Resources

Developing a Device Driver
Kernel Migration
Bringing Up a Hardware Platform