The AllocateCommonBufferEx routine allocates memory for a common buffer and maps this memory so that it can be accessed both by the processor and by a device that performs DMA operations.
PVOID AllocateCommonBufferEx( _In_ PDMA_ADAPTER DmaAdapter, _In_opt_ PPHYSICAL_ADDRESS MaximumAddress, _In_ ULONG Length, _Out_ PPHYSICAL_ADDRESS LogicalAddress, _In_ BOOLEAN CacheEnabled, _In_ NODE_REQUIREMENT PreferredNode );
- DmaAdapter [in]
A pointer to a DMA_ADAPTER structure. This structure is the adapter object that represents the driver's bus-master DMA device or system DMA channel. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.
- MaximumAddress [in, optional]
A pointer to a variable that contains the maximum logical address for the common buffer. This parameter indicates that the buffer should be allocated from memory below this address. This parameter is optional and can be specified as NULL to indicate that there is no maximum address.
- Length [in]
The size, in bytes, of the common buffer that is to be allocated for the DMA operation.
- LogicalAddress [out]
A pointer to a variable into which this routine writes the logical address that the device can use to access the common buffer. The DMA device should use this logical address instead of the physical address that is returned by a routine such as MmGetPhysicalAddress.
- CacheEnabled [in]
Whether the routine must enable or disable caching of memory in the common buffer that is to be allocated. If TRUE, caching is enabled. If FALSE, it is disabled. If the hardware platform does not enforce cache coherency for DMA operations, then caching should be disabled.
- PreferredNode [in]
The preferred NUMA node from which the memory is to be allocated. If N is the number of NUMA nodes in a multiprocessor system, PreferredNode is a number in the range 0 to N–1. For a one-processor system or a non-NUMA multiprocessor system, set PreferredNode to zero.
AllocateCommonBufferEx returns the virtual address of the memory allocated for the common buffer. If the buffer cannot be allocated, NULL is returned.
AllocateCommonBufferEx is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.
AllocateCommonBufferEx is an extended version of the AllocateCommonBuffer routine. The following list summarizes the features that are available only in the extended version:
- The caller can specify a maximum logical address for the common buffer that is to be allocated.
- The caller can specify a preferred NUMA node in which the common buffer is to be allocated.
For more information about DMA operations that use a common buffer, see the following topics:
|Available starting with Windows 8.|