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

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 minipuerto debe inicializar.

[in] MiniportDriverContext

Identificador de un área de contexto asignada por el controlador donde 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 minipuerto, 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 miniporte 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 estos 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 mediante una llamada a Función NdisMRegisterMiniportDriver de la rutina DriverEntry . NDIS puede llamar a MiniportInitializeEx después de que DriverEntry devuelva. Para obtener más información, consulte 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 suele llamar a NdisIMInitializeDeviceInstanceEx.

Los controladores pueden registrarse como un controlador de miniporte combinado y un controlador intermedio (consulte NdisMRegisterMiniportDriver). Este tipo de controlador intermedio de miniporte funciona de forma similar a un controlador intermedio superpuesta 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 el adaptador de miniporte que se inicializa. 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 proporcionar 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 minipuerto 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 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
  • grupos de estructuras de NET_BUFFER y 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 Funciones NdisAllocateNetBufferPool y guarde 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 Función NdisAllocateNetBufferAndNetBufferList . Un controlador también puede usar estructuras asignadas con NdisAllocateNetBuffer y Funciones NdisAllocateNetBufferList .

Si las funciones del controlador, que no sean la función MiniportInterrupt , compartan 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 de 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 Función NdisMSetMiniportAttributes 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 bus-master, MiniportInitializeEx debe llamar a Función NdisMRegisterScatterGatherDma después de llamar a NdisMSetMiniportAttributes y antes de llamar a Función NdisMAllocateSharedMemory . Si el dispositivo admite DMA subordinado, MiniportInitializeEx debe llamar a NdisMSetMiniportAttributes antes de llamar a . Función NdisMRegisterDmaChannel .

Después de que MiniportInitializeEx llame a 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 llame a NdisMRegisterInterruptEx y siga recibiendo interrupciones hasta su llamada a . 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 se devuelva 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 minipuerto en la función MiniportHaltEx .

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 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 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, 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

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

Consulte también

DriverEntry

MiniportCheckForHangEx

MiniportHaltEx

MiniportInterrupt

MiniportRestart

NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES

NDIS_MINIPORT_INIT_PARAMETERS

NET_BUFFER

NET_BUFFER_LIST

NdisAllocateNetBuffer

NdisAllocateNetBufferAndNetBufferList

NdisAllocateNetBufferList

NdisAllocateNetBufferListPool

NdisAllocateNetBufferPool

NdisAllocateSpinLock

NdisAllocateTimerObject

NdisMAllocateSharedMemory

NdisMDeregisterInterruptEx

NdisMGetBusData

NdisMIndicateReceiveNetBufferLists

NdisMMapIoSpace

NdisMRegisterDmaChannel

NdisMRegisterInterruptEx

NdisMRegisterIoPortRange

NdisMRegisterMiniportDriver

NdisMRegisterScatterGatherDma

NdisMSetMiniportAttributes

NdisMSleep

NdisMSynchronizeWithInterruptEx

NdisOpenConfigurationEx

NdisReadConfiguration

NdisSetTimerObject

NdisWaitEvent

NdisWriteErrorLogEntry

NetTimerCallback

ProtocolBindAdapterEx