DriverEntry pro rutinu ovladačů WDF

[Platí pro KMDF a UMDF]

DriverEntry je první rutina dodávaná ovladače, která se volá po načtení ovladače. Zodpovídá za inicializaci řidiče.

Syntaxe

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

Parametry

DriverObject [in]
Ukazatel na DRIVER_OBJECT strukturu, která představuje objekt ovladače WDM ovladače.

RegistryPath [in]
Ukazatel na UNICODE_STRING strukturu, která určuje cestu ke klíči Parameters ovladače v registru.

Návratová hodnota

Pokud je rutina úspěšná, musí vrátit STATUS_SUCCESS. V opačném případě musí vrátit jednu z chybových hodnot definovaných v ntstatus.h.

Poznámky

Stejně jako všechny ovladače WDM musí mít ovladače založené na rozhraní DriverEntry rutina, která se volá po načtení ovladače. Rutina ovladače DriverEnt ry založená na rozhraní musí:

• Aktivujte trasování softwaru WPP.

  DriverEntry by měl obsahovat makro WPP_INIT_TRACING pro aktivaci trasování softwaru.

• Volání WdfDriverCreate.

  Volání WdfDriverCreate umožňuje ovladači používat rozhraní Windows Driver Framework. (Ovladač nemůže volat jiné rutiny architektury před voláním WdfDriverCreate.)

• Přidělte všechny systémové prostředky, které nejsou specifické pro zařízení, a globální proměnné, které by mohly potřebovat.

  Ovladače obvykle přidružují systémové prostředky k jednotlivým zařízením. Ovladače založené na rozhraní proto přidělují většinu prostředků v EvtDriverDeviceAdd zpětné volání, které se volá při zjištění jednotlivých zařízení.

  Vzhledem k tomu, že několik instancí ovladače UMDF může být hostováno samostatnými instancemi Wudfhost, globální proměnná nemusí být k dispozici ve všech instancích ovladače UMDF.

• Získejte parametry specifické pro ovladač z registru.

  Některé ovladače z registru získají parametry. Tyto ovladače mohou volat WdfDriverOpenParametersRegistryKey otevřít klíč registru, který obsahuje tyto parametry.

• Zadejte návratovou hodnotu DriverEntry.

Poznámka ovladač UMDF běží v hostitelském procesu v uživatelském režimu, zatímco ovladač KMDF běží v režimu jádra v systémovém procesu. Architektura může načíst několik instancí ovladače UMDF do samostatných instancí hostitelského procesu. Výsledek:

• Architektura může volat rutinu DriverEntry ovladače UMDF vícekrát, pokud načte instance ovladače v různých hostitelských procesech. Naproti tomu architektura volá rutinu DriverEntry ovladače KMDF pouze jednou.
• Pokud ovladač UMDF v rutině DriverEntry vytvoří globální proměnnou, nemusí být proměnná dostupná pro všechny instance ovladače. Globální proměnná, kterou ovladač KMDF vytvoří v jeho rutině DriverEntry, je však k dispozici pro všechny instance ovladače.

Další informace o volání rutiny ovladače DriverEnt ry založené na architektuře naleznete v tématu Sestavení a načítání ovladače WDF.

Rutina DriverEntry není deklarována v hlavičkách WDK. Ověření statického ovladače (SDV) a dalších ověřovacích nástrojů může vyžadovat deklaraci, například:

DRIVER_INITIALIZE MyDriverEntry;

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

Příklady

Následující příklad kódu ukazuje vzorový ovladač serial (KMDF) DriverEntry rutiny.

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

Viz také

WdfDriverCreate

EvtDriverDeviceAdd