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

Artículo
08/07/2023

NDIS llama a la función MiniportInitializeEx del controlador de miniporte para inicializar un adaptador de minipuerto para las operaciones de E/S de red.

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

Sintaxis

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

Parámetros

[in] NdisMiniportHandle

Un controlador proporcionado por NDIS que identifica el adaptador de minipuerto que el controlador de miniporte debe inicializar.

[in] MiniportDriverContext

Identificador de un área de contexto asignada por el controlador en la que el controlador mantiene la información de estado y configuración. El controlador de minipuerto pasó este área de contexto al Función NdisMRegisterMiniportDriver .

[in] MiniportInitParameters

Puntero a un NDIS_MINIPORT_INIT_PARAMETERS estructura que define los parámetros de inicialización para el adaptador de minipuerto.

Valor devuelto

MiniportInitializeEx puede devolver uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	MiniportInitializeEx configurado y configurado el adaptador de miniporte, y asignó todos los recursos que el controlador debe tener para realizar operaciones de E/S de red.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx no pudo obtener el adaptador de miniportar para aceptar los parámetros de configuración que MiniportInitializeEx obtuvo del registro.
NDIS_STATUS_RESOURCES	MiniportInitializeEx no pudo asignar recursos para realizar operaciones de E/S de red. MiniportInitializeEx debe llamar a la función NdisWriteErrorLogEntry para identificar el conflicto de recursos (por ejemplo, intervalo de puertos de E/S, vector de interrupción, intervalo de memoria del dispositivo, según corresponda). Proporcionar un registro de errores proporciona a los usuarios o administradores del sistema información que se puede usar para volver a configurar el equipo para evitar conflictos de recursos de hardware.
NDIS_STATUS_FAILURE	Error de MiniportInitializeEx por motivos distintos de los de la lista anterior. El controlador debe llamar a NdisWriteErrorLogEntry con parámetros que especifiquen el motivo del error.

Comentarios

NDIS llama a MiniportInitializeEx como parte de una operación PnP del sistema. Los controladores especifican el punto de entrada MiniportInitializeEx llamando al Función NdisMRegisterMiniportDriver de la rutina DriverEntry . NDIS puede llamar a MiniportInitializeEx después de que DriverEntry devuelva. Para obtener más información, vea DriverEntry of NDIS Miniport Drivers.

En el caso de los controladores intermedios de NDIS, NDIS puede llamar a MiniportInitializeEx en el contexto de . Función NdisIMInitializeDeviceInstanceEx o después de que se devuelva. Esta función ProtocolBindAdapterEx del controlador normalmente llama a NdisIMInitializeDeviceInstanceEx.

Los controladores pueden registrarse como un controlador de minipuerto combinado y un controlador intermedio (consulte NdisMRegisterMiniportDriver). Este tipo de controlador intermedio de miniporte funciona de forma similar a un controlador intermedio en capas sobre un controlador de miniporte físico. Para cada instancia de dispositivo virtual o físico de un controlador intermedio de miniporte, si la clave del Registro IMMiniport está establecida en DWORD:0x0000001, NDIS llama a la función MiniportInitializeEx que el controlador registró para el dispositivo virtual. De lo contrario, NDIS llama a la función MiniportInitializeEx del controlador que el controlador registró para el dispositivo físico.

Hasta que se devuelva MiniportInitializeEx , NDIS no envía ninguna solicitud para que se inicialice el adaptador de miniporte. El adaptador de minipuerto está en estado de inicialización .

Para obtener información de configuración para el adaptador de minipuerto, un controlador llama a las funciones NdisOpenConfigurationEx y NdisReadConfiguration . El controlador puede llamar a la función NdisMGetBusData para obtener información específica del bus.

Los controladores de minipuerto deben llamar al Función NdisMSetMiniportAttributes y proporciona un NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES estructura que contiene los siguientes atributos:

Identificador de un área de contexto asignada por el controlador.
Marcas de atributos adecuadas.
Intervalo de tiempo de espera para llamar a su Función MiniportCheckForHangEx .
Tipo de la interfaz.

El controlador de minipuerto pasa NdisMSetMiniportAttributes un identificador en el miembro MiniportAdapterContext de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. El controlador mantiene información de estado para el adaptador de miniporte especificado en este área de contexto. NDIS pasa este identificador como parámetro de entrada a otras funciones MiniportXxx .

Los controladores de minipuerto deben establecer los atributos en NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES estructura después de establecer los atributos de registro en la estructura de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES y antes de establecer atributos adicionales.

MiniportInitializeEx también puede asignar recursos como los siguientes:

Memoria del grupo no paginado
NET_BUFFER y grupos de estructuras de NET_BUFFER_LIST
Bloqueos de número
Temporizadores
Puertos de E/S
DMA
Memoria compartida
Interrupciones

Si el controlador indica que recibe con el Función NdisMIndicateReceiveNetBufferLists , la función MiniportInitializeEx debe llamar a NdisAllocateNetBufferListPool y Las funciones NdisAllocateNetBufferPool y guardan los identificadores devueltos por estas funciones NDIS. Normalmente, los datos de red que el controlador indica posteriormente con NdisMIndicateReceiveNetBufferLists hacen referencia a estructuras asignadas con el Función NdisAllocateNetBufferAndNetBufferList . Un controlador también puede usar estructuras asignadas con NdisAllocateNetBuffer y Funciones NdisAllocateNetBufferList .

Si las funciones del controlador, aparte de la función MiniportInterrupt , comparten recursos, MiniportInitializeEx deben llamar a la función NdisAllocateSpinLock para configurar los bloqueos de número necesarios para sincronizar el acceso a dichos recursos compartidos. Los recursos que otras funciones de controlador comparten con MiniportInterrupt, como los registros NIC, están protegidos por el objeto de interrupción que el controlador configuró con el Función NdisMRegisterInterruptEx . Las funciones del controlador acceden a estos recursos mediante una llamada a Función NdisMSynchronizeWithInterruptEx .

MiniportInitializeEx puede llamar a la función NdisAllocateTimerObject con una función NetTimerCallback proporcionada por el controlador y un puntero a la memoria asignada por el controlador para un objeto de temporizador. Los controladores pueden configurar varias funciones NetTimerCallback , cada una con su propio objeto de temporizador. Un controlador puede llamar a la función NdisSetTimerObject para habilitar una función NetTimerCallback periódica. Un controlador también puede llamar a la función NdisSetTimerObject para habilitar una función NetTimerCallback única.

MiniportInitializeEx debe llamar a NdisMSetMiniportAttributes función antes de llamar a cualquier función NdisMXxx , como las funciones NdisMRegisterIoPortRange o NdisMMapIoSpace , que reclama recursos de hardware para el adaptador de miniport. MiniportInitializeEx debe llamar a NdisMSetMiniportAttributes antes de intentar asignar recursos para las operaciones DMA.

Si el dispositivo admite DMA de bus-master, MiniportInitializeEx debe llamar al Función NdisMRegisterScatterGatherDma después de llamar a NdisMSetMiniportAttributes y antes de llamar a la Función NdisMAllocateSharedMemory . Si el dispositivo admite DMA subordinado, MiniportInitializeEx debe llamar a NdisMSetMiniportAttributes antes de llamar al Función NdisMRegisterDmaChannel .

Después de que MiniportInitializeEx llame a La función NdisMRegisterInterruptEx , NDIS puede llamar a la función MiniportInterrupt del controlador. NDIS llama a MiniportInterrupt si la NIC genera una interrupción o si cualquier otro dispositivo con el que la NIC comparte una interrupción genera una interrupción. Tenga en cuenta que un controlador de minipuerto puede obtener una interrupción tan pronto como llama a NdisMRegisterInterruptEx y sigue recibiendo interrupciones hasta que su llamada a la Devuelve la función NdisMDeregisterInterruptEx .

MiniportInitializeEx debe probar la NIC para asegurarse de que el hardware está configurado correctamente. Si el controlador debe esperar a que se produzcan cambios de estado en el hardware, MiniportInitializeEx puede usar la función NdisWaitEvent o la función NdisMSleep .

Después de que MiniportInitializeEx vuelva correctamente, el adaptador de miniporte se encuentra en estado Pausado . NDIS puede llamar a la función MiniportRestart para realizar la transición del adaptador de miniporte al estado En ejecución .

Si MiniportInitializeEx devuelve NDIS_STATUS_SUCCESS, el controlador debe liberar todos los recursos del adaptador de miniport en la función MiniportHaltEx .

El controlador debe llamar a NdisMSetMiniportAttributes y establecer los GeneralAttributes en la estructura NDIS_MINIPORT_ADAPTER_ATTRIBUTES si devuelve NDIS_STATUS_SUCCESS.

Si se produjo un error en MiniportInitializeEx , MiniportInitializeEx debe liberar todos los recursos asignados antes de que devuelva y el adaptador de miniporte vuelva al estado Detenido .

NDIS llama a MiniportInitializeEx en IRQL = PASSIVE_LEVEL.

Ejemplos

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

MINIPORT_INITIALIZE MyInitializeEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

El tipo de función MINIPORT_INITIALIZE 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_INITIALIZE 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