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

Artigo
03/08/2023

A rotina GetScatterGatherListEx 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

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [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, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *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. 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 comprimento, 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 GetScatterGatherListEx é 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, o parâmetro ExecutionRoutine será opcional e poderá ser NULL. Se esse parâmetro for NULL, o chamador poderá usar os recursos alocados por GetScatterGatherListEx para executar a transferência de DMA após o retorno de GetScatterGatherListEx . 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, 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 alocada. Esse parâmetro aponta para uma estrutura SCATTER_GATHER_LIST . A rotina aloca essa estrutura e a matriz SCATTER_GATHER_ELEMENT para a qual ela aponta.

O parâmetro ScatterGatherList é opcional e pode ser NULL se o parâmetro ExecutionRoutine não for NULL.

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 GetScatterGatherListEx 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

GetScatterGatherListEx 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_INSUFFICIENT_RESOURCES	A rotina falhou ao alocar os recursos necessários para a transferência de DMA.

Comentários

GetScatterGatherListEx 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_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

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

O driver de um dispositivo master de barramento pode usar GetScatterGatherListEx para combinar as operações executadas pelas rotinas AllocateAdapterChannelEx e MapTransferEx em uma única chamada. GetScatterGatherListEx executa as seguintes operações:

Aloca os recursos necessários para a transferência de AMD.
Cria uma lista de dispersão/coleta com base nos valores dos parâmetros Mdl, Offset e Length .
Chama a rotina AdapterListControl fornecida pelo driver e fornece a lista de dispersão/coleta para essa rotina como um parâmetro.

Os recursos alocados são liberados automaticamente após o retorno da rotina AdapterListControl . Se GetScatterGatherListEx for chamado de forma síncrona (ou seja, se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido), a rotina AdapterListControl poderá ser omitida. Nesse caso, o chamador usa os recursos alocados para iniciar a transferência de DMA após o retorno de GetScatterGatherListEx . O chamador deve liberar explicitamente esses recursos.

Por padrão, GetScatterGatherListEx retorna de forma assíncrona, sem aguardar a conclusão da alocação de recursos 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 GetScatterGatherListEx se comportará da seguinte maneira:

Se os recursos solicitados não estiverem disponíveis imediatamente, GetScatterGatherListEx não aguardará recursos, não criará uma lista de dispersão/coleta e não chamará a rotina AdapterListControl . Em vez disso, GetScatterGatherListEx 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 GetScatterGatherListEx 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 GetScatterGatherListEx . Nesse caso, o driver deve fornecer um ponteiro ScatterGatherList válido e não NULL. Além disso, depois que o driver inicia a transferência de DMA, o driver deve chamar a rotina FreeAdapterObject para liberar os recursos que GetScatterGatherListEx alocou para o objeto do adaptador.

GetScatterGatherListEx é uma versão estendida da rotina GetScatterGatherList . Os seguintes recursos estão disponíveis apenas na versão estendida:

GetScatterGatherListEx é semelhante à rotina BuildScatterGatherListEx , exceto que GetScatterGatherListEx aloca automaticamente o buffer para a lista de dispersão/coleta.

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