PCREATE_COMMON_BUFFER_FROM_MDL回调函数 (wdm.h)

项目
08/08/2023

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结构中 返回的地址中的指针调用。驱动程序通过将 DeviceDescription 参数的 Version 成员设置为 DEVICE_DESCRIPTION_VERSION3 调用 IoGetDmaAdapter 来获取此例程的地址。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

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

若要创建 HAL 负责维护后备内存的公共缓冲区，请使用 AllocateCommonBufferWithBounds。