通过

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
 传递的 HwDeviceExtensionNULL。
STOR_STATUS_INVALID_IRQL
 调用在无效的 IRQL 中发出。
STOR_STATUS_INSUFFICIENT_RESOURCES
 系统没有足够的映射寄存器可用于传输。
STOR_STATUS_BUFFER_TOO_SMALL
Length 参数太大，无法容纳在缓冲区中。

言论

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

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

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

要求

要求 价值
目标平台 普遍
标头 storport.h （包括 Storport.h）
IRQL DISPATCH_LEVEL

另请参阅

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList