Description

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.

Parameters

DmaAdapter [in]

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

Mdl [in]

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.

ExtendedConfigs [in]

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.

ExtendedConfigsCount [in]

Provides the number of extended configurations in the ExtendedConfigs array.

LogicalAddress [out]

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.

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.

See also

DMA_ADAPTER

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter

PALLOCATE_COMMON_BUFFER_WITH_BOUNDS