Ejemplo de paquete de controladores de DCH-Compliant

Artículo
05/05/2023

En este artículo se describe cómo el ejemplo de controlador DCHU aplica los principios de diseño de DCH. Puede usarlo como modelo para aplicar los principios de diseño de DCH a su propio paquete de controladores.

Si desea una copia local del repositorio de ejemplo, clone desde Windows-driver-samples.

Algunas partes del ejemplo pueden usar directivas y API que solo están disponibles en determinadas versiones de Windows 10 y versiones posteriores. Consulte Instalación de dispositivos y controladores para ver en qué versión del sistema operativo se admite una directiva determinada.

Prerequisites

Antes de leer esta sección, debe familiarizarse con los principios de diseño de DCH.

Introducción

En el ejemplo se proporcionan escenarios de ejemplo en los que dos asociados de hardware, Contoso (un generador de sistemas o OEM) y Fabrikam (un fabricante de dispositivos o IHV) trabajan juntos para crear un controlador compatible con DCH para un dispositivo en el próximo sistema de Contoso. El dispositivo en cuestión es un kit de aprendizaje USB FX2 de OSR. En el pasado, Fabrikam escribiría un paquete de controladores heredado que se personalizó en una línea de producto específica de Contoso y, a continuación, lo entregaría al OEM para controlar el mantenimiento. Esto dio lugar a una sobrecarga de mantenimiento significativa, por lo que Fabrikam decidió refactorizar el código y crear un paquete de controladores compatible con DCH en su lugar.

Uso de secciones o directivas declarativas y aislamiento correcto de INF

En primer lugar, Fabrikam revisa la lista de secciones y directivas INF que no son válidas en los paquetes de controladores compatibles con DCH. Durante este ejercicio, Fabrikam observa que usan muchas de estas secciones y directivas en su paquete de controladores.

Su controlador INF registra un coins installer que aplica archivos y configuraciones dependientes de la plataforma. Esto significa que el paquete de controladores es mayor de lo que debe ser y es más difícil atender al controlador cuando un error afecta solo a un subconjunto de los sistemas OEM que envían el controlador. Además, la mayoría de las modificaciones específicas del OEM están relacionadas con la personalización de marca, por lo que Fabrikam debe actualizar el paquete de controladores cada vez que se agrega un OEM o cuando un problema menor afecta a un subconjunto de sistemas OEM.

Fabrikam quita las directivas y secciones no declarativas y usa la herramienta InfVerif para comprobar que el nuevo archivo INF del paquete de controladores sigue el requisito de INF declarativo.

Uso de infs de extensión para componentes de un paquete de controladores

A continuación, Fabrikam separa las personalizaciones específicas de los asociados oem (como Contoso) del paquete de controladores base en un INF de extensión.

El siguiente fragmento de código, actualizado desde [osrfx2_DCHU_extension.inx], especifica la Extension clase e identifica a Contoso como proveedor, ya que poseerá el paquete de controladores de extensión:

[Version]
...
Class       = Extension
ClassGuid   = {e2f84ce7-8efa-411c-aa69-97454ca4cb57}
Provider    = Contoso
ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID
...

En [osrfx2_DCHU_base.inx], Fabrikam especifica las siguientes entradas:

[OsrFx2_AddReg]
HKR, OSR, "OperatingMode",, "Default" ; FLG_ADDREG_TYPE_SZ
HKR, OSR, "OperatingParams",, "None" ; FLG_ADDREG_TYPE_SZ

En [osrfx2_DCHU_extension.inx], Contoso invalida el valor del Registro OperatingParams establecido por la base y agrega OperatingExceptions:

[OsrFx2Extension_AddReg]
HKR, OSR, "OperatingParams",, "-Extended"
HKR, OSR, "OperatingExceptions",, "x86"

Las extensiones siempre se procesan después del INF base, pero en ningún orden definido. Si un INF base se actualiza a una versión más reciente, las extensiones se seguirán aplicando después de instalar el nuevo INF base.

Instalación de un servicio desde un archivo INF

Fabrikam usa un servicio Win32 para controlar los LED en la placa OSR. Ven este componente como parte de la funcionalidad básica del dispositivo, por lo que lo incluyen como parte de su INF base ([osrfx2_DCHU_base.inx]). Este servicio en modo de usuario (usersvc) se puede agregar e iniciar mediante declaración especificando la directiva AddService en el archivo 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

Este servicio también se puede instalar en un componente o extensión INF, en función del escenario.

Uso de un componente para instalar software heredado desde un paquete de controladores

Fabrikam tiene un archivo osrfx2_DCHU_componentsoftware.exe ejecutable que instalaron anteriormente mediante un co-instalador. Este software heredado muestra las claves del Registro establecidas por la placa y es necesaria para el OEM. Se trata de un ejecutable basado en GUI que solo se ejecuta en Windows para ediciones de escritorio. Para instalarlo, Fabrikam crea un paquete de controladores de componentes independiente y lo agrega en su extensión INF.

El siguiente fragmento de código de [osrfx2_DCHU_extension.inx] usa la directiva AddComponent para crear un dispositivo secundario virtual:

[OsrFx2Extension_Install.NT.Components]
AddComponent = osrfx2_DCHU_component,,OsrFx2Extension_ComponentInstall


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

A continuación, en el componente INF [osrfx2_DCHU_component.inx], Fabrikam especifica la directiva AddSoftware para instalar el ejecutable opcional:

[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

El código fuente de la aplicación Win32 se incluye en el ejemplo.

El paquete de controladores de componentes solo se distribuye en las SKU de escritorio debido a la selección de destino establecida en el Panel del Centro de desarrollo para hardware de Windows. Para obtener más información, consulta Publicar un controlador en Windows Update.

Permitir la comunicación con una aplicación de soporte técnico de hardware

Fabrikam quiere proporcionar una aplicación complementaria basada en GUI como parte del paquete de controladores de Windows. Dado que las aplicaciones complementarias basadas en Win32 no pueden formar parte de un paquete de Controladores de Windows, portar su aplicación Win32 a la Plataforma universal de Windows (UWP) y emparejar la aplicación con el dispositivo.

El siguiente fragmento de código de muestra cómo el paquete de osrfx2_DCHU_base/device.c controladores base agrega una funcionalidad personalizada a la instancia de la interfaz de 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 nueva aplicación (no incluida en el ejemplo) es segura y se puede actualizar fácilmente en Microsoft Store. Con la aplicación para UWP lista, Contoso usa DISM: administración y mantenimiento de imágenes de implementación para cargar previamente la aplicación en imágenes de edición de escritorio de Windows.

Acoplamiento estricto de varios archivos INF

Lo ideal es que haya contratos de control de versiones seguros entre base, extensiones y componentes. Hay ventajas de mantenimiento al tener estos tres paquetes con servicio de forma independiente (el escenario de "acoplamiento flexible"), pero hay escenarios en los que deben agruparse en un único paquete de controladores ("estrechamente acoplado") debido a contratos de control de versiones deficientes. El ejemplo incluye ejemplos de ambos escenarios:

DCHU_Sample\osrfx2_DCHU_extension_loose
DCHU_Sample\osrfx2_DCHU_extension_tight

Cuando la extensión y el componente están en el mismo paquete de controladores ("estrechamente acoplado"), la extensión INF especifica la directiva CopyINF para hacer que el componente INF se copie en el sistema de destino. Esto se muestra en DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Esta directiva también se puede usar para coordinar la instalación de archivos INF en dispositivos multifunción. Para obtener más información, vea Copiar archivos INF.

Nota:

Aunque un controlador base puede cargar una extensión (y dirigirse al controlador base en la etiqueta de envío), una extensión empaquetada con otro controlador no se puede publicar en el identificador de hardware de la extensión.

Ejecución desde el almacén de controladores

Para facilitar la actualización del controlador, Fabrikam especifica el almacén de controladores como destino para copiar los archivos del controlador mediante dirid 13 siempre que sea posible. El uso de un valor de directorio de destino de 13 puede dar lugar a una estabilidad mejorada durante el proceso de actualización del controlador. Este es un ejemplo de [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Consulte la página Run from Driver Store (Ejecutar desde el almacén de controladores ) para obtener más detalles sobre cómo buscar y cargar archivos dinámicamente desde el almacén de controladores.

Resumen

En el diagrama siguiente se muestran los paquetes de controladores que Fabrikam y Contoso crearon para su controlador compatible con DCH. En el ejemplo de acoplamiento flexible, realizarán tres envíos independientes en el Panel del Centro de desarrollo para hardware de Windows: uno para la base, otro para la extensión y otro para el componente. En el ejemplo estrechamente acoplado, realizarán dos envíos: base y extensión/componente.

Paquetes de controladores de extensión, base y componente.

El componente INF coincidirá en el identificador de hardware del componente, mientras que la base y las extensiones coincidirán en el identificador de hardware de la placa.