estrutura DEVICE_DESCRIPTION (wdm.h)

Artigo
08/08/2023

A estrutura DEVICE_DESCRIPTION descreve os atributos do dispositivo físico para o qual um driver está solicitando um adaptador DMA.

Sintaxe

typedef struct _DEVICE_DESCRIPTION {
  ULONG            Version;
  BOOLEAN          Master;
  BOOLEAN          ScatterGather;
  BOOLEAN          DemandMode;
  BOOLEAN          AutoInitialize;
  BOOLEAN          Dma32BitAddresses;
  BOOLEAN          IgnoreCount;
  BOOLEAN          Reserved1;
  BOOLEAN          Dma64BitAddresses;
  ULONG            BusNumber;
  ULONG            DmaChannel;
  INTERFACE_TYPE   InterfaceType;
  DMA_WIDTH        DmaWidth;
  DMA_SPEED        DmaSpeed;
  ULONG            MaximumLength;
  ULONG            DmaPort;
  ULONG            DmaAddressWidth;
  ULONG            DmaControllerInstance;
  ULONG            DmaRequestLine;
  PHYSICAL_ADDRESS DeviceAddress;
} DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;

Membros

Version

A versão dessa estrutura. O membro Version da estrutura DEVICE_DESCRIPTION que é passada para a rotina IoGetDmaAdapter determina qual versão da estrutura DMA_ADAPTER é retornada por essa rotina. Veja a seguir uma lista dos valores possíveis do membro Version e as versões de DMA_ADAPTER correspondentes:

DEVICE_DESCRIPTION_VERSION

Se a versão = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter ignorará o membro IgnoreCount e retornará a versão 1 da estrutura DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION1

Se a versão = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter usará o membro IgnoreCount e retornará a versão 1 da estrutura DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION2

Se a versão = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter usará o membro IgnoreCount e retornará a versão 2 da estrutura DMA_ADAPTER . A versão 2 está disponível a partir do Windows XP.

DEVICE_DESCRIPTION_VERSION3

Se a versão = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter usará o membro IgnoreCount e retornará a versão 3 da estrutura DMA_ADAPTER . A versão 3 está disponível a partir do Windows 8.

Master

Se o dispositivo é um dispositivo DMA master barramento. Defina como TRUE se o dispositivo for um dispositivo DMA master barramento. Defina como FALSE se for um dispositivo DMA subordinado.

ScatterGather

Para um dispositivo DMA master barramento, esse membro indica se o dispositivo dá suporte ao DMA de dispersão/coleta. Defina como TRUE se o dispositivo puder fazer dispersão/coletar DMA. Caso contrário, defina esse membro como FALSE.

Para um dispositivo DMA subordinado, o valor ScatterGather não é usado. Em vez disso, IoGetDmaAdapter pressupõe que a capacidade de dispersão/coleta de um dispositivo DMA subordinado seja a mesma do controlador de DMA do sistema subjacente ao qual o dispositivo está conectado.

DemandMode

Esse membro será usado somente se Version for DEVICE_DESCRIPTION_VERSION2.

Para um dispositivo DMA subordinado, esse membro indica se deve usar o modo de demanda do controlador de DMA do sistema. Defina como TRUE para usar o modo de demanda. Caso contrário, defina esse membro como FALSE.

Para um dispositivo DMA master barramento, o valor DemandMode não é usado.

Se Version for DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION3, o valor DemandMode não será usado.

AutoInitialize

Para um dispositivo DMA subordinado, esse membro indica se deve usar o modo de inicialização automática do controlador de DMA do sistema. Defina como TRUE para usar o modo de inicialização automática. Caso contrário, defina esse membro como FALSE.

Para um dispositivo DMA master barramento, o valor autoInitializar não é usado.

Dma32BitAddresses

Esse membro será usado somente se Version for DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Dma32BitAddresses especifica se o dispositivo pode usar endereços completos de 32 bits para operações de DMA. Defina como TRUE se o dispositivo der suporte a endereços de 32 bits. Caso contrário, defina esse membro como FALSE.

Se Version = DEVICE_DESCRIPTION_VERSION3, o valor Dma32BitAddresses não será usado.

IgnoreCount

Se deve ignorar o contador de transferência do controlador DMA. Defina como TRUE se o controlador DMA nesta plataforma não mantiver um contador de transferência preciso e, portanto, exigir uma solução alternativa. Caso contrário, defina esse membro como FALSE.

Se Version = DEVICE_DESCRIPTION_VERSION, o valor IgnoreCount não será usado.

Para obter mais informações, consulte a seção Comentários.

Reserved1

Reservado para uso do sistema. Deve ser FALSE.

Dma64BitAddresses

Esse membro será usado somente se Version for DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Dma64BitAddresses especifica se o dispositivo pode usar endereços completos de 64 bits para operações de DMA. Defina como TRUE se o dispositivo der suporte a endereços de 64 bits. Caso contrário, defina esse membro como FALSE.

Se Version = DEVICE_DESCRIPTION_VERSION3, o valor Dma64BitAddresses não será usado.

BusNumber

O número do barramento atribuído pelo sistema para o ônibus de E/S. Esse membro não é usado por drivers WDM.

DmaChannel

O número do canal DMA ao qual um dispositivo subordinado é atribuído. O driver do dispositivo obtém esse número de canal da lista de recursos que recebe na solicitação IRP_MN_START_DEVICE que inicia o dispositivo. Para obter mais informações sobre esse número, consulte a descrição do membro Dma.Channel no CM_PARTIAL_RESOURCE_DESCRIPTOR.

InterfaceType

O tipo de interface do barramento de E/S a ser usado para DMA. Defina esse membro como o valor de enumeração INTERFACE_TYPE que indica o tipo de interface. Para obter mais informações, consulte a seção Comentários.

DmaWidth

Para um dispositivo DMA subordinado, esse membro especifica a largura dos dados de DMA para transferências pelo controlador de DMA do sistema. Os valores possíveis são Width8Bits, Width16Bits, Width32Bits e Width64Bits.

Para um dispositivo DMA master barramento, o valor DmaWidth não é usado.

DmaSpeed

Esse membro será usado somente se Version for DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 ou DEVICE_DESCRIPTION_VERSION2.

Para um dispositivo DMA subordinado, esse membro especifica uma das seguintes velocidades para o DMA do sistema: Compatível, TypeA, TypeB, TypeC ou TypeF.

Para um dispositivo DMA master barramento, o valor DmaSpeed não é usado.

Se Version = DEVICE_DESCRIPTION_VERSION3, o valor DmaSpeed não será usado.

MaximumLength

O número máximo de bytes que o dispositivo pode transferir em uma operação de DMA que usa o objeto adaptador alocado.

DmaPort

O número da porta do barramento do tipo microcanal. Esse parâmetro é obsoleto, mas é mantido na estrutura para compatibilidade com drivers herdados.

DmaAddressWidth

Esse membro será usado somente se Version = DEVICE_DESCRIPTION_VERSION3.

Para um dispositivo DMA master barramento, DmaAddressWidth especifica a largura, em bits, de um endereço DMA. O valor DmaAddressWidth deve ser diferente de zero e não deve exceder 64. Se a largura do endereço de memória for maior que a largura do endereço DMA, os registros de mapa serão necessários para acessar uma região de memória que esteja além do alcance do endereço do controlador de DMA.

Para um dispositivo DMA subordinado, o valor DmaAddressWidth não é usado. Em vez disso, IoGetDmaAdapter pressupõe que a largura do endereço de um dispositivo DMA subordinado seja igual à do controlador de DMA do sistema subjacente ao qual o dispositivo está conectado.

DmaControllerInstance

Não usado.

DmaRequestLine

Esse membro será usado somente se Version = DEVICE_DESCRIPTION_VERSION3.

Para um dispositivo DMA subordinado, DmaRequestLine especifica a linha de solicitação no controlador DMA ao qual o dispositivo está conectado. O driver do dispositivo obtém o número dessa linha de solicitação da lista de recursos que recebe na solicitação IRP_MN_START_DEVICE que inicia o dispositivo. Para obter mais informações sobre o número da linha de solicitação, consulte a descrição do membro u.DmaV3.RequestLine em CM_PARTIAL_RESOURCE_DESCRIPTOR.

Para um dispositivo DMA master barramento, o valor DmaRequestLine não é usado.

DeviceAddress

Esse membro será usado somente se Version = DEVICE_DESCRIPTION_VERSION3.

Para um dispositivo DMA subordinado, DeviceAddress é o endereço mapeado na memória do registro de dados no dispositivo usado como origem ou destino para uma transferência de DMA. Esse registro de dados está localizado em um deslocamento conhecido específico do dispositivo do endereço inicial do dispositivo. A largura desse registro é especificada pelo membro DmaWidth . O driver do dispositivo obtém o endereço inicial do dispositivo da lista de recursos que recebe na solicitação IRP_MN_START_DEVICE que inicia o dispositivo. Para obter mais informações sobre esse endereço, consulte a descrição do membro u.Memory.Start no CM_PARTIAL_RESOURCE_DESCRIPTOR.

Para um dispositivo DMA master barramento, o membro DeviceAddress não é usado.

Comentários

O driver de um dispositivo que usa o DMA para transferir dados usa a estrutura DEVICE_DESCRIPTION para passar informações sobre o dispositivo para a rotina IoGetDmaAdapter . O driver chama essa rotina para solicitar um objeto adaptador para um PDO (objeto de dispositivo físico). Esse PDO representa a conexão física do dispositivo com o barramento de E/S a ser usado para DMA. Para obter mais informações, consulte Obtendo um objeto adaptável.

Para alocar recursos para um controlador de DMA, o gerente de E/S precisa de informações sobre o controlador, mas pode obter algumas dessas informações apenas de um driver. Por exemplo, o driver de um dispositivo master de barramento sabe se o dispositivo dá suporte a DMA de dispersão/coleta ou usa endereços completos de 32 bits. Ou, o driver de um dispositivo subordinado pode determinar o número do canal DMA da lista de recursos que o driver recebe na solicitação IRP_MN_START_DEVICE que inicia o dispositivo. O driver usa a estrutura DEVICE_DESCRIPTION para passar essas informações para o gerente de E/S.

Antes de chamar IoGetDmaAdapter, o driver deve primeiro inicializar a estrutura de DEVICE_DESCRIPTION inteira e, em seguida, preencher os membros selecionados para descrever o dispositivo.

O membro InterfaceType especifica o tipo de interface de barramento que será usada para DMA. Se você definir InterfaceType como InterfaceTypeUndefined, IoGetDmaAdapter consultará o PDO para determinar o tipo de interface correto para seu dispositivo. Ou você pode especificar um tipo de interface explícito, como Internal, Isa, Eisa ou PCIBus. Para obter mais informações, consulte a lista de tipos de interface com suporte em INTERFACE_TYPE.

Se o membro ScatterGather estiver definido como TRUE e o membro InterfaceType estiver definido como PCIBus, o membro Dma32BitAddresses será ignorado e IoGetDmaAdapter assumirá que o dispositivo dá suporte a endereços DMA de 32 bits.

Se o membro Dma64BitAddresses estiver definido como TRUE, o membro Dma32BitAddresses será ignorado e IoGetDmaAdapter pressupõe que o dispositivo dá suporte a endereços DMA de 64 bits.

Para indicar que o hardware do controlador DMA não pode manter uma contagem de transferência precisa de forma confiável, defina IgnoreCount como TRUE e defina Version como um valor diferente de DEVICE_DESCRIPTION_VERSION. Em uma plataforma que tem esse controlador de DMA, o sistema operacional ignora o contador de transferência de DMA, mas deve tomar precauções especiais para manter a integridade dos dados durante as operações de DMA. Normalmente, o uso de uma solução alternativa para compensar um controlador de DMA deficiente degrada a velocidade das transferências de DMA.

Um driver deve especificar TypeF como o valor DmaSpeed somente se o firmware ACPI do computador der suporte a ele.