Ejemplo de paquete de controlador compatible con DCH
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 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.
Requisitos previos
Antes de leer esta sección, debe familiarizarse con los principios de diseño de DCH.
Información general
En el ejemplo se proporcionan escenarios de ejemplo en los que dos partners 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. Antes, Fabrikam escribía un paquete de controladores heredado personalizado para una línea de productos específica de Contoso y, a continuación, se lo entregaba al OEM para que se encargara de su 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 del INF
En primer lugar, Fabrikam revisa la lista de secciones INF y directivas 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 coinstalador que aplica archivos y configuraciones dependientes de la plataforma. Esto significa que el paquete de controladores es más grande de lo que debería ser, y es más difícil dar servicio al controlador cuando un error afecta solo a un subconjunto de los sistemas OEM que distribuyen el controlador. Además, la mayoría de las modificaciones específicas de los OEM están relacionadas con la marca, por lo que Fabrikam necesita 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 secciones y directivas 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 INF de extensión para separar por componentes un paquete de controladores
A continuación, Fabrikam separa las personalizaciones específicas de los partners 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 clase Extension e identifica 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 sin un orden definido. Si se actualiza un INF base a una versión más reciente, las extensiones se volverán a aplicar 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 principal 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 declarativamente 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 INF de componente o de extensión, 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 se instaló anteriormente mediante un coinstalador. Este software heredado muestra las claves del registro establecidas por la placa que necesita 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 componente independiente y lo agrega a su INF de extensión.
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 INF del componente [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 segmentación establecida en el Panel del Centro de desarrollo para hardware de Windows. Para obtener más información, consulte Publicación de un controlador en Windows Update.
Permitir la comunicación con una aplicación para compatibilidad con 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, migran su aplicación Win32 a la Plataforma universal de Windows (UWP) y emparejar la aplicación con el dispositivo.
En el fragmento de código siguiente de osrfx2_DCHU_base/device.c se muestra cómo el paquete de 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 la base, las extensiones y los componentes. Tener estos tres paquetes atendidos de forma independiente tiene sus ventajas (el escenario de "acoplamiento flexible"), pero hay escenarios en los que es necesario agruparlos en un único paquete de controladores ("acoplamiento fijo") debido a contratos de control de versiones deficientes. El ejemplo incluye ejemplos de ambos escenarios:
DCHU_Sample\osrfx2_DCHU_extension_tight
Cuando la extensión y el componente están en el mismo paquete de controladores ("acoplamiento fijo"), el INF de extensión especifica la directiva CopyINF para hacer que el INF de componente 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, consulte Copia de archivos INF.
Nota:
Aunque un controlador base puede cargar una extensión (y tener como destino el controlador base en la etiqueta de envío), una extensión agrupada 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. Usar un valor de directorio de destino de 13 puede dar lugar a una estabilidad mejorada durante el proceso de actualización del controlador. A continuación se muestra un ejemplo de [osrfx2_DCHU_base.inx]:
[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store
Consulte la página Ejecución 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 de acoplamiento fijo, realizarán dos envíos: base y extensión/componente.
El INF de componente coincidirá con el identificador de hardware del componente, mientras que la base y las extensiones coincidirán en el identificador de hardware de la placa.
Consulte también
Introducción al desarrollo de controladores de Windows
Uso de un archivo INF de extensión
osrfx2_DCHU_component.inx con acoplamiento flexible
osrfx2_DCHU_extension.inx con acoplamiento flexible