DXGKDDI_NOTIFY_SURPRISE_REMOVAL função de retorno de chamada (dispmprt.h)

  • Artigo

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

Confira também

D3DKMT_WDDM_1_2_CAPS

DXGK_DRIVERCAPS

DXGK_SURPRISE_REMOVAL_TYPE

DxgkDdiAddDevice