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

Artigo
03/08/2023

A rotina AllocateAdapterChannelEx aloca os recursos necessários para executar uma transferência de DMA e chama a rotina AdapterControl fornecida pelo driver para iniciar a transferência de DMA.

Sintaxe

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER . Essa estrutura é o objeto do adaptador que representa o dispositivo DMA master do barramento ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter .

[in] DeviceObject

Um ponteiro para uma estrutura DEVICE_OBJECT . Essa estrutura é o PDO (objeto de dispositivo físico) que representa o dispositivo de destino para a operação de DMA solicitada.

[in] DmaTransferContext

Um ponteiro para um contexto de transferência de DMA inicializado. Esse contexto foi inicializado por uma chamada anterior para a rotina InitializeDmaTransferContext . Esse contexto deve ser exclusivo em todas as solicitações de alocação do adaptador. 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 .

[in] NumberOfMapRegisters

O número de registros de mapa a serem usados na transferência de DMA. O driver de chamada deve definir esse valor como o menor do número de registros de mapa necessários para atender à solicitação de transferência atual e ao número de registros de mapa disponíveis. O driver anteriormente chamou a rotina GetDmaTransferInfo para obter o número de registros de mapa necessários para a transferência e chamou a rotina IoGetDmaAdapter para obter o número de registros de mapa disponíveis.

[in] Flags

Os sinalizadores de alocação de canal do adaptador. Há suporte para o sinalizador a seguir.

Sinalizador	Significado
DMA_SYNCHRONOUS_CALLBACK	A rotina AllocateAdapterChannelEx é chamada de forma síncrona. Se esse sinalizador estiver definido e os recursos de DMA necessários não estiverem disponíveis imediatamente, a chamada falhará e retornará STATUS_INSUFFICIENT_RESOURCES.

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, o parâmetro ExecutionRoutine será opcional e poderá ser NULL. Para obter mais informações sobre esse sinalizador, consulte a seção Comentários.

[in, optional] ExecutionRoutine

Um ponteiro para a rotina AdapterControl fornecida pelo driver que inicia a transferência de DMA para o driver. O gerenciador de E/S chama a rotina AdapterControl depois que os recursos necessários são alocados para o objeto do adaptador. Depois que a rotina AdapterControl retorna, o gerenciador de E/S libera automaticamente o objeto do adaptador. O gerente de E/S também pode liberar os recursos alocados para esse objeto, dependendo do valor retornado por essa rotina.

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, a ExecutionRoutine será opcional e poderá ser NULL. Nesse caso, o chamador pode usar os recursos alocados por AllocateAdapterChannelEx e, posteriormente, liberar esses recursos chamando a rotina FreeAdapterObject . Para obter mais informações, consulte a seção Comentários.

[in, optional] ExecutionContext

O contexto de controle de adaptador determinado pelo driver. Esse contexto é passado para a rotina AdapterControl como o parâmetro Context .

[out, optional] MapRegisterBase

Um ponteiro para uma variável na qual a rotina grava um identificador nos registros de mapa alocados. O chamador pode fornecer esse identificador como um parâmetro para a rotina FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters ou MapTransferEx .

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, MapRegisterBase deverá ser um ponteiro válido, não NULL . Se o parâmetro ExecutionRoutine não for NULL, MapRegisterBase deverá ser NULL. A chamada falhará se MapRegisterBase não for NULL e o sinalizador DMA_SYNCHRONOUS_CALLBACK não estiver definido ou se MapRegisterBase e ExecutionRoutine forem NULL.

Retornar valor

AllocateAdapterChannelEx 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	A rotina falhou devido a valores de parâmetro inválidos passados pelo chamador.
STATUS_INSUFFICIENT_RESOURCES	A rotina não conseguiu alocar recursos necessários para a transferência de DMA.

Comentários

AllocateAdapterChannelEx não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada por 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.

AllocateAdapterChannelEx aloca os recursos necessários para executar uma operação de DMA. Esses recursos incluem canais de DMA e registros de mapa. Depois que todos os recursos necessários são alocados para uso pelo adaptador DMA, AllocateAdapterChannelEx chama a rotina AdapterControl fornecida pelo chamador para iniciar a operação de DMA.

Por padrão, AllocateAdapterChannelEx retorna de forma assíncrona, sem aguardar a conclusão da alocação de recursos solicitada. Após esse retorno, o chamador pode, se necessário, cancelar a solicitação de alocação pendente chamando a rotina CancelAdapterChannel .

Se o driver de chamada definir o sinalizador DMA_SYNCHRONOUS_CALLBACK , a rotina AllocateAdapterChannelEx se comportará da seguinte maneira:

Se os recursos de DMA solicitados não estiverem disponíveis imediatamente, AllocateAdapterChannelEx não aguardará os recursos e não chamará a rotina AdapterControl . Em vez disso, AllocateAdapterChannelEx falha e retorna STATUS_INSUFFICIENT_RESOURCES.
O driver não será necessário para fornecer uma rotina AdapterControl se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido.
Se o driver fornecer uma rotina AdapterControl , o sinalizador DMA_SYNCHRONOUS_CALLBACK indicará que essa rotina deve ser chamada no contexto do thread de chamada, antes que AllocateAdapterChannelEx retorne.
Se o driver não fornecer uma rotina AdapterControl , o driver poderá usar os recursos alocados após AllocateAdapterChannelEx retornar. Nesse caso, o driver deve chamar FreeAdapterObject depois que ele terminar de usar os recursos alocados.

AllocateAdapterChannelEx é uma versão estendida da rotina AllocateAdapterChannel . Os seguintes recursos estão disponíveis apenas na versão estendida:

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