Função StorPortBuildScatterGatherList (storport.h)

A rotina StorPortBuildScatterGatherList cria uma lista de dispersão/coleta para o buffer de dados especificado.

Sintaxe

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

Um ponteiro para a extensão do dispositivo de hardware para o HBA (adaptador de barramento de host).

[in] Mdl

Um ponteiro para uma MDL (lista de descritores de memória) que descreve as páginas de memória associadas ao buffer de dados.

[in] CurrentVa

O endereço virtual do buffer de dados.

[in] Length

O comprimento, em bytes, do buffer de dados.

[in] ExecutionRoutine

Um ponteiro para um ExecutionRoutine fornecido pelo miniportor. O driver storport chama essa rotina depois de criar a lista de dispersão/coleta. O driver de miniporte deve executar todas as operações que fazem uso da lista de dispersão/coleta dentro da rotina de execução, não no código que segue a chamada para a rotina StorPortBuildScatterGatherList .

Uma ExecutionRoutine é declarada da seguinte maneira:

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

DeviceObject

Os drivers de miniport devem ignorar esse parâmetro.

Irp

Os drivers de miniport devem ignorar esse parâmetro.

ScatterGather

Um ponteiro para uma estrutura STOR_SCATTER_GATHER_LIST que contém a lista de dispersão/coleta do buffer de dados especificado.

Contexto

O valor de contexto especificado no parâmetro Context da função StorPortBuildScatterGatherList.

O driver storport chama ExecutionRoutine de um driver de miniport em IRQL = DISPATCH_LEVEL.

[in] Context

Um valor de contexto que o driver de porta passa para a rotina de execução especificada no parâmetro ExecutionRoutine . A rotina de execução usa esse valor para identificar exclusivamente a solicitação.

[in] WriteToDevice

Um valor que indica a direção da transferência de DMA. Um valor true indica uma transferência que é do buffer de dados para o dispositivo e um valor de FALSE indica uma transferência que é do dispositivo para o buffer de dados.

[in, out] ScatterGatherBuffer

Um ponteiro para um buffer fornecido pelo miniporto que recebe a lista de dispersão/coleta. Um driver de miniporte pode alocar memória para esse buffer chamando a rotina StorPortAllocatePool .

[in] ScatterGatherBufferLength

O tamanho, em bytes, do buffer apontado pelo parâmetro ScatterGatherBuffer .

Retornar valor

StorPortBuildScatterGatherList retorna um dos seguintes valores:

Código de retorno	Descrição
STOR_STATUS_NOT_IMPLEMENTED	Essa função não é implementada no sistema operacional ativo.
STOR_STATUS_SUCCESS	Indica que a rotina criou a lista de dispersão/coleta com êxito. Importante Confira 'Comentários'.
STOR_STATUS_INVALID_PARAMETER	O HwDeviceExtension passado era NULL.
STOR_STATUS_INVALID_IRQL	A chamada foi feita em um IRQL inválido.
STOR_STATUS_INSUFFICIENT_RESOURCES	O sistema não tem registros de mapa suficientes disponíveis para a transferência.
STOR_STATUS_BUFFER_TOO_SMALL	O parâmetro Length é muito grande para caber dentro do buffer.

Comentários

O driver de miniporto chama StorPortPutScatterGatherList para liberar os recursos que StorPortBuildScatterGatherList alocou ao construir a lista de dispersão/coleta.

O driver de miniporte deve chamar StorPortPutScatterGatherList antes de liberar ou reutilização da memória alocada para a lista de dispersão/coleta.

Nota Se StorPortBuildScatterGatherList retornar STOR_STATUS_SUCCESS, o retorno de chamada em ExecutionRoutine foi enfileirado com êxito para ser executado após a criação da lista de dispersão/coleta. O miniporto não deve assumir que ExecutionRoutine foi chamado ou que a lista de dispersão/coleta está pronta quando StorPortBuildScatterGatherList retorna. Se necessário, o miniporto pode sincronizar a execução do código seguindo StorPortBuildScatterGatherList com o retorno de chamada em ExecutionRoutine para garantir que a lista de dispersão/coleta esteja disponível.

 

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	storport.h (inclua Storport.h)
IRQL	DISPATCH_LEVEL

Confira também

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList