MINIPORT_INITIALIZE função de retorno de chamada (ndis.h)
O NDIS chama a função MiniportInitializeEx de um driver de miniport para inicializar um adaptador de miniporto para operações de E/S de rede.
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 miniporto que o driver de miniporto deve inicializar.
[in] MiniportDriverContext
Um identificador para uma área de contexto alocada pelo driver em que o driver mantém informações de estado e configuração. O driver de miniporto 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 miniporto.
Valor de retorno
MiniportInitializeEx pode retornar um dos seguintes valores de status:
| Código de retorno | Descrição |
|---|---|
|
MiniportInitializeEx configurado e configurado o adaptador de miniporto e alocado todos os recursos que o driver deve ter para executar operações de E/S de rede. |
|
MiniportInitializeEx não conseguiu que o adaptador de miniporto aceitasse os parâmetros de configuração que MiniportInitializeEx obtidos do registro. |
|
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 conflitos de recursos de hardware. |
|
MiniportInitializeEx falhou por motivos diferentes daqueles da lista anterior. O driver deve chamar NdisWriteErrorLogEntry com parâmetros que especificam o motivo da falha. |
Observações
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 de DriverEntry. O NDIS pode chamar MiniportInitializeEx depois que DriverEntry retorna. 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 de 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 intermediário de miniporto, 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é MiniportInitializeEx retornar, o NDIS não enviará nenhuma solicitação para o adaptador de miniporto que está sendo inicializado. O adaptador de miniporto está no estado inicializando.
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 fornecer um NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES estrutura que contém os seguintes atributos:
- Um identificador para uma área de contexto alocada pelo driver.
- Sinalizadores de atributos apropriados.
- O intervalo de tempo limite para chamar seu função de MiniportCheckForHangEx.
- O tipo de interface.
Os drivers de miniporto devem definir os atributos no NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES estrutura depois de definirem os atributos de registro na estrutura NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES e antes de definirem quaisquer atributos adicionais.
MiniportInitializeEx também pode alocar recursos como o seguinte:
- Memória do pool sem páginas
-
pools de estrutura NET_BUFFER e NET_BUFFER_LIST
- Bloqueios de rotação
- Temporizadores
- Portas de E/S
- DMA
- Memória compartilhada
- Interrompe
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 de NetTimerCallback única vez.
MiniportInitializeEx deve chamar o função NdisMSetMiniportAttributes antes de chamar qualquer função NdisMXxx, como a função NdisMRegisterIoPortRange ou NdisMMapIoSpace, que declara recursos de hardware para o adaptador de miniport. MiniportInitializeEx deve chamar NdisMSetMiniportAttributes antes de tentar alocar recursos para operações de DMA.
Se o dispositivo der suporte ao DMA mestre do barramento, MiniportInitializeEx deverá chamar o função NdisMRegisterScatterGatherDma depois de chamar NdisMSetMiniportAttributes e antes de chamar o função de NdisMAllocateSharedMemory. Se o dispositivo der suporte ao DMA subordinado, MiniportInitializeEx deverá chamar NdisMSetMiniportAttributes antes de chamar o função de NdisMRegisterDmaChannel.
Depois de MiniportInitializeEx chamar o função NdisMRegisterInterruptEx, o NDIS pode chamar a função miniportInterrupt do driver. O NDIS chama MiniportInterrupt se a NIC gerar uma interrupção ou se qualquer outro dispositivo com o qual a NIC compartilhar uma interrupção gerará 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 o função NdisMDeregisterInterruptEx retorna.
MiniportInitializeEx deve testar a NIC para verificar se o hardware está 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 retorna com êxito, o adaptador de miniporto está no estado pausado. O NDIS pode chamar a função MiniportRestart para fazer a transição do adaptador de miniporto para o estado Executando.
Se MiniportInitializeEx retornar NDIS_STATUS_SUCCESS, o driver deverá liberar todos os recursos para o adaptador de miniporto na função MiniportHaltEx.
O driver deve chamar NdisMSetMiniportAttributes e definir o GeneralAttributes na estrutura NDIS_MINIPORT_ADAPTER_ATTRIBUTES se retornar NDIS_STATUS_SUCCESS.
Se MiniportInitializeEx falhar, MiniportInitializeEx deverá liberar todos os recursos alocados antes de retornar e o adaptador de miniporto retornar ao estado Interrompido.
Chamadas NDIS MiniportInitializeEx no IRQL = PASSIVE_LEVEL.
exemplos de
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 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 |
|---|---|
| de cliente com suporte mínimo | Com suporte no NDIS 6.0 e posterior. |
| da Plataforma de Destino | Windows |
| cabeçalho | ndis.h (inclua Ndis.h) |
| IRQL | PASSIVE_LEVEL |