DXGKDDI_NOTIFY_SURPRISE_REMOVAL funzione di callback (dispmprt.h)
DXGKDDI_NOTIFY_SURPRISE_REMOVAL viene chiamato dal sistema operativo quando un utente disconnette un dispositivo di visualizzazione esterno senza notificare al sistema.
Sintassi
DXGKDDI_NOTIFY_SURPRISE_REMOVAL DxgkddiNotifySurpriseRemoval;
NTSTATUS DxgkddiNotifySurpriseRemoval(
[in] PVOID MiniportDeviceContext,
[in] DXGK_SURPRISE_REMOVAL_TYPE RemovalType
)
{...}
Parametri
[in] MiniportDeviceContext
Handle per un blocco di contesto associato a una scheda di visualizzazione. La funzione DxgkDdiAddDevice del driver miniport di visualizzazione ha fornito in precedenza questo handle al sottosistema kernel della grafica DirectX.
[in] RemovalType
Valore di tipo DXGK_SURPRISE_REMOVAL_TYPE che identifica il tipo di evento di rimozione delle sorprese.
Valore restituito
Restituisce STATUS_SUCCESS se le risorse software sono state pulite per RemovalType = DxgkRemovalHibernation. Se il driver restituisce invece un codice di errore, il sistema operativo tenterà di riavviare il sistema, come descritto nella sezione Osservazioni seguente.
Osservazioni
Questo callback può essere implementato facoltativamente da Windows Display Driver Model (WDDM) 1.2 e versioni successive visualizzano i driver miniport.
Nota
Il sistema operativo chiama DxgkDdiNotifySurpriseRemoval solo se il driver miniport di visualizzazione indica il supporto impostando il SupportSurpriseRemovalInHibernation membro della struttura DXGK_DRIVERCAPS su 1.
Quando il sistema operativo rileva una rimozione a sorpresa, notifica il driver il più rapidamente possibile. DxgkDdiNotifySurpriseRemoval è una funzione DDI di livello zero, il che significa che può essere chiamato quando un driver ha un carico di lavoro GPU in sospeso e/o viene eseguito all'interno di altre funzioni DDI. Poiché una chiamata a questa funzione indica che l'hardware grafico è stato fisicamente rimosso o è scomparso dal sistema, qualsiasi ulteriore tentativo di accesso all'hardware potrebbe causare problemi come un blocco rigido.
Il sistema operativo classifica la rimozione delle sorprese come indicato di seguito:
La rimozione delle sorprese si verifica quando il sistema e il dispositivo grafico sono in uno stato a basso consumo, ad esempio sospensione o ibernazione. Quando il sistema operativo riprende dallo stato a basso consumo, rileva questa rimozione a sorpresa e chiama immediatamente il DxgkDdiNotifySurpriseRemoval callback con RemovalType = DxgkRemovalHibernation. In questo caso non ci saranno probabilmente chiamate GPU o DDI in sospeso, quindi dovrebbe essere relativamente sicuro e facile da gestire per il driver. I dettagli di stato restituiti sono i seguenti:
- Il sistema operativo prevede che il driver gestisca il DxgkDdiNotifySurpriseRemoval chiamare correttamente e restituire STATUS_SUCCESS.
- Se il dispositivo grafico rimosso è il dispositivo auto-test (POST), il sistema operativo tenterà di riavviare correttamente il sistema indipendentemente dallo stato restituito.
- Per un dispositivo non POST, se il driver non riesce la chiamata e supporta solo SupportSurpriseRemovalInHibernation nel relativo DXGK_DRIVERCAPS, il sistema verrà riavviato normalmente. Se supporta SupportSurpriseRemoval in DXGK_DRIVERCAPS, il sistema operativo ignorerà lo stato restituito e continuerà a arrestare il dispositivo grafico. Vedere le note di restituzione aggiuntive di seguito.
Il dispositivo grafico è sorprendentemente rimosso/scollegato quando è ancora in esecuzione. Quando il sistema operativo rileva questo tipo di rimozione a sorpresa, chiama immediatamente il DxgkDdiNotifySurpriseRemoval callback con RemovalType = DxgkRemovalPnPNotify. In questo caso potrebbero essere ancora presenti alcune chiamate GPU in sospeso o DDI da completare. Quando il driver riceve questa notifica e può gestire questa rimozione a sorpresa, il driver deve immediatamente contrassegnare il dispositivo come rimozione a sorpresa nel proprio contesto di dispositivo per evitare l'accesso hardware e quindi restituire STATUS_SUCCESS al sistema operativo. Il sistema operativo continuerà a chiamare altre funzioni DDI per pulire le risorse e arrestare il dispositivo grafico. Come indicato di seguito, il driver deve rilasciare o pulire solo le risorse software e non deve toccare o accedere ad alcun hardware in queste chiamate DDI. Se il driver non riesce a gestire questa rimozione a sorpresa, dovrebbe restituire un errore corretto al sistema operativo. Per eventuali errori, il sistema operativo controlla immediatamente il sistema per evitare ulteriori danni hardware o dati.
Se il driver miniport di visualizzazione restituisce STATUS_SUCCESS, il sottosistema kernel della grafica DirectX continuerà a rimuovere la scheda di visualizzazione esterna dallo stack di grafica e chiamerà altri driver implementati DxgkDdiXxx funzioni in modalità kernel per rilasciare tutte le risorse. In questo caso, il driver deve completare la pulizia delle risorse software in risposta alle chiamate dal sistema operativo, ma non deve toccare o pulire le impostazioni hardware. Se nessun altro hardware usa il driver, il sistema operativo scaricherà il driver.
Se il driver restituisce un codice di errore, non imposta DXGK_DRIVERCAPS.SupportSurpriseRemovalInHibernationo non implementa questa funzione, il sottosistema del kernel della grafica DirectX non chiamerà più funzioni dxgkDdiXxx e tenterà di riavviare il sistema. In questo caso, la risorsa allocata prima della disconnessione del dispositivo di visualizzazione esterno non verrà rilasciata.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 8 |
| server minimo supportato | Windows Server 2012 |
| piattaforma di destinazione | Desktop |
| intestazione | dispmprt.h |
| IRQL | PASSIVE_LEVEL |