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

Artigo
08/07/2023

Aviso

As funções de retorno de chamada MiniportResetEx e MiniportCheckForHangEx são desencorajadas para todos os drivers NDIS 6.83 e posteriores. Para obter mais informações, consulte Operações Check-for-Hang e Reset no NDIS 6.83 e posterior.

O NDIS chama a função MiniportResetEx de um driver de miniport do NDIS para iniciar uma redefinição de uma NIC (cartão de interface de rede). Para obter mais informações, consulte Miniport Adapter Check-for-Hang and Reset Operations and Miniport Driver Hardware Reset.

Nota Um driver de miniporto NDIS pode declarar essa função usando o tipo MINIPORT_RESET .

Sintaxe

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

Parâmetros

[in] MiniportAdapterContext

Um identificador para uma área de contexto que o driver de miniporto alocou em sua função MiniportInitializeEx . O driver de miniporto usa essa área de contexto para manter informações de estado para um adaptador de miniporte.

[out] AddressingReset

Um ponteiro para uma variável booliana. O driver de miniporte define essa variável como TRUE se o NDIS deve chamar a função MiniportOidRequest para restaurar o endereçamento e outras configurações para os valores atuais. Para obter mais informações, consulte Redefinição de hardware.

Retornar valor

MiniportResetEx pode retornar um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	MiniportResetEx redefiniu com êxito o adaptador de miniporto para um estado operacional.
NDIS_STATUS_PENDING	O driver concluirá a operação de redefinição de forma assíncrona chamando a função NdisMResetComplete quando a operação for concluída.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx determinou que o adaptador de miniporto estava sendo redefinido no momento, portanto, essa chamada é supérférica.
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx redefiniu com êxito o adaptador de miniporto, mas ocorreu um erro recuperável durante a operação. MiniportResetEx deveria ter chamado a função NdisWriteErrorLogEntry com mais informações sobre o erro.
NDIS_STATUS_HARD_ERRORS	MiniportResetEx tentou redefinir o adaptador de miniporto, mas ocorreu um erro irrecuperável durante a operação. MiniportResetEx deveria ter chamado NdisWriteErrorLogEntry com mais informações sobre o erro.

Comentários

Um driver especifica o ponto de entrada MiniportResetEx quando ele chama o Função NdisMRegisterMiniportDriver .

MiniportResetEx não é necessário para drivers intermediários.

MiniportResetEx pode redefinir os parâmetros do adaptador de miniport. Se uma redefinição causar uma alteração no endereço da estação do adaptador de miniporto, o driver de miniporto restaurará automaticamente o valor anterior do endereço da estação após a conclusão da redefinição. Quaisquer máscaras de endereçamento multicast ou funcionais, redefinidas pelo hardware, não precisam ser redefinidas nessa função.

Se uma operação de redefinição alterar outras informações, como informações de endereçamento multicast ou funcional, MiniportResetEx deverá definir a variável em AddressingReset como TRUE antes de retornar. Isso faz com que o NDIS chame a função MiniportOidRequest para restaurar as informações. O NDIS também restaura a lista de padrões Wake on the LAN (WoL) chamando OID_PNP_ADD_WAKE_UP_PATTERN. O driver deve liberar a lista de padrões WoL de seu contexto de adaptador porque a lista de hardware já está redefinida.

O NDIS não anulará nenhuma solicitação OID pendente nem enviará solicitações. Se o driver puder concluir o OID pendente com segurança ou enviar solicitações após uma redefinição, o driver poderá manter o OID pendente ou enviar solicitações até que a operação de redefinição seja concluída. Caso contrário, o driver deverá concluir o OID pendente ou enviar solicitações chamando o NdisMOidRequestComplete ou NdisMSendNetBufferListsComplete funções respectivamente antes de MiniportResetEx retornar.

Nota A partir do NDIS 6.30, o driver de miniporto não deve manter o OID pendente ou enviar solicitações até que a operação de redefinição seja concluída. Em vez disso, o driver deve concluir essas solicitações pendentes chamando as funções NdisMOidRequestComplete ou NdisMSendNetBufferListsComplete respectivamente antes da conclusão da operação de redefinição. Se o driver concluir a operação de redefinição de forma assíncrona, ele deverá concluir o OID pendente e enviar solicitações antes que o driver chame NdisMResetComplete.

Um driver de miniporte não deve chamar a função NdisMIndicateStatusEx para sinalizar o início e o término de cada operação de redefinição. O NDIS notifica os drivers de protocolo associados quando uma redefinição começa e termina.

Se MiniportResetEx precisar aguardar as alterações de estado no adaptador de miniporto durante as operações de redefinição, ele poderá chamar a função NdisStallExecution . No entanto, um
A função MiniportResetEx não deve chamar NdisStallExecution com um intervalo de tempo maior que 50 microssegundos. Se o driver precisar esperar mais de 50 microssegundos (ou se sondar), ele deverá definir um temporizador e retornar NDIS_STATUS_PENDING.

Se MiniportResetEx retornar NDIS_STATUS_PENDING, o driver deverá concluir a redefinição chamando a função NdisMResetComplete .

Se um adaptador de miniporto estiver no estado MediaConnectStateConnected e seu estado for alterado devido a uma redefinição, incluindo uma alteração no estado MediaConnectStateUnknown, o driver de miniporte deverá relatar a alteração de estado com uma indicação de NDIS_STATUS_LINK_STATE status. O driver de miniporto também deve indicar uma indicação de status MediaConnectStateConnected quando o link for restabelecido após a redefinição.

MiniportResetEx pode ser precedido por uma interrupção.

O NDIS chama a função MiniportCheckForHangEx periodicamente para determinar se ela deve chamar MiniportResetEx. O tempo limite padrão para chamar MiniportCheckForHangEx é de 2 segundos. Se esse padrão for muito curto, um driver de miniporto poderá definir um valor Maior CheckForHangTimeInSeconds ao chamar o
Função NdisMSetMiniportAttributes durante a inicialização. Para obter mais informações, consulte Miniport Adapter Check-for-Hang and Reset Operations.

O NDIS não pode determinar se uma NIC parou de responder para operações de recebimento. Para lidar com esse tipo de falha, a função MiniportCheckForHangEx pode monitorar operações de recebimento e, se necessário, retornar TRUE para forçar uma redefinição. Um miniporto também pode solicitar uma redefinição chamando NdisMResetMiniport.

O NDIS chama MiniportResetEx em IRQL <= DISPATCH_LEVEL.

Exemplos

Para definir uma função MiniportResetEx , 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 MiniportResetEx chamada "MyResetEx", use o tipo MINIPORT_RESET conforme mostrado neste exemplo de código:

MINIPORT_RESET MyResetEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

O tipo de função MINIPORT_RESET é 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_RESET 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	<= DISPATCH_LEVEL