MINIPORT_RESET función de devolución de llamada (ndis.h)

Artículo
08/07/2023

Advertencia

Las funciones de devolución de llamada MiniportResetEx y MiniportCheckForHangEx no son recomendables para todos los controladores NDIS 6.83 y versiones posteriores. Para obtener más información, vea Operaciones de comprobación de bloqueo y restablecimiento en NDIS 6.83 y versiones posteriores.

NDIS llama a la función MiniportEx del controlador NDIS para iniciar un restablecimiento de una tarjeta de interfaz de red (NIC). Para obtener más información, vea Miniport Adapter Check-for-Hang and Reset Operations and Miniport Driver Hardware Reset.

Nota Un controlador de miniporte NDIS puede declarar esta función mediante el tipo MINIPORT_RESET .

Sintaxis

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

Parámetros

[in] MiniportAdapterContext

Identificador de un área de contexto que el controlador de minipuerto asignó en su función MiniportInitializeEx . El controlador de minipuerto usa este área de contexto para mantener la información de estado de un adaptador de minipuerto.

[out] AddressingReset

Puntero a una variable booleana. El controlador de minipuerto establece esta variable en TRUE si NDIS debe llamar a la función MiniportOidRequest para restaurar el direccionamiento y otras opciones de configuración a los valores actuales. Para obtener más información, vea Restablecimiento de hardware.

Valor devuelto

MiniportResetEx puede devolver uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	MiniportResetEx restablece correctamente el adaptador de miniporte a un estado operativo.
NDIS_STATUS_PENDING	El controlador completará la operación de restablecimiento de forma asincrónica llamando a la función NdisMResetComplete cuando se realice la operación.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx determinó que el adaptador de miniporte se estaba restableciendo actualmente, por lo que esta llamada es superflua.
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx restableció correctamente el adaptador de miniport, pero se produjo un error recuperable durante la operación. MiniportResetEx debe haber llamado a la función NdisWriteErrorLogEntry con más información sobre el error.
NDIS_STATUS_HARD_ERRORS	MiniportResetEx intentó restablecer el adaptador de miniport, pero se produjo un error irrecuperable durante la operación. MiniportResetEx debe haber llamado a NdisWriteErrorLogEntry con más información sobre el error.

Comentarios

Un controlador especifica el punto de entrada MiniportResetEx cuando llama a . Función NdisMRegisterMiniportDriver .

MiniportResetEx no es necesario para controladores intermedios.

MiniportResetEx puede restablecer los parámetros del adaptador de miniport. Si un restablecimiento provoca un cambio en la dirección de la estación del adaptador de miniporte, el controlador de minipuerto restaura automáticamente el valor anterior de la dirección de la estación una vez completado el restablecimiento. Las máscaras de direccionamiento multidifusión o funcional, restablecidas por el hardware, no tienen que restablecerse en esta función.

Si una operación de restablecimiento cambia otra información, como la información de direccionamiento multidifusión o funcional, MiniportResetEx debe establecer la variable en AddressingReset en TRUE antes de que se devuelva. Esto hace que NDIS llame a la función MiniportOidRequest para restaurar la información. NDIS también restaura la lista de patrones Wake on the LAN (WoL) llamando a OID_PNP_ADD_WAKE_UP_PATTERN. El controlador debe liberar la lista de patrones woL de su contexto de adaptador porque la lista de hardware ya se ha restablecido.

NDIS no anulará ninguna solicitud de OID pendiente ni enviará solicitudes. Si el controlador puede completar de forma segura OID pendiente o enviar solicitudes después de un restablecimiento, el controlador puede contener OID pendiente o enviar solicitudes hasta una vez completada la operación de restablecimiento. De lo contrario, el controlador debe completar el OID pendiente o enviar solicitudes mediante una llamada a NdisMOidRequestComplete o Funciones NdisMSendNetBufferListsComplete respectivamente antes de que miniportResetEx devuelva.

Nota A partir de NDIS 6.30, el controlador de miniporte no debe contener OID pendiente ni enviar solicitudes hasta que se complete la operación de restablecimiento. En su lugar, el controlador debe completar estas solicitudes pendientes llamando a las funciones NdisMOidRequestComplete o NdisMSendNetBufferListsComplete respectivamente antes de que se complete la operación de restablecimiento. Si el controlador completa la operación de restablecimiento de forma asincrónica, debe completar el OID pendiente y enviar solicitudes antes de que el controlador llame a NdisMResetComplete.

Un controlador de minipuerto no debe llamar a la función NdisMIndicateStatusEx para indicar el inicio y el fin de cada operación de restablecimiento. NDIS notifica a los controladores de protocolo enlazados cuando comienza y finaliza un restablecimiento.

Si MiniportResetEx debe esperar cambios de estado en el adaptador de minipuerto durante las operaciones de restablecimiento, puede llamar a la función NdisStallExecution . Sin embargo, un
La función MiniportResetEx no debe llamar a NdisStallExecution con un intervalo de tiempo mayor que 50 microsegundos. Si el controlador debe esperar más de 50 microsegundos (o si sondea), debe establecer un temporizador en su lugar y devolver NDIS_STATUS_PENDING.

Si MiniportResetEx devuelve NDIS_STATUS_PENDING, el controlador debe completar el restablecimiento llamando a la función NdisMResetComplete .

Si un adaptador de minipuerto está en el estado MediaConnectStateConnected y su estado cambia debido a un restablecimiento, incluido un cambio en el estado MediaConnectStateUnknown , el controlador de miniport debe notificar el cambio de estado con una indicación de estado de NDIS_STATUS_LINK_STATE . El controlador de minipuerto también debe indicar una indicación de estado MediaConnectStateConnected cuando se restablece el vínculo después del restablecimiento.

MiniportResetEx puede ser reemplazado por una interrupción.

NDIS llama periódicamente a la función MiniportCheckForHangEx para determinar si debe llamar a MiniportResetEx. El tiempo de espera predeterminado para llamar a MiniportCheckForHangEx es de 2 segundos. Si este valor predeterminado es demasiado corto, un controlador de minipuerto puede establecer un valor CheckForHangTimeInSeconds mayor al llamar a .
Función NdisMSetMiniportAttributes durante la inicialización. Para obtener más información, vea Miniport Adapter Check-for-Hang and Reset Operations.

NDIS no puede determinar si una NIC ha dejado de responder para las operaciones de recepción. Para controlar este tipo de error, la función MiniportCheckForHangEx puede supervisar las operaciones de recepción y, si es necesario, devolver TRUE para forzar un restablecimiento. Un miniport también puede solicitar un restablecimiento llamando a NdisMResetMiniport.

NDIS llama a MiniportResetEx en IRQL <= DISPATCH_LEVEL.

Ejemplos

Para definir una función MiniportResetEx , primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función MiniportResetEx denominada "MyResetEx", use el tipo de MINIPORT_RESET como se muestra en este ejemplo de código:

MINIPORT_RESET MyResetEx;

A continuación, implemente la función de la siguiente manera:

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

El tipo de función MINIPORT_RESET se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función MINIPORT_RESET en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante el uso de tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL