Пример пакета драйвера DCH-Compliant
В этой статье описывается, как пример драйвера 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_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 компонента будет соответствовать идентификатору оборудования компонента, а базовые и расширения будут совпадать с идентификатором оборудования платы.
См. также раздел
начало работы с драйверами Windows
Использование INF-файла расширения
"слабосвязанный" osrfx2_DCHU_component.inx
"слабосвязанный" osrfx2_DCHU_extension.inx