Enumerazione dinamica

L'enumerazione dinamica è la capacità di un driver di rilevare e segnalare le modifiche al numero e al tipo di dispositivi connessi al sistema durante l'esecuzione del sistema.

I driver del bus devono usare l'enumerazione dinamica se il numero o i tipi di dispositivi connessi al dispositivo padre dipendono dalla configurazione di un sistema. Alcuni di questi dispositivi potrebbero essere sempre connessi al sistema e alcuni potrebbero essere collegati e scollegati mentre il sistema è in esecuzione.

Ad esempio, il numero e il tipo di dispositivi collegati al bus PCI di un sistema dipendono dal sistema, ma sono permanenti, a meno che un utente non spenga l'alimentazione, apre il caso e aggiunge o rimuove un dispositivo usando un cacciavite. D'altra parte, un utente può aggiungere o rimuovere dispositivi USB collegando o scollegando un cavo mentre il sistema è in esecuzione.

Elenchi figlio dinamici

Il framework consente ai driver di supportare l'enumerazione dinamica fornendo oggetti lista figlio del framework. Ogni oggetto della lista dei figli rappresenta un elenco di dispositivi figli connessi a un dispositivo padre. Il driver del bus per il dispositivo padre deve identificare i dispositivi figli del dispositivo padre, aggiungerli all'elenco dei dispositivi figli del dispositivo padre e creare un oggetto dispositivo fisico (PDO) per ognuno di essi.

Ogni volta che un driver crea un oggetto dispositivo framework che rappresenta un FDO per un dispositivo, il framework crea un elenco figlio vuoto e predefinito per il dispositivo. Il driver può ottenere un handle per l'elenco figlio predefinito di un dispositivo chiamando WdfFdoGetDefaultChildList. In genere, se stai scrivendo un driver bus che enumera le unità figlio di un dispositivo, il tuo driver può aggiungere unità all'elenco predefinito. Se è necessario creare elenchi figlio aggiuntivi, il driver può chiamare WdfChildListCreate.

Prima che un driver possa usare un elenco figlio, deve configurare l'oggetto elenco figlio inizializzando una struttura WDF_CHILD_LIST_CONFIG e passando la struttura a WdfFdoInitSetDefaultChildListConfig, per l'elenco figlio predefinito o a WdfChildListCreate, per elenchi figlio aggiuntivi.

Descrizioni figlio dinamiche

Ogni volta che un driver del bus identifica un dispositivo figlio, deve aggiungere la descrizione del dispositivo figlio all'elenco dei dispositivi figli. Una descrizione figlio consiste in una descrizione di identificazione obbligatoria e in una descrizione dell'indirizzo facoltativa.

Descrizione identificazione Una descrizione di identificazione è una struttura che contiene informazioni che identificano in modo univoco ogni dispositivo enumerato dal driver. Il driver definisce questa struttura, ma il suo primo membro deve essere una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER.

In genere, una descrizione di identificazione contiene le stringhe di identificazione del dispositivo, possibilmente un numero di serie e informazioni sulla posizione del dispositivo sul bus, ad esempio un numero di slot.

Il driver può fornire il set seguente di funzioni di callback, che consentono al framework di modificare le informazioni in una descrizione di identificazione:

• EvtChildListIdentificationDescriptionCompare, che confronta il contenuto di due strutture di descrizione di identificazione.

• EvtChildListIdentificationDescriptionCopy, che copia il contenuto di una struttura di descrizione di identificazione in un altro.

• EvtChildListIdentificationDescriptionDuplicate, che crea una nuova descrizione di identificazione duplicando una struttura di descrizione dell'identificazione esistente e, se necessario, allocando buffer aggiuntivi.

• EvtChildListIdentificationDescriptionCleanup, che dealloca i buffer che la funzione di callback EvtChildListIdentificationDescriptionDuplicate ha allocato.

In genere, è necessario fornire queste funzioni di callback se le strutture di descrizione dell'identificazione del driver contengono puntatori a buffer allocati in modo dinamico. Per altre informazioni sullo scopo di queste funzioni di callback, vedere le relative pagine di riferimento.

Descrizione indirizzo Una descrizione dell'indirizzo è una struttura che contiene informazioni che il driver richiede per accedere al dispositivo sul bus, se le informazioni possono cambiare mentre il dispositivo rimane collegato. Il driver definisce questa struttura, ma il primo membro deve essere una struttura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER .

Le descrizioni degli indirizzi sono facoltative. Se le informazioni sull'indirizzo di un dispositivo non possono cambiare tra il momento in cui il dispositivo è collegato e l'ora in cui è scollegato, tutte le informazioni sull'indirizzo del dispositivo possono essere archiviate in una descrizione di identificazione. Ad esempio, i controller USB assegnano indirizzi ai dispositivi quando i dispositivi sono collegati e questi indirizzi non cambiano.

D'altra parte, alcuni autobus usano informazioni di indirizzamento che possono cambiare. Ad esempio, il bus IEEE 1394 usa un "numero di generazione", ovvero il numero di reimpostazioni del bus che si sono verificate. Ogni richiesta di I/O asincrona a un dispositivo IEEE 1394 deve includere il numero di generazione. Poiché queste informazioni sull'indirizzo possono cambiare, il driver deve archiviarlo in una descrizione dell'indirizzo.

Per modificare le informazioni in una descrizione dell'indirizzo, il driver può fornire il set di funzioni di callback seguente:

• EvtChildListAddressDescriptionCopy, che copia il contenuto di una struttura di descrizione dell'indirizzo in un altro.

• EvtChildListAddressDescriptionDuplicate, che crea una nuova descrizione dell'indirizzo duplicando una struttura di descrizione degli indirizzi esistente e, se necessario, allocando buffer aggiuntivi.

• EvtChildListAddressDescriptionCleanup, che dealloca i buffer che la funzione di callback EvtChildListAddressDescriptionDuplicate ha allocato.

In genere, è necessario fornire queste funzioni di callback se le strutture di descrizione degli indirizzi del driver contengono puntatori a buffer allocati in modo dinamico. Per altre informazioni sullo scopo di queste funzioni di callback, vedere le relative pagine di riferimento.

Aggiunta di dispositivi a un elenco figlio dinamico

Quando il framework chiama la funzione di callback EvtDriverDeviceAdd di un driver del bus, la funzione di callback deve chiamare WdfDeviceCreate per creare un FDO per il dispositivo padre, che in genere è un adattatore bus. Per ulteriori informazioni sulla creazione di un FDO, consultare Creazione di oggetti dispositivo in un driver di funzione. Il driver deve quindi enumerare i dispositivi figli del dispositivo padre e aggiungere i dispositivi figli alla lista dei figli.

Facoltativamente, il driver può chiamare WdfDeviceSetBusInformationForChildren per fornire al framework informazioni sul bus. È consigliabile farlo perché semplifica l'identificazione del bus da parte di dispositivi figlio e app.

Per aggiungere dispositivi figlio a una lista figlio, il driver deve chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent per ogni dispositivo figlio trovato. Questa chiamata informa il framework che un driver ha individuato un dispositivo figlio connesso a un dispositivo madre. Quando il driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent, fornisce una descrizione dell'identificazione e, facoltativamente, una descrizione dell'indirizzo.

Dopo che il driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent per segnalare un nuovo dispositivo, il framework informa il gestore PnP che il nuovo dispositivo esiste. Il gestore PnP compila uno stack di dispositivi e uno stack di driver per il nuovo dispositivo. Come parte di questo processo, il framework chiama la funzione di callback EvtChildListCreateDevice del driver del bus. Questa funzione di callback deve chiamare WdfDeviceCreate per creare un PDO per il nuovo dispositivo.

In genere, diversi dispositivi figlio sono connessi a un elemento padre, quindi il driver del bus deve chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent più volte. Il modo più efficiente per eseguire questo processo è il seguente:

1. Chiama WdfChildListBeginScan.

2. Chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent per ogni dispositivo figlio.

3. Chiamare WdfChildListEndScan.

Se si circonda l'enumerazione dinamica del driver con chiamate a WdfChildListBeginScan e WdfChildListEndScan, il framework archivia tutte le modifiche alla lista dei figli. Notifica al gestore PnP delle modifiche quando il driver chiama WdfChildListEndScan. In un secondo momento, il framework chiama la funzione di callback EvtChildListCreateDevice del driver del bus per ogni dispositivo nell'elenco di dispositivi figlio. Questa funzione di callback chiama WdfDeviceCreate per creare un PDO per ogni nuovo dispositivo.

Quando il driver chiama WdfChildListBeginScan, il framework contrassegna tutti i dispositivi segnalati in precedenza come non più presenti. Pertanto, il driver deve chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent per tutti gli elementi figlio rilevabili dal driver, non solo gli elementi figlio appena individuati. Per aggiungere un singolo elemento figlio a un elenco figlio, il driver può effettuare una singola chiamata a WdfChildListUpdateAllChildDescriptionsAsPresent senza prima chiamare WdfChildListBeginScan.

Aggiornamento di un elenco figlio dinamico

Per aggiornare le informazioni in un elenco figlio dinamico, utilizzare uno dei metodi seguenti:

1. Quando un dispositivo padre riceve un interrupt che indica l'arrivo o la rimozione di un figlio, la funzione di callback EvtInterruptDpc del driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent se un dispositivo è collegato o WdfChildListUpdateChildDescriptionAsMissing se un dispositivo è scollegato.

2. Il driver può fornire una funzione di callback EvtChildListScanForChildren , che il framework chiama ogni volta che il dispositivo padre entra nello stato di lavoro (D0). Questa funzione di callback deve enumerare tutti i dispositivi figlio chiamando WdfChildListBeginScan, WdfChildListAddOrUpdateChildDescriptionAsPresent (o WdfChildListUpdateAllChildDescriptionsAsPresent) e WdfChildListEndScan.

È possibile usare una o entrambe queste tecniche nel programma del driver.

Scorrere un elenco figlio dinamico

Per esaminare il contenuto di un sottoelenco, il driver può percorrere l'elenco usando una delle tecniche seguenti:

• Per ottenere il contenuto di ogni descrizione del dispositivo figlio, uno alla volta, il driver può:

  1. Chiamare WdfChildListBeginIteration.
  2. Chiama WdfChildListRetrieveNextDevice tutte le volte che sia necessario.
  3. Chiamare WdfChildListEndIteration.

  Quando si chiama WdfChildListBeginIteration, il driver specifica un flag tipizzato di WDF_RETRIEVE_CHILD_FLAGS che indica se il framework deve recuperare tutte le descrizioni dei dispositivi o solo un subset. Quando WdfChildListRetrieveNextDevice trova una corrispondenza, recupera le descrizioni di identificazione e di indirizzo del dispositivo bambino, oltre a un handle per l'oggetto dispositivo.

• Per ottenere la descrizione dell'indirizzo attualmente contenuta in una descrizione del dispositivo figlio, il driver può chiamare WdfChildListRetrieveAddressDescription, specificando una descrizione di identificazione. Il framework attraversa l'elenco figlio fino a quando non trova un dispositivo figlio con una descrizione di identificazione corrispondente. Recupera quindi la descrizione dell'indirizzo.

• Se è necessario ottenere un riferimento per l'oggetto dispositivo del framework associato a un particolare dispositivo figlio, il driver può chiamare WdfChildListRetrievePdo. Il framework attraversa l'elenco figlio fino a quando non trova un dispositivo figlio con una descrizione di identificazione corrispondente e quindi restituisce un handle di oggetto dispositivo. Per proteggere il chiamante dalla rimozione improvvisa di PnP del PDO in un altro thread, eseguire il wrapping della chiamata con WdfChildListBeginIteration e WdfChildListEndIteration.

Accesso alle descrizioni di identificazione e indirizzo di un PDO

Il tuo driver può chiamare i seguenti metodi per accedere alla descrizione di identificazione o alla descrizione dell'indirizzo di un PDO.

• WdfPdoRetrieveIdentificationDescription, che recupera la descrizione di identificazione associata a un PDO.

• WdfPdoRetrieveAddressDescription, che recupera la descrizione dell'indirizzo associata a un PDO.

• WdfPdoUpdateAddressDescription, che aggiorna la descrizione dell'indirizzo associata a un PDO.

Gestione delle richieste di rienumerazione

I driver del bus basati su framework che supportano l'enumerazione dinamica possono ricevere una richiesta di ridenumerazione di un determinato dispositivo figlio tramite l'interfaccia REENUMERATE_SELF_INTERFACE_STANDARD. Per altre info, vedi Gestione delle richieste di enumerazione.