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

Artigo
08/08/2023

A rotina GetDmaTransferInfo calcula os requisitos de alocação para uma transferência de DMA de dispersão/coleta.

Sintaxe

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

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] Mdl

Um ponteiro para a cadeia de MDL que descreve as páginas de memória que devem ser transferidas. Para obter mais informações, consulte a seção Comentários.

[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] WriteOnly

Indica se a transferência é uma operação somente gravação (ou seja, uma transferência para o dispositivo da memória). Se WriteOnly for TRUE, as informações retornadas sobre a transferência poderão não ser válidas para uma transação de leitura. Esse parâmetro pode indicar que operações de controle de cache adicionais são necessárias nos limites do buffer para impor a coerência de cache.

[in, out] TransferInfo

Um ponteiro para uma estrutura de DMA_TRANSFER_INFO alocada pelo chamador. O chamador deve definir o membro Version da estrutura como DMA_TRANSFER_INFO_VERSION1 antes de chamar GetDmaTransferInfo.

Retornar valor

GetDmaTransferInfo 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_NOT_SUPPORTED	A rotina não dá suporte à versão especificada da estrutura DMA_TRANSFER_INFO_XXX .

Comentários

GetDmaTransferInfo 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 GetDmaTransferInfo para calcular o tamanho do buffer de dispersão/coleta a ser alocado para as rotinas BuildScatterGatherListEx e MapTransferEx .

GetDmaTransferInfo substitui a rotina CalculateScatterGatherList e é mais conveniente usar com BuildScatterGatherListEx.

Os parâmetros Mdl, Offset e Length juntos especificam uma coleção de regiões de memória física a serem usadas como um buffer para uma transferência de DMA de dispersão/coleta. Cada região de memória física normalmente é uma página ou parte de uma página. GetDmaTransferInfo determina os requisitos de alocação para essa transferência. Esses requisitos incluem o seguinte:

O número de elementos na lista de dispersão/coleta. Cada elemento é uma estrutura SCATTER_GATHER_ELEMENT que descreve um bloco de memória fisicamente contíguo.
A quantidade de memória a ser alocada para manter a lista de dispersão/coleta especificada. (Essa alocação de memória inclui o espaço necessário para a lista de dispersão/coleta que descreve o buffer de E/S, mas não para o buffer de E/S em si.)
O número de registros de mapa necessários para converter os endereços físicos na lista de dispersão/coleta em endereços lógicos.

Para obter informações sobre as informações de transferência de DMA fornecidas pela versão 1 da estrutura DMA_TRANSFER_INFO_XXX , consulte DMA_TRANSFER_INFO_V1.

Um MDL descreve as páginas de memória física subjacentes a um bloco de memória virtual bloqueado e contíguo. Normalmente, essas páginas de memória física são não contíguas. Uma cadeia de MDL é uma coleção ordenada de MDLs que descreve a memória que pode ser usada para armazenar dados de E/S em buffer. Normalmente, as regiões de memória virtual descritas pelos MDLs na cadeia são não contíguas. Para obter mais informações sobre MDLs e cadeias de MDL, consulte Usando MDLs.

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