Ripristino di una scheda di interfaccia di rete non risponde con NETAdapterCx PLDR

NetAdapterCx offre un modo efficace per reimpostare e ripristinare i dispositivi di rete che non funzionano correttamente tramite la reimpostazione del dispositivo a livello di piattaforma (PLDR). Senza riavviare l'intero sistema Windows, l'operazione PLDR rimuove lo stack dei dispositivi di rete interessati garantendo il riavvio dell'hardware e dei driver da uno stato vuoto. NetAdapterCx consente anche ai driver client di raccogliere la diagnostica dai dispositivi non riusciti prima che vengano reimpostati a livello di piattaforma.

La route PLDR viene attivata quando viene rilevato un comportamento anomalo del dispositivo. Può essere attivata da:

• Sistema operativo. Ad esempio, il lato sistema operativo può attivare PLDR quando un pacchetto in transito è bloccato nel driver per troppo tempo.

• Driver client IHV (Independent Hardware Vendor). Ad esempio, i driver client possono richiedere a NetAdapterCx di attivare PLDR quando un driver rileva che il dispositivo non risponde al relativo comando di controllo.

Per fornire errori e ripristino dei dispositivi descrittivi, è consigliabile che IHD e i produttori di apparecchiature originali supportino PLDR per i dispositivi di rete. Per altre informazioni su PLDR, vedere Reimpostazione e ripristino di un dispositivo. NetAdapterCx non recupera i dispositivi di rete tramite la reimpostazione del dispositivo a livello di funzione.

Registrare il callback della raccolta di diagnostica facoltativa

Come parte del processo di ripristino e reimpostazione NetAdapterCx, il driver client può raccogliere diagnostica specifica del dispositivo dal dispositivo non riuscito prima che il dispositivo sia reimpostato a livello di piattaforma. IHV e Microsoft possono usare questi dati nell'analisi post-errore per migliorare la qualità dei propri prodotti.

Registrare NET_DEVICE_RESET_CAPABILITIES

I driver client devono inizializzare e registrare la struttura NET_DEVICE_RESET_CAPABILITIES nella relativa funzione di callback EVT_WDF_DRIVER_DEVICE_ADD per raccogliere la diagnostica specifica del dispositivo.

NET_DEVICE_RESET_CAPABILITIES contiene:

• GUID univoco. L'IHV specifica questo GUID e lo usa in un secondo momento per identificare e recuperare la diagnostica di reimpostazione da un dump della memoria. Ad esempio, il comando con estensione enumtag può essere usato per recuperare la diagnostica.

• Funzione di callback dell'evento EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS . NetAdapterCx richiama questo callback per raccogliere la diagnostica. Se il driver client fornisce un callback EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS , NetAdapterCx lo richiama sul driver client usando un thread dedicato .

L'esempio seguente illustra come registrare NET_DEVICE_RESET_CAPABILITIES in 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);

    ...
}

Per informazioni su come inizializzare la struttura NET_DEVICE_RESET_CAPABILITIES , vedere NET_DEVICE_RESET_CAPABILITIES_INIT.

Per informazioni su come annunciare la struttura NET_DEVICE_RESET_CAPABILITIES a NetAdapterCx, vedere NetDeviceInitSetResetCapabilities.

Implementare EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS

La sequenza di reimpostazione e ripristino può essere eseguita in qualsiasi momento. Di conseguenza, l'implementazione del callback del driver client EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS deve considerare quanto segue:

• NetAdapterCx sincronizza il callback EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS con altri callback che possono verificarsi durante la sequenza di risparmio energia. Il driver client può presupporre che NetAdapterCx non richiami callback come l'annullamento/arresto della coda di pacchetti, la versione hardware e l'eliminazione dell'oggetto dispositivo fino a quando non EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS restituisce .

• Il driver client deve prestare particolare attenzione durante la gestione della raccolta di diagnostica per evitare deadlock. Deve tenere presente che l'hardware potrebbe essere già in uno stato di errore.

• È fondamentale per EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS completare il prima possibile, in modo che il resto del processo PLDR possa procedere. EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS deve essere affidabile e deve restituire entro 3 secondi.

• NetAdapterCx richiama sempre EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS in PASSIVE_LEVEL.

Per inviare la diagnostica a NetAdapterCx, il driver client esegue la procedura seguente:

1. Preallocare un buffer flat da un pool di paging o non di paging per raccogliere la diagnostica di reimpostazione. Il driver deve preallocare questo buffer per evitare un errore di memoria insufficiente durante la reimpostazione del dispositivo.

2. All'interno del callback EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS inviare la diagnostica come buffer di dati flat chiamando l'API NetDeviceStoreResetDiagnostics . Il driver client deve chiamare l'API NetDeviceStoreResetDiagnostics in PASSIVE_LEVEL.

3. Liberare il buffer dei dati una volta restituito NetDeviceStoreResetDiagnostics .

Importante

L'API NetDeviceStoreResetDiagnostics deve essere chiamata solo nel callback EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS . Non può essere usato anche per inviare nuovamente i dati di diagnostica dopo la restituzione precedente di NetDeviceStoreResetDiagnostics . La violazione di uno di questi casi comporterà un controllo di bug.

Importante

La limitazione delle dimensioni per la diagnostica di reimpostazione è di 1 MB.

Come un driver client richiede PLDR

Un driver client attiva PLDR usando l'API NetAdapterCx NetDeviceRequestReset quando rileva un errore del dispositivo. NetDeviceRequestReset restituisce immediatamente al driver client. La sequenza di ripristino e reimpostazione descritta in NetAdapterCx reset and recover sequence viene attivata ed è asincrona alla chiamata NetDeviceRequestReset .

Una sola operazione PLDR può verificarsi in qualsiasi momento. Di conseguenza, le chiamate successive di NetDeviceRequestReset non hanno alcun effetto quando un'operazione PLDR è già stata avviata.

La chiamata a NetDeviceRequestReset non ha effetto anche se la sequenza di risparmio energia è già stata avviata.

Sequenza di ripristino e ripristino di NetAdapterCx

Quando il sistema operativo o il driver client attiva PLDR, si verifica la sequenza seguente:

1. Raccogliere la diagnostica di reimpostazione: NetAdapterCx richiama il callback del driver client EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS per raccogliere la diagnostica dal dispositivo non riuscito. Ad esempio, il driver può raccogliere uno snapshot del firmware del dispositivo. Questo passaggio è facoltativo e si verifica solo se il driver client ha registrato la struttura NET_DEVICE_RESET_CAPABILITIES . In caso contrario, NetAdapterCx ignorerà questo passaggio.

2. Eseguire PLDR: NetAdapterCx esegue l'operazione di reimpostazione del dispositivo a livello di piattaforma. La potenza NetAdapterCx ricicla l'hardware e rimuove lo stack di dispositivi software.

Il diagramma seguente illustra la sequenza di ripristino e ripristino di NetAdapterCx: