Conversione di un driver da UMDF 1 a UMDF 2
Questo argomento descrive come convertire un driver User-Mode Driver Framework (UMDF) 1 in UMDF 2. È possibile iniziare con un driver UMDF 1 che usa i file Sources/Dirs (non un progetto di Visual Studio) oppure è possibile convertire un driver UMDF 1 contenuto in un progetto di Visual Studio. Il risultato sarà un progetto driver UMDF 2 in Visual Studio. I driver UMDF 2 vengono eseguiti in entrambi i Windows 10 per le edizioni desktop (Home, Pro, Enterprise e Education) e Windows 10 Mobile.
L'esempio di driver Echo è un esempio di driver che è stato convertito da UMDF 1 a UMDF 2.
Introduzione
Per iniziare, aprire un nuovo progetto driver in Visual Studio. Selezionare il modello Driver-WDF-Modalità> utente di Visual C++->>Windows (UMDF 2). Visual Studio apre un modello parzialmente popolato che include stub per le funzioni di callback che il driver deve implementare. Questo nuovo progetto driver sarà la base del driver UMDF 2. Usare l'esempio Echo di UMDF 2 come guida al tipo di codice da introdurre.
Esaminare quindi il codice driver UMDF 1 esistente e determinare i mapping degli oggetti. Ogni oggetto COM in UMDF 1 ha un oggetto WDF corrispondente in UMDF 2. Ad esempio, l'interfaccia IWDFDevice esegue il mapping all'oggetto dispositivo WDF, rappresentato da un handle WDFDEVICE. Quasi tutti i metodi di interfaccia forniti dal framework in UMDF 1 hanno metodi corrispondenti in UMDF 2. Ad esempio, IWDFDevice::GetDefaultIoQueue esegue il mapping a WdfDeviceGetDefaultQueue.
Analogamente, le funzioni di callback fornite dal driver hanno equivalenti nelle due versioni. In UMDF 1 la convenzione di denominazione per le interfacce fornite dal driver (ad eccezione di IDriverEntry) è IObjectCallbackXxx, mentre in UMDF 2 la convenzione di denominazione per le routine fornite dal driver è EvtObjectXxx. Ad esempio, il metodo IDriverEntry::OnDeviceAdd viene mappato al metodo EvtDriverDeviceAdd.
Il driver implementa funzioni di callback sia in UMDF 1 che in 2, ma il modo in cui il driver fornisce puntatori ai callback differisce. In UMDF 1 il driver implementa metodi di callback come membri delle interfacce fornite dal driver. Il driver registra queste interfacce con il framework quando crea oggetti framework, ad esempio chiamando IWDFDriver::CreateDevice.
In UMDF 2, il driver fornisce puntatori alle funzioni di callback fornite dal driver nelle strutture di configurazione, ad esempio WDF_DRIVER_CONFIG e WDF_IO_QUEUE_CONFIG.
Gestione della durata dell'oggetto
I driver che usano UMDF 1 devono implementare il conteggio dei riferimenti per determinare quando è sicuro eliminare gli oggetti. Poiché il framework tiene traccia dei riferimenti agli oggetti per conto del driver, un driver UMDF 2 non deve contare i riferimenti.
In UMDF 2 ogni oggetto framework ha un oggetto padre predefinito. Quando un oggetto padre viene eliminato, il framework elimina oggetti figlio associati. Quando il driver chiama un metodo di creazione di oggetti, ad esempio WdfDeviceCreate, può accettare l'elemento padre predefinito oppure specificare un elemento padre personalizzato in una struttura WDF_OBJECT_ATTRIBUTES . Per un elenco di oggetti framework e dei relativi oggetti padre predefiniti, vedere Riepilogo degli oggetti Framework.
Inizializzazione driver
Un driver UMDF 1 implementa l'interfaccia IDriverEntry . Nel relativo metodo IDriverEntry::OnDeviceAdd callback, il driver in genere:
- Crea e inizializza un'istanza dell'oggetto callback del dispositivo.
- Crea il nuovo oggetto dispositivo framework chiamando IWDFDriver::CreateDevice.
- Configura le code del dispositivo e i relativi oggetti callback corrispondenti.
- Crea un'istanza di una classe di interfaccia del dispositivo chiamando IWDFDevice::CreateDeviceInterface.
Un driver UMDF 2 implementa DriverEntry e EvtDriverDeviceAdd. Nella routine DriverEntry , un driver UMDF 2 chiama in genere WDF_DRIVER_CONFIG_INIT per inizializzare la struttura di WDF_DRIVER_CONFIG del driver. Passa quindi questa struttura a WdfDriverCreate.
Nella sua funzione EvtDriverDeviceAdd , il driver potrebbe eseguire alcune delle operazioni seguenti:
- Compilare la struttura WDFDEVICE_INIT , che fornisce informazioni usate per creare l'oggetto dispositivo. Per altre informazioni sull'uso di WDFDEVICE_INIT, vedere Creazione di un oggetto dispositivo Framework.
- Configurare l'area di contesto dell'oggetto dispositivo. Per informazioni sull'allocazione e l'accesso allo spazio di contesto per gli oggetti framework, vedere Framework Object Context Space.
- Creare l'oggetto device.
- Specificare i gestori delle richieste per l'oggetto dispositivo.
- Creare code di I/O.
- Creare interfacce del dispositivo.
- Impostare i criteri di inattività del dispositivo e le impostazioni di riattivazione, se l'oggetto dispositivo possiede i criteri di alimentazione.
- Creare oggetti di interruzione, se l'hardware supporta gli interruzioni.
Installazione del driver
Quando si crea un nuovo progetto driver in Visual Studio, il nuovo progetto contiene un file inx. Quando si compila il driver, Visual Studio compila il file inx in un file INF che può essere usato come parte di un pacchetto driver.
Mentre un file INF per un driver UMDF 1 deve includere un ID classe driver, un DriverCLSID non è obbligatorio in un file INF per un driver UMDF 2.
Anche se un driver UMDF 1 deve fare riferimento al co-installer nel file INF, non è necessario alcun riferimento constaller in un file INF UMDF 2. Anche se un riferimento per la coinstallazione può essere visualizzato in un file INF per un driver UMDF 2, non è necessario.
Archiviazione del contesto del dispositivo
In UMDF 1, il driver archivia in genere il contesto del dispositivo in un oggetto callback creato dal driver, ad esempio specificando membri privati della classe oggetto callback del dispositivo. In alternativa, un driver UMDF 1 può chiamare il metodo IWDFObject::AssignContext per registrare il contesto in un oggetto framework.
In UMDF 2, il framework alloca lo spazio di contesto in base alla struttura facoltativa WDF_OBJECT_ATTRIBUTES fornita dal driver quando chiama un metodo di creazione di oggetti. Dopo aver chiamato il metodo di creazione di un oggetto, un driver può chiamare WdfObjectAllocateContext una o più volte per allocare spazio di contesto aggiuntivo a un oggetto specifico. Per i passaggi che devono essere usati da un driver UMDF 2 per definire una struttura di contesto e un metodo di accesso, vedere Framework Object Context Space.
Debug del driver
Per eseguire il debug di un driver UMDF 2, si useranno le estensioni in Wdfkd.dll anziché Wudfext.dll. Per altre informazioni sulle estensioni in Wudfext.dll, vedere Riepilogo delle estensioni del debugger in Wdfkd.dll.
In UMDF 2 è anche possibile ottenere informazioni aggiuntive sul debug dei driver tramite Inflight Trace Recorder (IFR), come descritto in Using Inflight Trace Recorder in KMDF e UMDF 2 Driver. È anche possibile usare il proprio registratore in volo (IFR) del framework. Vedere Uso del Logger dell'evento di Framework.
Argomenti correlati
Spazio di contesto dell'oggetto Framework