PCREATE_COMMON_BUFFER_FROM_MDL回调函数（wdm.h）

项目
02/07/2025

CreateCommonBufferFromMdl 例程将尝试通过测试设备访问兼容性从 MDL 创建通用缓冲区，并可能根据转换类型将内存映射到连续逻辑范围。与其他所有常见的缓冲区分配函数一样，此函数不提供向前进度保证。

语法

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
)
{...}

参数

[in] DmaAdapter

提供指向执行作的 DMA 适配器的指针。

[in] Mdl

提供将映射到公共缓冲区的 MDL。

若要使 MDL 能够支持通用缓冲区，必须满足以下条件：

MDL 必须具有始终驻留在公共缓冲区的生存期内且映射到系统地址空间的页面。这可以通过以下方法实现：
MDL 是通过 mmBuildMdlForNonPagedPool从非分页池中的缓冲区创建的。
MDL 已通过 MmProbeAndLockPages 锁定，并通过 mmGetSystemAddressForMdlSafe映射到系统空间。
MDL 的物理页是通过 MmAllocatePagesForMdlEx 分配的，并通过 MmGetSystemAddressForMdlSafe映射到系统空间。
MDL 必须表示页面对齐的区域，并且是PAGE_SIZE的倍数。
- 如果使用 SubSection 扩展配置，则所使用的 MDL 部分必须进行页面对齐，并且是PAGE_SIZE的倍数。
MDL 不能是链接的 MDL。
- 如果使用 SubSection 扩展配置，则可以提供链式 MDL，但所使用的 MDL 部分必须包含在链中的单个 MDL 中。
如果未使用 DMA 重新映射，MDL 必须表示物理上连续的内存，并且可供设备访问。

[in] ExtendedConfigs

提供 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION 结构的可选数组，以进一步配置 MDL 支持的通用缓冲区的创建。

如果在数组中提供了相同 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE 的多个配置，则创建将失败。

[in] ExtendedConfigsCount

提供 ExtendedConfigs 数组中的扩展配置数。

[out] LogicalAddress

成功时提供生成的常见缓冲区的逻辑地址。

返回值

如果调用成功，CreateCommonBufferFromMdl 返回 STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	描述
STATUS_INVALID_PARAMETER	调用方提供了不兼容的 MDL 或扩展配置。
STATUS_NOT_SUPPORTED	调用方提供了当前系统上不支持的扩展配置。
STATUS_INSUFFICIENT_RESOURCES	系统没有足够的内存来创建预订和映射元数据。

言论

CreateCommonBufferFromMdl 不是可以直接按名称调用的系统例程。只能通过从 DMA_OPERATIONS 结构中返回的地址的指针调用此例程。驱动程序通过调用 IoGetDmaAdapter，并将 DeviceDescription 参数的版本成员调用为 DEVICE_DESCRIPTION_VERSION3，从而获取此例程的地址。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

CreateCommonBufferFromMdl 创建的通用缓冲区将通过 FreeCommonBuffer删除。调用方必须提供系统虚拟地址作为虚拟地址，以确保从适配器的公共缓冲区记帐结构中正确删除通用缓冲区。驱动程序仍负责解锁和释放 MDL 及其后盾页。

若要创建一个公共缓冲区，其中 HAL 负责维护后盾内存，请使用 AllocateCommonBufferWithBounds。