PALLOCATE_COMMON_BUFFER_WITH_BOUNDS callback function (wdm.h)

Article
01/19/2023

This callback function allocates the memory for a common buffer and maps it so that it can be accessed by a master device and the CPU. The common buffer can be bound by an optional minimum and maximum logical address.

Syntax

PALLOCATE_COMMON_BUFFER_WITH_BOUNDS PallocateCommonBufferWithBounds;

PVOID PallocateCommonBufferWithBounds(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MinimumAddress,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [in]           ULONG Flags,
  [in, optional] MEMORY_CACHING_TYPE *CacheType,
  [in]           NODE_REQUIREMENT PreferredNode,
  [out]          PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parameters

[in] DmaAdapter

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.

[in, optional] MinimumAddress

A pointer to a variable that contains the minimum logical address for the common buffer. This parameter indicates that the buffer should be allocated from memory at and above this address. This parameter is optional and can be specified as NULL to indicate that there is no minimum address.

[in, optional] MaximumAddress

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.

[in] Length

The size, in bytes, of the common buffer that is to be allocated for the DMA operation.

[in] Flags

The size, in bytes, of the common buffer that is to be allocated for the DMA operation.

Flag	Meaning
DOMAIN_COMMON_BUFFER_LARGE_PAGE	The common buffer will be allocated using a larger page granularity of PAGE_SIZE * 512. Note that this can increase the chance of the allocation being unsuccessful.

[in, optional] CacheType

A pointer to a MEMORY_CACHING_TYPE enumeration indicating whether the routine must enable or disable cached memory in the common buffer that is to be allocated. Only values of MmNonCached and MmCached are supported. The parameter is optional and can be specified as NULL to specify the caching will be dependent upon the hardware platform default.

[in] PreferredNode

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.

[out] LogicalAddress

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.

Return value

Returns PVOID that is the virtual address of the memory allocated for the common buffer. If the buffer cannot be allocated, then returns NULL.

Remarks

This callback function is an extended version of the PALLOCATE_COMMON_BUFFER_EX routine. The following list summarizes the features that are available only in the extended version:

The caller can specify a minimum logical address for the common buffer that is to be allocated.
The caller can provide a caching type override that will be followed regardless of the hardware platform.
The caller can specify the use of a larger granularity for their common buffer allocation.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1803
Target Platform	Desktop
Header	wdm.h (include Wdm.h)
IRQL	PASSIVE_LEVEL