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 miniporto de exibição anteriormente forneceu 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.
Valor de retorno
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.
Observações
Opcionalmente, esse retorno de chamada pode ser implementado pelo WDDM (Modelo de Driver de Exibição do Windows) 1.2 e, posteriormente, exibir drivers de miniporto.
Nota
O sistema operacional chama DxgkDdiNotifySurpriseRemoval somente se o driver de miniporto de exibição indicar suporte definindo o SupportSurpriseRemovalInHibernation membro 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 imediatamente chama o do driver DxgkDdiNotifySurpriseRemoval retorno de chamada 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. Os detalhes de status de retorno 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 energia), 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 só oferecer suporte a SupportSurpriseRemovalInHibernation em seu DXGK_DRIVERCAPS, o sistema operacional reiniciará o sistema normalmente. Se ele der suporte a SupportSurpriseRemoval no DXGK_DRIVERCAPS, o sistema operacional ignorará o status de retorno e continuará interrompendo o dispositivo gráfico. Veja as notas adicionais de retorno abaixo.
O dispositivo gráfico é removido/desconectado quando ainda está em execução. Quando o sistema operacional detecta esse tipo de remoção surpresa, ele chama imediatamente o do driver DxgkDdiNotifySurpriseRemoval retorno de chamada com RemovalType = DxgkRemovalPnPNotify. Ainda pode haver algumas chamadas de DDI ou trabalho de GPU pendentes para serem concluídas 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 ao sistema operacional. O sistema operacional continuará chamando outras funções DDI para limpar os recursos e parar o dispositivo gráfico. Conforme observado abaixo, o driver só deve liberar ou limpar 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 dados.
Se o driver de miniporto de exibição retornar STATUS_SUCCESS, o subsistema kernel de elementos gráficos DirectX continuará removendo o adaptador de exibição externo da pilha de elementos gráficos e chamará outros DxgkDdiXxx implementados pelo driver funções de modo kernel 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 limpar 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.SupportSurpriseRemovalInHibernationou não implementa essa função, o subsistema de kernel de elementos gráficos DirectX não chamará mais funções de DxgkDdiXxx implementadas 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 |
|---|---|
| de cliente com suporte mínimo | Windows 8 |
| servidor com suporte mínimo | Windows Server 2012 |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | dispmprt.h |
| IRQL | PASSIVE_LEVEL |