DEVICE_DESCRIPTION

The DEVICE_DESCRIPTION structure describes the attributes of the physical device for which a driver is requesting a DMA object.

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;
} DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;

Members

Version

Specifies the version of this structure. The possible values are:

DEVICE_DESCRIPTION_VERSION

When DEVICE_DESCRIPTION is passed to IoGetDmaAdapter, the routine ignores the IgnoreCount member, and returns version 1 of the DMA_ADAPTER structure.

DEVICE_DESCRIPTION_VERSION1

When DEVICE_DESCRIPTION is passed to IoGetDmaAdapter, the IgnoreCount member is valid, and returns version 1 of the DMA_ADAPTER structure.

DEVICE_DESCRIPTION_VERSION2

When DEVICE_DESCRIPTION is passed to IoGetDmaAdapter, the IgnoreCount member is valid, and returns version 2 of the DMA_ADAPTER structure. Version 2 is available on Windows XP and later.

Master

Indicates whether the device runs as a bus-master adapter (TRUE) or a slave DMA device (FALSE).

ScatterGather

Indicates whether the device supports scatter/gather DMA.

DemandMode

Indicates whether to use the system DMA controller's demand mode. Not used for bus-master DMA.

AutoInitialize

Indicates whether to use the system DMA controller's autoinitialize mode. Not used for bus-master DMA.

Dma32BitAddresses

Specifies the use of 32-bit addresses for DMA operations.

IgnoreCount

Indicates whether to ignore the DMA controller's transfer counter. Set to TRUE if the DMA controller in this platform does not maintain an accurate transfer counter, and therefore requires a workaround. If the Version member is DEVICE_DESCRIPTION_VERSION, the value of IgnoreCount is ignored.

Reserved1

Reserved for system use. Must be FALSE.

Dma64BitAddresses

Specifies the use of 64-bit addresses for DMA operations.

BusNumber

Specifies the system-assigned value for the I/O bus. Not used by WDM drivers.

DmaChannel

Specifies the channel number to which a slave device is attached.

InterfaceType

Specifies the type of I/O bus involved in the DMA operation.

DmaWidth

Specifies the DMA data size for system DMA. Possible values are Width8Bits, Width16Bits, and Width32Bits. Not used for bus-master DMA.

DmaSpeed

Specifies one of the following speeds for system DMA: Compatible, TypeA, TypeB, TypeC, or TypeF. Not used for bus-master DMA.

MaximumLength

Specifies the maximum number of bytes the device can handle in each DMA operation.

DmaPort

Specifies the Microchannel-type bus port number. This parameter is obsolete, but is retained in the structure for compatibility with legacy drivers.

Headers

Defined in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Drivers of devices that use DMA to transfer data use this structure to pass device information when requesting a DMA object. A driver should first zero-initialize the structure, then fill in the information for its device.

The InterfaceType specifies the bus interface. At present, its value can be one of the following: Internal, Isa, Eisa, or PCIBus. Additional types of buses will be supported in future versions of the operating system. The upper bound on the types of buses supported is always MaximumInterfaceType.

Setting Version to DEVICE_DESCRIPTION_VERSION1 or DEVICE_DESCRIPTION_VERSION2 and IgnoreCount to TRUE indicates that the current platform’s DMA controller cannot be relied on to maintain an accurate transfer counter. In platforms with such a DMA controller, the system ignores the DMA counter but must take extra precautions to maintain data integrity during transfer operations. Using this workaround to compensate for a deficient DMA controller degrades the speed of DMA transfers.

A driver should specify TypeF as the DmaSpeed value only if the machine's ACPI BIOS supports it.

See Also

IoGetDmaAdapter