Export (0) Print
Expand All

AllocateCommonBufferEx routine

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.

Syntax


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
);

Parameters

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.

Return value

AllocateCommonBufferEx returns the virtual address of the memory allocated for the common buffer. If the buffer cannot be allocated, NULL is returned.

Remarks

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:

Using Common Buffers
Using Common-Buffer Bus-Master DMA
Using Common-Buffer System DMA

Requirements

Version

Available starting with Windows 8.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

PASSIVE_LEVEL

See also

AllocateCommonBuffer
DMA_ADAPTER
DMA_OPERATIONS
IoGetDmaAdapter
MmGetPhysicalAddress

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft