Esempio di pacchetto DCH-Compliant driver
Questo articolo descrive come l'esempio di driver DCHU applica i principi di progettazione DCH. È possibile usarlo come modello per applicare i principi di progettazione DCH al proprio pacchetto driver.
Se si vuole 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. Fare riferimento all'installazione del dispositivo e del driver per visualizzare la versione del sistema operativo su cui è supportata una determinata direttiva.
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) lavorano insieme per creare un driver conforme a DCH per un dispositivo nel sistema futuro di Contoso. Il dispositivo in questione è un kit di apprendimento USB FX2 OSR. In passato, Fabrikam scriverebbe un pacchetto driver legacy personalizzato in una specifica linea di prodotti Contoso e quindi passarlo all'OEM per gestire la manutenzione. Ciò comportava un notevole sovraccarico di manutenzione, quindi Fabrikam decise di eseguire il refactoring del codice e di creare invece un pacchetto driver conforme a DCH.
Usare sezioni/direttive dichiarative e isolare correttamente INF
Prima di tutto, Fabrikam esamina l'elenco delle sezioni e delle direttive INF non valide nei pacchetti di driver conformi a DCH. Durante questo esercizio, Fabrikam noterà che usano molte di queste sezioni e direttive nel pacchetto driver.
Il driver INF registra un co-installer che applica impostazioni e file dipendenti dalla piattaforma. Ciò significa che il pacchetto driver è più grande di quello che deve essere, ed è più difficile eseguire il servizio del driver quando un bug influisce solo su 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 un OEM viene aggiunto o quando un problema secondario influisce su 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 segue il requisito INF dichiarativo.
Usare gli INFS di estensione per componentizzare un pacchetto driver
Successivamente, Fabrikam separa le personalizzazioni specifiche dei partner OEM (ad esempio Contoso) dal pacchetto del 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 poiché sarà proprietario del pacchetto del 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 in nessun 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 della loro base INF ([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ò essere installato anche in un componente o in un'estensione INF, a seconda dello scenario.
Usare un componente per installare software legacy da un pacchetto driver
Fabrikam ha un file osrfx2_DCHU_componentsoftware.exe eseguibile installato in precedenza usando un co-installer. 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 di driver del componente separato e lo aggiunge nell'estensione INF.
Il frammento di codice seguente da [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
Nel componente INF [osrfx2_DCHU_component.inx], Fabrikam specifica quindi 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 del driver del componente viene distribuito solo negli SKU desktop a causa della destinazione impostata nella Windows Hardware Dev Center dashboard. Per altre informazioni, vedere 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 di Driver di Windows, portano l'app Win32 all'piattaforma UWP (Universal Windows Platform) (UWP) e associano l'app al dispositivo.
Il frammento di codice osrfx2_DCHU_base/device.c seguente mostra 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 di distribuzione per pre-caricare l'applicazione nelle immagini di Windows Desktop Edition.
Accoppiamento stretto di più file INF
Idealmente, dovrebbe esserci contratti di controllo delle versioni forti tra base, estensioni e componenti. Esistono vantaggi di manutenzione per avere questi tre pacchetti gestiti in modo indipendente (lo scenario "associato in modo libero"), ma ci sono scenari in cui devono essere raggruppati in un singolo 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 abbinato"), l'estensione INF specifica la direttiva CopyINF per causare la copia del componente INF nel sistema di destinazione. Questo è illustrato 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 indirizzare 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 driver usando dirid 13 , se possibile. L'uso di un valore della 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 altre informazioni su come trovare e caricare in modo dinamico i file dall'Archivio driver, vedere la pagina Esegui dall'Archivio driver.
Riepilogo
Il diagramma seguente illustra i pacchetti driver creati da Fabrikam e Contoso per il driver conforme a DCH. Nell'esempio associato in modo libero, verranno inviati tre invii separati sul Windows Hardware Dev Center dashboard: uno per la base, uno per l'estensione e uno per il componente. Nell'esempio strettamente associato verranno inviati due invii: base e estensione/componente.
Il componente INF corrisponde all'ID hardware del componente, mentre le estensioni e di base corrispondono all'ID hardware della scheda.
Vedi anche
Introduzione con i driver di Windows
Uso di un file INF di estensione
osrfx2_DCHU_extension.inx "associato in modo libero"
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per