IRP_MN_QUERY_DEVICE_RELATIONS

Articolo
06/15/2023

Il gestore PnP invia questa richiesta per determinare determinate relazioni tra i dispositivi. I tipi di driver seguenti gestiscono questa richiesta:

I driver del bus devono gestire le richieste di busRelations per la scheda o il controller (FDO del bus). I driver di filtro possono gestire le richieste busRelations .
I driver del bus devono gestire le richieste TargetDeviceRelation per i dispositivi figlio (PDO figlio).
I driver di funzione e filtro possono gestire le richieste Di rimozioneRelations ePowerRelations .
I driver del bus possono gestire le richieste di EjectionRelations per i dispositivi figlio (PDO figlio).

Valore

0x07

Codice principale

IRP_MJ_PNP

Data di invio

Il gestore PnP invia questo IRP per raccogliere informazioni sui dispositivi con una relazione con il dispositivo specificato.

Il gestore PnP esegue una query su BusRelations (dispositivi figlio) di un dispositivo quando il dispositivo viene enumerato e in altre occasioni mentre il dispositivo è attivo, ad esempio quando un driver chiama la routine IoInvalidateDeviceRelations per indicare che un dispositivo figlio è arrivato o è partito.

Il gestore PnP esegue una query su RemoveRelations di un dispositivo prima di rimuovere i driver di un dispositivo. La query di gestione PnP per RemovalRelations e EjectionRelations prima di espulse un dispositivo.

La gestione PnP esegue una query su TargetDeviceRelation di un dispositivo quando un driver o un'applicazione in modalità utente registra la notifica PnP di un oggetto EventCategoryTargetDeviceChange nel dispositivo. La query di gestione PnP per il dispositivo associato a un determinato oggetto file. IRP_MN_QUERY_DEVICE_RELATIONS è l'unico IRP PnP con un parametro di oggetto file valido. Un driver può eseguire query su uno stack di dispositivi per TargetDeviceRelation. Un driver non deve fornire un oggetto file quando si invia la query TargetDeviceRelation .

Il gestore PnP esegue una query su PowerRelations di un dispositivo quando il driver per il dispositivo chiama IoInvalidateDeviceRelations per indicare che il set di dispositivi con cui questo dispositivo ha una relazione implicita di risparmio energia è stata modificata. Le richieste di PowerRelations sono supportate a partire da Windows 7.

Per le richieste BusRelations, RemovalRelations, EjectionRelations e PowerRelations, il gestore PnP invia IRP_MN_QUERY_DEVICE_RELATIONS in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.

Per le richieste TargetDeviceRelation , il gestore PnP invia questo IRP in IRQL = PASSIVE_LEVEL in un contesto di thread arbitrario.

Parametri di input

Il membro Parameters.QueryDeviceRelations.Type della struttura IO_STACK_LOCATION specifica il tipo di relazioni che vengono sottoposte a query. I valori possibili includono BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelations e PowerRelations.

Il membro FileObject della struttura di IO_STACK_LOCATION corrente punta a un oggetto file valido solo se Parameters.QueryDeviceRelations.Type è TargetDeviceRelation.

Parametri di output

Restituito nel blocco di stato di I/O.

Blocco dello stato I/O

Un driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o su uno stato di errore, ad esempio STATUS_INSUFFICIENT_RESOURCES.

In caso di esito positivo, un driver imposta Irp-IoStatus.Information> su un puntatore PDEVICE_RELATIONS che punta alle informazioni sulle relazioni richieste. La struttura DEVICE_RELATIONS è definita come segue:

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

Operazione

Se un driver restituisce le relazioni in risposta a questa IRP_MN_QUERY_DEVICE_RELATIONS, il driver alloca una struttura DEVICE_RELATIONS dalla memoria con pagina che contiene un conteggio e il numero appropriato di puntatori a oggetti dispositivo. Il gestore PnP libera la struttura quando non è più necessaria. Se un driver sostituisce una struttura DEVICE_RELATIONS allocata da un altro driver, il driver deve liberare la struttura precedente.

Un driver deve fare riferimento al PDO di qualsiasi dispositivo che segnala in questo oggetto IRP (ObReferenceObject). Il gestore PnP rimuove il riferimento quando appropriato.

Un driver di funzione o filtro deve essere preparato per gestire questa IRP per un dispositivo in qualsiasi momento dopo il completamento della routine AddDevice per il dispositivo. I driver del bus devono essere preparati per gestire una query per BusRelations immediatamente dopo l'enumerazione di un dispositivo.

Per le regole generali sulla gestione di irp secondari Plug and Play , vedere Plug and Play.

Le sottosezioni seguenti descrivono le azioni specifiche per la gestione delle varie query.

Richiesta busRelations

Quando il gestore PnP esegue query per le relazioni del bus (dispositivi figlio) di un adattatore o un controller, il driver del bus deve restituire un elenco di puntatori agli oggetti PDO di qualsiasi dispositivo fisicamente presente nel bus. Il driver del bus segnala tutti i dispositivi, indipendentemente dal fatto che siano stati avviati. Il conducente del bus potrebbe dover attivare il dispositivo del bus per determinare quali bambini sono presenti.

Avviso Non è possibile passare un oggetto dispositivo a qualsiasi routine che accetta un oggetto PDO come argomento finché la gestione PnP crea un nodo dispositivo (devnode) per tale oggetto. Se il driver passa un oggetto dispositivo, il sistema verificherà il bug con Verifica bug 0xCA: PNP_DETECTED_FATAL_ERROR. Il gestore PnP crea il nodo devnode in risposta alla richiesta di IRP_MN_QUERY_DEVICE_RELATIONS . Il driver può presupporre che il devnode del PDO sia stato creato quando riceve una richiesta di IRP_MN_QUERY_RESOURCE_REQUIREMENTS .

Il driver del bus che risponde a questo IRP è il driver di funzione per l'adattatore del bus o il controller, non il driver del bus padre per il bus a cui è connesso l'adattatore o il controller. I driver di funzione per i dispositivi non bus non gestiscono questa query. Tali driver passano solo l'IRP al driver inferiore successivo. Vedere la figura seguente. I driver di filtro in genere non gestiscono questa query.

Nei sistemi operativi Windows Vista e versioni successive è consigliabile che i driver siano sempre stati pennati nell'IRP_MN_QUERY_DEVICE_RELATIONS IRP e completino l'elaborazione in un secondo momento. Questo ordine consente al sistema di elaborare le query di relazione del bus in modo asincrono. Nei sistemi operativi prima di Windows Vista i driver possono restituire in modo sicuro STATUS_PENDING dalle routine di invio, ma il gestore PnP non si sovrappone alla query di relazione del bus con qualsiasi altra operazione.

Il diagramma seguente illustra come i driver gestiscono una query per le relazioni con il bus.

diagramma che illustra i driver che gestiscono una query per le relazioni con il bus.

Nell'esempio illustrato nella figura, il gestore PnP invia un IRP_MN_QUERY_DEVICE_RELATIONS per busRelations ai driver per il dispositivo hub USB. Gestione PnP richiede un elenco dei figli del dispositivo hub.

Come per tutti i PnP IRP, il gestore PnP invia l'IRP al driver superiore nello stack di dispositivi per il dispositivo.
Un driver di filtro facoltativo potrebbe essere il driver principale nello stack. Un driver di filtro in genere non gestisce questa IRP; passa l'IRP verso il basso dello stack. Un driver di filtro può gestire questo IRP, ad esempio, se il driver espone un dispositivo non enumerabile sul bus.
Il driver del bus dell'hub USB gestisce l'IRP.

Driver del bus hub USB:
- Crea un oggetto PDO per qualsiasi dispositivo figlio che non ne ha già uno.
- Contrassegna l'oggetto PDO inattivo per qualsiasi dispositivo che non è più presente sul bus. Il driver del bus non elimina tali PDOs.Per altre informazioni su quando eliminare i PDO, vedere Rimozione di un dispositivo.
- Segnala tutti i dispositivi figlio presenti sul bus.
  
  Per ogni dispositivo figlio, il driver del bus fa riferimento al PDO e inserisce un puntatore all'oggetto PDO nella struttura DEVICE_RELATIONS.
  
  In questo esempio sono presenti due PDO: uno per il dispositivo joystick e uno per il dispositivo da tastiera.
  
  Il driver del bus deve verificare se un altro driver ha già creato una struttura DEVICE_RELATIONS per questo IRP. In tal caso, il driver del bus deve aggiungere alle informazioni esistenti.
  
  Se nel bus non è presente alcun dispositivo figlio, il driver imposta il conteggio su zero nella struttura DEVICE_RELATIONS e restituisce esito positivo.
- Imposta i valori appropriati nel blocco di stato di I/O e passa l'IRP al driver inferiore successivo. Il driver del bus per l'adattatore o il controller non completa l'IRP.
Un filtro inferiore facoltativo, se presente, in genere non gestisce questo IRP. Tale driver di filtro passa l'IRP verso il basso dello stack. Se un driver con filtro inferiore gestisce questo IRP, può aggiungere PDO all'elenco di dispositivi figlio, ma non deve eliminare alcun PDO creato da altri driver.
Il driver del bus padre non gestisce l'IRP, a meno che non sia l'unico driver nello stack di dispositivi (il dispositivo è in modalità non elaborata). Come per tutti i PnP IRP, il driver del bus padre completa l'IRP con IoCompleteRequest.

Se nello stack di dispositivi sono presenti uno o più driver di filtro del bus, tali driver potrebbero gestire l'IRP fino al driver del bus e/o nel modo in cui si esegue il backup dello stack di dispositivi (se sono presenti routine IoCompletion ). In base alle regole IRP PnP, tale driver può aggiungere pdO all'IRP nel suo percorso verso il basso dello stack e/o modificare l'elenco delle relazioni nel modo in cui viene eseguito il backup dello stack (nelle routine IoCompletion ).

Richiesta EjectionRelations

Un driver restituisce puntatori a PDO di tutti i dispositivi che potrebbero essere rimossi fisicamente dal sistema quando il dispositivo specificato viene espulso. Non segnalare i PDO dei bambini del dispositivo; Gestione PnP richiede sempre che i dispositivi figlio vengano rimossi prima del dispositivo padre.

Il gestore PnP invia un IRP_MN_EJECT IRP a un dispositivo che viene espulso. Il driver per tale dispositivo riceve anche una rimozione di IRP. Le relazioni di esezione del dispositivo ricevono una IRP_MN_REMOVE_DEVICE IRP (non unIRP_MN_EJECT IRP).

Solo un driver del bus padre può rispondere a una query EjectionRelations per uno dei relativi dispositivi figlio. I driver di funzione e filtro devono passarlo al driver inferiore successivo nello stack di dispositivi. Se un driver del bus riceve l'IRP come driver di funzione per la scheda o il controller, il driver del bus esegue le attività di un driver di funzione e deve passare l'IRP al driver inferiore successivo.

Richiesta di PowerRelations

A partire da Windows 7, la query PowerRelations consente a un driver di specificare una relazione di risparmio energia all'esterno della relazione convenzionale tra un bus padre che supporta l'enumerazione PnP e un dispositivo figlio enumerato nel bus. Ad esempio, se un driver del bus non può enumerare un dispositivo figlio sul bus o se un dispositivo è figlio di più di un bus, la query PowerRelations può descrivere le relazioni di alimentazione del dispositivo figlio con il bus o gli autobus.

Il gestore PnP genera una query di PowerRelations per un dispositivo quando il driver per il dispositivo chiama la routine IoInvalidateDeviceRelations e specifica un valore di parametro Type di PowerRelations.

In risposta a questa query, il driver per il dispositivo di destinazione ,ovvero il dispositivo di destinazione per la query, fornisce una struttura DEVICE_RELATIONS che contiene puntatori a tutti gli altri dispositivi che devono essere attivati dal power manager prima che il dispositivo di destinazione sia attivato. Al contrario, questi altri dispositivi devono essere disattivati solo dopo che il dispositivo di destinazione è disattivato. Il risparmio energia usa le informazioni della query per garantire che questi dispositivi siano attivati e disattivati nell'ordine corretto.

Questa garanzia di ordinamento si applica solo alle transizioni dello stato di sospensione del sistema globale, che includono transizioni verso e da S1, S2, S3 (sospensione), S4 (ibernazione) e stati di alimentazione del sistema S5 (arresto). La garanzia di ordinamento di PowerRelations non si applica alle transizioni dello stato di alimentazione del dispositivo Dx mentre il sistema rimane nello stato del sistema S0 (in esecuzione), tranne nel caso delle transizioni di Power Management (DFx) di Runtime diretto .

Se il dispositivo di destinazione si trova nel percorso del dispositivo per un file speciale (ad esempio il file di paging, il file di ibernazione o il file di dump di arresto anomalo), il driver per il dispositivo di destinazione deve eseguire un passaggio aggiuntivo quando gestisce un IRP_MN_DEVICE_USAGE_NOTIFICATION IRP in cui InPath è TRUE. Questo driver deve assicurarsi che i dispositivi i cui PDO siano forniti per la query PowerRelations possono supportare anche il percorso del dispositivo per il file speciale. Per confermare questo supporto, il driver per il dispositivo di destinazione deve prima inviare il IRP_MN_DEVICE_USAGE_NOTIFICATION IRP a ognuno di questi dispositivi e questo IRP deve specificare lo stesso valore UsageNotification.Type del dispositivo di destinazione. Solo se tutti i dispositivi che ricevono l'IRP completano l'IRP con un codice di stato riuscito possono IRP_MN_DEVICE_USAGE_NOTIFICATION completare correttamente il driver per il dispositivo di destinazione. In caso contrario, questo driver deve completare l'IRP con un codice di stato di errore.

Quando questo stesso driver gestisce un IRP_MN_DEVICE_USAGE_NOTIFICATION IRP per cui InPath è FALSE, il driver deve inviare il IRP_MN_DEVICE_USAGE_NOTIFICATION IRP allo stesso set di dispositivi dipendenti come per il caso in cui InPath è TRUE. Tuttavia, il driver non dovrebbe mai completare l'IRP con un codice di stato di errore quando InPath è FALSE.

Il driver che risponde alla query PowerRelations deve registrare per le notifiche di modifica del dispositivo di destinazione in tutti i dispositivi i cui PDO vengono forniti per la query PowerRelations . Per eseguire la registrazione per queste notifiche, il driver può chiamare la routine IoRegisterPlugPlayNotification e specificare un valore del parametro EventCategoryTargetDeviceChange.

Richiesta di rimozioneRelations

Un driver restituisce puntatori a PDO di tutti i dispositivi i cui driver devono essere rimossi quando i driver per il dispositivo specificato vengono rimossi. Non segnalare i PDO dei bambini del dispositivo; Il gestore PnP richiede già la rimozione dei dispositivi figlio prima di rimuovere un dispositivo.

L'ordine in cui vengono rimosse le relazioni di rimozione non è definito.

Qualsiasi driver nello stack di dispositivi può gestire questo tipo di query di relazioni. Un driver di funzione o filtro gestisce l'IRP prima di passarlo al driver inferiore successivo. Un driver del bus gestisce l'IRP e quindi lo completa.

Richiesta TargetDeviceRelation

La query TargetDeviceRelation consente alla gestione PnP di eseguire query su uno stack di dispositivi non PnP per l'oggetto PDO nello stack di dispositivi PnP che controlla l'hardware.

In generale, i driver inoltrano il IRP_MN_QUERY_DEVICE_RELATIONS IRP verso il basso dello stack fino a quando l'IRP raggiunge la parte inferiore di uno stack di dispositivi specifico. Un driver nella parte inferiore di uno stack non PnP quindi inoltra o rimette l'IRP nello stack PnP pertinente. Ad esempio, il gestore PnP potrebbe inviare una query TargetDeviceRelation all'oggetto dispositivo nella parte superiore dello stack del file system, ovvero uno stack non PnP. Ogni oggetto dispositivo nello stack del file system passerà la query all'oggetto dispositivo sotto di esso finché la query non raggiunge l'oggetto dispositivo nella parte inferiore dello stack. L'oggetto dispositivo più basso nello stack inoltra o rimette la query TargetDeviceRelation all'oggetto dispositivo nella parte superiore dello stack del volume di archiviazione PnP e quindi la query verrà passata al PDO nella parte inferiore dello stack di volumi di archiviazione.

L'elenco seguente riepiloga le situazioni in cui è possibile acquisire in modo sicuro un puntatore al PDO nella parte inferiore di uno stack di dispositivi PnP:

Oggetto Device in un PnP

Un oggetto dispositivo che si trova in uno stack di dispositivi PnP illustra il PDO dello stack quando viene chiamata la routine AddDevice per il dispositivo. Il driver può memorizzare in modo sicuro il puntatore al PDO se l'uso del puntatore è sincronizzato correttamente con i messaggi di IRP_MN_REMOVE_DEVICE in ingresso usando le routine di blocco rimosse.
Oggetto Device in uno stack non PnP, non nella parte inferiore dello stack

Per un oggetto dispositivo che non si trova nella parte inferiore di uno stack non PnP, un driver può inviare una query TargetDeviceRelation per ottenere un puntatore al PDO nella parte inferiore dello stack di dispositivi PnP corrispondente.
Oggetto file per il dispositivo

Dato un oggetto file per il dispositivo, un driver può chiamare IoGetRelatedDeviceObject per ottenere l'oggetto dispositivo e quindi seguire le istruzioni nell'elemento elenco precedente.
Handle per l'oggetto dispositivo

Dato un handle all'oggetto dispositivo, un driver può chiamare ObReferenceObjectByHandle per ottenere l'oggetto file per il dispositivo e quindi seguire le istruzioni nell'elemento di elenco precedente.

Un driver del bus padre deve gestire una query di relazioni TargetDeviceRelation per i dispositivi figlio. Il driver del bus fa riferimento al PDO del dispositivo figlio con ObReferenceObject e restituisce un puntatore all'oggetto PDO nella struttura DEVICE_RELATIONS . Nella struttura è presente un solo puntatore PDO per questo tipo di relazione. Il gestore PnP rimuove il riferimento all'oggetto PDO quando il driver o l'applicazione annullano la registrazione per la notifica nel dispositivo.

Solo un driver del bus padre risponde a una query TargetDeviceRelation . I driver di funzione e filtro devono passarlo al driver inferiore successivo nello stack di dispositivi. Se un driver del bus riceve l'IRP come driver di funzione per la scheda o il controller, il driver del bus esegue le attività di un driver di funzione e deve passare l'IRP al driver inferiore successivo.

Se un driver non si trova in uno stack basato su PDO, il driver invia una nuova query di relazione con dispositivo di destinazione all'oggetto dispositivo associato all'handle di file in cui il driver esegue I/O.

Invio di questo IRP

I driver non devono inviare IRP_MN_QUERY_DEVICE_RELATIONS per richiedere busRelations. I driver non sono limitati all'invio di questo IRP per RemovalRelations o EjectionRelations, ma non è probabile che un driver lo farebbe.

I driver possono eseguire query su uno stack di dispositivi per TargetDeviceRelation. Per informazioni sull'invio di IRP, vedere Gestione degli INDIRIZZI DI accesso. I passaggi seguenti si applicano in modo specifico a questo IRP:

Impostare i valori nel percorso dello stack I/O successivo dell'IRP: impostare MajorFunction su IRP_MJ_PNP, impostare MinorFunction su IRP_MN_QUERY_DEVICE_RELATIONS, impostare Parameters.QueryDeviceRelations.Type su TargetDeviceRelation e impostare Irp-FileObject> su un oggetto file valido.
Inizializzare IoStatus.Status per STATUS_NOT_SUPPORTED.

Se un driver ha inviato questo IRP per ottenere il PDO in risposta a un IRP_MN_QUERY_DEVICE_RELATIONS per TargetDeviceRelation ricevuto dal driver, il driver segnala l'oggetto PDO e libera la struttura delle relazioni restituite al termine dell'IRP. Se un driver ha avviato questa IRP per un altro motivo, il driver libera la struttura delle relazioni quando l'IRP completa e dereferenzia il PDO quando non è più necessario.