PCREATE_COMMON_BUFFER_FROM_MDL回调函数 (wdm.h)

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

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

若要创建一个公共缓冲区,其中 HAL 负责维护支持内存,请使用 AllocateCommonBufferWithBounds

要求

   
最低受支持的服务器 Windows Server 2022
目标平台 桌面
Header wdm.h
IRQL PASSIVE_LEVEL

另请参阅

DMA_ADAPTER

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION

DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter

PALLOCATE_COMMON_BUFFER_WITH_BOUNDS