MINIPORT_INITIALIZE função de retorno de chamada (ndis.h)

Artigo
09/02/2023

O NDIS chama a função MiniportInitializeEx de um driver de miniport para inicializar um adaptador de miniporta para operações de E/S de rede.

Nota Você deve declarar a função usando o tipo MINIPORT_INITIALIZE . Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

MINIPORT_INITIALIZE MiniportInitialize;

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

Parâmetros

[in] NdisMiniportHandle

Um identificador fornecido pelo NDIS que identifica o adaptador de miniporta que o driver de miniporto deve inicializar.

[in] MiniportDriverContext

Um identificador para uma área de contexto alocada por driver em que o driver mantém informações de estado e configuração. O driver de miniporta passou essa área de contexto para o Função NdisMRegisterMiniportDriver .

[in] MiniportInitParameters

Um ponteiro para um NDIS_MINIPORT_INIT_PARAMETERS estrutura que define os parâmetros de inicialização para o adaptador de miniport.

Retornar valor

MiniportInitializeEx pode retornar um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	MiniportInitializeEx configurou e configurou o adaptador de miniporte e alocou todos os recursos que o driver deve ter para executar operações de E/S de rede.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx não pôde obter o adaptador miniport para aceitar os parâmetros de configuração que MiniportInitializeEx obteve do registro.
NDIS_STATUS_RESOURCES	MiniportInitializeEx não pôde alocar recursos para executar operações de E/S de rede. MiniportInitializeEx deve chamar a função NdisWriteErrorLogEntry para identificar o conflito de recursos (por exemplo, intervalo de portas de E/S, vetor de interrupção, intervalo de memória do dispositivo, conforme apropriado). Fornecer um registro de log de erros fornece ao usuário ou ao administrador do sistema informações que podem ser usadas para reconfigurar o computador para evitar esses conflitos de recursos de hardware.
NDIS_STATUS_FAILURE	O MiniportInitializeEx falhou por motivos diferentes daqueles da lista anterior. O driver deve chamar NdisWriteErrorLogEntry com parâmetros que especificam o motivo da falha.

Comentários

O NDIS chama MiniportInitializeEx como parte de uma operação PnP do sistema. Os drivers especificam o ponto de entrada MiniportInitializeEx chamando o Função NdisMRegisterMiniportDriver da rotina DriverEntry . O NDIS pode chamar MiniportInitializeEx depois que DriverEntry retornar. Para obter mais informações, consulte DriverEntry of NDIS Miniport Drivers.

Para drivers intermediários do NDIS, o NDIS pode chamar MiniportInitializeEx no contexto do Função NdisIMInitializeDeviceInstanceEx ou depois de retornar. Essa função ProtocolBindAdapterEx de um driver geralmente chama NdisIMInitializeDeviceInstanceEx.

Os drivers podem se registrar como um driver de miniporto combinado e um driver intermediário (consulte NdisMRegisterMiniportDriver). Esse driver miniport-intermediário funciona de forma semelhante a um driver intermediário em camadas sobre um driver de miniporto físico. Para cada instância de dispositivo virtual ou físico de um driver miniport-intermediário, se a chave do Registro IMMiniport estiver definida como DWORD:0x0000001, o NDIS chamará a função MiniportInitializeEx que o driver registrou para o dispositivo virtual. Caso contrário, o NDIS chamará a função MiniportInitializeEx do driver que o driver registrou para o dispositivo físico.

Até que MiniportInitializeEx retorne, o NDIS não envia nenhuma solicitação para o adaptador de miniporto que está sendo inicializado. O adaptador de miniporta está no estado de inicialização .

Para obter informações de configuração para o adaptador de miniporto, um driver chama as funções NdisOpenConfigurationEx e NdisReadConfiguration . O driver pode chamar a função NdisMGetBusData para obter informações específicas do barramento.

Os drivers de miniporto devem chamar o Função NdisMSetMiniportAttributes e fornece um NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES estrutura que contém os seguintes atributos:

Um identificador para uma área de contexto alocada por driver.
Sinalizadores de atributos apropriados.
O intervalo de tempo limite para chamar seu Função MiniportCheckForHangEx .
O tipo de interface.

O driver de miniporta passa um identificador NdisMSetMiniportAttributes no membro MiniportAdapterContext do NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. O driver mantém informações de estado para o adaptador de miniporto especificado nessa área de contexto. O NDIS passa esse identificador como um parâmetro de entrada para outras funções MiniportXxx .

Os drivers de miniport devem definir os atributos no NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES estrutura depois de definir os atributos de registro na estrutura NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES e antes de definirem atributos adicionais.

MiniportInitializeEx também pode alocar recursos como o seguinte:

Memória do pool não paginado
pools de estrutura NET_BUFFER e NET_BUFFER_LIST
Bloqueios de rotação
Temporizadores
Portas de E/S
DMA
Memória compartilhada
Interrupções

Se o driver indicar que recebe com o Função NdisMIndicateReceiveNetBufferLists , a função MiniportInitializeEx deve chamar o NdisAllocateNetBufferListPool e NdisAllocateNetBufferPool funções e salvar os identificadores retornados por essas funções NDIS. Normalmente, os dados de rede que o driver indica posteriormente com NdisMIndicateReceiveNetBufferLists referenciam estruturas que foram alocadas com o Função NdisAllocateNetBufferAndNetBufferList . Um driver também pode usar estruturas que foram alocadas com o NdisAllocateNetBuffer e Funções NdisAllocateNetBufferList .

Se as funções de driver, além da função MiniportInterrupt , compartilharem recursos, MiniportInitializeEx deverá chamar a função NdisAllocateSpinLock para configurar os bloqueios de rotação necessários para sincronizar o acesso a esses recursos compartilhados. Os recursos que outras funções de driver compartilham com MiniportInterrupt, como registros NIC, são protegidos pelo objeto de interrupção que o driver configurou com o Função NdisMRegisterInterruptEx . As funções de driver acessam esses recursos chamando o Função NdisMSynchronizeWithInterruptEx .

MiniportInitializeEx pode chamar a função NdisAllocateTimerObject com uma função NetTimerCallback fornecida pelo driver e um ponteiro para a memória alocada pelo driver para um objeto de temporizador. Os drivers podem configurar várias funções NetTimerCallback , cada uma com seu próprio objeto de temporizador. Um driver pode chamar a função NdisSetTimerObject para habilitar uma função NetTimerCallback periódica. Um driver também pode chamar a função NdisSetTimerObject para habilitar uma função NetTimerCallback única.

MiniportInitializeEx deve chamar o A função NdisMSetMiniportAttributes antes de chamar qualquer função NdisMXxx , como as funções NdisMRegisterIoPortRange ou NdisMMapIoSpace , que declara recursos de hardware para o adaptador de miniporto. MiniportInitializeEx deve chamar NdisMSetMiniportAttributes antes de tentar alocar recursos para operações de DMA.

Se o dispositivo der suporte ao DMA master de barramento, MiniportInitializeEx deverá chamar o Função NdisMRegisterScatterGatherDma depois de chamar NdisMSetMiniportAttributes e antes de chamar o Função NdisMAllocateSharedMemory . Se o dispositivo der suporte a DMA subordinado, MiniportInitializeEx deverá chamar NdisMSetMiniportAttributes antes de chamar o Função NdisMRegisterDmaChannel .

Depois que MiniportInitializeEx chamar o Função NdisMRegisterInterruptEx , o NDIS pode chamar a função MiniportInterrupt do driver. O NDIS chama MiniportInterrupt se a NIC gera uma interrupção ou se qualquer outro dispositivo com o qual a NIC compartilha uma interrupção gera uma interrupção. Observe que um driver de miniporto pode receber uma interrupção assim que chama NdisMRegisterInterruptEx e continua recebendo interrupções até sua chamada para oA função NdisMDeregisterInterruptEx retorna.

MiniportInitializeEx deve testar a NIC para garantir que o hardware esteja configurado corretamente. Se o driver precisar aguardar que as alterações de estado ocorram no hardware, MiniportInitializeEx poderá usar a função NdisWaitEvent ou a função NdisMSleep .

Depois que MiniportInitializeEx retornar com êxito, o adaptador de miniporto estará no estado Pausado . O NDIS pode chamar a função MiniportRestart para fazer a transição do adaptador de miniporto para o estado Em execução .

Se MiniportInitializeEx retornar NDIS_STATUS_SUCCESS, o driver deverá liberar todos os recursos para o adaptador de miniporte na função MiniportHaltEx .

O driver deve chamar NdisMSetMiniportAttributes e definir GeneralAttributes na estrutura NDIS_MINIPORT_ADAPTER_ATTRIBUTES se retornar NDIS_STATUS_SUCCESS.

Se MiniportInitializeEx falhou, MiniportInitializeEx deverá liberar todos os recursos alocados antes de retornar e o adaptador de miniporto retornar ao estado Parado .

O NDIS chama MiniportInitializeEx em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função MiniportInitializeEx , primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função MiniportInitializeEx chamada "MyInitializeEx", use o tipo MINIPORT_INITIALIZE conforme mostrado neste exemplo de código:

MINIPORT_INITIALIZE MyInitializeEx;

Em seguida, implemente sua função da seguinte maneira:

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

O tipo de função MINIPORT_INITIALIZE é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função MINIPORT_INITIALIZE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL