PCREATE_COMMON_BUFFER_FROM_MDL callback function (wdm.h)

Article
01/06/2023

The CreateCommonBufferFromMdl routine will attempt to create a common buffer from an MDL by testing for device access compatibility and potentially mapping the memory to a contiguous logical range depending on the translation type. Like all other common buffer allocation functions, this function does not provide a forward progress guarantee.

Syntax

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parameters

[in] DmaAdapter

Provides a pointer to the DMA Adapter that is performing the operation.

[in] Mdl

Provides the MDL that will be mapped to a common buffer.

For an MDL to be able to back a common buffer, the following conditions must be met:

The MDL must have pages that are always resident for the lifetime of the common buffer and that are mapped into the system address space. This can be accomplished by the following approaches:
The MDL is created from a buffer in the non-paged pool via MmBuildMdlForNonPagedPool.
The MDL has been locked via MmProbeAndLockPages and mapped to system space via MmGetSystemAddressForMdlSafe.
The physical pages for the MDL have been allocated via MmAllocatePagesForMdlEx and mapped to system space via MmGetSystemAddressForMdlSafe.
The MDL must represent a page-aligned region and be a multiple of PAGE_SIZE.
- If the SubSection extended configuration is being used, then the portion of the MDL being used must be page-aligned and be a multiple of PAGE_SIZE.
The MDL must not be a chained MDL.
- If the SubSection extended configuration is being used, then a chained MDL can be provided, but the portion of the MDL being used must be contained in a single MDL in the chain.
If DMA Remapping is not being used, the MDL must represent physically contiguous memory and be accessible to the device.

[in] ExtendedConfigs

Provides an optional array of DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION structures to further configure the creation of the MDL backed common buffer.

If multiple configurations of the same DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE are provided in the array, creation will fail.

[in] ExtendedConfigsCount

Provides the number of extended configurations in the ExtendedConfigs array.

[out] LogicalAddress

On success provides the logical address of the resulting common buffer.

Return value

CreateCommonBufferFromMdl return STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return code	Description
STATUS_INVALID_PARAMETER	The caller has provided an incompatible MDL or extended configuration.
STATUS_NOT_SUPPORTED	The caller has provided an extended configuration that is not supported on the current system.
STATUS_INSUFFICIENT_RESOURCES	The system does not have enough memory to create book-keeping and mapping metadata.

Remarks

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

A common buffer created by CreateCommonBufferFromMdl will be removed via FreeCommonBuffer. The caller must provide the system virtual address as the virtual address to ensure the common buffer is correctly removed from the Adapter's common buffer bookkeeping structures. The driver is still responsible for unlocking and freeing the MDL and its backing pages.

To create a common buffer where the HAL is responsible for maintaining the backing memory, use AllocateCommonBufferWithBounds.

Requirements

Requirement	Value
Minimum supported server	Windows Server 2022
Target Platform	Desktop
Header	wdm.h
IRQL	PASSIVE_LEVEL