PALLOCATE_DOMAIN_COMMON_BUFFER callback function (wdm.h)

This callback function allocates the memory for a domain common buffer.

Syntax

PALLOCATE_DOMAIN_COMMON_BUFFER PallocateDomainCommonBuffer;

NTSTATUS PallocateDomainCommonBuffer(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in]           HANDLE DomainHandle,
  [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,
  [out]          PVOID *VirtualAddress
)
{...}

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] DomainHandle

The handle to the DMA domain that the caller obtained from a previous call to PGET_DMA_DOMAIN.

[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.

Possible values include:

• 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.

[out] VirtualAddress

A pointer to a variable into which this routine writes the corresponding virtual address of the allocated buffer.

Return value

Returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate NTSTATUS value.

Requirements