Função WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Artigo
02/27/2024

[Aplica-se somente ao KMDF]

O método WdfDmaTransactionAllocateResources reserva um habilitador de DMA de modo de sistema ou de pacote único para uso exclusivo (e repetido) com o objeto de transação especificado. O driver pode inicializar e iniciar a transação várias vezes enquanto mantém recursos reservados.

Sintaxe

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Parâmetros

[in] DmaTransaction

Um identificador para o objeto de transação DMA para o qual os recursos de DMA devem ser reservados.

[in] DmaDirection

Um valor de tipo WDF_DMA_DIRECTION especificando a direção de transferência de DMA para a qual os recursos estão sendo reservados. Se o driver não especificou um perfil duplex, a estrutura ignorará esse valor.

[in] RequiredMapRegisters

O número de registros de mapa que o driver deseja reservar. Se zero, a estrutura deriva o número necessário de registros de mapa da transação inicializada.

[in] EvtReserveDmaFunction

Um ponteiro para a função de retorno de chamada de evento EvtReserveDma do driver.

[in] EvtReserveDmaContext

Um ponteiro para um buffer que contém o contexto a ser fornecido à função de retorno de chamada de evento EvtReserveDma do driver.

Retornar valor

WdfDmaTransactionAllocateResources retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método retornará um dos valores a seguir.

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O parâmetro DmaDirection contém um valor inválido.
STATUS_INSUFFICIENT_RESOURCES	O número de solicitações de registro de mapa excede o número atribuído ao habilitador ou o driver anteriormente chamado WdfDmaTransactionSetImmediateExecution e os recursos necessários para a solicitação não estão disponíveis.
STATUS_INVALID_DEVICE_REQUEST	O DMA versão 3 ou posterior não está habilitado ou o driver chamou esse método para um habilitador de DMA de coleta de dispersão.

Comentários

WdfDmaTransactionAllocateResources envia uma solicitação para registros de mapa para o mecanismo de DMA do sistema. Quando a solicitação for atendida, a estrutura chamará a função de retorno de chamada de evento EvtReserveDma do driver. Para obter mais informações sobre a reserva de recursos, consulte Reservando recursos de DMA.

Os drivers baseados em estrutura normalmente chamam WdfDmaTransactionAllocateResources de dentro de um manipulador de solicitação de E/S. Um driver também pode chamar WdfDmaTransactionAllocateResources de sua função de retorno de chamada EvtDriverDeviceAdd , depois de criar um objeto de habilitador de DMA.

Quando chamado com um habilitador de DMA de dispersão/coleta, WdfDmaTransactionAllocateResources causa um bug verificador marcar.

O driver deve criar a transação especificada por DmaTransaction antes de chamar WdfDmaTransactionAllocateResources. Depois de chamar WdfDmaTransactionAllocateResources, o driver inicializa e inicia a transação. O driver pode reinicializar e reinicializar o mesmo objeto de transação várias vezes, evitando o atraso que, de outra forma, ocorreria entre transações, pois os registros de mapa eram liberados de volta para o HAL e depois realocados.

Um driver pode chamar WdfDmaTransactionAllocateResources nas seguintes situações:

O driver recebe um conjunto de canais DMA em sua função de retorno de chamada EvtDevicePrepareHardware . No EvtDevicePrepareHardware, o driver inicializa uma transação de DMA e chama WdfDmaTransactionAllocateResources para reservar o habilitador para uso exclusivo com essa transação. Como alternativa, o driver pode chamar WdfDmaTransactionAllocateResources de um manipulador de solicitação e, em seguida, iniciar a transação várias vezes.
O driver precisa executar uma série de transações no habilitador. O driver reserva o habilitador, inicializa e inicia várias transações usando o mesmo objeto de transação e libera o habilitador.

Antes de chamar WdfDmaTransactionAllocateResources, o driver deve determinar o número de registros de mapa necessários para qualquer transação que ele iniciará usando essa reserva. Para fazer isso, o driver pode chamar [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. Macro /wdm/nf-wdm-address_and_size_to_span_pages.md) ou WdfDmaTransactionGetTransferInfo.

Ao chamar WdfDmaTransactionAllocateResources, o driver não deve solicitar mais registros de mapa do que o solicitado quando criou o habilitador.

Para chamar WdfDmaTransactionAllocateResources de maneira não bloqueada, o driver deve primeiro chamar WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources requer dma versão 3. Para selecionar o DMA versão 3, defina o membro WdmDmaVersionOverride de WDF_DMA_ENABLER_CONFIG como 3.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.11
Cabeçalho	wdfdmatransaction.h (include Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf)