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

Artigo
03/01/2024

A rotina GetScatterGatherList prepara o sistema para uma operação de dispersão/coleta de DMA em nome do objeto de dispositivo de destino, por meio do controlador DMA do sistema ou de um adaptador master de barramento.

Sintaxe

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [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
)
{...}

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 em MdlAddress no 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, a ser mapeado.

[in] ExecutionRoutine

Ponteiro para uma rotina AdapterListControl fornecida pelo driver, que é chamada em 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 a rotina AdapterListControl do driver 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.

Retornar valor

Essa rotina pode retornar um dos seguintes valores NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	A operação foi realizada com êxito.
STATUS_INSUFFICIENT_RESOURCES	A rotina não pôde alocar memória suficiente ou o número de registros de mapa necessários para a transferência é maior do que o valor retornado por IoGetDmaAdapter.
STATUS_BUFFER_TOO_SMALL	O buffer é muito pequeno para a transferência solicitada.

Comentários

A rotina GetScatterGatherList aloca dinamicamente um buffer para manter a lista de dispersão/coleta. Para possíveis valores NTSTATUS se a alocação do buffer falhar, consulte o valor retornado.

GetScatterGatherList 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 de DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter.

Assim que o canal DMA apropriado e todos os registros de mapa necessários estiverem disponíveis, GetScatterGatherList criará uma lista de dispersão/coleta, inicializará os registros de mapa e chamará a rotina AdapterListControl fornecida pelo driver para executar a operação de E/S.

GetScatterGatherList combina as ações das rotinas AllocateAdapterChannel e MapTransfer para drivers que executam DMA de dispersão/coleta. GetScatterGatherList determina quantos registros de mapa são necessários para a transferência, aloca os registros de mapa, mapeia os buffers para DMA e preenche a lista de dispersão/coleta. Em seguida, ele chama a rotina AdapterListControl fornecida, passando um ponteiro para a lista de dispersão/coleta em ScatterGather. O driver deve manter esse ponteiro para uso ao chamar PutScatterGatherList. Observe que GetScatterGatherList não tem as restrições de enfileiramento que se aplicam a AllocateAdapterChannel.

Em sua rotina AdapterListControl , o driver deve executar a E/S. No retorno da rotina fornecida pelo driver, GetScatterGatherList mantém os registros de mapa, mas libera a estrutura do adaptador DMA. O driver deve chamar PutScatterGatherList (que libera os buffers) antes de poder acessar os dados no buffer.

Essa rotina pode lidar com MDLs encadeados, desde que o número total de registros de mapa exigidos por todos os MDLs encadeados não exceda o número de registros de mapa disponíveis.

Requisitos

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