PBUILD_SCATTER_GATHER_LIST função de retorno de chamada (wdm.h)
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) |