PCREATE_COMMON_BUFFER_FROM_MDL callback function (wdm.h)
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 |
See also
DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION