Utilizzo del GUID_DEVICE_RESET_INTERFACE_STANDARD

Articolo
06/15/2023

L'interfaccia GUID_DEVICE_RESET_INTERFACE_STANDARD definisce un modo standard per consentire ai driver di funzione di tentare di reimpostare e ripristinare un dispositivo che non funziona correttamente.

Tramite questa interfaccia sono disponibili due tipi di reimpostazioni dei dispositivi:

Reimpostazione del dispositivo a livello di funzione. In questo caso, l'operazione di reimpostazione è limitata a un dispositivo specifico e non è visibile ad altri dispositivi. Il dispositivo rimane connesso al bus durante il ripristino e torna a uno stato valido (stato iniziale) dopo la reimpostazione. Questo tipo di reimpostazione ha l'impatto minimo sul sistema.
- Questo tipo di reimpostazione può essere implementato dal driver del bus o dal firmware ACPI. Il driver del bus può implementare una reimpostazione a livello di funzione se la specifica del bus definisce un meccanismo di reimpostazione in banda che soddisfa i requisiti. Il firmware ACPI può facoltativamente eseguire l'override di una reimpostazione a livello di funzione definita dal driver del bus con la propria implementazione.
Reimpostazione del dispositivo a livello di piattaforma. In questo caso, l'operazione di reimpostazione fa sì che il dispositivo venga segnalato come mancante dal bus. L'operazione di reimpostazione influisce su un dispositivo specifico e su tutti gli altri dispositivi connessi tramite la stessa linea di alimentazione o reimpostazione. Questo tipo di reimpostazione ha l'impatto maggiore sul sistema. Il sistema operativo rimuove e ricompila gli stack di tutti i dispositivi interessati per garantire che tutto venga riavviato da uno stato vuoto.

A partire da Windows 10, queste voci del Registro di sistema nella HKLM\SYSTEM\CurrentControlSet\Control\Pnp chiave configurano l'operazione di reimpostazione:

DeviceResetRetryInterval: periodo di tempo prima dell'avvio dell'operazione di reimpostazione. Il valore predefinito è 3 secondi. Il valore minimo è 100 millisecondi; il valore massimo è 30 secondi.
DeviceResetMaximumRetries: numero di tentativi di reimpostazione dell'operazione.

Nota

L'interfaccia GUID_DEVICE_RESET_INTERFACE_STANDARD è disponibile a partire da Windows 10.

Uso dell'interfaccia di reimpostazione del dispositivo

Se un driver di funzione rileva che il dispositivo non funziona correttamente, deve prima tentare una reimpostazione a livello di funzione. Se una reimpostazione a livello di funzione non risolve il problema, il driver può scegliere di tentare una reimpostazione a livello di piattaforma. Tuttavia, una reimpostazione a livello di piattaforma deve essere usata solo come opzione finale.

Per eseguire una query per questa interfaccia, un driver di dispositivo invia un IRP_MN_QUERY_INTERFACE IRP nello stack di driver. Per questo IRP, il driver imposta il parametro di input InterfaceType su GUID_DEVICE_RESET_INTERFACE_STANDARD. Al termine dell'IRP, il parametro di output Interface è un puntatore a una struttura DEVICE_RESET_INTERFACE_STANDARD. Questa struttura contiene un puntatore alla routine DeviceReset, che può essere usata per richiedere una reimpostazione a livello di funzione o a livello di piattaforma.

Supporto dell'interfaccia di reimpostazione del dispositivo nei driver di funzione

Per supportare l'interfaccia di reimpostazione del dispositivo, lo stack di dispositivi deve soddisfare i requisiti seguenti.

Il driver di funzione deve gestire correttamente IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_REMOVE_DEVICE e IRP_MN_SURPRISE_REMOVAL.

Nella maggior parte dei casi, quando il driver riceve IRP_MN_QUERY_REMOVE_DEVICE, deve restituire un esito positivo in modo che il dispositivo possa essere rimosso in modo sicuro. Tuttavia, potrebbero esserci casi in cui il dispositivo non può essere arrestato in modo sicuro, ad esempio se il dispositivo è bloccato in un ciclo di scrittura in un buffer di memoria. In questi casi, il driver deve restituire STATUS_DEVICE_HUNG a IRP_MN_QUERY_REMOVE_DEVICE. Il gestore PnP continuerà il processo di IRP_MN_QUERY_REMOVE_DEVICE e IRP_MN_REMOVE_DEVICE, ma tale stack specifico non riceverà IRP_MN_REMOVE_DEVICE. Al contrario, lo stack di dispositivi riceverà IRP_MN_SURPRISE_REMOVAL dopo che il dispositivo è stato reimpostato.

Per altre informazioni su questi provider di integrazione, vedere:

Gestione di una richiesta di IRP_MN_QUERY_REMOVE_DEVICE

Gestione di una richiesta di IRP_MN_REMOVE_DEVICE

Gestione di una richiesta di IRP_MN_SURPRISE_REMOVAL

Supporto dell'interfaccia di reimpostazione del dispositivo nei driver di filtro

I driver di filtro possono intercettare IRP_MN_QUERY_INTERFACE IRP con tipo di interfaccia GUID_DEVICE_RESET_INTERFACE_STANDARD. In questo modo, possono continuare a delegare all'interfaccia GUID_DEVICE_RESET_INTERFACE_STANDARD, ma eseguire operazioni specifiche del dispositivo prima o dopo l'operazione di reimpostazione. In alternativa, possono eseguire l'override dell'interfaccia GUID_DEVICE_RESET_INTERFACE_STANDARD restituita dal driver del bus con la propria interfaccia per fornire la propria operazione di reimpostazione.

Supporto dell'interfaccia di reimpostazione del dispositivo nei driver del bus

I driver del bus che partecipano al processo di reimpostazione del dispositivo (ovvero, i driver del bus associati al dispositivo che richiede il ripristino e i driver del bus associati ai dispositivi che rispondono alla richiesta di reimpostazione) devono soddisfare uno dei requisiti seguenti:

Essere in grado di collegare a caldo. Il conducente dell'autobus deve essere in grado di rilevare un dispositivo rimosso dall'autobus senza preavviso e un dispositivo collegato al bus.
In alternativa, deve implementare l'interfaccia GUID_REENUMERATE_SELF_INTERFACE_STANDARD. In questo modo si simula il pull di un dispositivo da un bus e viene collegato di nuovo. I driver bus predefiniti (ad esempio PCI e SDBUS) supportano questa interfaccia. Pertanto, se il dispositivo da reimpostare utilizza uno di questi autobus, non è necessario apportare modifiche ai conducenti degli autobus.

Per i driver di bus basati su WDF, il framework WDF registra l'interfaccia GUID_REENUMERATE_SELF_INTERFACE_STANDARD per conto dei driver. Pertanto, la registrazione di questa interfaccia non è necessaria per tali driver. Se il driver del bus deve eseguire alcune operazioni prima che i dispositivi figlio vengano nuovamente enumerati, deve registrarsi per la routine di callback EvtChildListDeviceReenumenumerated ed eseguire le operazioni in tale routine. Poiché questa routine di callback può essere chiamata in parallelo per tutti i PDO, il codice nella routine potrebbe dover proteggere da race condition.

Firmware ACPI: reimpostazione a livello di funzione

Per supportare la reimpostazione del dispositivo a livello di funzione, deve essere definito un metodo _RST all'interno dell'ambito dispositivo. Se presente, questo metodo eseguirà l'override dell'implementazione del driver del bus di reimpostazione del dispositivo a livello di funzione (se presente) per tale dispositivo. Quando viene eseguito, il metodo _RST deve reimpostare solo il dispositivo e non deve influire su altri dispositivi. Inoltre, il dispositivo deve rimanere connesso sul bus.

Firmware ACPI: reimpostazione a livello di piattaforma

Per supportare la reimpostazione del dispositivo a livello di piattaforma, sono disponibili due opzioni:

Il firmware ACPI può definire un'istanza di PowerResource che implementa il metodo _RST e tutti i dispositivi interessati da questo metodo di reimpostazione possono fare riferimento a questo oggetto PowerResource tramite un oggetto _PRR definito nell'ambito del dispositivo.
Il dispositivo può dichiarare un oggetto _PR3. In questo caso, il driver ACPI utilizzerà il ciclo di alimentazione D3cold per eseguire la reimpostazione e le dipendenze tra i dispositivi verranno determinate dall'oggetto _PR3.

Se l'oggetto _PRR esiste nell'ambito Device, il driver ACPI userà il metodo _RST in PowerResource a cui si fa riferimento per eseguire la reimpostazione. Se non viene definito alcun oggetto _PRR ma viene definito l'oggetto _PR3, il driver ACPI utilizzerà il ciclo di alimentazione D3cold per eseguire la reimpostazione. Se non viene definito né il _PRR né l'oggetto _PR3, il dispositivo non supporta una reimpostazione a livello di piattaforma e il driver ACPI segnala che la reimpostazione a livello di piattaforma non è disponibile.

Verifica del firmware ACPI nel sistema di test

Per testare il driver che supporta la reimpostazione e il ripristino del dispositivo, seguire questa procedura. Questa procedura presuppone l'uso di questo file ASL di esempio.

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)
}

Compilare il file ASL di test in un AML usando un compilatore ASL, ad esempio Asl.exe. Eseguibile incluso in Windows Driver Kit (WDK).

Asl <test>.asl

Il comando precedente genera SSDT.aml.

Rinominare SSDT.aml in acpitabl.dat.
Copiare acpitabl.dat in %systemroot%\system32 nel sistema di test.
Abilitare la firma di test nel sistema di test.

bcdedit /set testsigning on

Riavviare il sistema di test.
Verificare che la tabella sia caricata. In Debugger di Windows usare questi comandi.

!acpicache
dt _DESCRIPTION_HEADER indirizzo della tabella 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

Vedere anche

_DEVICE_RESET_INTERFACE_STANDARD

Condividi tramite