StorPortBuildScatterGatherList 函数 (storport.h)

  • 项目

StorPortBuildScatterGatherList 例程为指定的数据缓冲区创建散点/收集列表。

语法

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

参数

[in] HwDeviceExtension

指向主机总线适配器的硬件设备扩展的指针 (HBA) 。

[in] Mdl

指向内存描述符列表的指针 (描述与数据缓冲区关联的内存页的 MDL) 。

[in] CurrentVa

数据缓冲区的虚拟地址。

[in] Length

数据缓冲区的长度（以字节为单位）。

[in] ExecutionRoutine

指向微型端口驱动程序提供的 ExecutionRoutine 的指针。 Storport 驱动程序在创建散点/收集列表后调用此例程。 微型端口驱动程序应在执行例程中执行所有使用散点/收集列表的操作，而不是在执行例程之后调用 StorPortBuildScatterGatherList 例程的代码中。

ExecutionRoutine 声明如下：

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

微型端口驱动程序应忽略此参数。

Irp

微型端口驱动程序应忽略此参数。

ScatterGather

指向 STOR_SCATTER_GATHER_LIST 结构的指针，该结构包含指定数据缓冲区的散点/收集列表。

上下文

StorPortBuildScatterGatherList 函数的 Context 参数中指定的上下文值。

Storport 驱动程序在 IRQL = DISPATCH_LEVEL调用微型端口驱动程序的 ExecutionRoutine 。

[in] Context

端口驱动程序传递给 ExecutionRoutine 参数中指定的执行例程的上下文值。 执行例程使用此值来唯一标识请求。

[in] WriteToDevice

一个 指示 DMA 传输方向的值。 值为 TRUE 表示从数据缓冲区传输到设备，值为 FALSE 表示从设备到数据缓冲区的传输。

[in, out] ScatterGatherBuffer

指向接收散点/收集列表的微型端口提供的缓冲区的指针。 微型端口驱动程序可以通过调用 StorPortAllocatePool 例程为此缓冲区分配内存。

[in] ScatterGatherBufferLength

ScatterGatherBuffer 参数指向的缓冲区的大小（以字节为单位）。

返回值

StorPortBuildScatterGatherList 返回以下值之一：

返回代码 说明
STOR_STATUS_NOT_IMPLEMENTED
 此函数未在活动操作系统上实现。
STOR_STATUS_SUCCESS
 指示例程已成功创建散点/收集列表。
重要 请参阅“备注”。
 
STOR_STATUS_INVALID_PARAMETER
 通过的 HwDeviceExtension 为 NULL。
STOR_STATUS_INVALID_IRQL
 调用是在无效的 IRQL 上进行的。
STOR_STATUS_INSUFFICIENT_RESOURCES
 系统没有足够的地图寄存器可用于传输。
STOR_STATUS_BUFFER_TOO_SMALL
Length 参数太大，无法容纳缓冲区。

注解

微型端口驱动程序调用 StorPortPutScatterGatherList ，以释放 StorPortBuildScatterGatherList 在构造散点/收集列表时分配的资源。

微型端口驱动程序必须先调用 StorPortPutScatterGatherList ，然后才能释放或重用为散点/收集列表分配的内存。

注意 如果 StorPortBuildScatterGatherList 返回STOR_STATUS_SUCCESS，则 ExecutionRoutine 中的回调已成功在创建散点/收集列表后排队执行。 当 StorPortBuildScatterGatherList 返回时，微型端口不得假定调用了 ExecutionRoutine 或散点/收集列表已准备就绪。 如有必要，微型端口可以将 StorPortBuildScatterGatherList 后面的代码执行与 ExecutionRoutine 中的回调同步，以确保散点/收集列表可用。
 

要求

要求 值
目标平台 通用
标头 storport.h (包括 Storport.h)
IRQL DISPATCH_LEVEL

另请参阅

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList