Função IoGetDmaAdapter (wdm.h)

Artigo
08/08/2023

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)