Esempio di pacchetto driver conforme a DCH
Questo articolo descrive in che modo l'esempio di driver DCHU applica i principi di progettazione DCH. È possibile usarlo come modello per applicare i principi di progettazione DCH al pacchetto driver personalizzato.
Se si desidera una copia locale del repository di esempio, clonare da Windows-driver-samples.
Alcune parti dell'esempio possono usare direttive e API disponibili solo in determinate versioni di Windows 10 e versioni successive. Per informazioni sulla versione del sistema operativo supportata da una determinata direttiva, vedere Installazione di dispositivi e driver.
Prerequisiti
Prima di leggere questa sezione, è necessario acquisire familiarità con i principi di progettazione DCH.
Panoramica
L'esempio fornisce scenari di esempio in cui due partner hardware, Contoso (generatore di sistema o OEM) e Fabrikam (produttore di dispositivi o IHV) collaborano per creare un driver conforme a DCH per un dispositivo nel prossimo sistema di Contoso. Il dispositivo in questione è un kit di apprendimento USB FX2 OSR. In passato, Fabrikam scriveva un pacchetto driver legacy personalizzato in una specifica linea di prodotti Contoso e quindi passalo all'OEM per gestire la manutenzione. Ciò ha comportato un notevole sovraccarico di manutenzione, quindi Fabrikam ha deciso di effettuare il refactoring del codice e creare invece un pacchetto driver conforme a DCH.
Usare sezioni/direttive dichiarative e isolare correttamente INF
Prima di tutto, Fabrikam esamina l'elenco di sezioni e direttive INF non valide nei pacchetti driver conformi a DCH. Durante questo esercizio Fabrikam rileva che usano molte di queste sezioni e direttive nel pacchetto driver.
Il driver INF registra un co-programma di installazione che applica le impostazioni e i file dipendenti dalla piattaforma. Ciò significa che il pacchetto driver è più grande di quello che deve essere, ed è più difficile gestire il driver quando un bug interessa solo un subset dei sistemi OEM che spediscono il driver. Inoltre, la maggior parte delle modifiche specifiche dell'OEM è correlata alla personalizzazione, quindi Fabrikam deve aggiornare il pacchetto driver ogni volta che viene aggiunto un OEM o quando un problema secondario interessa un subset di sistemi OEM.
Fabrikam rimuove le sezioni e le direttive non dichiarative e usa lo strumento InfVerif per verificare che il nuovo file INF del pacchetto driver segua il requisito INF dichiarativo.
Usare gli INFS di estensione per componentizzare un pacchetto driver
Successivamente, Fabrikam separa le personalizzazioni specifiche per i partner OEM (ad esempio Contoso) dal pacchetto driver di base in un'estensione INF.
Il frammento di codice seguente, aggiornato da [osrfx2_DCHU_extension.inx], specifica la Extension classe e identifica Contoso come provider perché è proprietario del pacchetto driver di estensione:
[Version]
...
Class = Extension
ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57}
Provider = Contoso
ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID
...
In [osrfx2_DCHU_base.inx], Fabrikam specifica le voci seguenti:
[OsrFx2_AddReg]
HKR, OSR, "OperatingMode",, "Default" ; FLG_ADDREG_TYPE_SZ
HKR, OSR, "OperatingParams",, "None" ; FLG_ADDREG_TYPE_SZ
In [osrfx2_DCHU_extension.inx]Contoso esegue l'override del valore del Registro di sistema OperatingParams impostato dalla base e aggiunge OperatingExceptions:
[OsrFx2Extension_AddReg]
HKR, OSR, "OperatingParams",, "-Extended"
HKR, OSR, "OperatingExceptions",, "x86"
Le estensioni vengono sempre elaborate dopo l'INF di base, ma non in ordine definito. Se un INF di base viene aggiornato a una versione più recente, le estensioni verranno comunque applicate nuovamente dopo l'installazione del nuovo INF di base.
Installare un servizio da un file INF
Fabrikam usa un servizio Win32 per controllare i LED nella scheda OSR. Visualizzano questo componente come parte della funzionalità principale del dispositivo, quindi lo includono come parte del relativo INF di base ([osrfx2_DCHU_base.inx]). Questo servizio in modalità utente (usersvc) può essere aggiunto e avviato in modo dichiarativo specificando la direttiva AddService nel file INF:
[OsrFx2_Install.NT]
CopyFiles = OsrFx2_CopyFiles
[OsrFx2_Install.NT.Services]
AddService = WUDFRd, 0x000001fa, WUDFRD_ServiceInstall ; Flag 0x2 sets this as the service for the device
AddService = osrfx2_DCHU_usersvc,, UserSvc_ServiceInstall
[UserSvc_ServiceInstall]
DisplayName = %UserSvcDisplayName%
ServiceType = 0x10 ; SERVICE_WIN32_OWN_PROCESS
StartType = 0x3 ; SERVICE_DEMAND_START
ErrorControl = 0x1 ; SERVICE_ERROR_NORMAL
ServiceBinary = %13%\osrfx2_DCHU_usersvc.exe
AddTrigger = UserSvc_AddTrigger ; AddTrigger syntax is only available in Windows 10 Version 2004 and above
[UserSvc_AddTrigger]
TriggerType = 1 ; SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL
Action = 1 ; SERVICE_TRIGGER_ACTION_SERVICE_START
SubType = %GUID_DEVINTERFACE_OSRFX2% ; Interface GUID
DataItem = 2, "USB\VID_0547&PID_1002" ; SERVICE_TRIGGER_DATA_TYPE_STRING
[OsrFx2_CopyFiles]
osrfx2_DCHU_base.dll
osrfx2_DCHU_filter.dll
osrfx2_DCHU_usersvc.exe
Tale servizio può anche essere installato in un componente o in un'estensione INF, a seconda dello scenario.
Usare un componente per installare il software legacy da un pacchetto driver
Fabrikam dispone di un file osrfx2_DCHU_componentsoftware.exe eseguibile installato in precedenza tramite un co-programma di installazione. Questo software legacy visualizza le chiavi del Registro di sistema impostate dalla scheda ed è richiesto dall'OEM. Si tratta di un eseguibile basato su GUI che viene eseguito solo in Windows per le edizioni desktop. Per installarlo, Fabrikam crea un pacchetto driver del componente separato e lo aggiunge nell'estensione INF.
Il frammento di codice seguente di [osrfx2_DCHU_extension.inx] usa la direttiva AddComponent per creare un dispositivo figlio virtuale:
[OsrFx2Extension_Install.NT.Components]
AddComponent = osrfx2_DCHU_component,,OsrFx2Extension_ComponentInstall
[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab
Quindi, nel componente INF [osrfx2_DCHU_component.inx], Fabrikam specifica la direttiva AddSoftware per installare il file eseguibile facoltativo:
[OsrFx2Component_Install.NT.Software]
AddSoftware = osrfx2_DCHU_componentsoftware,, OsrFx2Component_SoftwareInstall
[OsrFx2Component_SoftwareInstall]
SoftwareType = 1
SoftwareBinary = osrfx2_DCHU_componentsoftware.exe
SoftwareArguments = <<DeviceInstanceId>>
SoftwareVersion = 1.0.0.0
[OsrFx2Component_CopyFiles]
osrfx2_DCHU_componentsoftware.exe
Il codice sorgente per l'app Win32 è incluso nell'esempio.
Il pacchetto driver del componente viene distribuito solo negli SKU desktop a causa del targeting impostato nel dashboard di Windows Hardware Dev Center. Per altre info, vedi Pubblicare un driver in Windows Update.
Consentire la comunicazione con un'app di supporto hardware
Fabrikam vuole fornire un'app complementare basata su GUI come parte del pacchetto driver di Windows. Poiché le applicazioni complementari basate su Win32 non possono far parte di un pacchetto driver di Windows, convertino l'app Win32 nell'piattaforma UWP (Universal Windows Platform) (UWP) e associano l'app al dispositivo.
Il frammento di codice osrfx2_DCHU_base/device.c seguente illustra come il pacchetto driver di base aggiunge una funzionalità personalizzata all'istanza dell'interfaccia del dispositivo:
WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = { 0 };
static const wchar_t customCapabilities[] = L"CompanyName.yourCustomCapabilityName_YourStorePubId\0";
WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT(&PropertyData,
&GUID_DEVINTERFACE_OSRUSBFX2,
&DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities);
Status = WdfDeviceAssignInterfaceProperty(Device,
&PropertyData,
DEVPROP_TYPE_STRING_LIST,
sizeof(customCapabilities),
(PVOID)customCapabilities);
La nuova app (non inclusa nell'esempio) è sicura e può essere aggiornata facilmente in Microsoft Store. Con l'applicazione UWP pronta, Contoso usa Gestione e manutenzione immagini distribuzione per pre-caricare l'applicazione nelle immagini di Windows Desktop Edition.
Accoppiamento stretto di più file INF
Idealmente, dovrebbero esserci contratti di controllo delle versioni sicuri tra base, estensioni e componenti. Esistono vantaggi di manutenzione nell'avere questi tre pacchetti gestiti in modo indipendente (lo scenario "ad accoppiamento libero"), ma esistono scenari in cui devono essere raggruppati in un unico pacchetto driver ("strettamente accoppiato") a causa di contratti di controllo delle versioni scarsi. L'esempio include esempi di entrambi gli scenari:
DCHU_Sample\osrfx2_DCHU_extension_tight
Quando l'estensione e il componente si trovano nello stesso pacchetto driver ("strettamente accoppiato"), l'estensione INF specifica la direttiva CopyINF per fare in modo che il componente INF venga copiato nel sistema di destinazione. Questa operazione è illustrata in DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx:
[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf
Questa direttiva può essere usata anche per coordinare l'installazione dei file INF nei dispositivi multifunzione. Per altre informazioni, vedere Copia di file INF.
Nota
Mentre un driver di base può eseguire il payload di un'estensione (e specificare come destinazione il driver di base nell'etichetta di spedizione), un'estensione in bundle con un altro driver non può essere pubblicata nell'ID hardware dell'estensione.
Eseguire dall'archivio driver
Per semplificare l'aggiornamento del driver, Fabrikam specifica l'archivio driver come destinazione per copiare i file del driver usando dirid 13 laddove possibile. L'uso di un valore di directory di destinazione pari a 13 può comportare una maggiore stabilità durante il processo di aggiornamento del driver. Ecco un esempio di [osrfx2_DCHU_base.inx]:
[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store
Per altri dettagli su come trovare e caricare in modo dinamico i file dall'Archivio driver, vedere la pagina Esegui da Archivio driver.
Riepilogo
Il diagramma seguente illustra i pacchetti driver creati da Fabrikam e Contoso per il driver conforme a DCH. Nell'esempio ad accoppiamento libero verranno inviati tre invii separati nel dashboard di Windows Hardware Dev Center: uno per la base, uno per l'estensione e uno per il componente. Nell'esempio strettamente accoppiato verranno inviati due invii: base e estensione/componente.
Il componente INF corrisponderà all'ID hardware del componente, mentre la base e le estensioni corrisponderanno all'ID hardware della scheda.
Vedi anche
Introduzione allo sviluppo di driver Windows
Uso di un file INF di estensione
osrfx2_DCHU_component.inx "loosely coupled"
osrfx2_DCHU_extension.inx "loosely coupled"