DXGKDDI_NOTIFY_SURPRISE_REMOVAL função de retorno de chamada (dispmprt.h)
DXGKDDI_NOTIFY_SURPRISE_REMOVAL é chamado pelo sistema operacional quando um usuário desconecta um dispositivo de exibição externo sem notificar o sistema.
Sintaxe
DXGKDDI_NOTIFY_SURPRISE_REMOVAL DxgkddiNotifySurpriseRemoval;
NTSTATUS DxgkddiNotifySurpriseRemoval(
[in] PVOID MiniportDeviceContext,
[in] DXGK_SURPRISE_REMOVAL_TYPE RemovalType
)
{...}
Parâmetros
[in] MiniportDeviceContext
Um identificador para um bloco de contexto associado a um adaptador de exibição. A função DxgkDdiAddDevice do driver de miniporta de exibição forneceu anteriormente esse identificador para o subsistema de kernel de elementos gráficos DirectX.
[in] RemovalType
Um valor do tipo DXGK_SURPRISE_REMOVAL_TYPE que identifica o tipo de evento de remoção surpresa.
Retornar valor
Retorna STATUS_SUCCESS se os recursos de software foram limpos para RemovalType = DxgkRemovalHibernation. Se o driver retornar um código de erro, o sistema operacional tentará reinicializar o sistema, conforme descrito na seção Comentários a seguir.
Comentários
Opcionalmente, esse retorno de chamada pode ser implementado pelo WDDM (Modelo de Driver de Vídeo do Windows) 1.2 e por drivers de miniporta de exibição posteriores.
Observação
O sistema operacional chamará DxgkDdiNotifySurpriseRemoval somente se o driver de miniporto de exibição indicar suporte definindo o membro SupportSurpriseRemovalInHibernation da estrutura DXGK_DRIVERCAPS como 1.
Quando o sistema operacional detecta uma remoção surpresa, ele notifica o driver o mais rápido possível. DxgkDdiNotifySurpriseRemoval é uma função DDI de nível zero , o que significa que ela pode ser chamada quando um driver tem carga de trabalho de GPU pendente e/ou está em execução dentro de outras funções DDI. Como uma chamada para essa função indica que o hardware gráfico foi fisicamente removido ou desapareceu do sistema, qualquer outra tentativa de acessar o hardware pode causar problemas como um travamento rígido.
O sistema operacional categoriza a remoção surpresa da seguinte maneira:
A remoção surpresa ocorre quando o sistema e o dispositivo gráfico estão em um estado de baixa potência, como suspensão ou hibernação. Quando o sistema operacional é retomado do estado de baixa potência, ele detecta essa remoção surpresa e chama imediatamente o retorno de chamada DxgkDdiNotifySurpriseRemoval do driver com RemovalType = DxgkRemovalHibernation. Provavelmente não haverá nenhum trabalho de GPU pendente ou chamadas DDI nesse caso, portanto, deve ser relativamente seguro e fácil para o driver lidar. Retornar status detalhes são os seguintes:
- O sistema operacional espera que o driver manipule a chamada DxgkDdiNotifySurpriseRemoval corretamente e retorne STATUS_SUCCESS.
- Se o dispositivo gráfico removido for o dispositivo POST (auto-teste de ativação), o sistema operacional tentará reinicializar o sistema normalmente, independentemente do status retornado.
- Para um dispositivo não POST, se o driver falhar na chamada e oferecer suporte apenas a SupportSurpriseRemovalInHibernation em seu DXGK_DRIVERCAPS, o sistema operacional reinicializará o sistema normalmente. Se ele der suporte a SupportSurpriseRemoval em DXGK_DRIVERCAPS, o sistema operacional ignorará o status de retorno e continuará interrompendo o dispositivo gráfico. Veja as notas de retorno adicionais abaixo.
O dispositivo gráfico é removido/desconectado de surpresa quando ainda está em execução. Quando o sistema operacional detecta esse tipo de remoção surpresa, ele chama imediatamente o retorno de chamada DxgkDdiNotifySurpriseRemoval do driver com RemovalType = DxgkRemovalPnPNotify. Ainda pode haver alguns trabalhos de GPU pendentes ou chamadas DDI para concluir nesse caso. Quando o driver recebe essa notificação e pode lidar com essa remoção surpresa, o driver deve marcar imediatamente esse dispositivo como remoção surpresa em seu próprio contexto de dispositivo para evitar qualquer acesso de hardware e, em seguida, retornar STATUS_SUCCESS de volta para o sistema operacional. O sistema operacional continuará chamando outras funções DDI para limpo os recursos e interromper o dispositivo gráfico. Conforme observado abaixo, o driver só deve liberar ou limpo os recursos de software e não deve tocar ou acessar nenhum hardware nessas chamadas DDI. Se o driver não puder lidar com essa remoção surpresa, ele deverá retornar uma falha adequada ao sistema operacional. Para qualquer falha, o sistema operacional verificará o sistema imediatamente para evitar danos adicionais de hardware ou de dados.
Se o driver de miniporta de exibição retornar STATUS_SUCCESS, o subsistema de kernel de elementos gráficos DirectX continuará removendo o adaptador de exibição externo da pilha de gráficos e chamará outras funções de modo kernel DxgkDdiXxx implementadas pelo driver para liberar todos os recursos. Nesse caso, o driver deve concluir sua limpeza de recursos de software em resposta a chamadas do sistema operacional, mas não deve tocar ou limpo nenhuma configuração de hardware. Se nenhum outro hardware estiver usando o driver, o sistema operacional descarregará o driver.
Se o driver retornar um código de erro, não definirá DXGK_DRIVERCAPS. SupportSurpriseRemovalInHibernation ou não implementa essa função, o subsistema kernel de elementos gráficos DirectX não chamará mais nenhuma função DxgkDdiXxxx implementada pelo driver e tentará reinicializar o sistema. Nesse caso, o recurso que foi alocado antes do dispositivo de exibição externo ser desconectado não será liberado.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8 |
| Servidor mínimo com suporte | Windows Server 2012 |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | dispmprt.h |
| IRQL | PASSIVE_LEVEL |