Подпрограмма DriverEntry для драйверов WDF

[Применимо к KMDF и UMDF]

DriverEntry — это первая подпрограмма, предоставляемая драйвером, которая вызывается после загрузки драйвера. Он отвечает за инициализацию драйвера.

Синтаксис

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

Параметры

DriverObject [in]
Указатель на структуру DRIVER_OBJECT, представляющую объект драйвера WDM драйвера драйвера.

RegistryPath [in]
Указатель на структуру 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 в отдельные экземпляры процесса узла. В результате:

• Платформа может вызывать подпрограмму DriverEntry драйвера UMDF несколько раз, если она загружает экземпляры драйвера в различных процессах узла. В отличие от этого, платформа вызывает подпрограмму DriverEntry драйвера KMDF только один раз.
• Если драйвер UMDF создает глобальную переменную в подпрограмме DriverEntry, переменная может быть недоступна для всех экземпляров драйвера. Однако глобальная переменная, созданная драйвером KMDF в подпрограмме DriverEntry, доступна всем экземплярам драйвера.

Дополнительные сведения о вызове подпрограммы драйвера на основе платформы DriverEntry см. в разделе Сборка и загрузка драйвера WDF.

Подпрограмма DriverEntry не объявлена в заголовках WDK. Для проверки статических драйверов (SDV) и других средств проверки может потребоваться объявление, например следующее:

DRIVER_INITIALIZE MyDriverEntry;

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

Примеры

В следующем примере кода показан пример драйвера DriverEntry с примером последовательности (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;
}

См. также

WdfDriverCreate

EvtDriverDeviceAdd