struktur DEVICE_DESCRIPTION (wdm.h)

Artikel
08/08/2023

Struktur DEVICE_DESCRIPTION menjelaskan atribut perangkat fisik tempat driver meminta adaptor DMA.

Sintaks

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;

Anggota

Version

Versi struktur ini. Anggota versi struktur DEVICE_DESCRIPTION yang diteruskan ke rutinitas IoGetDmaAdapter menentukan versi struktur DMA_ADAPTER mana yang dikembalikan oleh rutinitas ini. Berikut ini adalah daftar nilai yang mungkin dari anggota Versi dan versi DMA_ADAPTER terkait:

DEVICE_DESCRIPTION_VERSION

Jika Versi = DEVICE_DESCRIPTION_VERSION, IoGetDmaAdapter mengabaikan anggota IgnoreCount , dan mengembalikan versi 1 dari struktur DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION1

Jika Versi = DEVICE_DESCRIPTION_VERSION1, IoGetDmaAdapter menggunakan anggota IgnoreCount , dan mengembalikan versi 1 dari struktur DMA_ADAPTER .

DEVICE_DESCRIPTION_VERSION2

Jika Versi = DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter menggunakan anggota IgnoreCount , dan mengembalikan versi 2 dari struktur DMA_ADAPTER . Versi 2 tersedia dimulai dengan Windows XP.

DEVICE_DESCRIPTION_VERSION3

Jika Versi = DEVICE_DESCRIPTION_VERSION3, IoGetDmaAdapter menggunakan anggota IgnoreCount , dan mengembalikan versi 3 dari struktur DMA_ADAPTER . Versi 3 tersedia dimulai dengan Windows 8.

Master

Apakah perangkat adalah perangkat DMA master bus. Atur ke TRUE jika perangkat adalah perangkat DMA master bus. Atur ke FALSE jika merupakan perangkat DMA subordinat.

ScatterGather

Untuk perangkat DMA master bus, anggota ini menunjukkan apakah perangkat mendukung DMA sebar/kumpulkan. Atur ke TRUE jika perangkat dapat menyebarkan/mengumpulkan DMA. Jika tidak, atur anggota ini ke FALSE.

Untuk perangkat DMA subordinat, nilai ScatterGather tidak digunakan. Sebaliknya, IoGetDmaAdapter mengasumsikan bahwa kemampuan menyebar/mengumpulkan perangkat DMA bawahan sama dengan pengontrol DMA sistem yang mendasar tempat perangkat terhubung.

DemandMode

Anggota ini hanya digunakan jika Versi DEVICE_DESCRIPTION_VERSION2.

Untuk perangkat DMA subordinat, anggota ini menunjukkan apakah akan menggunakan mode permintaan pengontrol DMA sistem. Atur ke TRUE untuk menggunakan mode permintaan. Jika tidak, atur anggota ini ke FALSE.

Untuk perangkat DMA master bus, nilai DemandMode tidak digunakan.

Jika Versi DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, atau DEVICE_DESCRIPTION_VERSION3, nilai DemandMode tidak digunakan.

AutoInitialize

Untuk perangkat DMA bawahan, anggota ini menunjukkan apakah akan menggunakan mode autoinisialisasi pengontrol DMA sistem. Atur ke TRUE untuk menggunakan mode autoinitialize. Jika tidak, atur anggota ini ke FALSE.

Untuk perangkat DMA master bus, nilai AutoInitialize tidak digunakan.

Dma32BitAddresses

Anggota ini hanya digunakan jika Versi DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, atau DEVICE_DESCRIPTION_VERSION2.

Dma32BitAddresses menentukan apakah perangkat dapat menggunakan alamat 32-bit penuh untuk operasi DMA. Atur ke TRUE jika perangkat mendukung alamat 32-bit. Jika tidak, atur anggota ini ke FALSE.

Jika Versi = DEVICE_DESCRIPTION_VERSION3, nilai Dma32BitAddresses tidak digunakan.

IgnoreCount

Apakah akan mengabaikan penghitung transfer pengontrol DMA. Atur ke TRUE jika pengontrol DMA di platform ini tidak mempertahankan penghitung transfer yang akurat, dan karenanya memerlukan solusi. Jika tidak, atur anggota ini ke FALSE.

Jika Versi = DEVICE_DESCRIPTION_VERSION, nilai IgnoreCount tidak digunakan.

Untuk informasi lebih lanjut, lihat bagian Keterangan.

Reserved1

Dicadangkan untuk penggunaan sistem. Harus FALSE.

Dma64BitAddresses

Anggota ini hanya digunakan jika Versi DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, atau DEVICE_DESCRIPTION_VERSION2.

Dma64BitAddresses menentukan apakah perangkat dapat menggunakan alamat 64-bit penuh untuk operasi DMA. Atur ke TRUE jika perangkat mendukung alamat 64-bit. Jika tidak, atur anggota ini ke FALSE.

Jika Versi = DEVICE_DESCRIPTION_VERSION3, nilai Dma64BitAddresses tidak digunakan.

BusNumber

Nomor bus yang ditetapkan sistem untuk bus I/O. Anggota ini tidak digunakan oleh driver WDM.

DmaChannel

Jumlah saluran DMA tempat perangkat subordinat ditetapkan. Driver perangkat memperoleh nomor saluran ini dari daftar sumber daya yang diterimanya dalam permintaan IRP_MN_START_DEVICE yang memulai perangkat. Untuk informasi selengkapnya tentang nomor ini, lihat deskripsi anggota Dma.Channel di CM_PARTIAL_RESOURCE_DESCRIPTOR.

InterfaceType

Jenis antarmuka bus I/O yang akan digunakan untuk DMA. Atur anggota ini ke nilai enumerasi INTERFACE_TYPE yang menunjukkan jenis antarmuka. Untuk informasi lebih lanjut, lihat bagian Keterangan.

DmaWidth

Untuk perangkat DMA subordinat, anggota ini menentukan lebar data DMA untuk ditransfer oleh pengontrol DMA sistem. Nilai yang mungkin adalah Width8Bits, Width16Bits, Width32Bits, dan Width64Bits.

Untuk perangkat DMA master bus, nilai DmaWidth tidak digunakan.

DmaSpeed

Anggota ini hanya digunakan jika Versi DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1, atau DEVICE_DESCRIPTION_VERSION2.

Untuk perangkat DMA subordinat, anggota ini menentukan salah satu kecepatan berikut untuk DMA sistem: Kompatibel, TypeA, TypeB, TypeC, atau TypeF.

Untuk perangkat DMA master bus, nilai DmaSpeed tidak digunakan.

Jika Versi = DEVICE_DESCRIPTION_VERSION3, nilai DmaSpeed tidak digunakan.

MaximumLength

Jumlah maksimum byte yang dapat ditransfer perangkat dalam operasi DMA yang menggunakan objek adaptor yang dialokasikan.

DmaPort

Nomor port bus jenis Microchannel. Parameter ini kedaluwarsa, tetapi dipertahankan dalam struktur untuk kompatibilitas dengan driver warisan.

DmaAddressWidth

Anggota ini hanya digunakan jika Versi = DEVICE_DESCRIPTION_VERSION3.

Untuk perangkat DMA master bus, DmaAddressWidth menentukan lebar, dalam bit, dari alamat DMA. Nilai DmaAddressWidth harus bukan nol dan tidak boleh melebihi 64. Jika lebar alamat memori lebih besar dari lebar alamat DMA, daftar peta diperlukan untuk mengakses wilayah memori yang berada di luar jangkauan alamat pengontrol DMA.

Untuk perangkat DMA subordinat, nilai DmaAddressWidth tidak digunakan. Sebaliknya, IoGetDmaAdapter mengasumsikan bahwa lebar alamat perangkat DMA subordinat sama dengan pengontrol DMA sistem yang mendasar tempat perangkat terhubung.

DmaControllerInstance

Tidak digunakan.

DmaRequestLine

Anggota ini hanya digunakan jika Versi = DEVICE_DESCRIPTION_VERSION3.

Untuk perangkat DMA subordinat, DmaRequestLine menentukan baris permintaan pada pengontrol DMA tempat perangkat tersambung. Driver perangkat memperoleh jumlah baris permintaan ini dari daftar sumber daya yang diterimanya dalam permintaan IRP_MN_START_DEVICE yang memulai perangkat. Untuk informasi selengkapnya tentang nomor baris permintaan, lihat deskripsi anggota u.DmaV3.RequestLine di CM_PARTIAL_RESOURCE_DESCRIPTOR.

Untuk perangkat DMA master bus, nilai DmaRequestLine tidak digunakan.

DeviceAddress

Anggota ini hanya digunakan jika Versi = DEVICE_DESCRIPTION_VERSION3.

Untuk perangkat DMA subordinat, DeviceAddress adalah alamat pendaftaran data yang dipetakan memori pada perangkat yang digunakan sebagai sumber atau tujuan untuk transfer DMA. Pendaftaran data ini terletak di offset khusus perangkat yang diketahui dari alamat mulai perangkat. Lebar register ini ditentukan oleh anggota DmaWidth . Driver perangkat mendapatkan alamat mulai perangkat dari daftar sumber daya yang diterimanya dalam permintaan IRP_MN_START_DEVICE yang memulai perangkat. Untuk informasi selengkapnya tentang alamat ini, lihat deskripsi anggota u.Memory.Start di CM_PARTIAL_RESOURCE_DESCRIPTOR.

Untuk perangkat DMA master bus, anggota DeviceAddress tidak digunakan.

Keterangan

Driver perangkat yang menggunakan DMA untuk mentransfer data menggunakan struktur DEVICE_DESCRIPTION untuk meneruskan informasi tentang perangkat ke rutinitas IoGetDmaAdapter . Driver memanggil rutinitas ini untuk meminta objek adaptor untuk objek perangkat fisik (PDO). PDO ini mewakili koneksi fisik perangkat ke bus I/O yang akan digunakan untuk DMA. Untuk informasi selengkapnya, lihat Mendapatkan Objek Adapter.

Untuk mengalokasikan sumber daya untuk pengontrol DMA, manajer I/O memerlukan informasi tentang pengontrol tetapi dapat memperoleh beberapa informasi ini hanya dari driver. Misalnya, driver untuk perangkat bus-master tahu apakah perangkat mendukung sebar/kumpulkan DMA atau menggunakan alamat 32-bit penuh. Atau, driver untuk perangkat subordinat dapat menentukan nomor saluran DMA dari daftar sumber daya yang diterima driver dalam permintaan IRP_MN_START_DEVICE yang memulai perangkat. Driver menggunakan struktur DEVICE_DESCRIPTION untuk meneruskan informasi ini ke manajer I/O.

Sebelum memanggil IoGetDmaAdapter, driver harus terlebih dahulu menginisialisasi seluruh struktur DEVICE_DESCRIPTION , lalu mengisi anggota yang dipilih untuk menjelaskan perangkat.

Anggota InterfaceType menentukan jenis antarmuka bus yang akan digunakan untuk DMA. Jika Anda mengatur InterfaceType ke InterfaceTypeUndefined, IoGetDmaAdapter meminta PDO untuk menentukan jenis antarmuka yang benar untuk perangkat Anda. Atau, Anda dapat menentukan jenis antarmuka eksplisit, seperti Internal, Isa, Eisa, atau PCIBus. Untuk informasi selengkapnya, lihat daftar jenis antarmuka yang didukung di INTERFACE_TYPE.

Jika anggota ScatterGather diatur ke TRUE dan anggota InterfaceType diatur ke PCIBus, anggota Dma32BitAddresses diabaikan dan IoGetDmaAdapter mengasumsikan bahwa perangkat mendukung alamat DMA 32-bit.

Jika anggota Dma64BitAddresses diatur ke TRUE, anggota Dma32BitAddresses diabaikan dan IoGetDmaAdapter mengasumsikan bahwa perangkat mendukung alamat DMA 64-bit.

Untuk menunjukkan bahwa perangkat keras pengontrol DMA tidak dapat mempertahankan jumlah transfer yang akurat, atur IgnoreCount ke TRUE, dan atur Versi ke nilai selain DEVICE_DESCRIPTION_VERSION. Dalam platform yang memiliki pengontrol DMA seperti itu, sistem operasi mengabaikan penghitung transfer DMA tetapi harus mengambil tindakan pencegahan khusus untuk menjaga integritas data selama operasi DMA. Biasanya, penggunaan solusi untuk mengimbangi pengontrol DMA yang kekurangan menurunkan kecepatan transfer DMA.

Driver harus menentukan TypeF sebagai nilai DmaSpeed hanya jika firmware ACPI komputer mendukungnya.