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

Artículo
02/07/2025

La función MiniportPnpIrp permite que un controlador de miniporte administre opcionalmente sus recursos Plug and Play (PnP). miniportPnpIrp nunca se define directamente mediante controladores de miniport. 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 MiniportFilterResourceResourceRequirements.

Nota Debe declarar esta función mediante el tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS o el tipo de 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 miniporte controló correctamente la solicitud de inicio del dispositivo.
NDIS_STATUS_RESOURCES	El controlador de miniport no pudo controlar la solicitud del dispositivo de inicio debido a recursos bajos.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements falló por motivos distintos de recursos insuficientes.

Observaciones

Comentarios de MiniportFilterResourceRequirements

La función MiniportFilterResourceRequirements es una función opcional. Los controladores de miniport deben registrar esta función si admiten MSI-X y al menos se cumple una de las siguientes opciones:

El controlador requiere la capacidad de cambiar la afinidad de interrupción para cada mensaje MSI-X.
El controlador se registrará para 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 una 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 de dispositivos hayan completado el procesamiento del IRP.

El controlador de 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 miniport puede establecer una directiva de afinidad para cada recurso de tipo CmResourceTypeInterrupt que describe un mensaje de 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 de KAFFINITY en el miembro Interrupt.TargetedProcessors en la estructura de 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 miniporte 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 de MSI-X a una CPU en tiempo de ejecución, el controlador de miniport puede llamar a función NdisMConfigMSIXTableEntry.

Un controlador de miniport 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ínea 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ínea en MiniportInitializeEx.

Para asignar memoria para una nueva lista de requisitos de recursos, use función NdisAllocateMemoryWithTagPriority. El controlador de miniport puede liberar la memoria de la lista de requisitos de recursos antiguos con la función de 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 CmResourceTypeMemory y recursos de CmResourceTypePort. Los controladores de 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 miniporte devuelve NDIS_STATUS_RESOURCES o NDIS_STATUS_FAILURE de MiniportFilterResourceRequirements, NDIS usará los requisitos de recursos especificados por el controlador de bus 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 de

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 análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir un MiniportFilterResourceRequirements función denominada "MyFilterResourceRequirements", use el tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS tal 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 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, vea Anotación del comportamiento de la función.

Comentarios de MiniportStartDevice

miniportStartDevice es una función opcional. Los controladores de miniporte que admiten MSI-X pueden especificar un punto de entrada para esta función en . 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 miniporta agrega nuevos recursos en función miniportFilterResourceRequirements, debe proporcionar una función MiniportStartDevice para quitar los recursos.

Si un controlador de miniporte modifica los recursos de tal forma que un controlador de bus subyacente no pueda reconocer los recursos, el controlador debe proporcionar una función MiniportStartDevice para quitar los recursos. Es posible que un controlador de bus subyacente produzca un error en una solicitud de dispositivo de inicio 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 del dispositivo de inicio 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 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 análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir un miniportStartDevice función denominada "MyStartDevice", use el tipo MINIPORT_START_DEVICE tal 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 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, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Se admite en NDIS 6.0 y versiones posteriores.
de la plataforma de destino de	Windows
encabezado de	ndis.h (incluya Ndis.h)
irQL	PASSIVE_LEVEL