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

Artigo
08/08/2023

A rotina InitializeDmaTransferContext inicializa um contexto de transferência de DMA opaco que é 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 master barramento do driver ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter .

[out] DmaTransferContext

Um ponteiro para um buffer alocado pelo 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.

Retornar valor

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

Comentários

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

Um contexto de transferência de DMA inicializado deve ser fornecido como um parâmetro para a rotina AllocateAdapterChannelEx, GetScatterGatherListEx ou 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 CancelAdapterChannel .

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

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