Bekerja dengan GUID_DEVICE_RESET_INTERFACE_STANDARD

Artikel
06/14/2023

Antarmuka GUID_DEVICE_RESET_INTERFACE_STANDARD mendefinisikan cara standar bagi driver fungsi untuk mencoba mengatur ulang dan memulihkan perangkat yang tidak berfungsi.

Dua jenis reset perangkat tersedia melalui antarmuka ini:

Reset perangkat tingkat fungsi. Dalam hal ini, operasi reset dibatasi untuk perangkat tertentu, dan tidak terlihat oleh perangkat lain. Perangkat tetap terhubung ke bus di seluruh reset dan kembali ke status valid (status awal) setelah reset. Jenis reset ini memiliki dampak paling sedikit pada sistem.
- Jenis reset ini dapat diimplementasikan baik oleh pengemudi bus atau oleh firmware ACPI. Pengemudi bus dapat menerapkan reset tingkat fungsi jika spesifikasi bus menentukan mekanisme reset in-band yang memenuhi persyaratan. Firmware ACPI dapat secara opsional mengambil alih reset tingkat fungsi yang ditentukan pengemudi bus dengan implementasinya sendiri.
Reset perangkat tingkat platform. Dalam hal ini, operasi reset menyebabkan perangkat dilaporkan hilang dari bus. Operasi reset memengaruhi perangkat tertentu dan semua perangkat lain yang terhubung ke perangkat tersebut melalui rel daya atau jalur reset yang sama. Jenis reset ini memiliki dampak paling besar pada sistem. OS akan merobohkan dan membangun kembali tumpukan semua perangkat yang terpengaruh untuk memastikan bahwa semuanya dimulai ulang dari status kosong.

Mulai dari Windows 10, entri registri ini di bawah HKLM\SYSTEM\CurrentControlSet\Control\Pnp kunci mengonfigurasi operasi reset:

DeviceResetRetryInterval: Periode waktu sebelum operasi reset dimulai. Nilai defaultnya adalah 3 detik. Nilai minimum adalah 100 milidetik; nilai maksimum adalah 30 detik.
DeviceResetMaximumRetries: Berapa kali operasi reset dicoba.

Catatan

Antarmuka GUID_DEVICE_RESET_INTERFACE_STANDARD tersedia mulai dari Windows 10.

Menggunakan antarmuka reset perangkat

Jika driver fungsi mendeteksi bahwa perangkat tidak berfungsi dengan benar, pertama-tama harus mencoba reset tingkat fungsi. Jika reset tingkat fungsi tidak memperbaiki masalah, maka driver dapat memilih untuk mencoba reset tingkat platform. Namun, reset tingkat platform hanya boleh digunakan sebagai opsi akhir.

Untuk mengkueri antarmuka ini, driver perangkat mengirim IRP_MN_QUERY_INTERFACE IRP ke bawah tumpukan driver. Untuk IRP ini, driver mengatur parameter input InterfaceType ke GUID_DEVICE_RESET_INTERFACE_STANDARD. Setelah berhasil menyelesaikan IRP, parameter output Antarmuka adalah penunjuk ke struktur DEVICE_RESET_INTERFACE_STANDARD. Struktur ini berisi penunjuk ke rutinitas DeviceReset, yang dapat digunakan untuk meminta reset tingkat fungsi atau tingkat platform.

Mendukung antarmuka reset perangkat di driver fungsi

Untuk mendukung antarmuka reset perangkat, tumpukan perangkat harus memenuhi persyaratan berikut.

Driver fungsi harus menangani IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_REMOVE_DEVICE, dan IRP_MN_SURPRISE_REMOVAL dengan benar.

Dalam kebanyakan kasus, ketika driver menerima IRP_MN_QUERY_REMOVE_DEVICE, driver harus mengembalikan keberhasilan sehingga perangkat dapat dihapus dengan aman. Namun, mungkin ada kasus di mana perangkat tidak dapat dihentikan dengan aman, seperti jika perangkat terjebak dalam penulisan perulangan ke buffer memori. Dalam kasus seperti itu, driver harus mengembalikan STATUS_DEVICE_HUNG ke IRP_MN_QUERY_REMOVE_DEVICE. Manajer PnP akan melanjutkan proses IRP_MN_QUERY_REMOVE_DEVICE dan IRP_MN_REMOVE_DEVICE, tetapi tumpukan tertentu tidak akan menerima IRP_MN_REMOVE_DEVICE. Sebaliknya, tumpukan perangkat akan menerima IRP_MN_SURPRISE_REMOVAL setelah perangkat direset.

Untuk informasi selengkapnya tentang IRP ini, lihat:

Menangani Permintaan IRP_MN_QUERY_REMOVE_DEVICE

Menangani Permintaan IRP_MN_REMOVE_DEVICE

Menangani Permintaan IRP_MN_SURPRISE_REMOVAL

Mendukung antarmuka reset perangkat di driver filter

Driver filter dapat mencegat IRP_MN_QUERY_INTERFACE RUN yang memiliki jenis antarmuka GUID_DEVICE_RESET_INTERFACE_STANDARD. Dengan demikian, mereka dapat terus mendelegasikan ke antarmuka GUID_DEVICE_RESET_INTERFACE_STANDARD tetapi melakukan operasi khusus perangkat sebelum atau sesudah operasi reset. Atau, mereka dapat mengambil alih antarmuka GUID_DEVICE_RESET_INTERFACE_STANDARD yang dikembalikan oleh pengemudi bus dengan antarmukanya sendiri untuk menyediakan operasi resetnya sendiri.

Mendukung antarmuka reset perangkat di driver bus

Driver bus yang berpartisipasi dalam proses reset perangkat (yaitu, driver bus yang terkait dengan perangkat yang meminta reset dan driver bus yang terkait dengan perangkat yang merespons permintaan reset) harus memenuhi salah satu persyaratan berikut:

Mampu steker panas. Pengemudi bus harus dapat mendeteksi perangkat yang dihapus dari bus tanpa pemberitahuan, dan perangkat yang dicolokkan ke bus.
Atau, ia harus mengimplementasikan antarmuka GUID_REENUMERATE_SELF_INTERFACE_STANDARD. Ini mensimulasikan perangkat yang ditarik dari bus dan dicolokkan kembali. Driver bus bawaan (seperti PCI dan SDBUS) mendukung antarmuka ini. Oleh karena itu, jika perangkat yang direset menggunakan salah satu bus ini, tidak ada modifikasi driver bus yang diperlukan.

Untuk driver bus berbasis WDF, kerangka kerja WDF mendaftarkan antarmuka GUID_REENUMERATE_SELF_INTERFACE_STANDARD atas nama driver. Oleh karena itu, mendaftarkan antarmuka ini tidak diperlukan untuk driver tersebut. Jika driver bus perlu melakukan beberapa operasi sebelum perangkat anaknya dijumlahkan kembali, driver bus harus mendaftar untuk rutinitas panggilan balik EvtChildListDeviceReenumerated dan melakukan operasi dalam rutinitas tersebut. Karena rutinitas panggilan balik ini dapat dipanggil secara paralel untuk semua PDO, kode dalam rutinitas mungkin perlu dilindungi dari kondisi ras.

Firmware ACPI: Reset tingkat fungsi

Untuk mendukung reset perangkat tingkat fungsi, harus ada metode _RST yang ditentukan di dalam cakupan Perangkat. Jika ada, metode ini akan mengambil alih implementasi driver bus dari reset perangkat tingkat fungsi (jika ada) untuk perangkat tersebut. Saat dijalankan, metode _RST harus mengatur ulang hanya perangkat tersebut, dan tidak boleh memengaruhi perangkat lain. Selain itu, perangkat harus tetap terhubung di bus.

Firmware ACPI: Reset tingkat platform

Untuk mendukung reset perangkat tingkat platform, ada dua opsi:

Firmware ACPI dapat menentukan PowerResource yang mengimplementasikan metode _RST, dan semua perangkat yang terpengaruh oleh metode reset ini dapat merujuk ke PowerResource ini melalui objek _PRR yang ditentukan di bawah cakupan Perangkat mereka.
Perangkat dapat mendeklarasikan objek _PR3. Dalam hal ini, driver ACPI akan menggunakan daur daya D3cold untuk melakukan reset, dan mengatur ulang dependensi antara perangkat akan ditentukan dari objek _PR3.

Jika objek _PRR ada dalam cakupan Perangkat, driver ACPI akan menggunakan metode _RST di PowerResource yang direferensikan untuk melakukan reset. Jika tidak ada objek _PRR yang ditentukan tetapi objek _PR3 ditentukan, maka driver ACPI akan menggunakan siklus daya D3cold untuk melakukan reset. Jika tidak ada objek _PRR atau _PR3 yang ditentukan, maka perangkat tidak mendukung reset tingkat platform dan driver ACPI akan melaporkan bahwa reset tingkat platform tidak tersedia.

Memverifikasi firmware ACPI pada sistem pengujian

Untuk menguji driver Anda yang mendukung reset dan pemulihan perangkat, ikuti prosedur ini. Prosedur ini mengasumsikan Anda menggunakan contoh file ASL ini.

DefinitionBlock("SSDT.AML", "SSDT", 0x01, "XyzOEM", "TestTabl", 0x00001000)
{
   Scope(\_SB_)
      {
       PowerResource(PWFR, 0x5, 0x0)
       {
           Method(_RST, 0x0, NotSerialized)    { }
           
           // Placeholder methods as power resources need _ON, _OFF, _STA.
           Method(_STA, 0x0, NotSerialized)
           {
               Return(0xF)
           }

           Method(_ON_, 0x0, NotSerialized)    { }

           Method(_OFF, 0x0, NotSerialized)    { }

       } // PowerResource()
   } // Scope (\_SB_)

   // Assumes WiFi device is declared under \_SB.XYZ.
   Scope(\_SB_.XYZ.WIFI)
       {

       // Declare PWFR as WiFi reset power rail
       Name(_PRR, Package(One)
           {
               \_SB_.PWFR
           })
       } // Scope (\_SB)
}

Kompilasi file ASL pengujian ke AML dengan menggunakan pengkompilasi ASL, seperti Asl.exe. Executable yang disertakan dalam Windows Driver Kit (WDK).

Asl <test>.asl

Perintah sebelumnya menghasilkan SSDT.aml.

Ganti nama SSDT.aml menjadi acpitabl.dat.
Salin acpitabl.dat ke %systemroot%\system32 pada sistem pengujian.
Aktifkan penandatanganan pengujian pada sistem pengujian.

bcdedit /set testsigning on

Reboot sistem pengujian.
Verifikasi bahwa tabel dimuat. Di Windows Debugger, gunakan perintah ini.

!acpicache
dt _DESCRIPTION_HEADER alamat tabel SSDT

0: kd> !acpicache
Dumping cached ACPI tables...
  SSDT @(ffffffffffd03018) Rev: 0x1 Len: 0x000043 TableID: TestTabl
  XSDT @(ffffffffffd05018) Rev: 0x1 Len: 0x000114 TableID: HSW-FFRD
       ...
       ...
 
0: kd> dt _DESCRIPTION_HEADER ffffffffffd03018
ACPI!_DESCRIPTION_HEADER
   +0x000 Signature        : 0x54445353
   +0x004 Length           : 0x43
   +0x008 Revision         : 0x1 ''
   +0x009 Checksum         : 0x37 '7'
   +0x00a OEMID            : [6]  "XyzOEM"
   +0x010 OEMTableID       : [8]  "TestTabl"
   +0x018 OEMRevision      : 0x1000
   +0x01c CreatorID        : [4]  "MSFT"
   +0x020 CreatorRev       : 0x5000000

Lihat juga

_DEVICE_RESET_INTERFACE_STANDARD

Bagikan melalui