HalAllocateCommonBuffer

PVOID
HalAllocateCommonBuffer(
IN PADAPTER_OBJECT AdapterObject,
IN ULONG Length,
OUT PPHYSICAL_ADDRESS LogicalAddress,
IN BOOLEAN CacheEnabled
);

HalAllocateCommonBuffer allocates memory and maps it so that it is simultaneously accessible from both the processor and a device for DMA operations.

Parameters

AdapterObject: Points to the adapter object representing the busmaster adapter or DMA controller channel. This pointer was returned by HalGetAdapter.
Length: Specifies the number of bytes to allocate.
LogicalAddress: Points to a variable that receives the logical address the device can use to access the allocated buffer. Use this address rather than calling MmGetPhysicalAddress because the HAL can take into account any platform-specific memory restrictions.
CacheEnabled: Specifies whether the allocated memory can be cached.

Return Value

HalAllocateCommonBuffer returns the base virtual address of the allocated range. If the buffer cannot be allocated, it returns NULL.

Comments

HalAllocateCommonBuffer supports DMA in which the device and the processor are continuously communicating through system memory, as in a control structure for a busmaster DMA device.

HalAllocateCommonBuffer also supports slave devices whose drivers use a system DMA controller’s autoinitialize mode.

HalAllocateCommonBuffer does the following:

Allocates memory that can be reached from both the processor and the device. This memory appears contiguous to the device.
Allocates map registers to map the buffer, if required by the system.
Sets up a translation for the device, including loading map registers if necessary.

To use resident system memory economically, drivers should allocate as few of these buffers per device as possible. HalAllocateCommonBuffer allocates at least a page of memory, whatever the requested Length. For successful allocations requesting less than PAGE_SIZE, only the given Length can be accessed by the caller. For successful allocations requesting more than an integral multiple of PAGE_SIZE, any remaining bytes on the last allocated page are inaccessible to the caller.

If a driver needs several pages of common buffer space, but the pages need not be contiguous, the driver should make several one-page requests to HalAllocateCommonBuffer rather than one large request. This approach conserves contiguous memory.

Drivers typically call HalAllocateCommonBuffer during driver initialization. After initialization, it is possible that only one-page requests will succeed, if any.

Callers of HalAllocateCommonBuffer are typically running at IRQL PASSIVE_LEVEL. When called from IRQL_PASSIVE_LEVEL, HalAllocateCommonBuffer makes several attempts to locate the requested memory. HalAllocateCommonBuffer can be called from IRQL_DISPATCH_LEVEL, but less effort is made to locate the requested memory, and it is possible that only one-page requests will succeed, if any.