Portabilidad de controladores de miniport de NDIS a NetAdapterCx
En esta página se describe cómo convertir un controlador de miniport de NDIS 6.x en un controlador cliente netAdapterCx.
Para obtener información general sobre WDF, revise la Guía de desarrollo de controladores de WDF.
Configuración de la compilación
Abra el proyecto de controlador de miniporte NDIS existente en Visual Studio y siga estos pasos para convertirlo en un proyecto de KMDF.
En primer lugar, vaya a Propiedades de configuración-Controlador> Configuración-Driver Model (Modelo de controlador)> y compruebe que Type of driver (Tipo de controlador) está establecido en KMDF y que KMDF Version Major (Versión principal de KMDF) y KMDF Version Minor (Versión secundaria de KMDF) están vacíos.
En las propiedades del proyecto, abra Controlador Configuración-Controlador> adaptador de red y establezca Vínculo a la extensión de clase adaptador de red en Sí.
- Si el controlador convertido seguirá llamando a las API de NDIS, continúe vinculando con
ndis.lib.
- Si el controlador convertido seguirá llamando a las API de NDIS, continúe vinculando con
Quite macros de preprocesador NDIS, como
NDIS650_MINIPORT=1.Agregue los siguientes encabezados a cada archivo de origen (o al encabezado común o precompilado):
#include <ntddk.h> #include <wdf.h> #include <netadaptercx.h>Agregue decoraciones WDF estándar a su INF:
[Yourdriver.Wdf] KmdfService = Yourdriverservice, Yourdriver.wdfsect [Yourdriver.wdfsect] KmdfLibraryVersion = <insert here>Agregue nuevas palabras clave de red necesarias a la sección NT de su INF:
*If Conectar orPresent
*Conectar ionType
*DirectionType
*AccessType
*HardwareLoopback
Para obtener más información sobre estas palabras clave y un ejemplo, vea Archivos INF para controladores de cliente netAdapterCx.
Inicialización del controlador
Quite la llamada a NdisMRegisterMiniportDriver de DriverEntry y agregue lo siguiente:
WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
status = WdfDriverCreate(. . . );
if (!NT_SUCCESS(status)) {
return status;
}
Si se establece, quite la marca WdfDriverInitNoDispatchOverride de la llamada a WdfDriverCreate.
DriverUnload es una rutina opcional para un controlador de cliente de red WDF, por lo que puede quitarlo si lo desea. No llame a NdisMDeregisterMiniportDriver desde DriverUnload.
Inicialización del dispositivo
A continuación, distribuirá el código de MiniportInitializeEx en los controladores de devolución de llamada de eventos WDF adecuados, varios de los cuales son opcionales. Para obtener más información sobre la secuencia de devolución de llamada, consulte Secuencia de encendido para un controlador de cliente WDF del adaptador de red.
Llamará a los métodos equivalentes a NdisMSetMiniportAttributes cuando inicie el adaptador net, pero antes de llamar a NetAdapterStart. Sin embargo, en lugar de llamar a una rutina con una estructura de NDIS_MINIPORT_ADAPTER_ATTRIBUTES genérica, el controlador cliente llama a diferentes funciones para establecer diferentes tipos de funcionalidades.
Para obtener información sobre las devoluciones de llamada, deberá proporcionar y cuándo iniciar un adaptador net, consulta Inicialización de dispositivos y adaptadores.
Lectura de la configuración del Registro
A continuación, reemplace las llamadas a NdisOpenConfigurationEx y las funciones relacionadas por los NetConfiguration* métodos . Los NetConfiguration* métodos son similares a las Ndis*Configuration* funciones y no es necesario reestructurar el código.
Para obtener más información, consulte Acceso a la información de configuración.
Recepción de códigos de control de E/S (IOCTL) desde el modo de usuario
Lea esta sección si el controlador NDIS llama a NdisRegisterDeviceEx, una rutina que se usa para crear un objeto de dispositivo de control (CDO) para recibir ioCTLs del modo de usuario.
Estas son dos maneras de hacerlo en el controlador cliente de red de WDF.
El puerto más sencillo es crear un objeto de dispositivo de control llamando a WdfControlDeviceInitAllocate desde la devolución de llamada de EVT_WDF_DRIVER_DEVICE_ADD del cliente. Para obtener más información, consulta Usar objetos de dispositivo de control.
Sin embargo, la solución recomendada es crear una interfaz de dispositivo, como se describe en Uso de interfaces de dispositivo.
Finalización de la inicialización del dispositivo
En este punto de EVT_WDF_DRIVER_DEVICE_ADD, puedes hacer cualquier otra cosa que quieras inicializar el dispositivo, como asignar interrupciones.
Control de las notificaciones de cambio de estado de energía
Un controlador cliente WDF no recibe OID_PNP_SET_POWER para los cambios de estado de energía.
En su lugar, un cliente WDF registra funciones de devolución de llamada opcionales para recibir notificaciones de cambio de estado de energía. Para obtener información general, consulte Compatibilidad con PnP y administración de energía en controladores de funciones.
Normalmente, el código del controlador de OID_PNP_SET_POWER se mueve a EVT_WDF_DEVICE_D0_EXIT y EVT_WDF_DEVICE_D0_ENTRY.
Dado que la máquina de estado de energía de WDF es ligeramente diferente, es posible que tenga que realizar modificaciones menores en el código.
En concreto, en su función de devolución de llamada MiniportInitializeEx , un controlador de miniporte NDIS realiza tareas de inicialización única, así como trabajo para llevar el dispositivo al estado D0. A continuación, repite el trabajo para ir a D0 en su controlador de OID_PNP_SET_POWER .
Por el contrario, un cliente WDF realiza tareas de inicialización única en devoluciones de llamada de eventos antes de EVT_WDF_DEVICE_D0_ENTRY, durante el cual el dispositivo está en un estado de bajo consumo. A continuación, realiza el trabajo para ir a D0 en EVT_WDF_DEVICE_D0_ENTRY.
En resumen, en WDF, coloque el código "ir a D0" en un solo lugar, en lugar de dos.
Para obtener más información sobre la secuencia de devolución de llamada, consulte Secuencia de encendido para un controlador de cliente netAdapterCx.
Consulta y configuración de funcionalidades de administración de energía
Del mismo modo, un controlador cliente WDF no recibe OID_PM_PARAMETERS para consultar ni establecer funcionalidades de hardware de administración de energía del adaptador de red.
En su lugar, el controlador consulta la configuración de wake-on-LAN (WoL) necesaria desde el objeto NETPOWERSETTINGS. Para obtener más información, consulte Configuración de la administración de energía.
Las marcas reales que se devuelven tienen la misma semántica que para un miniporte NDIS 6, por lo que no es necesario realizar cambios profundos en la lógica. La principal diferencia es que ahora puede consultar estas marcas durante la secuencia de apagado. Consulte Secuencia de apagado para obtener un controlador de cliente netAdapterCx.
Una vez que haya movido este código, puede eliminar los controladores de OID para OID_PNP_SET_POWER y OID_PM_PARAMETERS.
Dado que el marco netAdapter mantiene el dispositivo en D0 mientras el host usa la interfaz de red, el cliente normalmente no implementa lógica de energía; El comportamiento predeterminado de energía de NetAdapter es suficiente.
Ruta de acceso a datos
El modelo de programación de rutas de acceso de datos ha cambiado significativamente. Estas son algunas diferencias clave:
- En el modelo netAdapter, el tráfico de red ya no es por adaptador, como en NDIS, sino por cola de WDF. Consulte Creación de colas de E/S.
- En lugar de NET_BUFFER_LIST y grupos de NET_BUFFER, NetAdapterCx introduce un búfer de anillo compuesto por paquetes netos, que se asignan a NDIS de la siguiente manera:
- Un NET_PACKET es similar a un NET_BUFFER_LIST + NET_BUFFER.
- Un NET_PACKET_FRAGMENT es similar a una lista de descriptores de memoria (MDL). Cada NET_PACKET tiene uno o varios de estos.
- Para obtener más información sobre las estructuras de reemplazo y cómo usarlas, consulte Descriptores y extensiones de paquetes.
- En NDIS 6.x, el miniport debe controlar la semántica de inicio y pausa. En el modelo NetAdapterCx, este ya no es el caso.
- La devolución de llamada EVT_RXQUEUE_ADVANCE es similar a MINIPORT_RETURN_NET_BUFFER_LISTS en NDIS 6.x.
- La devolución de llamada EVT_TXQUEUE_ADVANCE es similar a MINIPORT_SEND_NET_BUFFER_LISTS en NDIS 6.x.
Eliminación del dispositivo
La eliminación de dispositivos para un controlador NIC de WDF es la misma que en cualquier otro controlador de dispositivo WDF, sin necesidad de procesamiento específico de red. La ruta de acceso de datos de red se cierra primero, seguida del dispositivo WDF. Para obtener información sobre el apagado de WDF, consulta Unplugs a User Unplugs a Device(Unplugs a Device).
Es probable que el controlador MiniportHaltEx se distribuya entre EVT_WDF_DEVICE_D0_EXIT y EVT_WDF_DEVICE_RELEASE_HARDWARE.
El cliente WDF no necesita eliminar NetAdapter ni ninguna de las colas de ruta de datos que creó. WDF elimina estos objetos automáticamente.
Puede eliminar MiniportShutdownEx, MiniportResetEx y MiniportCheckForHangEx. Estas devoluciones de llamada ya no se admiten.
Equivalentes de función NDIS-WDF
La mayoría NdisXxx de las funciones se pueden reemplazar por un equivalente de WDF. En general, debería encontrar que necesita muy poca funcionalidad que se importa desde NDIS.SYS.
Para obtener una lista de equivalentes de función, consulte equivalentes de función NDIS-WDF.
Depuración
Consulte Depuración de un controlador de cliente netAdapterCx.
La extensión del depurador !ndiskd.netadapter muestra resultados similares a los que muestra !ndiskd.miniport para un controlador NDIS 6.
Conclusión
Siguiendo los pasos descritos en este tema, debe tener un controlador de trabajo que inicie y detenga el dispositivo.
Nota: NetAdapterCx no admite actualmente el arranque iSCSI.