The AllocateCommonBuffer routine allocates memory and maps it so that it is simultaneously accessible from both the processor and a device for DMA operations.
PVOID AllocateCommonBuffer( _In_ PDMA_ADAPTER DmaAdapter, _In_ ULONG Length, _Out_ PPHYSICAL_ADDRESS LogicalAddress, _In_ BOOLEAN CacheEnabled );
- DmaAdapter [in]
- Length [in]
Specifies the number of bytes of memory to allocate.
- LogicalAddress [out]
Pointer 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 system can take into account any platform-specific memory restrictions.
- CacheEnabled [in]
Specifies whether the allocated memory can be cached. This parameter is ignored on computers with x86-based, x64-based, and Itanium-based processors, because the operating system assumes that DMA is always coherent with the caches of these processors. For these processors, the operating system always allocates common buffers that are cache-enabled, and a driver can use common buffers only if DMA operations for the device are coherent with the contents of the processor caches.
AllocateCommonBuffer returns the base virtual address of the allocated range. If the buffer cannot be allocated, it returns NULL.
AllocateCommonBuffer is not a system routine that can be called directly by name. This routine is callable only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter.
AllocateCommonBuffer supports DMA in which the device and the processor continuously communicate through system memory, as in a control structure for a bus-master DMA device.
AllocateCommonBuffer also supports subordinate devices whose drivers use a system DMA controller's autoinitialize mode.
AllocateCommonBuffer 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. AllocateCommonBuffer allocates at least a page of memory, regardless of the requested Length. After a successful allocation requesting fewer than PAGE_SIZE bytes, the caller can access only the requested Length. After a successful allocation requesting more than an integral multiple of PAGE_SIZE bytes, 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 AllocateCommonBuffer instead of one large request. This approach conserves contiguous memory.
Drivers typically call AllocateCommonBuffer as part of device start-up, during their response to a PnP IRP_MN_START_DEVICE request. After startup, it is possible that only one-page requests will succeed, if any.
|Available starting with Windows 2000.|
DDI compliance rules