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

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.

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

Confira também

AllocateAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST