WDF ドライバー用 DriverEntry ルーチン

  • [アーティクル]

[KMDF と UMDF に適用]

DriverEntry は、ドライバーが読み込まれた後に最初に呼び出されるドライバーが提供するルーチンです。 ドライバーの初期化を担当します。

構文

NTSTATUS DriverEntry(
  _In_ PDRIVER_OBJECT  DriverObject,
  _In_ PUNICODE_STRING RegistryPath
);

パラメーター

DriverObject [in]
ドライバーの WDM ドライバー オブジェクトを表す DRIVER_OBJECT 構造体へのポインター。

RegistryPath [in]
レジストリ内のドライバーの Parameters キーへのパスを指定する UNICODE_STRING 構造体へのポインター。

戻り値

ルーチンが成功した場合は、STATUS_SUCCESS を返す必要があります。 それ以外の場合は、ntstatus.h で定義されているエラー状態値のいずれかを返す必要があります。

解説

すべての WDM ドライバーと同様に、フレームワークベースのドライバーには 、ドライバーが読み込まれた後に呼び出される DriverEntry ルーチンが必要です。 フレームワークベースのドライバーの DriverEntry ルーチンは、次の条件を満たす必要があります。

  • WPP ソフトウェア トレースをアクティブ化します。

    DriverEntry には、ソフトウェア トレースをアクティブ化するための WPP_INIT_TRACING マクロを含める必要があります。

  • WdfDriverCreate を呼び出 します。

    WdfDriverCreate を呼び出すと、ドライバーは Windows Driver Framework インターフェイスを使用できるようになります。 (ドライバーは、WdfDriverCreate を呼び出すまで、他のフレームワーク ルーチンを呼び出すことはできません)

  • デバイス固有でないシステム リソースと、必要になる可能性があるグローバル変数を割り当てます。

    通常、ドライバーはシステム リソースを個々のデバイスに関連付けます。 そのため、フレームワークベースのドライバーは、EvtDriverDeviceAdd コールバックでほとんどのリソースを割り当てます。このコールバックは、個々のデバイスが検出されたときに呼び出されます。

    UMDF ドライバーの複数のインスタンスが Wudfhost の個別のインスタンスによってホストされる可能性があるため、UMDF ドライバーのすべてのインスタンスでグローバル変数を使用できるわけではありません。

  • レジストリからドライバー固有のパラメーターを取得します。

    一部のドライバーは、レジストリからパラメーターを取得します。 これらのドライバーは、WdfDriverOpenParametersRegistryKey を呼び出して、これらのパラメーターを含むレジストリ キーを開くことができます。

  • DriverEntry の戻り値を指定します。

注: UMDF ドライバーはユーザーモードのホスト プロセスで実行され、KMDF ドライバーはシステム プロセスでカーネルモードで実行されます。 フレームワークは、ホスト プロセスの個別のインスタンスに UMDF ドライバーの複数のインスタンスを読み込む可能性があります。 その結果、次のような影響が出ています。

  • フレームワークは、異なるホスト プロセスでドライバーのインスタンスを読み込む場合、UMDF ドライバーの DriverEntry ルーチンを複数回呼び出すことがあります。 これに対し、フレームワークは KMDF ドライバーの DriverEntry ルーチンを 1 回だけ呼び出します。
  • UMDF ドライバーが DriverEntry ルーチンでグローバル変数を作成する場合、その変数がドライバーのすべてのインスタンスで使用できない可能性があります。 しかし、KMDF ドライバーが DriverEntry ルーチンで作成するグローバル変数は、ドライバーのすべてのインスタンスで使用できます。

フレームワーク ベースのドライバーの DriverEntry ルーチンが呼び出されるタイミングの詳細については、「WDF ドライバーのビルドと読み込み」を参照してください。

DriverEntry ルーチンは、WDK ヘッダーでは宣言されていません。 静的ドライバー検証ツール (SDV) やその他の検証ツールでは、次のような宣言が必要になる場合があります。

DRIVER_INITIALIZE MyDriverEntry;

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
// Function body
}

例

次のコード例は、シリアル (KMDF) サンプル ドライバーの DriverEntry ルーチンを示しています。

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    WDFDRIVER  hDriver;
    NTSTATUS  status;
    WDF_OBJECT_ATTRIBUTES  attributes;
    SERIAL_FIRMWARE_DATA driverDefaults;

    //
    // Initialize WPP tracing.
    //
    WPP_INIT_TRACING(
                     DriverObject,
                     RegistryPath
                     );

    SerialDbgPrintEx(
                     TRACE_LEVEL_INFORMATION,
                     DBG_INIT,
                     "Serial Sample (WDF Version) - Built %s %s\n",
                     __DATE__, __TIME__
                     );
    //
    // Register a cleanup callback function (which calls WPP_CLEANUP)
    // for the framework driver object. The framework will call
    // the cleanup callback function when it deletes the driver object,
    // before the driver is unloaded.
    //
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    attributes.EvtCleanupCallback = SerialEvtDriverContextCleanup;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           SerialEvtDeviceAdd
                           );

    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             &attributes,
                             &config,
                             &hDriver
                             );
    if (!NT_SUCCESS(status)) {
        SerialDbgPrintEx(
                         TRACE_LEVEL_ERROR,
                         DBG_INIT,
                         "WdfDriverCreate failed with status 0x%x\n",
                         status
                         );
        //
        // Clean up tracing here because WdfDriverCreate failed.
        //
        WPP_CLEANUP(DriverObject);
        return status;
    }

    //
    // Call an internal routine to obtain registry values
    // to use for all the devices that the driver 
    // controls, including whether or not to break on entry.
    //
    SerialGetConfigDefaults(
                            &driverDefaults,
                            hDriver
                            );

    //
    // Break on entry if requested bt registry value.
    //
    if (driverDefaults.ShouldBreakOnEntry) {
        DbgBreakPoint();
    }

    return status;
}

関連項目

WdfDriverCreate

EvtDriverDeviceAdd