struktur DRIVER_OBJECT (wdm.h)

Artikel
03/01/2024

Setiap objek driver mewakili gambar driver mode kernel yang dimuat. Penunjuk ke objek driver adalah parameter input ke DriverEntry, AddDevice, dan opsional Menginisialisasi ulang rutinitas dan untuk rutinitas Bongkar muatnya , jika ada.

Objek driver sebagian buram. Penulis driver harus tahu tentang anggota tertentu dari objek driver untuk menginisialisasi driver dan untuk membongkarnya jika driver tidak dapat dimuat. Anggota objek driver berikut dapat diakses oleh driver.

Sintaks

typedef struct _DRIVER_OBJECT {
  CSHORT             Type;
  CSHORT             Size;
  PDEVICE_OBJECT     DeviceObject;
  ULONG              Flags;
  PVOID              DriverStart;
  ULONG              DriverSize;
  PVOID              DriverSection;
  PDRIVER_EXTENSION  DriverExtension;
  UNICODE_STRING     DriverName;
  PUNICODE_STRING    HardwareDatabase;
  PFAST_IO_DISPATCH  FastIoDispatch;
  PDRIVER_INITIALIZE DriverInit;
  PDRIVER_STARTIO    DriverStartIo;
  PDRIVER_UNLOAD     DriverUnload;
  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];
} DRIVER_OBJECT, *PDRIVER_OBJECT;

Anggota

Type

Menentukan Jenis anggota CSHORT.

Size

Menentukan Ukuran anggota CSHORT.

DeviceObject

Arahkan ke objek perangkat yang dibuat oleh driver. Anggota ini secara otomatis diperbarui ketika driver berhasil memanggil IoCreateDevice . Driver dapat menggunakan anggota ini dan anggota NextDevicedari DEVICE_OBJECT untuk menelusuri daftar semua objek perangkat yang dibuat driver.

Flags

Mendefinisikan Bendera anggota ULONG.

DriverStart

Mendefinisikan DriverStart anggota PVOID.

DriverSize

Mendefinisikan DriverSize anggota ULONG.

DriverSection

Mendefinisikan DriverSection anggota PVOID.

DriverExtension

Arahkan ke ekstensi driver. Satu-satunya anggota ekstensi driver yang dapat diakses adalah DriverExtension-AddDevice>, di mana rutinitas DriverEntry driver menyimpan rutinitas AddDevice driver.

DriverName

Menentukan anggota UNICODE_STRINGDriverName.

HardwareDatabase

Arahkan ke jalur \Registry\Machine\Hardware ke informasi konfigurasi perangkat keras di registri.

FastIoDispatch

Penunjuk ke struktur yang mendefinisikan titik masuk I/O cepat driver. Anggota ini hanya digunakan oleh FSD dan driver transportasi jaringan.

DriverInit

Titik masuk untuk rutinitas DriverEntry , yang disiapkan oleh manajer I/O.

DriverStartIo

Titik masuk untuk rutinitas StartIo driver, jika ada, yang diatur oleh rutinitas DriverEntry ketika driver menginisialisasi. Jika driver tidak memiliki rutinitas StartIo , anggota ini adalah NULL.

DriverUnload

Titik masuk untuk rutinitas Bongkar driver, jika ada, yang ditetapkan oleh rutinitas DriverEntry ketika driver menginisialisasi. Jika driver tidak memiliki rutinitas Bongkar , anggota ini adalah NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Tabel pengiriman yang terdiri dari array titik masuk untuk rutinitas DispatchXxx driver. Nilai indeks array adalah nilai IRP_MJ_XXX yang mewakili setiap kode fungsi utama IRP. Setiap driver harus mengatur titik masuk dalam array ini untuk permintaan IRP_MJ_XXX yang ditangani driver. Untuk informasi selengkapnya, lihat Menulis Rutinitas Pengiriman.

Untuk membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya, setiap rutinitas DispatchXxx dinyatakan menggunakan jenis DRIVER_DISPATCH, seperti yang ditunjukkan dalam contoh kode ini:

DRIVER_DISPATCH DispatchXxx;

Kemudian, rutinitas panggilan balik diimplementasikan sebagai berikut:

_Use_decl_annotations_
NTSTATUS
  DispatchXxx(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Jenis fungsi DRIVER_DISPATCH didefinisikan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan _Use_decl_annotations_ anotasi ke definisi fungsi Anda. Anotasi _Use_decl_annotations_ memastikan bahwa anotasi yang diterapkan ke jenis fungsi DRIVER_DISPATCH dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang _Use_decl_annotations_, lihat Menganotasi Perilaku Fungsi.

Keterangan

Setiap rutinitas inisialisasi driver mode kernel harus diberi nama DriverEntry sehingga sistem akan memuat driver secara otomatis. Jika nama rutin ini adalah sesuatu yang lain, penulis driver harus menentukan nama rutinitas inisialisasi untuk linker; jika tidak, loader sistem atau manajer I/O tidak dapat menemukan alamat transfer driver. Nama-nama rutinitas driver standar lainnya dapat dipilih atas kebijakan penulis driver.

Driver harus mengatur titik masuk DispatchXxx di objek driver yang diteruskan ke rutinitas DriverEntry ketika driver dimuat. Driver perangkat harus mengatur satu atau beberapa titik masuk DispatchXxx untuk IRP_MJ_XXX yang harus ditangani oleh driver dari jenis perangkat yang sama. Driver tingkat yang lebih tinggi harus mengatur satu atau beberapa titik masuk DispatchXxx untuk semua IRP_MJ_XXX yang harus diteruskan ke driver perangkat yang mendasar. Jika tidak, driver tidak dikirim IRP untuk IRP_MJ_XXX yang tidak mengatur rutinitas DispatchXxx di objek driver. Untuk informasi selengkapnya tentang kumpulan IRP_MJ_XXXX yang diperlukan driver untuk berbagai jenis perangkat yang mendasar untuk ditangani, lihat Kode Fungsi Utama IRP.

Rutinitas DriverEntry juga mengatur titik masuk AddDevice, StartIo , dan/atau Unload driver, jika ada, di objek driver.

String HardwareDatabase dapat digunakan oleh driver perangkat untuk mendapatkan informasi konfigurasi perangkat keras dari registri ketika driver dimuat. Driver diberikan akses baca-saja ke string ini.

Input RegistryPath ke driverEntry rutin menunjuk ke kunci \Registry\Machine\System\CurrentControlSet\Services\DriverName , di mana entri nilai DriverName mengidentifikasi driver. Adapun HardwareDatabase dalam objek driver input, driver diberikan akses baca-saja ke string ini.

Anggota yang tidak terdokumentasi dalam objek driver harus dianggap tidak dapat diakses. Driver dengan dependensi pada lokasi anggota objek atau pada akses ke anggota yang tidak terdokumentasi mungkin tidak tetap portabel dan dapat dioperasikan dengan driver lain dari waktu ke waktu.