DriverEntry untuk rutinitas Driver WDF

[Berlaku untuk KMDF dan UMDF]

DriverEntry adalah rutinitas pertama yang disediakan driver yang dipanggil setelah driver dimuat. Ini bertanggung jawab untuk menginisialisasi driver.

Sintaks

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

Parameter

DriverObject [in]
Penunjuk ke struktur DRIVER_OBJECT yang mewakili objek driver WDM driver.

RegistryPath [in]
Penunjuk ke struktur UNICODE_STRING yang menentukan jalur ke kunci Parameter driver dalam registri .

Menampilkan nilai

Jika rutinitas berhasil, rutinitas harus mengembalikan STATUS_SUCCESS. Jika tidak, itu harus mengembalikan salah satu nilai status kesalahan yang ditentukan dalam ntstatus.h.

Keterangan

Seperti semua driver WDM, driver berbasis kerangka kerja harus memiliki rutinitas DriverEntry , yang dipanggil setelah driver dimuat. Rutinitas DriverEntry berbasis kerangka kerja harus:

• Aktifkan pelacakan perangkat lunak WPP.

  DriverEntry harus menyertakan makro WPP_INIT_TRACING untuk mengaktifkan pelacakan perangkat lunak.

• Panggil WdfDriverCreate.

  Panggilan ke WdfDriverCreate memungkinkan driver menggunakan antarmuka Windows Driver Framework. (Driver tidak dapat memanggil rutinitas kerangka kerja lain sebelum memanggil WdfDriverCreate.)

• Alokasikan sumber daya sistem non-perangkat khusus dan variabel global yang mungkin diperlukan.

  Biasanya, driver mengaitkan sumber daya sistem dengan perangkat individual. Oleh karena itu, driver berbasis kerangka kerja mengalokasikan sebagian besar sumber daya dalam panggilan balik EvtDriverDeviceAdd , yang dipanggil saat perangkat individual terdeteksi.

  Karena beberapa instans driver UMDF mungkin dihosting oleh instans terpisah Wudfhost, variabel global mungkin tidak tersedia di semua instans driver UMDF.

• Dapatkan parameter khusus driver dari registri.

  Beberapa driver mendapatkan parameter dari registri. Driver ini dapat memanggil WdfDriverOpenParametersRegistryKey untuk membuka kunci registri yang berisi parameter ini.

• Berikan nilai pengembalian DriverEntry.

Catatan Driver UMDF berjalan dalam proses host mode pengguna, sementara driver KMDF berjalan dalam mode kernel dalam proses sistem. Kerangka kerja mungkin memuat beberapa instans driver UMDF ke dalam instans terpisah dari proses host. Akibatnya:

• Kerangka kerja mungkin memanggil rutinitas DriverEntry driver UMDF beberapa kali jika memuat instans driver dalam proses host yang berbeda. Sebaliknya, kerangka kerja memanggil rutinitas DriverEntry driver KMDF hanya sekali.
• Jika driver UMDF membuat variabel global dalam rutinitas DriverEntry-nya, variabel mungkin tidak tersedia untuk semua instans driver. Namun, variabel global yang dibuat driver KMDF dalam rutinitas DriverEntry-nya tersedia untuk semua instans driver.

Untuk informasi selengkapnya tentang kapan rutinitas DriverEntry driver berbasis kerangka kerja dipanggil, lihat Membangun dan Memuat Driver WDF.

Rutinitas DriverEntry tidak dideklarasikan dalam header WDK. Pemverifikasi Driver Statis (SDV) dan alat verifikasi lainnya mungkin memerlukan deklarasi seperti berikut:

DRIVER_INITIALIZE MyDriverEntry;

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

Contoh

Contoh kode berikut menunjukkan rutinitas DriverEntry driver sampel Serial (KMDF).

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

Lihat juga

WdfDriverBuat

EvtDriverDeviceAdd