Exemplo do pacote do driver DCH-Compliant

Este tópico descreve como o exemplo de driver DCHU aplica princípios de design DCH. Você pode usá-lo como um modelo para aplicar princípios de design DCH ao seu próprio pacote de driver.

Se você quiser uma cópia local do repositório de exemplo, clone de exemplos de driver do Windows.

Algumas partes do exemplo podem usar diretivas e APIs que só estão disponíveis em determinadas versões de Windows 10 e superiores. Consulte a Instalação do Dispositivo e do Driver para ver em qual versão do sistema operacional uma determinada diretiva tem suporte.

Pré-requisitos

Antes de ler esta seção, você deve se familiarizar com os Princípios de Design da DCH.

Visão geral

O exemplo fornece cenários de exemplo em que dois parceiros de hardware, Contoso (um construtor de sistema ou OEM) e Fabrikam (um fabricante de dispositivos ou IHV) estão trabalhando juntos para criar um driver compatível com DCH para um dispositivo no próximo sistema da Contoso. O dispositivo em questão é um kit de aprendizagem USB FX2 da OSR. No passado, a Fabrikam escreveria um pacote de driver herdado que era personalizado para uma linha de produto contoso específica e, em seguida, entregava-o ao OEM para lidar com a manutenção. Isso resultou em uma sobrecarga significativa de manutenção, portanto, a Fabrikam decidiu refatorar o código e criar um pacote de driver compatível com DCH.

Usar seções/diretivas declarativas e isolar corretamente o INF

Primeiro, a Fabrikam analisa a lista de seções e diretivas INF inválidas em pacotes de driver compatíveis com DCH. Durante este exercício, a Fabrikam observa que eles estão usando muitas dessas seções e diretivas em seu pacote de driver.

O INF do driver registra um co-instalador que aplica arquivos e configurações dependentes da plataforma. Isso significa que o pacote de driver é maior do que deveria ser e é mais difícil atender ao driver quando um bug afeta apenas um subconjunto dos sistemas OEM que enviam o driver. Além disso, a maioria das modificações específicas do OEM estão relacionadas à identidade visual, portanto, a Fabrikam precisa atualizar o pacote de driver sempre que um OEM é adicionado ou quando um pequeno problema afeta um subconjunto de sistemas OEM.

A Fabrikam remove as seções e diretivas não declarativas e usa a ferramenta InfVerif para verificar se o arquivo INF do novo pacote de driver segue o requisito INF declarativo.

Usar INFs de extensão para componentes de um pacote de driver

Em seguida, a Fabrikam separa personalizações específicas de parceiros OEM (como Contoso) do pacote de driver base em um INF de extensão.

O snippet a seguir, atualizado de [osrfx2_DCHU_extension.inx], especifica a classe e identifica a Extension Contoso como o provedor, uma vez que eles serão proprietários do pacote de driver de extensão:

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

Em [osrfx2_DCHU_base.inx], a Fabrikam especifica as seguintes entradas:

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

Em [osrfx2_DCHU_extension.inx], a Contoso substitui o valor do registro OperatingParams definido pela base e adiciona OperatingExceptions:

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

Observe que as extensões são sempre processadas após o INF base, mas sem ordem definida. Se um INF base for atualizado para uma versão mais recente, as extensões ainda serão aplicadas novamente após a instalação do novo INF base.

Instalar um serviço de um arquivo INF

A Fabrikam usa um serviço Win32 para controlar os LEDs na placa OSR. Eles veem esse componente como parte da funcionalidade principal do dispositivo, portanto, incluem-no como parte de seu INF base ([osrfx2_DCHU_base.inx]). Esse serviço de modo de usuário (usersvc) pode ser adicionado e iniciado declarativamente especificando a diretiva AddService no arquivo 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

Observe que esse serviço também pode ser instalado em um componente ou extensão INF, dependendo do cenário.

Usar um componente para instalar o software herdado de um pacote de driver

A Fabrikam tem um arquivo osrfx2_DCHU_componentsoftware.exe executável que eles instalaram anteriormente usando um co-instalador. Esse software herdado exibe as chaves do Registro definidas pelo quadro e é exigido pelo OEM. Esse é um executável baseado em GUI que é executado apenas no Windows para edições da área de trabalho. Para instalá-lo, a Fabrikam cria um pacote de driver de componente separado e o adiciona em seu INF de extensão.

O snippet a seguir de [osrfx2_DCHU_extension.inx] usa a diretiva AddComponent para criar um dispositivo filho virtual:

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

Em seguida, no componente INF [osrfx2_DCHU_component.inx], a Fabrikam especifica a diretiva AddSoftware para instalar o executável 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

O código-fonte do aplicativo Win32 está incluído no exemplo.

Observe que o pacote do driver de componente só é distribuído em SKUs da Área de Trabalho devido ao conjunto de direcionamento no painel do Centro de Desenvolvimento para Hardware do Windows. Para obter mais informações, consulte Publicar um driver para Windows Update.

Permitir comunicação com um aplicativo de suporte de hardware

A Fabrikam gostaria de fornecer um aplicativo complementar baseado em GUI como parte do pacote do Windows Driver. Como os aplicativos complementares baseados em Win32 não podem fazer parte de um pacote do Windows Driver, eles portam seu aplicativo Win32 para o Plataforma Universal do Windows (UWP) e emparelham o aplicativo com o dispositivo.

O snippet a seguir osrfx2_DCHU_base/device.c mostra como o pacote de driver base adiciona uma funcionalidade personalizada à instância de interface do 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);

O novo aplicativo (não incluído no exemplo) é seguro e pode ser atualizado facilmente na Microsoft Store. Com o aplicativo UWP pronto, a Contoso usa DISM – Serviço e Gerenciamento de Imagens de Implantação para pré-carregar o aplicativo em imagens de edição do Windows Desktop.

Acoplamento apertado de vários arquivos INF

O ideal é que haja contratos de controle de versão fortes entre base, extensões e componentes. Há vantagens de manutenção em ter esses três pacotes atendidos independentemente (o cenário "vagamente acoplado"), mas há cenários em que eles precisam ser empacotados em um único pacote de driver ("fortemente acoplado") devido a contratos de controle de versão ruins. O exemplo inclui exemplos de ambos os cenários:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Essa diretiva também pode ser usada para coordenar a instalação de arquivos INF em dispositivos multifuncionais. Para obter mais detalhes, consulte Copiar arquivos INF.

Observação

Embora um driver base possa carregar uma extensão (e direcionar o driver base no rótulo de envio), uma extensão agrupada com outro driver não pode ser publicada na ID de hardware da extensão.

Executar no Repositório de Driver

Para facilitar a atualização do driver, a Fabrikam especifica o Repositório de Driver como o destino para copiar os arquivos do driver usando dirid 13 sempre que possível. O uso de um valor de diretório de destino de 13 pode resultar em maior estabilidade durante o processo de atualização do driver. Aqui está um exemplo de [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Consulte a execução na página da Loja de Driver para obter mais detalhes sobre como localizar e carregar arquivos dinamicamente do Repositório de Driver.

Resumo

O diagrama a seguir mostra os pacotes de driver que a Fabrikam e a Contoso criaram para o driver compatível com DCH. No exemplo de acoplamento flexível, eles farão três envios separados no painel do Centro de Desenvolvimento para Hardware do Windows: um para a base, um para a extensão e outro para o componente. No exemplo bem acoplado, eles farão dois envios: base e extensão/componente.

Pacotes de driver de extensão, base e componente.

Observe que o componente INF corresponderá à ID de hardware do componente, enquanto a base e as extensões corresponderão à ID de hardware do quadro.

Confira também

Introdução com drivers do Windows

Usando um arquivo INF de extensão

osrfx2_DCHU_base.inx

"vagamente acoplado" osrfx2_DCHU_component.inx

"vagamente acoplado" osrfx2_DCHU_extension.inx

"bem acoplado" osrfx2_DCHU_component.inx

"firmemente acoplado" osrfx2_DCHU_extension.inx