Función StorPortBuildScatterGatherList (storport.h)

La rutina StorPortBuildScatterGatherList crea una lista de dispersión y recopilación para el búfer de datos especificado.

Sintaxis

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
);

Parámetros

[in] HwDeviceExtension

Puntero a la extensión de dispositivo de hardware para el adaptador de bus host (HBA).

[in] Mdl

Puntero a una lista de descriptores de memoria (MDL) que describe las páginas de memoria asociadas al búfer de datos.

[in] CurrentVa

Dirección virtual del búfer de datos.

[in] Length

Longitud, en bytes, del búfer de datos.

[in] ExecutionRoutine

Puntero a un controlador de minipuerto proporcionado por ExecutionRoutine. El controlador storport llama a esta rutina después de crear la lista de dispersión y recopilación. El controlador de miniporte debe realizar todas las operaciones que usan la lista de dispersión y recopilación dentro de la rutina de ejecución, no en el código que sigue la llamada a la rutina StorPortBuildScatterGatherList .

Una executionRoutine se declara de la siguiente manera:

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

DeviceObject

Los controladores miniport deben omitir este parámetro.

Irp

Los controladores miniport deben omitir este parámetro.

ScatterGather

Puntero a una estructura de STOR_SCATTER_GATHER_LIST que contiene la lista de dispersión y recopilación del búfer de datos especificado.

Context

Valor de contexto especificado en el parámetro Context de la función StorPortBuildScatterGatherList.

El controlador storport llama a executionRoutine del controlador de miniport en IRQL = DISPATCH_LEVEL.

[in] Context

Valor de contexto que el controlador de puerto pasa a la rutina de ejecución especificada en el parámetro ExecutionRoutine . La rutina de ejecución usa este valor para identificar de forma única la solicitud.

[in] WriteToDevice

Valor que indica la dirección de la transferencia DMA. Un valor true indica una transferencia que procede del búfer de datos al dispositivo y un valor de FALSE indica una transferencia que procede del dispositivo al búfer de datos.

[in, out] ScatterGatherBuffer

Puntero a un búfer proporcionado por miniporte que recibe la lista de dispersión y recopilación. Un controlador de minipuerto puede asignar memoria para este búfer llamando a la rutina StorPortAllocatePool .

[in] ScatterGatherBufferLength

Tamaño, en bytes, del búfer al que apunta el parámetro ScatterGatherBuffer .

Valor devuelto

StorPortBuildScatterGatherList devuelve uno de los siguientes valores:

Código devuelto	Descripción
STOR_STATUS_NOT_IMPLEMENTED	Esta función no se implementa en el sistema operativo activo.
STOR_STATUS_SUCCESS	Indica que la rutina creó correctamente la lista de dispersión y recopilación. Importante Vea "Comentarios".
STOR_STATUS_INVALID_PARAMETER	HwDeviceExtension pasado era NULL.
STOR_STATUS_INVALID_IRQL	La llamada se realizó en un IRQL no válido.
STOR_STATUS_INSUFFICIENT_RESOURCES	El sistema no tiene suficientes registros de mapa disponibles para la transferencia.
STOR_STATUS_BUFFER_TOO_SMALL	El parámetro Length es demasiado grande para caber en el búfer.

Comentarios

El controlador de minipuerto llama a StorPortPutScatterGatherList para liberar los recursos que StorPortBuildScatterGatherList asignó al construir la lista de dispersión y recopilación.

El controlador de minipuerto debe llamar a StorPortPutScatterGatherList antes de liberar o reutilizar la memoria asignada para la lista de dispersión o recopilación.

Nota Si StorPortBuildScatterGatherList devuelve STOR_STATUS_SUCCESS, la devolución de llamada de ExecutionRoutine se puso en cola correctamente para ejecutarse después de crear la lista de dispersión y recopilación. El miniport no debe suponer que se llamó a ExecutionRoutine o que la lista de dispersión o recopilación está lista cuando StorPortBuildScatterGatherList devuelve. Si es necesario, el miniporte puede sincronizar la ejecución del código después de StorPortBuildScatterGatherList con la devolución de llamada en ExecutionRoutine para asegurarse de que la lista de dispersión y recopilación esté disponible.

 

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	storport.h (incluya Storport.h)
IRQL	DISPATCH_LEVEL

Consulte también

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList