Função IoGetDmaAdapter (wdm.h)
A rotina IoGetDmaAdapter retorna um ponteiro para a estrutura do adaptador de DMA para um objeto de dispositivo físico.
Sintaxe
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
Parâmetros
[in, optional] PhysicalDeviceObject
Ponteiro para o objeto de dispositivo físico para o dispositivo que solicita a estrutura do adaptador DMA.
[in] DeviceDescription
Ponteiro para uma estrutura DEVICE_DESCRIPTION , que descreve os atributos do dispositivo físico. Independentemente da versão definida na estrutura DEVICE_DESCRIPTION, essa função sempre retorna DMA_ADAPTER->Version == 1.
[out] NumberOfMapRegisters
Um ponteiro para, na saída, o número máximo de registros de mapa que o driver pode alocar para qualquer operação de transferência de DMA.
Retornar valor
IoGetDmaAdapter retorna um ponteiro para uma estrutura DMA_ADAPTER , que contém ponteiros para funções que dão suporte a operações de DMA definidas pelo sistema. Se a estrutura não puder ser alocada, a rotina retornará NULL. Consulte o comentário da versão acima na descrição do parâmetro DeviceDescription .
Comentários
Antes de chamar essa rotina, um driver deve inicializar zero a estrutura de DEVICE_DESCRIPTION apontada por DeviceDescription e, em seguida, adicionar as informações relevantes para seu dispositivo a essa estrutura.
Em caso de êxito, o valor retornado da rotina aponta para uma estrutura DMA_ADAPTER . Essa estrutura contém um ponteiro para uma estrutura DMA_OPERATIONS , que é uma tabela de ponteiros para funções que o driver pode usar posteriormente para executar operações de DMA. A versão dessa estrutura retornada pela rotina é determinada da seguinte maneira:
Se o driver definir o membro Version da estrutura DEVICE_DESCRIPTION como DEVICE_DESCRIPTION_VERSION ou DEVICE_DESCRIPTION_VERSION1, a estrutura DMA_ADAPTER retornada apontará para a versão 1 da estrutura DMA_OPERATIONS .
Se o driver definir Version = DEVICE_DESCRIPTION_VERSION2, a estrutura DMA_ADAPTER retornada apontará para a versão 2 da estrutura DMA_OPERATIONS se houver suporte para a versão 2; caso contrário, a rotina retornará NULL. Os drivers devem marcar para ver se a versão 2 tem suporte antes de tentar usar qualquer função da versão 2.
Se o driver definir Version = DEVICE_DESCRIPTION_VERSION3, a estrutura DMA_ADAPTER retornada apontará para a versão 3 da estrutura DMA_OPERATIONS se houver suporte para a versão 3; caso contrário, a rotina retornará NULL. Os drivers devem marcar para ver se a versão 3 tem suporte antes de tentar usar qualquer função da versão 3. A versão 3 tem suporte a partir do Windows 8.
Um driver PnP chama IoGetDmaAdapter quando sua rotina AddDevice é chamada ou quando lida com uma solicitação de IRP_MN_START_DEVICE PnP para um dispositivo. Esse IRP inclui informações sobre os recursos de hardware do dispositivo que o driver deve fornecer na estrutura DeviceDescription .
O chamador usa o membro MaximumLength na estrutura DeviceDescription para indicar o número ideal de registros de mapa que ele pode usar. O gerenciador de E/S tentará alocar registros de mapa suficientes para acomodar uma operação de transferência de DMA desse tamanho máximo. Na saída, o gerenciador de E/S retorna, no parâmetro NumberOfMapRegisters , o número de registros de mapa que ele aloca. Os drivers devem marcar o valor retornado; não há garantia de que um driver receberá o mesmo número de registros de mapa solicitados.
Para liberar o objeto do adaptador, o driver deve chamar PutDmaAdapter por meio do ponteiro retornado na estrutura DMA_ADAPTER .
Conforme descrito anteriormente, IoGetDmaAdapter retornará NULL se não der suporte à versão da estrutura DMA_ADAPTER especificada por DeviceDescription-Version>. Os chamadores devem confiar nesse comportamento para determinar se a rotina retorna um ponteiro para a versão solicitada da estrutura DMA_ADAPTER . Quando IoGetDmaAdapter retorna um ponteiro para a versão 1 ou versão 2 ou 3 da estrutura DMA_ADAPTER , o membro Version dessa estrutura é sempre definido como 1. Portanto, o chamador não pode usar o membro Version da estrutura DMA_ADAPTER retornada para distinguir entre as versões 1, 2 e 3 dessa estrutura.
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |