Portabilidad de un controlador de UMDF 1 a UMDF 2
En este tema se describe cómo migrar un controlador de User-Mode Driver Framework (UMDF) 1 a UMDF 2. Puede empezar con un controlador UMDF 1 que use archivos Sources/Dirs (no un proyecto de Visual Studio) o puede convertir un controlador UMDF 1 incluido en un proyecto de Visual Studio. El resultado será un proyecto de controlador UMDF 2 en Visual Studio. Los controladores UMDF 2 se ejecutan en Windows 10 para ediciones de escritorio (Home, Pro, Enterprise y Education) y Windows 10 Mobile.
El ejemplo del controlador Echo es un ejemplo de un controlador que se ha migrado de UMDF 1 a UMDF 2.
Introducción
Para empezar, abra un nuevo proyecto de controlador en Visual Studio. Seleccione la plantilla Controlador visual C++->Windows Driver-WDF-User>> Mode Driver (UMDF 2). Visual Studio abre una plantilla rellenada parcialmente que incluye códigos auxiliares para las funciones de devolución de llamada que el controlador debe implementar. Este nuevo proyecto de controlador será la base del controlador UMDF 2. Use el ejemplo de eco de UMDF 2 como guía para el tipo de código que debe introducir.
A continuación, revise el código de controlador UMDF 1 existente y determine las asignaciones de objetos. Cada objeto COM de UMDF 1 tiene un objeto WDF correspondiente en UMDF 2. Por ejemplo, la interfaz IWDFDevice se asigna al objeto de dispositivo WDF, representado por un identificador WDFDEVICE. Casi todos los métodos de interfaz proporcionados por el marco en UMDF 1 tienen métodos correspondientes en UMDF 2. Por ejemplo, IWDFDevice::GetDefaultIoQueue se asigna a WdfDeviceGetDefaultQueue.
De forma similar, las funciones de devolución de llamada proporcionadas por el controlador tienen equivalentes en las dos versiones. En UMDF 1, la convención de nomenclatura para las interfaces proporcionadas por el controlador (excepto para IDriverEntry) es IObjectCallbackXxx, mientras que en UMDF 2, la convención de nomenclatura para rutinas proporcionadas por el controlador es EvtObjectXxx. Por ejemplo, el método de devolución de llamada IDriverEntry::OnDeviceAdd se asigna a EvtDriverDeviceAdd.
El controlador implementa funciones de devolución de llamada en UMDF 1 y 2, pero la manera en que el controlador proporciona punteros a sus devoluciones de llamada difiere. En UMDF 1, el controlador implementa métodos de devolución de llamada como miembros de interfaces proporcionadas por el controlador. El controlador registra estas interfaces con el marco cuando crea objetos de marco, por ejemplo llamando a IWDFDriver::CreateDevice.
En UMDF 2, el controlador proporciona punteros a las funciones de devolución de llamada proporcionadas por el controlador en estructuras de configuración como WDF_DRIVER_CONFIG y WDF_IO_QUEUE_CONFIG.
Administración de la duración del objeto
Los controladores que usan UMDF 1 deben implementar el recuento de referencias para determinar cuándo es seguro eliminar objetos. Dado que el marco realiza un seguimiento de las referencias de objeto en nombre del controlador, un controlador UMDF 2 no necesita contar referencias.
En UMDF 2, cada objeto de marco tiene un objeto primario predeterminado. Cuando se elimina un objeto primario, el marco elimina los objetos secundarios asociados. Cuando el controlador llama a un método de creación de objetos como WdfDeviceCreate, puede aceptar el elemento primario predeterminado o puede especificar un elemento primario personalizado en una estructura de WDF_OBJECT_ATTRIBUTES . Para obtener una lista de objetos de marco y sus objetos primarios predeterminados, vea Resumen de objetos de marco.
Inicialización del controlador
Un controlador UMDF 1 implementa la interfaz IDriverEntry . En su método de devolución de llamada IDriverEntry::OnDeviceAdd , el controlador normalmente:
- Crea e inicializa una instancia del objeto de devolución de llamada del dispositivo.
- Crea el nuevo objeto de dispositivo de marco llamando a IWDFDriver::CreateDevice.
- Configura las colas del dispositivo y sus objetos de devolución de llamada correspondientes.
- Crea una instancia de una clase de interfaz de dispositivo llamando a IWDFDevice::CreateDeviceInterface.
Un controlador UMDF 2 implementa DriverEntry y EvtDriverDeviceAdd. En su rutina DriverEntry , un controlador UMDF 2 suele llamar a WDF_DRIVER_CONFIG_INIT para inicializar la estructura de WDF_DRIVER_CONFIG del controlador. A continuación, pasa esta estructura a WdfDriverCreate.
En su función EvtDriverDeviceAdd , el controlador puede hacer algunas de las siguientes acciones:
- Rellene la estructura WDFDEVICE_INIT , que proporciona información que se usa para crear el objeto de dispositivo. Para obtener más información sobre el uso de WDFDEVICE_INIT, consulte Creación de un objeto de dispositivo framework.
- Configure el área de contexto del objeto de dispositivo. Para obtener información sobre la asignación y el acceso al espacio de contexto para objetos de marco, vea Espacio de contexto de objetos de marco.
- Cree el objeto de dispositivo.
- Especifique los controladores de solicitud para el objeto de dispositivo.
- Cree colas de E/S.
- Crear interfaces de dispositivo.
- Establezca la directiva de inactividad del dispositivo y la configuración de reactivación, si el objeto de dispositivo posee la directiva de energía.
- Cree objetos de interrupción, si el hardware admite interrupciones.
Instalación del controlador
Al crear un nuevo proyecto de controlador en Visual Studio, el nuevo proyecto contiene un archivo .inx. Al compilar el controlador, Visual Studio compila el archivo .inx en un archivo INF que se puede usar como parte de un paquete de controladores.
Aunque un archivo INF para un controlador UMDF 1 debe incluir un identificador de clase de controlador, no se requiere driverCLSID en un archivo INF para un controlador UMDF 2.
Además, aunque un controlador UMDF 1 debe hacer referencia al co-instalador en su archivo INF, no se requiere ninguna referencia de constador en un archivo INF de UMDF 2. Aunque una referencia de coinstaller puede aparecer en un archivo INF para un controlador UMDF 2, no es necesario.
Almacenamiento del contexto del dispositivo
En UMDF 1, el controlador normalmente almacena el contexto del dispositivo en un objeto de devolución de llamada creado por el controlador, por ejemplo, especificando miembros privados de la clase de objeto de devolución de llamada del dispositivo. Como alternativa, un controlador UMDF 1 puede llamar al método IWDFObject::AssignContext para registrar el contexto en un objeto de marco.
En UMDF 2, el marco asigna espacio de contexto basado en la estructura opcional WDF_OBJECT_ATTRIBUTES que proporciona el controlador cuando llama a un método de creación de objetos. Después de llamar al método create de un objeto, un controlador puede llamar a WdfObjectAllocateContext una o varias veces para asignar espacio de contexto adicional a un objeto específico. Para conocer los pasos que debe usar un controlador UMDF 2 para definir una estructura de contexto y un método de descriptor de acceso, consulte Espacio de contexto de objetos de marco.
Depuración del controlador
Para depurar un controlador UMDF 2, usará extensiones en Wdfkd.dll en lugar de Wudfext.dll. Para obtener más información sobre las extensiones en Wudfext.dll, vea Resumen de extensiones del depurador en Wdfkd.dll.
En UMDF 2, también puede obtener información adicional sobre la depuración de controladores a través de la grabadora de seguimiento en la luz (IFR), como se describe en Uso de la grabadora de seguimiento en KMDF y controladores UMDF 2. Además, puede usar la propia grabadora en curso (IFR) del marco. Consulte Uso del registrador de eventos de Framework.
Temas relacionados
Espacio de contexto del objeto framework
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de