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

A rotina AllocateAdapterChannelEx aloca os recursos necessários para executar uma transferência de DMA e, em seguida, 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 mestre do barramento do driver 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 o 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 do canal do adaptador. Há suporte para o sinalizador a seguir.

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 gerente 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 é retornada, o gerenciador de E/S libera automaticamente o objeto do adaptador. O gerente de E/S também pode liberar os recursos que foram 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 do 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 não NULL válido. 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.

Valor de retorno

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.

Observações

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 de 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 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 poderá, 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á 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 de 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 de AllocateAdapterChannelEx retornar.
• Se o driver não fornecer uma rotina AdapterControl , o driver poderá usar os recursos alocados após o retorno de AllocateAdapterChannelEx . Nesse caso, o driver deve chamar FreeAdapterObject depois de terminar de usar os recursos alocados.

Requirements

Consulte também

AdapterControl

AllocateAdapterChannel

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FlushAdapterBuffersEx

FreeAdapterObject

FreeMapRegisters

GetDmaTransferInfo

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx