DEVICE_DESCRIPTION 構造体 (wdm.h)

[アーティクル]
08/08/2023

DEVICE_DESCRIPTION構造体は、ドライバーが DMA アダプターを要求している物理デバイスの属性を記述します。

構文

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;

メンバー

Version

この構造体のバージョン。 IoGetDmaAdapter ルーチンに渡されるDEVICE_DESCRIPTION構造体の Version メンバーは、このルーチンによって返されるDMA_ADAPTER構造体のバージョンを決定します。 Version メンバーの 使用可能な値と、対応する DMA_ADAPTER バージョンの一覧を次に示します。

DEVICE_DESCRIPTION_VERSION

Version = DEVICE_DESCRIPTION_VERSION場合、IoGetDmaAdapterは IgnoreCount メンバーを無視し、DMA_ADAPTER構造体のバージョン 1 を返します。

DEVICE_DESCRIPTION_VERSION1

Version = DEVICE_DESCRIPTION_VERSION1場合、IoGetDmaAdapter は IgnoreCount メンバーを使用し、DMA_ADAPTER構造体のバージョン 1 を返します。

DEVICE_DESCRIPTION_VERSION2

Version = DEVICE_DESCRIPTION_VERSION2場合、IoGetDmaAdapter は IgnoreCount メンバーを使用し、DMA_ADAPTER構造体のバージョン 2 を返します。バージョン 2 は、Windows XP 以降で使用できます。

DEVICE_DESCRIPTION_VERSION3

Version = DEVICE_DESCRIPTION_VERSION3場合、IoGetDmaAdapter は IgnoreCount メンバーを使用し、DMA_ADAPTER構造体のバージョン 3 を返します。バージョン 3 は、Windows 8 以降で使用できます。

Master

デバイスがバスマスター DMA デバイスかどうか。デバイスがバスマスター DMA デバイスの場合は TRUE に 設定します。下位 DMA デバイスの場合は FALSE に設定します。

ScatterGather

バスマスター DMA デバイスの場合、このメンバーは、デバイスが散布/収集 DMA をサポートしているかどうかを示します。デバイスで分散/収集 DMA を実行できる場合は TRUE に 設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

下位 DMA デバイスの場合、 ScatterGather 値は使用されません。代わりに、 IoGetDmaAdapter は、下位 DMA デバイスの散布/収集機能が、デバイスが接続されている基になるシステム DMA コントローラーの機能と同じであると想定します。

DemandMode

このメンバーは、 Version がDEVICE_DESCRIPTION_VERSION2されている場合にのみ使用されます。

下位 DMA デバイスの場合、このメンバーはシステム DMA コントローラーの要求モードを使用するかどうかを示します。要求モードを使用するには 、TRUE に設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

バスマスター DMA デバイスの場合、 DemandMode 値は使用されません。

Version がDEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1、またはDEVICE_DESCRIPTION_VERSION3の場合、DemandMode 値は使用されません。

AutoInitialize

下位 DMA デバイスの場合、このメンバーは、システム DMA コントローラーの自動初期化モードを使用するかどうかを示します。自動初期化モードを使用するには 、TRUE に設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

バスマスター DMA デバイスの場合、 AutoInitialize 値は使用されません。

Dma32BitAddresses

このメンバーは、 Version がDEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1、またはDEVICE_DESCRIPTION_VERSION2の場合にのみ使用されます。

Dma32BitAddresses は、デバイスが DMA 操作に完全な 32 ビットアドレスを使用できるかどうかを指定します。デバイスが 32 ビットアドレスをサポートしている場合は TRUE に 設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

Version = DEVICE_DESCRIPTION_VERSION3の場合、Dma32BitAddresses 値は使用されません。

IgnoreCount

DMA コントローラーの転送カウンターを無視するかどうか。このプラットフォームの DMA コントローラーが正確な転送カウンターを維持しないため、回避策が必要な場合は TRUE に 設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

Version = DEVICE_DESCRIPTION_VERSIONの場合、IgnoreCount 値は使用されません。

詳細については、「解説」を参照してください。

Reserved1

システムで使用するために予約されています。 FALSE にする必要があります。

Dma64BitAddresses

このメンバーは、 Version がDEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1、またはDEVICE_DESCRIPTION_VERSION2の場合にのみ使用されます。

Dma64BitAddresses は、デバイスが DMA 操作に完全な 64 ビットアドレスを使用できるかどうかを指定します。デバイスが 64 ビットアドレスをサポートしている場合は TRUE に 設定します。それ以外の場合は、このメンバーを FALSE に設定 します。

Version = DEVICE_DESCRIPTION_VERSION3の場合、Dma64BitAddresses 値は使用されません。

BusNumber

I/O バスのシステム割り当てバス番号。このメンバーは WDM ドライバーでは使用されません。

DmaChannel

下位デバイスが割り当てられている DMA チャネルの番号。デバイスドライバーは、デバイスを起動する IRP_MN_START_DEVICE 要求で受け取るリソースの一覧からこのチャネル番号を取得します。この番号の詳細については、CM_PARTIAL_RESOURCE_DESCRIPTORの Dma.Channel メンバーの説明を参照してください。

InterfaceType

DMA に使用する I/O バスのインターフェイスの種類。このメンバーを、インターフェイスの種類を示す INTERFACE_TYPE 列挙値に設定します。詳細については、「解説」を参照してください。

DmaWidth

下位 DMA デバイスの場合、このメンバーは、システム DMA コントローラーによる転送の DMA データ幅を指定します。使用できる値は 、Width8Bits、 Width16Bits、 Width32Bits、 Width64Bits です。

バスマスター DMA デバイスの場合、 DmaWidth 値は使用されません。

DmaSpeed

このメンバーは、 Version がDEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1、またはDEVICE_DESCRIPTION_VERSION2の場合にのみ使用されます。

下位 DMA デバイスの場合、このメンバーは、システム DMA の速度として、Compatible、TypeA、TypeB、TypeC、TypeF のいずれかを指定します。

バスマスター DMA デバイスの場合、 DmaSpeed 値は使用されません。

Version = DEVICE_DESCRIPTION_VERSION3の場合、DmaSpeed 値は使用されません。

MaximumLength

割り当てられたアダプターオブジェクトを使用する DMA 操作でデバイスが転送できる最大バイト数。

DmaPort

Microchannel タイプのバスポート番号。このパラメーターは廃止されましたが、レガシドライバーとの互換性のために構造体に保持されます。

DmaAddressWidth

このメンバーは、 Version = DEVICE_DESCRIPTION_VERSION3の場合にのみ使用されます。

バスマスター DMA デバイスの場合、 DmaAddressWidth は DMA アドレスの幅をビット単位で指定します。 DmaAddressWidth 値は 0 以外で、64 を超えてはなりません。メモリアドレス幅が DMA アドレス幅より大きい場合、DMA コントローラーのアドレス範囲を超えるメモリ領域にアクセスするには、マップレジスタが必要です。

下位 DMA デバイスの場合、 DmaAddressWidth 値は使用されません。代わりに、 IoGetDmaAdapter は、下位 DMA デバイスのアドレス幅が、デバイスが接続されている基になるシステム DMA コントローラーのアドレス幅と同じであると想定します。

DmaControllerInstance

使用されていません。

DmaRequestLine

このメンバーは、 Version = DEVICE_DESCRIPTION_VERSION3の場合にのみ使用されます。

下位 DMA デバイスの場合、 DmaRequestLine は、デバイスが接続されている DMA コントローラーの要求行を指定します。デバイスドライバーは、デバイスを起動する IRP_MN_START_DEVICE 要求で受信したリソースリストから、この要求行の数を取得します。要求行番号の詳細については、CM_PARTIAL_RESOURCE_DESCRIPTORの u.DmaV3.RequestLine メンバーの説明を参照してください。

バスマスター DMA デバイスの場合、 DmaRequestLine 値は使用されません。

DeviceAddress

このメンバーは、 Version = DEVICE_DESCRIPTION_VERSION3の場合にのみ使用されます。

下位 DMA デバイスの場合、 DeviceAddress は、DMA 転送のソースまたは宛先として使用されるデバイス上のデータレジスタのメモリマップアドレスです。このデータレジスタは、デバイスの開始アドレスからの既知のデバイス固有のオフセットにあります。このレジスタの幅は、 DmaWidth メンバーによって指定されます。デバイスドライバーは、デバイスを起動する IRP_MN_START_DEVICE 要求で受信したリソース一覧からデバイスの開始アドレスを取得します。このアドレスの詳細については、CM_PARTIAL_RESOURCE_DESCRIPTORの u.Memory.Start メンバーの説明を参照してください。

バスマスター DMA デバイスの場合、 DeviceAddress メンバーは使用されません。

注釈

DMA を使用してデータを転送するデバイスのドライバーは 、DEVICE_DESCRIPTION 構造体を使用して、デバイスに関する情報を IoGetDmaAdapter ルーチンに渡します。ドライバーは、物理デバイスオブジェクト (PDO) のアダプターオブジェクトを要求するには、このルーチンを呼び出します。この PDO は、DMA に使用する I/O バスへのデバイスの物理接続を表します。詳細については、「アダプターオブジェクトの取得」を参照してください。

DMA コントローラーにリソースを割り当てるには、I/O マネージャーにはコントローラーに関する情報が必要ですが、この情報の一部はドライバーからのみ取得できます。たとえば、バスマスターデバイスのドライバーは、デバイスが分散/収集 DMA をサポートしているか、完全な 32 ビットアドレスを使用するかを認識します。または、下位デバイスのドライバーは、ドライバーがデバイスを起動する IRP_MN_START_DEVICE 要求で受信するリソースの一覧から DMA チャネル番号を決定できます。ドライバーは 、DEVICE_DESCRIPTION 構造体を使用して、この情報を I/O マネージャーに渡します。

IoGetDmaAdapter を呼び出す前に、ドライバーは最初にDEVICE_DESCRIPTION構造体全体をゼロ初期化してから、選択したメンバーを入力してデバイスを記述する必要があります。

InterfaceType メンバーは、DMA に使用されるバスインターフェイスの種類を指定します。 InterfaceType を InterfaceTypeUndefined に設定すると、IoGetDmaAdapter は PDO に対してクエリを実行して、デバイスの正しいインターフェイスの種類を判断します。または、 Internal、 Isa、 Eisa、 PCIBus などの明示的なインターフェイス型を指定することもできます。詳細については、 INTERFACE_TYPEでサポートされているインターフェイスの種類の一覧を参照してください。

ScatterGather メンバーが TRUE に設定され、InterfaceType メンバーが PCIBus に設定されている場合、Dma32BitAddresses メンバーは無視され、IoGetDmaAdapter はデバイスが 32 ビット DMA アドレスをサポートしていることを前提としています。

Dma64BitAddresses メンバーが TRUE に設定されている場合、Dma32BitAddresses メンバーは無視され、IoGetDmaAdapter はデバイスが 64 ビット DMA アドレスをサポートしていることを前提としています。

DMA コントローラーハードウェアが正確な転送数を確実に維持できないことを示すには、 IgnoreCount を TRUE に設定し、 Version を DEVICE_DESCRIPTION_VERSION以外の値に設定します。このような DMA コントローラーを備えたプラットフォームでは、オペレーティングシステムは DMA 転送カウンターを無視しますが、DMA 操作中にデータの整合性を維持するために特別な予防措置を講じる必要があります。通常、DMA コントローラーの不足を補うために回避策を使用すると、DMA 転送の速度が低下します。

ドライバーは、コンピューターの ACPI ファームウェアがサポートしている場合にのみ、DmaSpeed 値として TypeF を指定する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 以降でサポートされています。
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)