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

Artículo
02/26/2024

La función MiniportPnpIrp permite que un controlador de miniporte administre opcionalmente sus recursos de Plug and Play (PnP). MiniportPnpIrp en sí mismo nunca está definido por los controladores de miniport directamente. En su lugar, se define como MiniportFilterResourceRequirements o MiniportStartDevice.

Si se define como MiniportFilterResourceRequirements, esta función permite que un controlador de miniporte modifique los requisitos de recursos de un dispositivo. Si se define como MiniportStartDevice, esta función permite al controlador de miniportar quitar los recursos que agregó en el Función MiniportFilterResourceRequirements .

Nota Debe declarar esta función mediante el tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS o el tipo MINIPORT_START_DEVICE . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

Parámetros

[in] MiniportAddDeviceContext

Identificador de un área de contexto asignada por el controlador que el controlador de miniporte registró con NDIS en la función MiniportAddDevice .

[in] Irp

Si esta función se define como MiniportFilterResourceRequirements, este parámetro es un puntero al IRP_MN_FILTER_RESOURCE_REQUIREMENTS para que el controlador lo controle.

Si esta función se define como MiniportStartDevice, este parámetro es un puntero a un irP de IRP_MN_START_DEVICE .

Valor devuelto

MiniportPnpIrp devuelve uno de los siguientes valores:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	El controlador de minipuerto controló correctamente la solicitud de inicio del dispositivo.
NDIS_STATUS_RESOURCES	El controlador de minipuerto no pudo controlar la solicitud de inicio del dispositivo debido a recursos bajos.
NDIS_STATUS_FAILURE	Error de MiniportFilterResourceRequirements por motivos distintos de recursos insuficientes.

Comentarios

Comentarios de MiniportFilterResourceRequirements

La función MiniportFilterResourceRequirements es una función opcional. Los controladores miniport deben registrar esta función si admiten MSI-X y al menos uno de los siguientes valores es true:

El controlador requiere la capacidad de cambiar la afinidad de interrupción para cada mensaje MSI-X.
El controlador se registrará para las interrupciones basadas en líneas en . Función MiniportInitializeEx .

Para registrar MiniportFilterResourceRequirements, especifique el punto de entrada en . NDIS_MINIPORT_PNP_CHARACTERISTICS estructura.

NDIS llama a la función MiniportFilterResourceRequirements después de que NDIS reciba un IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP para una tarjeta de interfaz de red (NIC). NDIS llama a MiniportFilterResourceRequirements después de que los controladores de función subyacentes de la pila del dispositivo hayan completado el procesamiento del IRP.

El controlador miniport debe estar preparado para controlar IRP_MN_FILTER_RESOURCE_REQUIREMENTS desde MiniportFilterResourceRequirements inmediatamente después de que la función MiniportAddDevice devuelva NDIS_STATUS_SUCCESS.

Un controlador de minipuerto puede establecer una directiva de afinidad para cada recurso de tipo CmResourceTypeInterrupt que describe un mensaje MSI-X. Si una directiva de afinidad solicita el destino de un conjunto específico de procesadores, el controlador de miniporte también establece una máscara KAFFINITY en el miembro Interrupt.TargetedProcessors de la estructura IO_RESOURCE_DESCRIPTOR .

Si un controlador de miniporte NDIS 6.1 o posterior requiere más recursos de interrupción de mensajes, puede agregar más recursos de interrupción de mensajes a la lista de recursos. Si el sistema operativo puede proporcionar más recursos de interrupción de mensajes, el adaptador de minipuerto recibe los recursos de interrupción de mensajes agregados cuando se inicia.

A cada recurso de interrupción de mensaje de la lista se le asigna un número de mensaje que corresponde al orden que tiene en la lista de recursos. Los mensajes se numeran entre 0 y el número total de recursos de interrupción de mensajes menos uno.

Para asignar una entrada de tabla MSI-X a una CPU en tiempo de ejecución, el controlador de minipuerto puede llamar al Función NdisMConfigMSIXTableEntry .

Un controlador de minipuerto puede quitar todos los recursos de tipo CmResourceTypeInterrupt que son recursos de interrupción de mensajes. A continuación, el controlador puede registrarse para interrupciones basadas en líneas en la función MiniportInitializeEx . Si el controlador de miniporte no quita estos recursos de interrupción de mensajes, se producirá un error en el sistema operativo si el controlador intenta registrar la interrupción basada en líneas en MiniportInitializeEx.

Para asignar memoria para una nueva lista de requisitos de recursos, use Función NdisAllocateMemoryWithTagPriority . El controlador de minipuerto puede liberar la memoria de la lista de requisitos de recursos antiguos con la función NdisFreeMemory . El administrador de PnP libera cualquier memoria asignada por el controlador una vez completado el IRP asociado.

Los controladores de miniport no deben modificar otros recursos, como los recursos CmResourceTypeMemory y CmResourceTypePort . Los controladores miniport deben evitar agregar un nuevo recurso a la lista de recursos. Sin embargo, los controladores de minipuerto pueden agregar más recursos de interrupción de mensajes. Si el controlador de miniporte agrega más recursos de interrupción de mensajes, el controlador no debe quitarlos de la función MiniportStartDevice .

Si un controlador de minipuerto devuelve NDIS_STATUS_RESOURCES o NDIS_STATUS_FAILURE desde MiniportFilterResourceRequirements, NDIS usará los requisitos de recursos especificados por el controlador de autobús primario.

NDIS puede llamar a MiniportFilterResourceRequirements varias veces antes de que NDIS llame a la función MiniportRemoveDevice . Pero NDIS llama a MiniportFilterResourceRequirements solo cuando un dispositivo está en estado detenido.

NDIS llama a MiniportFilterResourceRequirements en IRQL = PASSIVE_LEVEL.

Ejemplo de MiniportFilterResourceRequirements

Para definir una función MiniportFilterResourceRequirements , 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 MiniportFilterResourceRequirements denominada "MyFilterResourceRequirements", use el tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS como se muestra en este ejemplo de código:

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

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

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

El tipo de función MINIPORT_FILTER_RESOURCE_REQUIREMENTS 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_FILTER_RESOURCE_REQUIREMENTS en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante 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.

Comentarios de MiniportStartDevice

MiniportStartDevice es una función opcional. Los controladores miniport que admiten MSI-X pueden especificar un punto de entrada para esta función en el NDIS_MINIPORT_PNP_CHARACTERISTICS estructura. Cuando NDIS recibe una solicitud del administrador de Plug and Play (PnP) para iniciar un dispositivo, NDIS llama a la función MiniportStartDevice, si existe. Si un controlador de minipuerto agrega nuevos recursos en el La función MiniportFilterResourceRequirements debe proporcionar una función MiniportStartDevice para quitar los recursos.

Si un controlador de minipuerto modifica los recursos de forma que un controlador de bus subyacente no pueda reconocer los recursos, el controlador debe proporcionar una función MiniportStartDevice para quitar los recursos. Un controlador de bus subyacente podría producir un error en una solicitud de inicio del dispositivo si no reconoce recursos que un controlador de miniporte agregado en MiniportFilterResourceRequirements. Si el controlador de miniporte agrega recursos de interrupción de mensajes, no debe quitarlos de MiniportStartDevice.

NDIS llama a MiniportStartDevice antes de reenviar la solicitud de inicio del dispositivo a los controladores subyacentes. Si un controlador subyacente completa correctamente la solicitud, NDIS llama a la función MiniportInitializeEx para inicializar el adaptador de miniport.

NDIS llama a MiniportStartDevice en IRQL = PASSIVE_LEVEL.

Ejemplo de MiniportStartDevice

Para definir una función MiniportStartDevice , primero debe proporcionar una declaración de función que identifique el tipo de función que está definiendo. 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 MiniportStartDevice denominada "MyStartDevice", use el tipo de MINIPORT_START_DEVICE como se muestra en este ejemplo de código:

MINIPORT_START_DEVICE MyStartDevice;

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

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

El tipo de función MINIPORT_START_DEVICE 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_START_DEVICE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante 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	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL