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

Artigo
03/08/2023

A rotina BuildScatterGatherListEx aloca os recursos necessários para uma transferência de DMA, cria uma lista de dispersão/coleta e chama a rotina AdapterListControl fornecida pelo driver para iniciar a transferência de DMA.

Cuidado

Não chame essa rotina para um dispositivo DMA do sistema.

Sintaxe

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER . Essa estrutura é o objeto do adaptador que representa o dispositivo DMA master barramento do driver ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter .

[in] DeviceObject

Um ponteiro para uma estrutura DEVICE_OBJECT . Essa estrutura é o PDO (objeto de dispositivo físico) que representa o dispositivo de destino para a operação de DMA solicitada.

[in] DmaTransferContext

Um ponteiro para um contexto de transferência de DMA inicializado. Esse contexto foi inicializado por uma chamada anterior para a rotina InitializeDmaTransferContext . Esse contexto deve ser exclusivo em todas as solicitações de alocação do adaptador. Para cancelar uma solicitação de alocação pendente, o chamador deve fornecer o contexto de transferência de DMA para a solicitação para a rotina CancelAdapterChannel .

[in] Mdl

Um ponteiro para uma cadeia de MDL que descreve o layout de página física para uma coleção de buffers bloqueados na memória virtual. A lista de dispersão/coleta para a transferência de DMA usará a região dessa memória especificada pelos parâmetros Offset e Length . Para obter mais informações sobre cadeias de MDL, consulte Usando MDLs.

[in] Offset

O deslocamento inicial para a transferência de DMA de dispersão/coleta. Esse parâmetro é um deslocamento de bytes do início do buffer no primeiro MDL na cadeia de MDL. Se os MDLs na cadeia de MDL especificarem um total de N bytes de espaço em buffer, os valores válidos de Offset estarão no intervalo de 0 a N a 1.

[in] Length

O tamanho, em bytes, da transferência de AMD. Se a cadeia de MDL especificar um total de N bytes de espaço em buffer, os valores válidos de Length estarão no intervalo de 1 a N–Offset.

[in] Flags

Os sinalizadores de alocação de canal do adaptador. Há suporte para o seguinte sinalizador:

Sinalizador	Significado
DMA_SYNCHRONOUS_CALLBACK	A rotina BuildScatterGatherListEx é chamada de forma síncrona. Se esse sinalizador estiver definido e os recursos de AMD necessários não estiverem disponíveis imediatamente, a chamada falhará e retornará STATUS_INSUFFICIENT_RESOURCES.

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, o parâmetro ExecutionRoutine será opcional e poderá ser NULL. Se esse sinalizador não estiver definido, ExecutionRoutine deverá ser um ponteiro válido, não NULL . Para obter mais informações sobre esse sinalizador, consulte a seção Comentários.

[in, optional] ExecutionRoutine

Um ponteiro para a rotina AdapterListControl fornecida pelo driver que inicia a transferência de DMA para o driver. O gerenciador de E/S chama a rotina AdapterListControl depois que os recursos necessários são alocados para o objeto do adaptador. Depois que a rotina AdapterListControl retorna, o gerenciador de E/S libera automaticamente o objeto adaptador e os recursos que foram alocados para esse objeto.

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, ExecutionRoutine será opcional e poderá ser NULL. Se ExecutionRoutine for NULL, o chamador poderá usar os recursos alocados por BuildScatterGatherListEx. Para obter mais informações, consulte a seção Comentários.

[in, optional] Context

O contexto de controle de adaptador determinado pelo driver. Esse contexto é passado para a rotina AdapterListControl como o parâmetro Context .

[in] WriteToDevice

A direção da transferência de DMA. Defina esse parâmetro como TRUE para uma operação de gravação, que transfere dados da memória para o dispositivo. Defina esse parâmetro como FALSE para uma operação de leitura, que transfere dados do dispositivo para a memória.

[in] ScatterGatherBuffer

Um ponteiro para um buffer alocado pelo chamador no qual a rotina grava a lista de dispersão/coleta para a transferência de DMA. Essa lista começa com uma estrutura SCATTER_GATHER_LIST , que é seguida por uma matriz SCATTER_GATHER_ELEMENT .

[in] ScatterGatherLength

O tamanho, em bytes, do buffer passado no parâmetro ScatterGatherBuffer . O tamanho do buffer alocado deve ser grande o suficiente para conter a lista de dispersão/coleta, além de dados internos que o sistema operacional armazena nesse buffer. Para calcular o tamanho do buffer necessário, chame a rotina GetDmaTransferInfo ou CalculateScatterGatherList .

[in, optional] DmaCompletionRoutine

Não usado. Defina como NULL.

[in, optional] CompletionContext

Não usado. Defina como NULL.

[out, optional] ScatterGatherList

Um ponteiro para uma variável na qual a rotina grava um ponteiro na lista de dispersão/coleta para a transferência de DMA. Essa lista começa com uma estrutura SCATTER_GATHER_LIST , que contém um ponteiro para uma matriz de SCATTER_GATHER_ELEMENT . Esse ponteiro de saída sempre corresponde ao valor do parâmetro ScatterGatherBuffer .

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido e o parâmetro ExecutionRoutine for NULL, ScatterGatherList deverá ser um ponteiro válido, não NULL . Se ExecutionRoutine não for NULL, ScatterGatherList será opcional e poderá ser NULL se o driver de chamada não exigir a lista de dispersão/coleta. A chamada BuildScatterGatherListEx falhará se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido e ScatterGatherList e ExecutionRoutine forem NULL ou se o sinalizador DMA_SYNCHRONOUS_CALLBACK não estiver definido e ExecutionRoutine for NULL.

Retornar valor

BuildScatterGatherListEx retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados por erro incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_PARAMETERS	A rotina falhou devido a valores de parâmetro inválidos passados pelo chamador.
STATUS_BUFFER_TOO_SMALL	O buffer fornecido pelo chamador no ScatterGatherBuffer é muito pequeno para conter a lista de dispersão/coleta.
STATUS_INSUFFICIENT_RESOURCES	A rotina falhou ao alocar os recursos necessários para a transferência de DMA.

Comentários

BuildScatterGatherListEx* 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 com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

Use BuildScatterGatherListEx somente para adaptadores de barramento master. Não use essa rotina para um adaptador de DMA do sistema.

BuildScatterGatherListEx é semelhante à rotina GetScatterGatherListEx , exceto pelo fato de exigir que o chamador aloque o buffer para a lista de dispersão/coleta.

Por exemplo, um driver pode pré-alocar um ou mais buffers de dispersão/coleta durante a inicialização do dispositivo. Posteriormente, uma chamada BuildScatterGatherListEx que usa esse buffer pode ter êxito em condições de baixa disponibilidade de memória que podem causar falha em uma chamada GetScatterGatherListEx .

Por padrão, BuildScatterGatherListEx retorna de forma assíncrona, sem aguardar a conclusão da alocação de recurso solicitada. Após esse retorno, o chamador pode, se necessário, cancelar a solicitação de alocação pendente chamando a rotina CancelAdapterChannel .

Se o driver de chamada definir o sinalizador DMA_SYNCHRONOUS_CALLBACK , a rotina BuildScatterGatherListEx se comportará da seguinte maneira:

Se os recursos solicitados não estiverem disponíveis imediatamente, BuildScatterGatherListEx não aguardará recursos, não criará uma lista de dispersão/coleta e não chamará a rotina AdapterListControl . Em vez disso, BuildScatterGatherListEx falha e retorna STATUS_INSUFFICIENT_RESOURCES.
O driver não será necessário para fornecer uma rotina AdapterListControl se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido.
Se o driver fornecer uma rotina AdapterListControl , o sinalizador DMA_SYNCHRONOUS_CALLBACK indicará que essa rotina deve ser chamada no contexto do thread de chamada, antes que BuildScatterGatherListEx retorne.
Se o driver não fornecer uma rotina AdapterListControl , o driver poderá usar os recursos alocados e a lista de dispersão/coleta após o retorno de BuildScatterGatherListEx . Nesse caso, o driver deve fornecer um ponteiro ScatterGatherList válido e não NULL. Além disso, após a conclusão da transferência de DMA iniciada pelo driver, o driver deve chamar a rotina FreeAdapterObject para liberar os recursos que BuildScatterGatherListEx alocou para o objeto do adaptador.

BuildScatterGatherListEx é uma versão estendida da rotina BuildScatterGatherList . A lista a seguir resume os recursos que estão disponíveis apenas na versão estendida:

Recurso	Descrição
Deslocamento inicial	O driver de chamada pode especificar um deslocamento inicial para uma transferência de DMA de dispersão/coleta em vez de iniciar a transferência no primeiro endereço de buffer no início da cadeia de MDL.
Cancelamento de solicitação de alocação	O driver pode chamar CancelAdapterChannel para cancelar uma solicitação de alocação pendente quando o adaptador DMA estiver na fila para aguardar os recursos de DMA.
Retorno de chamada síncrono	O driver pode definir o sinalizador DMA_SYNCHRONOUS_CALLBACK para solicitar que a rotina AdapterListControl fornecida pelo driver seja chamada no thread de chamada, antes que BuildScatterGatherListEx retorne.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL