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

Artigo
02/27/2024

A rotina AllocateAdapterChannel prepara o sistema para uma operação de DMA em nome do objeto de dispositivo de destino e, em seguida, chama a rotina AdapterControl fornecida pelo driver para executar a operação DMA.

Sintaxe

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

Parâmetros

[in] DmaAdapter

Ponteiro para a estrutura DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador de master de barramento ou o controlador de DMA.

[in] DeviceObject

Ponteiro para o objeto de dispositivo que representa o dispositivo de destino para uma operação de DMA solicitada.

[in] NumberOfMapRegisters

Especifica o número de registros de mapa a serem usados na transferência. Esse valor é o menor do número de registros de mapa necessários para atender à solicitação de transferência atual e o número de registros de mapa disponíveis retornados por IoGetDmaAdapter.

[in] ExecutionRoutine

Ponteiro para uma rotina AdapterControl fornecida pelo driver. A rotina é chamada quando o controlador de DMA do sistema ou o adaptador master de barramento fica disponível.

[in] Context

Ponteiro para o contexto determinado pelo driver a ser passado para a rotina AdapterControl .

Retornar valor

Essa rotina pode retornar um dos seguintes valores NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	O canal do adaptador foi alocado. O sistema chamará a rotina AdapterControl assim que a operação DMA puder começar.
STATUS_INSUFFICIENT_RESOURCES	O NumberOfMapRegisters é maior que o valor retornado por IoGetDmaAdapter. A rotina AdapterControl não será chamada.

Comentários

AllocateAdapterChannel 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 de DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter.

Um driver chama a rotina AllocateAdapterControl para registrar uma rotina AdapterControl que executa uma operação de DMA para o driver. A rotina AdapterControl executa uma operação de DMA usando o controlador DMA do sistema ou um adaptador master de barramento.

Se a operação DMA puder ser executada imediatamente, o sistema chamará imediatamente AdapterControl. Se o controlador DMA do sistema ou o adaptador master de barramento estiver em uso no momento, AllocateAdapterChannel enfileirará o AdapterControl até que o adaptador fique disponível. Em ambos os casos, AllocateAdapterChannel retorna STATUS_SUCCESS.

Se o sistema não tiver recursos para executar a operação DMA, AllocateAdapterChannel retornará STATUS_INSUFFICIENT_RESOURCES. Nesse caso, AdapterControl não está na fila e o driver deve concluir o IRP atual com o código de erro apropriado (como STATUS_INSUFFICIENT_RESOURCES).

Essa rotina reserva acesso exclusivo a um canal do controlador de DMA e registros de mapa para uma ou mais operações de DMA necessárias para atender à solicitação de transferência do IRP atual para o dispositivo especificado.

Somente uma solicitação de AMD pode ser enfileirada para um objeto de dispositivo a qualquer momento. Portanto, o driver não deve chamar AllocateAdapterChannel novamente para outra operação de DMA no mesmo objeto de dispositivo até que a rotina AdapterControl tenha concluído a execução. Além disso, um driver não deve chamar AllocateAdapterChannel de dentro de sua rotina AdapterControl .

O sistema passa o valor do membro CurrentIrp de DeviceObject como o parâmetro Irp de AdapterControl. Se AllocateAdapterChannel for chamado da rotina StartIo de um driver, isso será garantido para apontar para o IRP que StartIo foi chamado para processar. Caso contrário, para usar o parâmetro Irp de AdapterControl, o driver deve definir CurrentIrp para apontar para o IRP atual antes de chamar AllocateAdapterChannel.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Regras de conformidade da DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)