IRP_MN_QUERY_DEVICE_RELATIONS
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 BusRelations richieste per la scheda o il controller (FDO del bus). I driver di filtro possono gestire richieste di BusRelations.
I driver del bus devono gestire TargetDeviceRelation richieste per i dispositivi figlio (PDO figlio).
I driver di funzione e filtro possono gestire e richieste di PowerRelations.
I driver del bus possono gestire EjectionRelations richieste per i dispositivi figlio (PDO figlio).
Valore
0x07
Codice principale
Quando viene inviato
Il gestore PnP invia questo IRP per raccogliere informazioni sui dispositivi con una relazione con il dispositivo specificato.
Il gestore PnP esegue una query sul BusRelations di un dispositivo (dispositivi figlio) quando il dispositivo viene enumerato e in altri momenti mentre il dispositivo è attivo, ad esempio quando un driver chiama il IoInvalidateDeviceRelations routine per indicare che un dispositivo figlio è arrivato o è partito.
Il gestore PnP esegue una query sul RemoveRelations di un dispositivo prima di rimuovere i driver di un dispositivo. Il gestore PnP esegue query per RemovalRelations e EjectionRelations prima di espellere un dispositivo.
Il gestore PnP esegue una query TargetDeviceRelation di un dispositivo quando un driver o un'applicazione in modalità utente esegue la registrazione per la notifica PnP di un EventCategoryTargetDeviceChange nel dispositivo. Il gestore PnP esegue una query per il dispositivo associato a un particolare oggetto file. IRP_MN_QUERY_DEVICE_RELATIONS è l'unico IRP PnP con un parametro di oggetto file valido. Un driver può eseguire una query su uno stack di dispositivi per TargetDeviceRelation. Un driver non deve fornire un oggetto file quando invia il relativo TargetDeviceRelation query.
Il gestore PnP esegue una query PowerRelations di un dispositivo quando il driver per il dispositivo chiama IoInvalidateDeviceRelations per indicare che il set di dispositivi con cui il dispositivo ha una relazione implicita di risparmio energia è cambiata. powerRelations richieste sono supportate a partire da Windows 7.
Per BusRelations, RemovalRelations, EjectionRelationse richieste di powerRelations, il gestore PnP invia IRP_MN_QUERY_DEVICE_RELATIONS in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.
Per richieste di TargetDeviceRelation, il gestore PnP invia questo IRP in IRQL = PASSIVE_LEVEL in un contesto di thread arbitrario.
Parametri di input
Il Parameters.QueryDeviceRelations.Type membro della struttura IO_STACK_LOCATION specifica il tipo di relazioni su cui viene eseguita la query. I valori possibili includono BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelatione PowerRelations.
Il membro FileObject della struttura 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 di stato di 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 relazioni in risposta a questo IRP_MN_QUERY_DEVICE_RELATIONS, il driver alloca una struttura DEVICE_RELATIONS dalla memoria di paging 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 segnalato in questo IRP (ObReferenceObject). Il gestore PnP rimuove il riferimento quando appropriato.
Una funzione o un driver di filtro deve essere preparato per gestire questo IRP per un dispositivo in qualsiasi momento dopo il completamento della routine AddDevice per il dispositivo. I driver del bus devono essere preparati a gestire una query per BusRelations immediatamente dopo l'enumerazione di un dispositivo.
Per le regole generali sulla gestione di plug and play di runtime di integrazione secondari vedere Plug and Play.
Le sottosezioni seguenti descrivono le azioni specifiche per la gestione delle varie query.
richiesta busRelations
Quando il gestore PnP esegue una query per le relazioni tra bus (dispositivi figlio) di un adattatore o di un controller, il driver del bus deve restituire un elenco di puntatori ai PDO di qualsiasi dispositivo fisicamente presente sul bus. Il conducente del bus segnala tutti i dispositivi, indipendentemente dal fatto che siano stati avviati. Il conducente del bus potrebbe dover attivare il dispositivo bus per determinare quali elementi figlio sono presenti.
Avviso Un oggetto dispositivo non può essere passato a qualsiasi routine che accetta un PDO come argomento finché il gestore PnP non crea un nodo del dispositivo (devnode) per tale oggetto. Se il driver passa un oggetto dispositivo, il sistema verificherà bug con controllo dei 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 in modo sicuro che il nodo devnode del PDO sia stato creato quando riceve una richiesta di IRP_MN_QUERY_RESOURCE_REQUIREMENTS.
Il driver del bus che risponde a questo protocollo IRP è il driver di funzione per la scheda 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 semplicemente 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 eselaborino sempre il IRP_MN_QUERY_DEVICE_RELATIONS IRP e ne completino l'elaborazione in un secondo momento. Questo ordine consente al sistema di elaborare le query sulle relazioni tra 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 sovrappone la query di relazione del bus a qualsiasi altra operazione.
Il diagramma seguente illustra come i conducenti gestiscono una query per le relazioni tra 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. Il gestore PnP richiede un elenco degli elementi figlio del dispositivo hub.
Come per tutti i provider di integrazione PnP, il gestore PnP invia l'IRP al driver principale 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 questo IRP; passa l'IRP verso il basso nello stack. Un driver di filtro potrebbe 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 bus hub USB:
Crea un PDO per qualsiasi dispositivo figlio che non ne ha già uno.
Contrassegna l'inattività PDO per qualsiasi dispositivo che non è più presente sul bus. Il driver del bus non elimina tali PDOs.Per ulteriori 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 al 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 conducente del bus deve verificare se un altro conducente ha già creato una struttura DEVICE_RELATIONS per questo IRP. In tal caso, il conducente 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 l'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. Un driver di filtro di questo tipo passa l'IRP verso il basso nello stack. Se un driver con filtro inferiore gestisce questo IRP, può aggiungere PDO all'elenco dei dispositivi figlio, ma non deve eliminare alcun PDO creato da altri driver.
Il driver del bus padre non gestisce questo IRP, a meno che non sia l'unico driver nello stack di dispositivi (il dispositivo è in modalità non elaborata). Come per tutti i provider di integrazione PnP, 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 dell'autobus e/o nel modo in cui il provider di risorse 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 lungo lo stack e/o modificare l'elenco delle relazioni nel modo in cui esegue il backup dello stack (in routine IoCompletion).
richiesta EjectionRelations
Un driver restituisce puntatori a PDO di qualsiasi dispositivo che potrebbe essere fisicamente rimosso dal sistema quando il dispositivo specificato viene espulso. Non segnalare i PDO dei figli del dispositivo; Il gestore 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 un dispositivo di questo tipo riceve anche una rimozione di IRP. Le relazioni di espulsione del dispositivo ricevono un IRP_MN_REMOVE_DEVICE IRP (non un IRP IRP_MN_EJECT).
Solo un driver del bus padre può rispondere a una query EjectionRelations per uno dei dispositivi figlio. I driver di funzione e filtro devono passarlo al driver inferiore successivo nello stack di dispositivi. Se un driver del bus riceve questo IRP come driver di funzione per il relativo adattatore o controller, il driver del bus sta eseguendo 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 al di fuori della relazione convenzionale tra un bus padre che supporta l'enumerazione PnP e un dispositivo figlio enumerato sul 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 l'autobus o gli autobus.
Il gestore PnP invia una query PowerRelations per un dispositivo quando il driver per il dispositivo chiama la routine IoInvalidateDeviceRelations e specifica un valore del parametro type di PowerRelations.
In risposta a questa query, il driver per il dispositivo di destinazione ,ovvero il dispositivo che è la destinazione per la query, fornisce una struttura DEVICE_RELATIONS che contiene puntatori agli oggetti PDO di tutti gli altri dispositivi che devono essere attivati dal gestore di alimentazione prima che il dispositivo di destinazione sia attivato. Al contrario, questi altri dispositivi devono essere disattivati solo dopo la disattivazione del dispositivo di destinazione. Il risparmio energia usa le informazioni della query per garantire che questi dispositivi siano accesi e disattivati nell'ordine corretto.
Questa garanzia di ordinamento si applica solo alle transizioni di stato di sospensione del sistema globale, che includono transizioni da e verso S1, S2, S3 (sospensione), S4 (ibernazione) e S5 (arresto) stati di alimentazione del sistema. La garanzia di ordinamento PowerRelations non si applica alle transizioni di stato di alimentazione del dispositivo Dx mentre il sistema rimane nello stato del sistema S0 (in esecuzione), tranne nel caso di transizioni di power management del runtime diretto (DFx).
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 dump di arresto anomalo), il driver per il dispositivo di destinazione deve eseguire un passaggio aggiuntivo quando gestisce un IRP IRP_MN_DEVICE_USAGE_NOTIFICATION in cui InPath è TRUE. Questo driver deve assicurarsi che i dispositivi i cui PDO siano forniti per il PowerRelations query 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 UsageNotification.Type del dispositivo di destinazione. Solo se tutti i dispositivi che ricevono questo IRP completano l'IRP con un codice di stato di esito positivo possono completare correttamente il driver per il dispositivo di destinazione IRP_MN_DEVICE_USAGE_NOTIFICATION IRP. In caso contrario, questo driver deve completare l'IRP con un codice di stato di errore.
Quando lo stesso driver gestisce un IRP_MN_DEVICE_USAGE_NOTIFICATION IRP per il quale InPath è FALSE, il driver deve inviare il IRP_MN_DEVICE_USAGE_NOTIFICATION IRP allo stesso set di dispositivi dipendenti del caso in cui InPath sia TRUE. Tuttavia, il driver non deve mai completare questo IRP con un codice di stato di errore quando InPath è FALSE.
Il driver che risponde alla query di PowerRelations deve registrarsi per le notifiche di modifica del dispositivo di destinazione in tutti i dispositivi i cui PDO sono forniti per la query PowerRelations. Per registrarsi per queste notifiche, il driver può chiamare la routineIoRegisterPlugPlayNotificatione specificare un valore del parametro EventCategory di EventCategoryTargetDeviceChange.
rimozioneRelations Richiesta di
Un driver restituisce puntatori a PDO di qualsiasi dispositivo i cui driver devono essere rimossi quando vengono rimossi i driver per il dispositivo specificato. Non segnalare i PDO dei figli del dispositivo; Il gestore PnP richiede già la rimozione dei dispositivi figlio prima di rimuovere un dispositivo.
L'ordine in cui le relazioni di rimozione vengono rimosse non è definito.
Qualsiasi driver nello stack di dispositivi può gestire questo tipo di query di relazioni. Una funzione o un driver di filtro gestisce l'IRP prima di passarlo al driver inferiore successivo. Un autista di autobus gestisce l'IRP e quindi lo completa.
TargetDeviceRelation Request
La query TargetDeviceRelation consente al gestore PnP di eseguire query su uno stack di dispositivi non PnP per il 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 lo 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 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 passa la query all'oggetto dispositivo sottostante fino a quando la query non raggiunge l'oggetto dispositivo nella parte inferiore dello stack. L'oggetto dispositivo più basso nello stack inoltra o rimette il TargetDeviceRelation query sull'oggetto dispositivo nella parte superiore dello stack del volume di archiviazione PnP e quindi la query viene 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 apprende informazioni sul PDO dello stack quando viene chiamata la routine di AddDevice per il dispositivo. Il driver può memorizzare nella cache in modo sicuro il puntatore al PDO se l'uso del puntatore è sincronizzato correttamente con i messaggi IRP_MN_REMOVE_DEVICE in ingresso usando la rimuovere routine di blocco.
Oggetto dispositivo 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 un TargetDeviceRelation query 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 nella voce di 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 riportate nella voce di elenco precedente.
Un driver del bus padre deve gestire una query TargetDeviceRelation relazioni per i dispositivi figlio. Il driver del bus fa riferimento al PDO del dispositivo figlio con ObReferenceObject e restituisce un puntatore al PDO nella struttura DEVICE_RELATIONS. Esiste un solo puntatore PDO nella struttura per questo tipo di relazione. Il gestore PnP rimuove il riferimento al PDO quando il driver o l'applicazione annulla 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 questo IRP come driver di funzione per il relativo adattatore o controller, il driver del bus sta eseguendo 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 un nuovo IRP di query target-device-relation all'oggetto dispositivo associato all'handle di file in cui il driver esegue l'I/O.
l'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 faccia.
I driver possono eseguire query su uno stack di dispositivi per TargetDeviceRelation. Per informazioni sull'invio di runtime di integrazione, vedere gestione dei runtime di integrazione. I passaggi seguenti si applicano in modo specifico a questo IRP:
Impostare i valori nella posizione successiva dello stack di I/O di IRP: impostare MajorFunction su IRP_MJ_PNP, impostare MinorFunction su IRP_MN_QUERY_DEVICE_RELATIONS, impostare Parameters.QueryDeviceRelations.Type su TargetDeviceRelatione 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 che il driver ha ricevuto, il driver segnala il PDO e libera la struttura delle relazioni restituite al termine dell'IRP. Se un driver ha avviato questo IRP per un altro motivo, il driver libera la struttura delle relazioni al termine dell'IRP e dereferenzia il PDO quando non è più necessario.
Requisiti
Header |
Wdm.h (include Wdm.h, Ntddk.h o Ntifs.h) |
Vedere anche
IoRegisterPlugPlayNotification
IRP_MN_DEVICE_USAGE_NOTIFICATION