PBUILD_SCATTER_GATHER_LIST função de retorno de chamada (wdm.h)

Artigo
03/08/2023

A rotina BuildScatterGatherList prepara o sistema para uma operação de DMA, usando um buffer fornecido pelo driver para criar a lista de dispersão/coleta.

Sintaxe

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

Parâmetros

[in] DmaAdapter

Ponteiro para a estrutura DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador de master de barramento ou o controlador de DMA.

[in] DeviceObject

Ponteiro para o objeto de dispositivo que representa o dispositivo de destino para a operação de DMA.

[in] Mdl

Ponteiro para o MDL que descreve o buffer especificado pelo membro MdlAddress do IRP atual.

[in] CurrentVa

Ponteiro para o endereço virtual atual no MDL para que o buffer seja mapeado para uma operação de transferência de DMA.

[in] Length

Especifica o comprimento, em bytes, do buffer a ser mapeado.

[in] ExecutionRoutine

Ponteiro para uma rotina AdapterListControl fornecida pelo driver, que é chamada em IRQL = DISPATCH_LEVEL quando o controlador DMA do sistema ou o adaptador master de barramento está disponível.

[in] Context

Ponteiro para o contexto determinado pelo driver passado para ExecutionRoutine quando ele é chamado.

[in] WriteToDevice

Indica a direção da transferência de DMA: TRUE para uma transferência do buffer para o dispositivo e FALSE caso contrário.

[in] ScatterGatherBuffer

Ponteiro para o buffer fornecido pelo chamador que a rotina preenche com uma estrutura SCATTER_GATHER_LIST .

[in] ScatterGatherLength

Especifica o tamanho, em bytes, do buffer passado no parâmetro ScatterGatherBuffer .

Retornar valor

BuildScatterGatherList retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	A operação foi concluída com êxito.
STATUS_INSUFFICIENT_RESOURCES	O sistema não tem registros de mapa suficientes disponíveis para a transferência.
STATUS_BUFFER_TOO_SMALL	O Comprimento especificado é muito grande para caber dentro do buffer.

Comentários

BuildScatterGatherList não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada pelo ponteiro do endereço retornado em uma estrutura DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION2. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

BuildScatterGatherList executa a mesma operação que GetScatterGatherList, exceto que ele usa o buffer fornecido no parâmetro ScatterGatherBuffer para manter a lista de dispersão/coleta que ele cria. Por outro lado, GetScatterGatherList aloca dinamicamente um buffer para manter a lista de dispersão/coleta. Se a memória insuficiente estiver disponível para alocar o buffer, GetScatterGatherList poderá falhar com um erro de STATUS_INSUFFICIENT_RESOURCES. Os drivers que devem evitar esse cenário podem pré-alocar um buffer para manter a lista de dispersão/coleta e usar BuildScatterGatherList .

Um driver pode usar a rotina CalculateScatterGatherList para determinar o tamanho do buffer a ser alocado para manter a lista de dispersão/coleta.

O driver deve manter o ponteiro para a lista de dispersão/coleta em ScatterGatherBuffer para uso quando o driver chamar PutScatterGatherList. O driver deve chamar PutScatterGatherList (que libera a lista) antes de poder acessar os dados na lista.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows XP e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h)
IRQL	DISPATCH_LEVEL
Regras de conformidade da DDI	IrqlDispatch(wdm)