Exemplo de pacote de driver do DCH-Compliant
Este artigo descreve como o exemplo de driver DCHU aplica princípios de design de DCH. Você pode usá-lo como um modelo para aplicar princípios de design de DCH ao seu próprio pacote de driver.
Se você quiser uma cópia local do repositório de exemplo, clone do Windows-driver-samples.
Algumas partes do exemplo podem usar diretivas e APIs que só estão disponíveis em determinadas versões do Windows 10 e superior. Consulte Instalação de dispositivo e 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 do 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 dispositivo 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 OSR USB FX2. No passado, a Fabrikam gravava um pacote de driver herdado que era personalizado para uma linha de produto da Contoso específica e, em seguida, entregava-o ao OEM para lidar com a manutenção. Isso resultou em uma sobrecarga de manutenção significativa, 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 está 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 declarativo de INF.
Usar INFs de extensão para componentes de um pacote de driver
Em seguida, a Fabrikam separa as personalizações específicas para 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 Contoso Extension como o provedor, pois ele será o proprietário 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"
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 depois que o novo INF base for instalado.
Instalar um serviço de um arquivo INF
A Fabrikam usa um serviço Win32 para controlar os LEDs na placa OSR. Eles exibem 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
Esse serviço também pode ser instalado em um inf de componente ou extensão, 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. Este é um executável baseado em GUI que só é executado no Windows para edições desktop. 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.
O pacote de 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 no Windows Update.
Permitir a 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 de código a seguir mostra como o pacote de osrfx2_DCHU_base/device.c driver base adiciona uma funcionalidade personalizada à instância da 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 – Gerenciamento e Manutenção de Imagens de Implantação para pré-carregar o aplicativo em imagens da edição da Área de Trabalho do Windows.
Acoplamento rígido de vários arquivos INF
Idealmente, deve haver 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 de forma independente (o cenário "vagamente acoplado"), mas há cenários em que eles precisam ser agrupados em um único pacote de driver ("firmemente acoplado") devido a contratos de controle de versão ruins. O exemplo inclui exemplos de ambos os cenários:
DCHU_Sample\osrfx2_DCHU_extension_tight
Quando a extensão e o componente estão no mesmo pacote de driver ("firmemente acoplado"), a extensão INF especifica a diretiva CopyINF para fazer com que o componente INF seja copiado para o sistema de destino. Isso é demonstrado em DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx:
[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 informações, consulte Copiando arquivos INF.
Observação
Embora um driver base possa carregar uma extensão (e direcionar o driver base na etiqueta de remessa), 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 de driver usando dirid 13 sempre que possível. O uso de um valor de diretório de destino de 13 pode resultar em estabilidade aprimorada 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 página executar no Repositório 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 livremente acoplado, 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 firmemente acoplado, eles farão dois envios: base e extensão/componente.
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
"vagamente acoplado" osrfx2_DCHU_component.inx
"vagamente acoplado" osrfx2_DCHU_extension.inx
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de