Recuperando uma NIC sem resposta com NetAdapterCx PLDR

O NetAdapterCx fornece uma maneira eficaz de redefinir e recuperar dispositivos de rede com mau funcionamento por meio da PLDR (redefinição de dispositivo no nível da plataforma). Sem reinicializar todo o sistema Windows, a operação PLDR reduz a pilha de dispositivos de rede afetados, garantindo que seu hardware e drivers sejam reiniciados de um estado em branco. O NetAdapterCx também permite que os drivers de cliente coletem diagnóstico de dispositivos com falha antes de serem redefinidos no nível da plataforma.

PLDR é disparado quando um comportamento anormal do dispositivo é detectado. Ele pode ser disparado por:

• O sistema operacional (SO). Por exemplo, o lado do sistema operacional pode disparar PLDR quando um pacote em trânsito está preso no driver por muito tempo.

• Drivers de cliente IHV (fornecedor independente de hardware). Por exemplo, os drivers de cliente podem solicitar que NetAdapterCx dispare PLDR quando um driver detecta que seu dispositivo não está respondendo ao comando de controle.

Para fornecer falha e recuperação de dispositivos amigáveis, recomendamos que IHVs e OEMs (fabricantes de equipamentos originais) ofereçam suporte a PLDR para seus dispositivos de rede. Para obter mais informações sobre PLDR, consulte Redefinindo e recuperando um dispositivo. O NetAdapterCx não recupera dispositivos de rede por meio da redefinição de dispositivo no nível da função.

Registrar o retorno de chamada opcional da coleção diagnóstico

Como parte do processo de redefinição e recuperação do NetAdapterCx, o driver cliente pode coletar diagnóstico específicas do dispositivo do dispositivo com falha antes que o dispositivo seja redefinido no nível da plataforma. Os IHVs e a Microsoft podem usar esses dados na análise pós-falha para melhorar a qualidade de seus produtos.

Registrar NET_DEVICE_RESET_CAPABILITIES

Os drivers de cliente precisam inicializar e registrar a estrutura de NET_DEVICE_RESET_CAPABILITIES em sua função de retorno de chamada EVT_WDF_DRIVER_DEVICE_ADD para coletar diagnóstico específicas do dispositivo.

NET_DEVICE_RESET_CAPABILITIES contém:

• Um GUID exclusivo. O IHV especifica esse GUID e o usa posteriormente para identificar e recuperar o diagnóstico de redefinição de um despejo de memória. Por exemplo, o comando .enumtag pode ser usado para recuperar o diagnóstico.

• Uma função de retorno de chamada de evento EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS. NetAdapterCx invoca esse retorno de chamada para coletar diagnóstico. Se o driver do cliente fornecer um retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS , NetAdapterCx o invocará no driver cliente usando um thread dedicado .

O exemplo a seguir mostra como registrar NET_DEVICE_RESET_CAPABILITIES no NetAdapterCx:

EVT_WDF_DRIVER_DEVICE_ADD EvtWdfDriverDeviceAdd;
EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS EvtDeviceCollectResetDiagnostics;

NTSTATUS EvtWdfDriverDeviceAdd(
    WDFDRIVER Driver,
    PWDFDEVICE_INIT DeviceInit
)
{
    ...

    NET_DEVICE_RESET_CAPABILITIES resetCapabilities;
    NET_DEVICE_RESET_CAPABILITIES_INIT(
        &resetCapabilities,
        DUMMY_GUID,
        EvtDeviceCollectResetDiagnostics);
    NetDeviceInitSetResetCapabilities(DeviceInit, &resetCapabilities);

    ...
}

Para obter informações sobre como inicializar a estrutura de NET_DEVICE_RESET_CAPABILITIES , consulte NET_DEVICE_RESET_CAPABILITIES_INIT.

Para saber como anunciar a estrutura de NET_DEVICE_RESET_CAPABILITIES para NetAdapterCx, consulte NetDeviceInitSetResetCapabilities.

Implementar EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS

A redefinição e a sequência de recuperação podem acontecer a qualquer momento. Portanto, a implementação de retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS do driver de cliente deve considerar o seguinte:

• NetAdapterCx sincroniza o retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS com outros retornos de chamada que podem ocorrer durante a sequência de desligar. O driver do cliente pode assumir que NetAdapterCx não invocará retornos de chamada como cancelamento/parada de fila de pacotes, liberação de hardware e exclusão de objeto do dispositivo até que EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS retorne.

• O driver do cliente deve ter cuidado extra ao lidar com diagnóstico coleção para evitar deadlock. Ele deve levar em conta que o hardware já pode estar em um estado de falha.

• É essencial que EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS sejam concluídos o mais rápido possível para que o restante do processo PLDR possa continuar. EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS deve ser confiável e deve retornar dentro de 3 segundos.

• NetAdapterCx sempre invoca EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS em PASSIVE_LEVEL.

Para enviar diagnóstico ao NetAdapterCx, o driver cliente executa as seguintes etapas:

1. Preallocate um buffer simples de um pool paginado ou não paginado para coletar a diagnóstico de redefinição. O driver deve pré-alocar esse buffer para evitar um erro de memória insuficiente durante a redefinição do dispositivo.

2. No retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS, envie o diagnóstico como um buffer de dados simples chamando a API NetDeviceStoreResetDiagnostics. O driver do cliente deve chamar a API NetDeviceStoreResetDiagnostics em PASSIVE_LEVEL.

3. Libere o buffer de dados assim que NetDeviceStoreResetDiagnostics retornar.

Importante

A API NetDeviceStoreResetDiagnostics só deve ser chamada no retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS . Ele também não pode ser usado para enviar novamente diagnóstico dados após o retorno anterior de NetDeviceStoreResetDiagnostics. Violar qualquer um desses casos resultará em uma verificação de bugs.

Importante

A limitação de tamanho para redefinir diagnóstico é de 1 MB.

Como um driver de cliente solicita PLDR

Um driver de cliente dispara PLDR usando a API NetAdapterCx NetDeviceRequestReset quando detecta a falha do dispositivo. NetDeviceRequestReset retorna imediatamente para o driver cliente. A sequência de redefinição e recuperação descrita na sequência de redefinição e recuperação de NetAdapterCx é disparada e é assíncrona para a chamada NetDeviceRequestReset .

Somente uma operação PLDR pode acontecer a qualquer momento. Portanto, chamadas subsequentes de NetDeviceRequestReset não têm efeito quando uma operação PLDR já foi iniciada.

Chamar NetDeviceRequestReset também não terá efeito se a sequência de desligar já tiver sido iniciada.

Redefinição e recuperação da sequência netAdapterCx

Quando o sistema operacional ou o driver do cliente dispara o PLDR, a seguinte sequência ocorre:

1. Coletar diagnóstico de redefinição: NetAdapterCx invoca o retorno de chamada EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS do driver cliente para coletar diagnóstico do dispositivo com falha. Por exemplo, o driver pode coletar uma instantâneo do firmware do dispositivo. Essa etapa é opcional e só ocorre se o driver do cliente tiver registrado a estrutura NET_DEVICE_RESET_CAPABILITIES . Caso contrário, NetAdapterCx ignorará esta etapa.

2. Executar PLDR: NetAdapterCx executa a operação de redefinição de dispositivo no nível da plataforma. A energia netAdapterCx recicla o hardware e rasga a pilha de dispositivos de software.

O diagrama a seguir ilustra a sequência de redefinição e recuperação do NetAdapterCx: