DCH 準拠のドライバー パッケージの例DCH-Compliant Driver Package Example

このトピックでは、DCHU ドライバーのサンプルDCH 設計原則がどのように適用されるのかについて説明します。This topic describes how the DCHU driver sample applies DCH design principles. これをモデルとして使用し、ご自分のドライバー パッケージに DCH 設計原則を適用できます。You can use it as a model to apply DCH design principles to your own driver package.

サンプル リポジトリのローカル コピーが必要な場合は、Windows-driver-samples から複製できます。If you would like a local copy of the sample repo, clone from Windows-driver-samples.

このサンプルの一部では、特定のバージョンの Windows 10 以降でのみ使用できるディレクティブと API を使用する場合があります。Some portions of the sample may use directives and APIs that are only available on certain versions of Windows 10 and above. 特定のディレクティブがサポートされている OS バージョンを確認するには、「INF のディレクティブ」を参照してください。Please refer to INF Directives to see what OS version a given directive is supported on.

前提条件Prerequisites

このセクションを読む前に、DCH 設計原則を理解しておく必要があります。Before you read this section, you should become familiar with the DCH Design Principles.

概要Overview

サンプルで提供されているシナリオ例では、2 つのハードウェア パートナー Contoso (システム ビルダーまたは OEM) と Fabrikam (デバイスの製造元または IHV) が共同で、Contoso の次期システムのデバイス向け DCH 準拠ドライバーを作成しています。The sample provides example scenarios where two hardware partners, Contoso (a system builder, or OEM) and Fabrikam (a device manufacturer, or IHV) are working together to create a driver that is DCH-compliant for a device in Contoso's upcoming system. 対象のデバイスは OSR USB FX2 学習キットです。The device in question is an OSR USB FX2 learning kit. これまで、Fabrikam は、特定の Contoso 製品ライン用にカスタマイズされたレガシ ドライバー パッケージを作成し、サービスを処理するために OEM に渡していました。In the past, Fabrikam would write a legacy driver package that was customized to a specific Contoso product line, and then hand it to the OEM to handle servicing. その結果、大きなメンテナンス オーバーヘッドが発生していたため、Fabrikam は、コードをリファクタリングして、代わりに DCH 準拠ドライバー パッケージを作成することを決定しました。This resulted in significant maintenance overhead, so Fabrikam decided to refactor the code and create a DCH-compliant driver package instead.

宣言型セクションおよびディレクティブを使用して INF を適切に分離するUse declarative sections/directives and properly isolate INF

最初に、Fabrikam は DCH 準拠ドライバー パッケージで無効な INF のセクションとディレクティブの一覧を確認します。First, Fabrikam reviews the list of INF sections and directives that are invalid in DCH-compliant driver packages. その間に、Fabrikam は無効なセクションとディレクティブの多くをドライバー パッケージで使っていることに気付きます。During this exercise, Fabrikam notices that they're using many of these sections and directives in their driver package.

Fabrikam のドライバーの INF は、プラットフォームに依存する設定とファイルを適用する共同インストーラーを登録します。Their driver INF registers a co-installer that applies platform-dependent settings and files. そのため、ドライバー パッケージが本来のサイズより大きいだけでなく、ドライバーを搭載している OEM システムの一部のみがバグの影響を受ける場合のドライバーの保守作業が困難です。This means that the driver package is larger than it should be, and it is harder to service the driver when a bug affects only a subset of the OEM systems that ship the driver. また、OEM 固有の変更のほとんどはブランドに関連するため、OEM が追加されたり、軽微な問題が OEM システムのサブセットに影響を与えたりするたびに、Fabrikam はドライバー パッケージを更新する必要があります。Also, most of the OEM-specific modifications are related to branding, so Fabrikam needs to update the driver package every time an OEM is added or when a minor issue affects a subset of OEM systems.

Fabrikam は、非宣言型セクションとディレクティブを削除し、InfVerif ツールを使って新しいドライバー パッケージの INF ファイルが宣言型 INF の要件に従っていることを確認します。Fabrikam removes the non-declarative sections and directives and uses the InfVerif tool to verify that the new driver package's INF file follows the declarative INF requirement.

拡張 INF を使ってドライバー パッケージをコンポーネント化するUse extension INFs to componentize a driver package

次に、Fabrikam は、OEM パートナー (Contoso など) に固有のカスタマイズを基本ドライバー パッケージから分離して、拡張 INF にまとめます。Next, Fabrikam separates customizations that are specific to OEM partners (such as Contoso) from the base driver package into an extension INF.

osrfx2_DCHU_extension.inx から更新された次のスニペットでは、Extension クラスが指定されており、拡張ドライバー パッケージを所有する Contoso がプロバイダーとしてを識別されます。The following snippet, updated from osrfx2_DCHU_extension.inx, specifies the Extension class and identifies Contoso as the provider since they will own the extension driver package:

[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 では、次のエントリが指定されています。In osrfx2_DCHU_base.inx, Fabrikam specifies the following entries:

[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 を追加します。In osrfx2_DCHU_extension.inx, Contoso overrides the OperatingParams registry value set by the base and adds OperatingExceptions:

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

拡張機能は常に基本 INF の後に、しかし順不同で処理されることに注意してください。Note that extensions are always processed after the base INF but in no definite order. 基本 INF が新しいバージョンに更新された場合、拡張 INF は新しい基本 INF がインストールされた後で再適用されます。If a base INF is updated to a newer version, then the extensions will still be re-applied after the new base INF is installed.

INF ファイルからサービスをインストールするInstall a service from an INF file

Fabrikam では、OSR ボード上の LED 制御に Win32 サービスを使用しています。Fabrikam uses a Win32 service to control the LEDs on the OSR board. 同社にとってこのコンポーネントはデバイスのコア機能の一部であるため、基本 INF (osrfx2_DCHU_base.inx) の一部として組み込みます。They view this component as part of the core functionality of the device, so they include it as part of their base INF (osrfx2_DCHU_base.inx). このユーザーモード サービス (usersvc) は、INF ファイルに AddService ディレクティブを指定して宣言することで、追加および開始できます。This user-mode service (usersvc) can be added and started declaratively by specifying the AddService directive in the INF file:

[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 または拡張 INF にもインストールできることに注意してください。Note that such a service could also be installed in a component or extension INF, depending on the scenario.

コンポーネントを使ってドライバー パッケージからレガシ ソフトウェアをインストールするUse a component to install legacy software from a driver package

Fabrikam は、これまで共同インストーラーを使ってインストールしていた実行可能ファイル osrfx2_DCHU_componentsoftware.exe を持っています。Fabrikam has an executable file osrfx2_DCHU_componentsoftware.exe that they previously installed using a co-installer. このレガシ ソフトウェアはボードによって設定されるレジストリ キーを表示し、OEM が必要とします。This legacy software displays the registry keys set by the board and is required by the OEM. これは、デスクトップ エディションの Windows でのみ実行される GUI ベースの実行可能ファイルです。This is a GUI-based executable that only runs on Windows for desktop editions. これをインストールするため、Fabrikam は別のコンポーネント ドライバー パッケージを作成し、それを拡張 INF に追加します。To install it, Fabrikam creates a separate component driver package and adds it in their extension INF.

osrfx2_DCHU_extension.inx の次のスニペットは、AddComponent ディレクティブを使って仮想子デバイスを作成します。The following snippet from osrfx2_DCHU_extension.inx uses the AddComponent directive to create a virtual child device:

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

その後、コンポーネントの INF osrfx2_DCHU_component.inx で指定されている AddSoftware ディレクティブによって、オプションの実行可能ファイルがインストールされます。Then, in the component INF osrfx2_DCHU_component.inx, Fabrikam specifies the AddSoftware directive to install the optional executable:

[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 アプリのソース コードは、サンプルに含まれます。The source code for the Win32 app is included in the sample.

Windows ハードウェア デベロッパー センター ダッシュボードでターゲット指定が設定されているため、このコンポーネント ドライバー パッケージは デスクトップ SKU のみに配布されることに注意してください。Note that the component driver package is only distributed on Desktop SKUs due to targeting set in the Windows Hardware Dev Center dashboard. 詳しくは、「Windows Update にドライバーを公開する」をご覧ください。For more info, see Publish a driver to Windows Update.

ハードウェア サポート アプリとの通信を許可するAllow communication with a hardware support app

Fabrikam は、Windows ドライバー パッケージの一部として GUI ベースのコンパニオン アプリを提供したいと考えています。Fabrikam would like to provide a GUI-based companion app as part of the Windows Driver package. Win32 ベースのコンパニオン アプリケーションを Windows ドライバー パッケージの一部にすることはできないため、Win32 アプリをユニバーサル Windows プラットフォーム (UWP) に移植し、アプリをデバイスとペアリングします。Because Win32-based companion applications cannot be part of a Windows Driver package, they port their Win32 app to the Universal Windows Platform (UWP) and pair the app with the device.

osrfx2_DCHU_base/device.c の次のスニペットでは、ベース ドライバー パッケージがデバイス インターフェイスのインスタンスにカスタム機能を追加する方法が示されています。The following snippet from osrfx2_DCHU_base/device.c shows how the base driver package adds a custom capability to the device interface instance:

    WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = { 0 };
    static const wchar_t customCapabilities[] = L"CompanyName.yourCustomCapabilityNameTBD_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 で簡単に更新することができます。The new app (not included in the sample) is secure and can be updated easily in the Microsoft Store. UWP アプリケーション対応になったことで、Contoso は DISM (展開イメージのサービスと管理) を使ってアプリケーションを Windows デスクトップ エディションのイメージに事前に読み込みます。With the UWP application ready, Contoso uses DISM - Deployment Image Servicing and Management to pre-load the application on Windows Desktop edition images.

複数の INF ファイルを密結合するTightly coupling multiple INF files

基本パッケージ、拡張パッケージ、コンポーネント パッケージの間には、優れたバージョン管理コントラクトが存在するのが理想です。Ideally, there should be strong versioning contracts between base, extensions, and components. これら 3 つのパッケージが個別にサービスを受けることには ("疎結合" のシナリオ) サービス上のメリットがありますが、シナリオによっては、バージョン管理コントラクトが不十分なために、単一のドライバー パッケージへのバンドル ("密結合") が必要な場合があります。There are servicing advantages in having these three packages serviced independently (the "loosely coupled" scenario), but there are scenarios where they need to be bundled in a single driver package ("tightly coupled") due to poor versioning contracts. 次のサンプルでは、両方のシナリオの例が示されています。The sample includes examples of both scenarios:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

このディレクティブは、多機能デバイス内での INF ファイルのインストールを調整することもできます。This directive can also be used to coordinate installation of INF files in multifunction devices. 詳しくは、「Copying INF files」 (INF ファイルのコピー) をご覧ください。For more details, see Copying INF files.

注意

ベース ドライバーのペイロードに拡張機能を格納する (そして、配送先住所ラベルでベース ドライバーをターゲットにする) ことはできますが、別のドライバーとバンドルされている拡張機能を、拡張機能のハードウェア ID に公開することはできません。While a base driver can payload an extension (and target the base driver in the shipping label), an extension bundled with another driver cannot be published to the extension hardware ID.

ドライバー ストアから実行するRun from the driver store

ドライバーを容易に更新できるように、Fabrikam は、可能であれば dirid 13 を使って、ドライバー ストアをドライバー ファイルのコピー先として指定します。To make it easier to update the driver, Fabrikam specifies the Driver Store as the destination to copy the driver files by using dirid 13 where possible. コピー先ディレクトリの値として 13 を使うと、ドライバー更新プロセスの間の安定性が向上します。Using a destination directory value of 13 can result in improved stability during the driver update process. osrfx2_DCHU_base.inx の例を次に示します。Here is an example from osrfx2_DCHU_base.inx:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

ファイルを動的に見つけてドライバー ストアから読み込む方法の詳細については、「ドライバー パッケージの分離」を参照してください。See the driver package isolation page for more details regarding how to dynamically find and load files from the Driver Store.

要約Summary

次の図は、Fabrikam と Contoso が DCH 準拠ドライバー用に作成したドライバー パッケージを示したものです。The following diagram shows the driver packages that Fabrikam and Contoso created for their DCH-compliant driver. 疎結合の例では、Windows ハードウェア デベロッパー センター ダッシュボードで、基本パッケージ、拡張パッケージ、コンポーネントパッケージの 3 回にわたってパッケージが別個に提出されます。In the loosely coupled example, they will make three separate submissions on the Windows Hardware Dev Center dashboard: one for the base, one for the extension, and one for the component. 密結合の例では、基本パッケージと拡張/コンポーネント パッケージの 2 つが提出されます。In the tightly coupled example, they will make two submissions: base and extension/component.

拡張、基本、コンポーネントの各ドライバー パッケージ

コンポーネント INF はコンポーネント ハードウェア ID に一致し、基本 INF と拡張 INF はボードのハードウェア ID に一致することに注意してください。Note that the component INF will match on the component hardware ID, whereas the base and extensions will match on the board's hardware ID.

関連項目See also

Windows ドライバーの概要Getting Started with Windows Drivers

拡張 INF ファイルの使用Using an Extension INF File