Rutina DriverEntry para controladores WDF
[Se aplica a KMDF y UMDF]
DriverEntry es la primera rutina proporcionada por el controlador que se llama después de cargar un controlador. Es responsable de inicializar el controlador.
Sintaxis
NTSTATUS DriverEntry(
_In_ PDRIVER_OBJECT DriverObject,
_In_ PUNICODE_STRING RegistryPath
);
Parámetros
DriverObject [in]
Puntero a una estructura DRIVER_OBJECT que representa el objeto de controlador WDM del controlador.
RegistryPath [in]
Puntero a una estructura UNICODE_STRING que especifica la ruta de acceso a la clave Parameters del controlador en el Registro.
Valor devuelto
Si la rutina se realiza correctamente, debe devolver STATUS_SUCCESS. De lo contrario, debe devolver uno de los valores de estado de error definidos en ntstatus.h.
Comentarios
Al igual que todos los controladores WDM, los controladores basados en marcos deben tener una rutina DriverEntry , a la que se llama después de cargar el controlador. Una rutina DriverEntry basada en el marco debe:
Active el seguimiento de software de WPP.
DriverEntry debe incluir una macro de WPP_INIT_TRACING para activar el seguimiento de software.
Llame a WdfDriverCreate.
La llamada a WdfDriverCreate permite al controlador usar interfaces de Windows Driver Framework. (El controlador no puede llamar a otras rutinas de marco antes de llamar a WdfDriverCreate).
Asigne los recursos del sistema no específicos del dispositivo y las variables globales que pueda necesitar.
Normalmente, los controladores asocian recursos del sistema a dispositivos individuales. Por lo tanto, los controladores basados en marcos asignan la mayoría de los recursos en una devolución de llamada EvtDriverDeviceAdd , a la que se llama cuando se detectan dispositivos individuales.
Dado que varias instancias de un controlador UMDF pueden hospedarse en instancias independientes de Wudfhost, es posible que una variable global no esté disponible en todas las instancias de un controlador UMDF.
Obtenga parámetros específicos del controlador del registro.
Algunos controladores obtienen parámetros del Registro. Estos controladores pueden llamar a WdfDriverOpenParametersRegistryKey para abrir la clave del Registro que contiene estos parámetros.
Proporcione un valor devuelto DriverEntry.
Nota Un controlador UMDF se ejecuta en un proceso de host en modo de usuario, mientras que un controlador KMDF se ejecuta en modo kernel en un proceso del sistema. El marco puede cargar varias instancias de un controlador UMDF en instancias independientes del proceso de host. Como resultado:
- El marco podría llamar a una rutina DriverEntry del controlador UMDF varias veces si carga instancias del controlador en procesos host diferentes. En cambio, el marco llama a una rutina DriverEntry del controlador KMDF solo una vez.
- Si un controlador UMDF crea una variable global en su rutina DriverEntry, es posible que la variable no esté disponible para todas las instancias del controlador. Sin embargo, una variable global que crea un controlador KMDF en su rutina DriverEntry está disponible para todas las instancias del controlador.
Para obtener más información sobre cuándo se llama a una rutina DriverEntry basada en un controlador basado en marcos, vea Building and Loading a WDF Driver.
La rutina DriverEntry no se declara en encabezados WDK. El comprobador de controladores estáticos (SDV) y otras herramientas de comprobación pueden requerir una declaración como la siguiente:
DRIVER_INITIALIZE MyDriverEntry;
NTSTATUS
DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath
)
{
// Function body
}
Ejemplos
En el ejemplo de código siguiente se muestra la rutina DriverEntry del controlador de ejemplo 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;
}