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

Artigo
02/07/2025

A rotina de initializeDmaTransferContext inicializa um contexto de transferência de DMA opaco usado para acompanhar alocações pendentes de recursos de DMA.

Sintaxe

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

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.

[out] DmaTransferContext

Um ponteiro para um buffer alocado por chamador no qual InitializeDmaTransferContext grava os valores iniciais para o contexto de transferência de DMA. Esse contexto é opaco para o chamador. O chamador deve alocar um buffer grande o suficiente para conter o contexto de transferência de DMA. O tamanho, em bytes, desse contexto é especificado pela constante DMA_TRANSFER_CONTEXT_SIZE_V1 no arquivo de cabeçalho Wdm.h.

Valor de retorno

InitializeDmaTransferContext 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_INVALID_PARAMETERS	Essa rotina falhou devido a valores de parâmetro inválidos passados pelo chamador.

Observações

InitializeDmaTransferContext 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.

Um contexto de transferência de DMA inicializado deve ser fornecido como um parâmetro para o AllocateAdapterChannelEx, GetScatterGatherListExou rotina de BuildScatterGatherListEx. Cada uma dessas rotinas grava informações sobre a alocação de recursos de DMA solicitada no contexto de transferência de DMA. Essas informações são opacas para o chamador. 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 de CancelAdapterChannel.

O contexto de transferência de DMA fornecido para AllocateAdapterChannelEx, GetScatterGatherListExou BuildScatterGatherListEx deve ser exclusivo em todas as solicitações de alocação do adaptador.

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