Função IoGetDmaAdapter (wdm.h)

A rotina IoGetDmaAdapter retorna um ponteiro para a estrutura do adaptador 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.

Valor de retorno

IoGetDmaAdapter retorna um ponteiro para uma estrutura de 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.

Observações

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.

Com o sucesso, o valor retornado da rotina aponta para uma estrutura DMA_ADAPTER. Essa estrutura contém um ponteiro para uma estrutura de 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 versão da estrutura DEVICE_DESCRIPTION como DEVICE_DESCRIPTION_VERSION ou DEVICE_DESCRIPTION_VERSION1, a estrutura DMA_ADAPTER retornada aponta para a versão 1 da estrutura DMA_OPERATIONS.

• Se o driver definir Versão = DEVICE_DESCRIPTION_VERSION2, a estrutura de 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 verificar se há suporte para a versão 2 antes de tentar usar qualquer função versão 2.

• Se o driver definir Versão = DEVICE_DESCRIPTION_VERSION3, a estrutura de 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 verificar se há suporte para a versão 3 antes de tentar usar qualquer função versão 3. A versão 3 tem suporte a partir do Windows 8.

Um driver PnP chama IoGetDmaAdapter quando sua rotina de 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 de 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 gerente 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 verificar o valor retornado; não há nenhuma 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 pelo 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 contar com esse 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 versão 3 da estrutura de DMA_ADAPTER, o membro da versão dessa estrutura é sempre definido como 1. Portanto, o chamador não pode usar a versão membro da estrutura de DMA_ADAPTER retornada para distinguir entre as versões 1, 2 e 3 dessa estrutura.

Requisitos

Consulte também

AddDevice

DEVICE_DESCRIPTION

DMA_ADAPTER

DMA_OPERATIONS

IRP_MN_START_DEVICE

PutDmaAdapter