IRP_MN_QUERY_DEVICE_RELATIONS

Artikel
06/15/2023

Manajer PnP mengirimkan permintaan ini untuk menentukan hubungan tertentu di antara perangkat. Jenis driver berikut menangani permintaan ini:

Pengemudi bus harus menangani permintaan BusRelations untuk adaptor atau pengontrolnya (bus FDO). Driver filter mungkin menangani permintaan BusRelations .
Driver bus harus menangani permintaan TargetDeviceRelation untuk perangkat anak mereka (PDO anak).
Driver fungsi dan filter mungkin menangani permintaan RemovalRelations dan PowerRelations .
Driver bus mungkin menangani permintaan EjectionRelations untuk perangkat anak mereka (PDO anak).

Nilai

0x07

Kode Utama

IRP_MJ_PNP

Ketika Dikirim

Manajer PnP mengirimkan IRP ini untuk mengumpulkan informasi tentang perangkat dengan hubungan ke perangkat yang ditentukan.

Manajer PnP meminta BusRelations (perangkat anak) perangkat saat perangkat dijumlahkan dan di lain waktu saat perangkat aktif, seperti ketika driver memanggil rutinitas IoInvalidateDeviceRelations untuk menunjukkan bahwa perangkat anak telah tiba atau berangkat.

Manajer PnP meminta RemovalRelations perangkat sebelum menghapus driver perangkat. Manajer PnP meminta RemovalRelations dan EjectionRelations sebelum mengeluarkan perangkat.

Manajer PnP meminta TargetDeviceRelation perangkat saat driver atau aplikasi mode pengguna mendaftar untuk pemberitahuan PnP dari EventCategoryTargetDeviceChange pada perangkat. Manajer PnP meminta perangkat yang terkait dengan objek file tertentu. IRP_MN_QUERY_DEVICE_RELATIONS adalah satu-satunya IRP PnP yang memiliki parameter objek file yang valid. Driver dapat mengkueri tumpukan perangkat untuk TargetDeviceRelation. Driver tidak perlu menyediakan objek file saat mengirim kueri TargetDeviceRelation-nya .

Manajer PnP meminta PowerRelations perangkat ketika driver untuk perangkat memanggil IoInvalidateDeviceRelations untuk menunjukkan bahwa kumpulan perangkat yang memiliki hubungan manajemen daya implisit telah berubah. Permintaan PowerRelations didukung dimulai dengan Windows 7.

Untuk permintaan BusRelations, RemovalRelations, EjectionRelations, dan PowerRelations , manajer PnP mengirimkan IRP_MN_QUERY_DEVICE_RELATIONS di IRQL = PASSIVE_LEVEL dalam konteks utas sistem.

Untuk permintaan TargetDeviceRelation , manajer PnP mengirimkan IRP ini di IRQL = PASSIVE_LEVEL dalam konteks utas arbitrer.

Parameter Input

Anggota Parameters.QueryDeviceRelations.Type dari struktur IO_STACK_LOCATION menentukan jenis relasi yang sedang dikueri. Nilai yang mungkin termasuk BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelation, dan PowerRelations.

Anggota FileObject dari struktur IO_STACK_LOCATION saat ini menunjuk ke objek file yang valid hanya jika Parameters.QueryDeviceRelations.Type adalah TargetDeviceRelation.

Parameter Output

Dikembalikan di blok status I/O.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau ke status kegagalan seperti STATUS_INSUFFICIENT_RESOURCES.

Setelah berhasil, driver menetapkan Irp-IoStatus.Information> ke penunjuk PDEVICE_RELATIONS yang menunjuk ke informasi hubungan yang diminta. Struktur DEVICE_RELATIONS didefinisikan sebagai berikut:

typedef struct _DEVICE_RELATIONS {
  ULONG  Count;
  PDEVICE_OBJECT  Objects[1];  // variable length
} DEVICE_RELATIONS, *PDEVICE_RELATIONS;

Operasi

Jika driver mengembalikan hubungan sebagai respons terhadap IRP_MN_QUERY_DEVICE_RELATIONS ini, driver mengalokasikan struktur DEVICE_RELATIONS dari memori halaman yang berisi hitungan dan jumlah penunjuk objek perangkat yang sesuai. Manajer PnP membebaskan struktur ketika tidak lagi diperlukan. Jika driver mengganti struktur DEVICE_RELATIONS yang dialokasikan driver lain, driver harus membebaskan struktur sebelumnya.

Driver harus mereferensikan PDO perangkat apa pun yang dilaporkannya dalam IRP ini (ObReferenceObject). Manajer PnP menghapus referensi jika sesuai.

Fungsi atau driver filter harus disiapkan untuk menangani IRP ini untuk perangkat kapan saja setelah rutinitas AddDevice selesai untuk perangkat. Driver bus harus siap menangani kueri untuk BusRelations segera setelah perangkat dijumlahkan.

Untuk aturan umum tentang penanganan Plug and Play runtime integrasi kecil, lihat Plug and Play.

Subbagian berikut menjelaskan tindakan tertentu untuk menangani berbagai kueri.

Permintaan BusRelations

Ketika manajer PnP meminta relasi bus (perangkat anak) adaptor atau pengontrol, pengemudi bus harus mengembalikan daftar pointer ke PDO perangkat apa pun yang ada secara fisik di bus. Pengemudi bus melaporkan semua perangkat, terlepas dari apakah mereka telah dimulai. Sopir bus mungkin perlu menyalakan perangkat busnya untuk menentukan anak-anak mana yang ada.

Peringatan Objek perangkat tidak dapat diteruskan ke rutinitas apa pun yang mengambil PDO sebagai argumen hingga manajer PnP membuat simpul perangkat (devnode) untuk objek tersebut. (Jika driver melewati objek perangkat, sistem akan memeriksa bug dengan Pemeriksaan Bug 0xCA: PNP_DETECTED_FATAL_ERROR.) Manajer PnP membuat devnode sebagai respons terhadap permintaan IRP_MN_QUERY_DEVICE_RELATIONS . Driver dapat dengan aman mengasumsikan bahwa devnode PDO telah dibuat ketika menerima permintaan IRP_MN_QUERY_RESOURCE_REQUIREMENTS .

Pengemudi bus yang merespons IRP ini adalah driver fungsi untuk adaptor atau pengontrol bus, bukan pengemudi bus induk untuk bus yang terhubung dengan adaptor atau pengontrol. Driver fungsi untuk perangkat non-bus tidak menangani kueri ini. Pengemudi seperti itu hanya meneruskan IRP ke pengemudi bawah berikutnya. (Lihat gambar berikut.) Driver filter biasanya tidak menangani kueri ini.

Pada Windows Vista dan sistem operasi yang lebih baru, kami menyarankan agar driver selalu menunggu IRP_MN_QUERY_DEVICE_RELATIONS IRP dan menyelesaikan pemrosesannya nanti. Urutan ini memungkinkan sistem untuk memproses kueri relasi bus secara asinkron. (Pada sistem operasi sebelum Windows Vista, driver dapat dengan aman mengembalikan STATUS_PENDING dari rutinitas pengiriman mereka, tetapi manajer PnP tidak tumpang tindih dengan kueri relasi bus dengan operasi lain.)

Diagram berikut menunjukkan cara driver menangani kueri untuk relasi bus.

diagram yang mengilustrasikan pengemudi yang menangani kueri untuk relasi bus.

Dalam contoh yang ditunjukkan pada gambar, manajer PnP mengirimkan IRP_MN_QUERY_DEVICE_RELATIONS untuk BusRelations ke driver untuk perangkat hub USB. Manajer PnP meminta daftar anak perangkat hub.

Seperti semua IRP PnP, manajer PnP mengirim IRP ke driver teratas di tumpukan perangkat untuk perangkat.
Driver filter opsional mungkin merupakan driver teratas di tumpukan. Driver filter biasanya tidak menangani IRP ini; melewati IRP ke bawah tumpukan. Driver filter mungkin menangani IRP ini, misalnya, jika driver mengekspos perangkat yang tidak dapat dijumlahkan di bus.
Driver bus hub USB menangani IRP.

Driver bus hub USB:
- Membuat PDO untuk perangkat anak apa pun yang belum memilikinya.
- Menandai PDO tidak aktif untuk perangkat apa pun yang tidak lagi ada di bus. Driver bus tidak menghapus PDO tersebut.Untuk informasi selengkapnya tentang kapan harus menghapus PDO, lihat Menghapus Perangkat.
- Melaporkan perangkat anak apa pun yang ada di bus.
  
  Untuk setiap perangkat anak, driver bus mereferensikan PDO dan menempatkan pointer ke PDO dalam struktur DEVICE_RELATIONS.
  
  Ada dua PDO dalam contoh ini: satu untuk perangkat joystick dan satu untuk perangkat keyboard.
  
  Pengemudi bus harus memeriksa apakah pengemudi lain sudah membuat struktur DEVICE_RELATIONS untuk IRP ini. Jika demikian, pengemudi bus harus menambahkan ke informasi yang ada.
  
  Jika tidak ada perangkat anak yang ada di bus, driver mengatur hitungan ke nol dalam struktur DEVICE_RELATIONS dan mengembalikan keberhasilan.
- Mengatur nilai yang sesuai di blok status I/O dan meneruskan IRP ke driver yang lebih rendah berikutnya. Driver bus untuk adaptor atau pengontrol tidak menyelesaikan IRP.
Filter opsional yang lebih rendah, jika ada, biasanya tidak menangani IRP ini. Driver filter seperti itu melewati IRP ke bawah tumpukan. Jika driver filter bawah menangani IRP ini, driver dapat menambahkan PDO ke daftar perangkat anak tetapi tidak boleh menghapus PDO apa pun yang dibuat oleh driver lain.
Driver bus induk tidak menangani IRP ini, kecuali jika itu adalah satu-satunya driver di tumpukan perangkat (perangkat dalam mode mentah). Seperti semua IRP PnP, pengemudi bus induk menyelesaikan IRP dengan IoCompleteRequest.

Jika ada satu atau beberapa driver filter bus di tumpukan perangkat, driver tersebut mungkin menangani IRP saat turun ke pengemudi bus dan/atau saat IRP mencadangkan tumpukan perangkat (jika ada rutinitas IoCompletion ). Menurut aturan IRP PnP, driver tersebut dapat menambahkan PDO ke IRP saat turun ke tumpukan dan/atau memodifikasi daftar hubungan pada cara IRP mencadangkan tumpukan (dalam rutinitas IoCompletion ).

Permintaan EjectionRelations

Driver mengembalikan pointer ke PDO dari perangkat apa pun yang mungkin dihapus secara fisik dari sistem ketika perangkat yang ditentukan dikeluarkan. Jangan laporkan PDO anak-anak perangkat; manajer PnP selalu meminta agar perangkat anak dihapus sebelum perangkat induknya.

Manajer PnP mengirimkan IRP IRP_MN_EJECT ke perangkat yang sedang dikeluarkan. Driver untuk perangkat tersebut juga menerima hapus IRP. Hubungan ejeksi perangkat menerima IRP IRP_MN_REMOVE_DEVICE (bukan IRP IRP_MN_EJECT ).

Hanya pengemudi bus induk yang dapat merespons kueri EjectionRelations untuk salah satu perangkat turunannya. Driver fungsi dan filter harus meneruskannya ke driver bawah berikutnya di tumpukan perangkat. Jika pengemudi bus menerima IRP ini sebagai driver fungsi untuk adaptor atau pengontrolnya, pengemudi bus melakukan tugas driver fungsi dan harus meneruskan IRP ke driver yang lebih rendah berikutnya.

Permintaan PowerRelations

Dimulai dengan Windows 7, kueri PowerRelations memungkinkan driver menentukan hubungan manajemen daya di luar hubungan konvensional antara bus induk yang mendukung enumerasi PnP dan perangkat anak yang dijumlahkan di bus. Misalnya, jika pengemudi bus tidak dapat menghitung perangkat anak di bus, atau jika perangkat adalah anak dari lebih dari satu bus, kueri PowerRelations dapat menjelaskan hubungan daya perangkat anak dengan bus atau bus.

Manajer PnP mengeluarkan kueri PowerRelations untuk perangkat saat driver untuk perangkat memanggil rutinitas IoInvalidateDeviceRelations dan menentukan nilai parameter JenisPowerRelations.

Menanggapi kueri ini, driver untuk perangkat target (yaitu, perangkat yang menjadi target untuk kueri) menyediakan struktur DEVICE_RELATIONS yang berisi penunjuk ke PDO perangkat lain yang harus diaktifkan oleh manajer daya sebelum perangkat target diaktifkan. Sebaliknya, perangkat lain ini harus dimatikan hanya setelah perangkat target dimatikan. Manajer daya menggunakan informasi dari kueri untuk menjamin bahwa perangkat ini diaktifkan dan dinonaktifkan dalam urutan yang benar.

Jaminan pemesanan ini hanya berlaku untuk transisi status tidur sistem global, yang mencakup transisi ke dan dari status daya sistem S1, S2, S3 (tidur), S4 (hibernasi), dan S5 (matikan). Jaminan pemesanan PowerRelations tidak berlaku untuk transisi status daya perangkat Dx saat sistem tetap dalam status sistem S0 (berjalan), kecuali dalam kasus transisi Directed Runtime Power Management (DFx ).

Jika perangkat target berada di jalur perangkat untuk file khusus (seperti file halaman, file hibernasi, atau file crash dump), driver untuk perangkat target harus melakukan langkah tambahan saat menangani IRP IRP_MN_DEVICE_USAGE_NOTIFICATIONdi mana InPathTRUE. Driver ini harus memastikan bahwa perangkat yang PDO-nya disediakan untuk kueri PowerRelations juga dapat mendukung berada di jalur perangkat untuk file khusus. Untuk mengonfirmasi dukungan ini, driver untuk perangkat target harus terlebih dahulu mengirim IRP_MN_DEVICE_USAGE_NOTIFICATION IRP ke masing-masing perangkat ini, dan IRP ini harus menentukan UsageNotification.Type yang sama dengan perangkat target. Hanya jika semua perangkat yang menerima IRP ini menyelesaikan IRP dengan kode status keberhasilan dapat driver untuk perangkat target berhasil menyelesaikan IRP_MN_DEVICE_USAGE_NOTIFICATION IRP-nya. Jika tidak, driver ini harus menyelesaikan IRP ini dengan kode status kegagalan.

Ketika driver yang sama ini menangani IRP IRP_MN_DEVICE_USAGE_NOTIFICATIONyang InPath-nyaFALSE, driver harus mengirim IRP IRP_MN_DEVICE_USAGE_NOTIFICATION ke set perangkat dependen yang sama seperti untuk kasus di mana InPathTRUE. Namun, driver tidak boleh menyelesaikan IRP ini dengan kode status kegagalan ketika InPathFALSE.

Driver yang merespons kueri PowerRelations harus mendaftar untuk pemberitahuan perubahan perangkat target di semua perangkat yang PDO-nya disediakan untuk kueri PowerRelations . Untuk mendaftar pemberitahuan ini, driver dapat memanggil rutinitas IoRegisterPlugPlayNotification dan menentukan nilai parameter EventCategoryEventCategoryTargetDeviceChange.

Permintaan RemovalRelations

Driver mengembalikan penunjuk ke PDO dari perangkat apa pun yang drivernya harus dihapus ketika driver untuk perangkat yang ditentukan dihapus. Jangan laporkan PDO anak-anak perangkat; manajer PnP sudah meminta penghapusan perangkat anak sebelum menghapus perangkat.

Urutan penghapusan hubungan dihapus tidak terdefinisi.

Setiap driver dalam tumpukan perangkat dapat menangani jenis kueri relasi ini. Fungsi atau driver filter menangani IRP sebelum meneruskannya ke driver bawah berikutnya. Pengemudi bus menangani IRP dan kemudian menyelesaikannya.

Permintaan TargetDeviceRelation

Kueri TargetDeviceRelation memungkinkan manajer PnP untuk mengkueri tumpukan perangkat non-PnP untuk PDO di tumpukan perangkat PnP yang mengontrol perangkat keras.

Secara umum, driver meneruskan IRP_MN_QUERY_DEVICE_RELATIONS IRP ke bawah tumpukannya sampai IRP mencapai bagian bawah tumpukan perangkat tertentu. Driver di bagian bawah tumpukan non-PnP kemudian meneruskan atau menerbitkan ulang IRP ke tumpukan PnP yang relevan. Misalnya, manajer PnP mungkin mengirim kueri TargetDeviceRelation ke objek perangkat di bagian atas tumpukan sistem file, yang merupakan tumpukan non-PnP. Setiap objek perangkat dalam tumpukan sistem file akan meneruskan kueri ke objek perangkat di bawahnya sampai kueri mencapai objek perangkat di bagian bawah tumpukan. Objek perangkat terendah dalam tumpukan akan meneruskan atau menerbitkan ulang kueri TargetDeviceRelation ke objek perangkat di bagian atas tumpukan volume penyimpanan PnP, dan kemudian kueri akan diteruskan ke PDO di bagian bawah tumpukan volume penyimpanan.

Daftar berikut ini meringkas situasi di mana Anda dapat memperoleh penunjuk dengan aman ke PDO di bagian bawah tumpukan perangkat PnP:

Objek perangkat dalam PnP

Objek perangkat yang berada dalam tumpukan perangkat PnP mempelajari tentang PDO tumpukan saat rutinitas AddDevice untuk perangkat dipanggil. Driver dapat dengan aman menyimpan penunjuk ke PDO jika penggunaan pointer disinkronkan dengan benar dengan pesan IRP_MN_REMOVE_DEVICE masuk dengan menggunakan rutinitas hapus kunci.
Objek perangkat dalam tumpukan non-PnP, bukan di bagian bawah tumpukan

Untuk objek perangkat yang tidak berada di bagian bawah tumpukan non-PnP, driver dapat mengirim kueri TargetDeviceRelation untuk mendapatkan penunjuk ke PDO di bagian bawah tumpukan perangkat PnP yang sesuai.
Objek file untuk perangkat

Mengingat objek file untuk perangkat, driver dapat memanggil IoGetRelatedDeviceObject untuk mendapatkan objek perangkat lalu mengikuti instruksi dalam item daftar sebelumnya.
Menangani ke objek perangkat

Diberikan handel ke objek perangkat, driver dapat memanggil ObReferenceObjectByHandle untuk mendapatkan objek file untuk perangkat lalu mengikuti instruksi dalam item daftar sebelumnya.

Driver bus induk harus menangani kueri hubungan TargetDeviceRelation untuk perangkat turunannya. Driver bus mereferensikan PDO perangkat anak dengan ObReferenceObject dan mengembalikan pointer ke PDO dalam struktur DEVICE_RELATIONS . Hanya ada satu penunjuk PDO dalam struktur untuk jenis relasi ini. Manajer PnP menghapus referensi ke PDO ketika driver atau aplikasi membatalkan pendaftaran pemberitahuan pada perangkat.

Hanya pengemudi bus induk yang merespons kueri TargetDeviceRelation . Driver fungsi dan filter harus meneruskannya ke driver bawah berikutnya di tumpukan perangkat. Jika pengemudi bus menerima IRP ini sebagai driver fungsi untuk adaptor atau pengontrolnya, pengemudi bus melakukan tugas driver fungsi dan harus meneruskan IRP ke driver yang lebih rendah berikutnya.

Jika driver tidak berada dalam tumpukan berbasis PDO, driver mengirim IRP kueri relasi perangkat target baru ke objek perangkat yang terkait dengan handel file tempat driver melakukan I/O.

Mengirim IRP ini

Driver tidak boleh mengirim IRP_MN_QUERY_DEVICE_RELATIONS untuk meminta BusRelations. Driver tidak dibatasi untuk mengirim IRP ini untuk RemovalRelations atau EjectionRelations, tetapi tidak mungkin driver akan melakukannya.

Driver dapat mengkueri tumpukan perangkat untuk TargetDeviceRelation. Lihat Menangani IRP untuk informasi tentang pengiriman RUN. Langkah-langkah berikut berlaku khusus untuk IRP ini:

Atur nilai di lokasi tumpukan I/O berikutnya dari IRP: atur MajorFunction ke IRP_MJ_PNP, atur MinorFunction ke IRP_MN_QUERY_DEVICE_RELATIONS, atur Parameters.QueryDeviceRelations.Type ke TargetDeviceRelation, dan atur Irp-FileObject> ke objek file yang valid.
Menginisialisasi IoStatus.Status ke STATUS_NOT_SUPPORTED.

Jika driver mengirim IRP ini untuk membuat PDO melaporkan sebagai respons terhadap IRP_MN_QUERY_DEVICE_RELATIONS untuk TargetDeviceRelation yang diterima driver, maka driver melaporkan PDO dan membebaskan struktur hubungan yang dikembalikan ketika IRP selesai. Jika driver memulai IRP ini karena alasan lain, driver membebaskan struktur hubungan ketika IRP selesai dan mendereferensikan PDO ketika tidak lagi diperlukan.