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

Artigo
02/07/2025

A rotina de 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 mestre do barramento do driver ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina de 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 desde o 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 Deslocamento estarão no intervalo de 0 a N–1.

[in] Length

O comprimento, em bytes, da transferência de DMA. 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–Deslocamento.

[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 podem 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 versão da estrutura para DMA_TRANSFER_INFO_VERSION1 antes de chamar GetDmaTransferInfo.

Valor de retorno

GetDmaTransferInfo retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis 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 deXXX DMA_TRANSFER_INFO_.

Observações

GetDmaTransferInfo não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina pode ser chamada apenas pelo ponteiro do endereço retornado em uma estrutura de DMA_OPERATIONS. Drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro de versão 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 de CalculateScatterGatherList e é mais conveniente usar com BuildScatterGatherListEx.

Os parâmetros Mdl, Offsete Length em conjunto especificam uma coleção de regiões de memória física a serem usadas como 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 traduzir os endereços físicos na lista de dispersão/coleta para endereços lógicos.

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

Um MDL descreve as páginas de memória física que estão 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 em buffer dados de E/S. 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
de cliente com suporte mínimo	Disponível a partir do Windows 8.
da Plataforma de Destino	Área de trabalho
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL