PALLOCATE_ADAPTER_CHANNEL função de retorno de chamada (wdm.h)
A rotina de AllocateAdapterChannel prepara o sistema para uma operação DMA em nome do objeto de dispositivo de destino e, em seguida, chama a rotina de adapterControl fornecida pelo driver para realizar a operação de DMA.
PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;
NTSTATUS PallocateAdapterChannel(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] ULONG NumberOfMapRegisters,
[in] PDRIVER_CONTROL ExecutionRoutine,
[in] PVOID Context
)
{...}
[in] DmaAdapter
Ponteiro para a estrutura de DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador mestre do barramento ou o controlador DMA.
[in] DeviceObject
Ponteiro para o objeto do 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 de adapterControl fornecida pelo driver. A rotina é chamada quando o controlador DMA do sistema ou o adaptador mestre do barramento ficam disponíveis.
[in] Context
Ponteiro para o contexto determinado pelo driver a ser passado para a rotina AdapterControl.
Essa rotina pode retornar um dos seguintes valores NTSTATUS.
| Código de retorno | Descrição |
|---|---|
|
O canal do adaptador foi alocado. O sistema chamará a rotina de AdapterControl assim que a operação DMA puder começar. |
|
O NumberOfMapRegisters é maior que o valor retornado por IoGetDmaAdapter. A rotina de AdapterControl não será chamada. |
AllocateAdapterChannel 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.
Um driver chama a rotina AllocateAdapterControl para registrar uma rotina AdapterControl que executa uma operação DMA para o driver. A rotina AdapterControl executa uma operação de DMA usando o controlador DMA do sistema ou um adaptador mestre 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 mestre do 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 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 DMA pode ser enfileirada para um objeto de dispositivo a qualquer momento. Portanto, o driver não deve chamar AllocateAdapterChannel novamente para outra operação 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 de AdapterControl.
O sistema passa o valor do membro CurrentIrp do DeviceObject como o parâmetro Irp de AdapterControl. Se AllocateAdapterChannel for chamado da rotina de StartIo de do 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.
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 2000. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |
| regras de conformidade de DDI | IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm) |