DEVICE_DESCRIPTION structure (wdm.h)

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

Syntax

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;

Members

Version

The version of this structure. The Version member of the DEVICE_DESCRIPTION structure that is passed to the IoGetDmaAdapter routine determines which version of the DMA_ADAPTER structure is returned by this routine. The following is a list of the possible values of the Version member and the corresponding DMA_ADAPTER versions:

DEVICE_DESCRIPTION_VERSION

If Version = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter ignores the IgnoreCount member, and returns version 1 of the DMA_ADAPTER structure.

DEVICE_DESCRIPTION_VERSION1

If Version = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter uses the IgnoreCount member, and returns version 1 of the DMA_ADAPTER structure.

DEVICE_DESCRIPTION_VERSION2

If Version = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter uses the IgnoreCount member, and returns version 2 of the DMA_ADAPTER structure. Version 2 is available starting with Windows XP.

DEVICE_DESCRIPTION_VERSION3

If Version = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter uses the IgnoreCount member, and returns version 3 of the DMA_ADAPTER structure. Version 3 is available starting with Windows 8.

Master

Whether the device is a bus-master DMA device. Set to TRUE if the device is a bus-master DMA device. Set to FALSE if it is a subordinate DMA device.

ScatterGather

For a bus-master DMA device, this member indicates whether the device supports scatter/gather DMA. Set to TRUE if the device can do scatter/gather DMA. Otherwise, set this member to FALSE.

For a subordinate DMA device, the ScatterGather value is not used. Instead, IoGetDmaAdapter assumes that the scatter/gather capability of a subordinate DMA device is the same as that of the underlying system DMA controller to which the device is connected.

DemandMode

This member is used only if Version is DEVICE_DESCRIPTION_VERSION2.

For a subordinate DMA device, this member indicates whether to use the system DMA controller's demand mode. Set to TRUE to use demand mode. Otherwise, set this member to FALSE.

For a bus-master DMA device, the DemandMode value is not used.

If Version is DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, or DEVICE_DESCRIPTION_VERSION3, the DemandMode value is not used.

AutoInitialize

For a subordinate DMA device, this member indicates whether to use the system DMA controller's autoinitialize mode. Set to TRUE to use autoinitialize mode. Otherwise, set this member to FALSE.

For a bus-master DMA device, the AutoInitialize value is not used.

Dma32BitAddresses

This member is used only if Version is DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, or DEVICE_DESCRIPTION_VERSION2.

Dma32BitAddresses specifies whether the device can use full 32-bit addresses for DMA operations. Set to TRUE if the device supports 32-bit addresses. Otherwise, set this member to FALSE.

If Version = DEVICE_DESCRIPTION_VERSION3, the Dma32BitAddresses value is not used.

IgnoreCount

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. Otherwise, set this member to FALSE.

If Version = DEVICE_DESCRIPTION_VERSION, the IgnoreCount value is not used.

For more information, see the Remarks section.

Reserved1

Reserved for system use. Must be FALSE.

Dma64BitAddresses

This member is used only if Version is DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, or DEVICE_DESCRIPTION_VERSION2.

Dma64BitAddresses specifies whether the device can use full 64-bit addresses for DMA operations. Set to TRUE if the device supports 64-bit addresses. Otherwise, set this member to FALSE.

If Version = DEVICE_DESCRIPTION_VERSION3, the Dma64BitAddresses value is not used.

BusNumber

The system-assigned bus number for the I/O bus. This member is not used by WDM drivers.

DmaChannel

The number of the DMA channel to which a subordinate device is assigned. The device driver obtains this channel number from the resource list that it receives in the IRP_MN_START_DEVICE request that starts the device. For more information about this number, see the description of the Dma.Channel member in CM_PARTIAL_RESOURCE_DESCRIPTOR.

InterfaceType

The interface type of the I/O bus to use for DMA. Set this member to the INTERFACE_TYPE enumeration value that indicates the interface type. For more information, see the Remarks section.

DmaWidth

For a subordinate DMA device, this member specifies the DMA data width for transfers by the system DMA controller. Possible values are Width8Bits, Width16Bits, Width32Bits, and Width64Bits.

For a bus-master DMA device, the DmaWidth value is not used.

DmaSpeed

This member is used only if Version is DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, or DEVICE_DESCRIPTION_VERSION2.

For a subordinate DMA device, this member specifies one of the following speeds for system DMA: Compatible, TypeA, TypeB, TypeC, or TypeF.

For a bus-master DMA device, the DmaSpeed value is not used.

If Version = DEVICE_DESCRIPTION_VERSION3, the DmaSpeed value is not used.

MaximumLength

The maximum number of bytes the device can transfer in a DMA operation that uses the allocated adapter object.

DmaPort

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

DmaAddressWidth

This member is used only if Version = DEVICE_DESCRIPTION_VERSION3.

For a bus-master DMA device, DmaAddressWidth specifies the width, in bits, of a DMA address. The DmaAddressWidth value must be nonzero and must not exceed 64. If the memory address width is greater than the DMA address width, map registers are required to access a region of memory that is beyond the address reach of the DMA controller.

For a subordinate DMA device, the DmaAddressWidth value is not used. Instead, IoGetDmaAdapter assumes that the address width of a subordinate DMA device is the same as that of the underlying system DMA controller to which the device is connected.

DmaControllerInstance

Not used.

DmaRequestLine

This member is used only if Version = DEVICE_DESCRIPTION_VERSION3.

For a subordinate DMA device, DmaRequestLine specifies the request line on the DMA controller to which the device is connected. The device driver obtains the number of this request line from the resource list it receives in the IRP_MN_START_DEVICE request that starts the device. For more information about the request line number, see the description of the u.DmaV3.RequestLine member in CM_PARTIAL_RESOURCE_DESCRIPTOR.

For a bus-master DMA device, the DmaRequestLine value is not used.

DeviceAddress

This member is used only if Version = DEVICE_DESCRIPTION_VERSION3.

For a subordinate DMA device, DeviceAddress is the memory-mapped address of the data register on the device that is used as the source or destination for a DMA transfer. This data register is located at a known, device-specific offset from the device start address. The width of this register is specified by the DmaWidth member. The device driver obtains the device start address from the resource list it receives in the IRP_MN_START_DEVICE request that starts the device. For more information about this address, see the description of the u.Memory.Start member in CM_PARTIAL_RESOURCE_DESCRIPTOR.

For a bus-master DMA device, the DeviceAddress member is not used.

Remarks

The driver of a device that uses DMA to transfer data uses the DEVICE_DESCRIPTION structure to pass information about the device to the IoGetDmaAdapter routine. The driver calls this routine to request an adapter object for a physical device object (PDO). This PDO represents the device's physical connection to the I/O bus to use for DMA. For more information, see Getting an Adapter Object.

To allocate resources for a DMA controller, the I/O manager needs information about the controller but can obtain some of this information only from a driver. For example, the driver for a bus-master device knows whether the device supports scatter/gather DMA or uses full 32-bit addresses. Or, the driver for a subordinate device can determine the DMA channel number from the resource list that the driver receives in the IRP_MN_START_DEVICE request that starts the device. The driver uses the DEVICE_DESCRIPTION structure to pass this information to the I/O manager.

Before calling IoGetDmaAdapter, the driver should first zero-initialize the entire DEVICE_DESCRIPTION structure, then fill in selected members to describe the device.

The InterfaceType member specifies the type of bus interface that will be used for DMA. If you set InterfaceType to InterfaceTypeUndefined, IoGetDmaAdapter queries the PDO to determine the correct interface type for your device. Or, you can specify an explicit interface type, such as Internal, Isa, Eisa, or PCIBus. For more information, see the list of supported interface types in INTERFACE_TYPE.

If the ScatterGather member is set to TRUE and the InterfaceType member is set to PCIBus, the Dma32BitAddresses member is ignored and IoGetDmaAdapter assumes that the device supports 32-bit DMA addresses.

If the Dma64BitAddresses member is set to TRUE, the Dma32BitAddresses member is ignored and IoGetDmaAdapter assumes that the device supports 64-bit DMA addresses.

To indicate that the DMA controller hardware cannot reliably maintain an accurate transfer count, set IgnoreCount to TRUE, and set Version to a value other than DEVICE_DESCRIPTION_VERSION. In a platform that has such a DMA controller, the operating system ignores the DMA transfer counter but must take special precautions to maintain data integrity during DMA operations. Typically, the use of a 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 computer's ACPI firmware supports it.

Requirements

Requirement Value
Minimum supported client Supported starting with Windows 2000.
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)

See also

CM_PARTIAL_RESOURCE_DESCRIPTOR

CM_RESOURCE_LIST

DMA_ADAPTER

INTERFACE_TYPE

IRP_MN_START_DEVICE

IoGetDmaAdapter