Пример пакета драйвера DCH-Compliant

Статья
05/05/2023

В этой статье описывается, как пример драйвера DCHU применяет принципы проектирования DCH. Его можно использовать в качестве модели для применения принципов проектирования DCH к собственному пакету драйверов.

Если вам требуется локальная копия примера репозитория, клонируйте из Windows-driver-samples.

Некоторые части примера могут использовать директивы и API, доступные только в определенных версиях Windows 10 и более поздних версий. См. статью Установка устройств и драйверов , чтобы узнать, в какой версии ОС поддерживается данная директива.

Предварительные требования

Прежде чем читать этот раздел, ознакомьтесь с принципами проектирования DCH.

Обзор

В этом примере приведены примеры сценариев, в которых два партнера по оборудованию: Contoso (построитель систем или ИЗГОТОВИТЕЛЬ оборудования) и Fabrikam (производитель устройства или IHV) работают вместе над созданием драйвера, совместимого с DCH для устройства в предстоящей системе Contoso. Рассматриваемое устройство представляет собой комплект обучения OSR USB FX2. В прошлом Fabrikam писала устаревший пакет драйверов, настроенный для конкретной линейки продуктов Contoso, а затем передавала его изготовителю оборудования для обслуживания. Это привело к значительным затратам на обслуживание, поэтому Fabrikam решила рефакторинг кода и создать пакет драйверов, совместимый с DCH.

Использование декларативных разделов и директив и правильная изоляция INF

Во-первых, Fabrikam проверяет список разделов INF и директив, которые являются недопустимыми в пакетах драйверов, совместимых с DCH. В этом упражнении Компания Fabrikam замечает, что использует многие из этих разделов и директив в пакете драйверов.

Inf драйвера регистрирует совместный установщик, который применяет зависящие от платформы параметры и файлы. Это означает, что пакет драйвера больше, чем должно быть, и его труднее обслуживать, когда ошибка затрагивает только подмножество систем OEM, которые поставляют драйвер. Кроме того, большинство изменений, связанных с изготовителем оборудования, связаны с фирменной символикой, поэтому Fabrikam необходимо обновлять пакет драйверов каждый раз при добавлении изготовителя оборудования или если небольшая проблема затрагивает подмножество oem-систем.

Fabrikam удаляет не декларативные разделы и директивы и использует средство InfVerif , чтобы убедиться, что INF-файл нового пакета драйвера соответствует декларативному требованию INF.

Использование inFs расширения для компонентизации пакета драйвера

Затем Fabrikam отделяет настройки, относящиеся к партнерам OEM (например, Contoso), от базового пакета драйверов в расширение INF.

Следующий фрагмент кода, обновленный из [osrfx2_DCHU_extension.inx], указывает Extension класс и определяет Contoso в качестве поставщика, так как они будут владеть пакетом драйвера расширения:

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

В [osrfx2_DCHU_base.inx], Fabrikam указывает следующие записи:

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

В [osrfx2_DCHU_extension.inx], Contoso переопределяет значение реестра OperatingParams , заданное базой, и добавляет OperatingExceptions:

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

Расширения всегда обрабатываются после базового INF-файла, но не в определенном порядке. Если базовый INF-файл обновлен до более новой версии, расширения по-прежнему будут применяться повторно после установки нового базового INF-файла.

Установка службы из INF-файла

Fabrikam использует службу Win32 для управления светодиодами на плате OSR. Они рассматривают этот компонент как часть основных функциональных возможностей устройства, поэтому они включают его как часть своего базового INF ([osrfx2_DCHU_base.inx]). Эту службу в пользовательском режиме (usersvc) можно добавить и запустить декларативно, указав директиву AddService в 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

Такая служба также может быть установлена в компоненте или расширении INF в зависимости от сценария.

Использование компонента для установки устаревшего программного обеспечения из пакета драйверов

Fabrikam имеет исполняемый файл osrfx2_DCHU_componentsoftware.exe , который ранее был установлен с помощью совместного установщика. Это устаревшее программное обеспечение отображает разделы реестра, заданные на плате и необходимые изготовителю оборудования. Это исполняемый файл на основе графического пользовательского интерфейса, который выполняется только в windows для настольных версий. Чтобы установить его, Fabrikam создает отдельный пакет драйвера компонентов и добавляет его в расширение INF.

В следующем фрагменте кода из [osrfx2_DCHU_extension.inx] используется директива AddComponent для создания виртуального дочернего устройства:

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

Затем в компоненте INF [osrfx2_DCHU_component.inx], Fabrikam указывает директиву AddSoftware для установки необязательного исполняемого файла:

[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

Исходный код приложения Win32 включен в пример.

Пакет драйвера компонентов распространяется только на номера SKU для настольных компьютеров из-за назначения, заданного в информационная панель Центра разработки оборудования для Windows. Дополнительные сведения см. в статье Публикация драйвера в клиентский компонент Центра обновления Windows.

Разрешить взаимодействие с аппаратным приложением поддержки

Fabrikam хотела бы предоставить приложение-компаньон на основе графического пользовательского интерфейса в составе пакета драйверов Windows. Так как приложения-компаньоны на основе Win32 не могут входить в пакет драйверов Windows, они переносят свое приложение Win32 в универсальная платформа Windows (UWP) и объединяют приложение с устройством.

В следующем фрагменте кода показано osrfx2_DCHU_base/device.c , как базовый пакет драйвера добавляет пользовательскую возможность в экземпляр интерфейса устройства:

    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);

Новое приложение (не включено в пример) является безопасным и может быть легко обновлено в Microsoft Store. Когда приложение UWP готово, компания Contoso использует DISM — управление образами развертывания для предварительной загрузки приложения в образы windows Desktop Edition.

Тесная связь с несколькими INF-файлами

В идеале между базой, расширениями и компонентами должны быть строгие контракты управления версиями. Существуют преимущества обслуживания в том, что эти три пакета обслуживаются независимо (сценарий со слабой связью), но существуют сценарии, в которых их необходимо объединить в один пакет драйверов ("тесно связанные") из-за плохого контракта управления версиями. Пример включает примеры обоих сценариев:

DCHU_Sample\osrfx2_DCHU_extension_loose
DCHU_Sample\osrfx2_DCHU_extension_tight

Если расширение и компонент находятся в одном и том же пакете драйвера ("тесно связанных"), расширение INF указывает директиву CopyINF для копирования компонента INF в целевую систему. Это показано в DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Эту директиву также можно использовать для координации установки INF-файлов на многофункциональных устройствах. Дополнительные сведения см. в разделе Копирование INF-файлов.

Примечание

Хотя базовый драйвер может загрузить расширение (и нацеливать базовый драйвер на этикетке доставки), расширение, в комплекте с другим драйвером не может быть опубликовано в идентификаторе оборудования расширения.

Запуск из хранилища драйверов

Чтобы упростить обновление драйвера, Fabrikam указывает хранилище драйверов в качестве места назначения для копирования файлов драйверов с помощью dirid 13 , где это возможно. Использование значения целевого каталога 13 может привести к повышению стабильности во время обновления драйвера. Ниже приведен пример из [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Дополнительные сведения о динамическом поиске и загрузке файлов из хранилища драйверов см. на странице запуска из хранилища драйверов .

Сводка

На следующей схеме показаны пакеты драйверов, созданные Fabrikam и Contoso для драйверов, совместимых с DCH. В слабосвязанном примере они будут делать три отдельные отправки на информационная панель Центра разработки оборудования для Windows: один для базового, один для расширения и один для компонента. В примере с тесной связью они будут делать две отправки: базовую и расширение или компонент.

Пакеты расширений, базовых драйверов и драйверов компонентов.

Inf компонента будет соответствовать идентификатору оборудования компонента, а базовые и расширения будут совпадать с идентификатором оборудования платы.