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

Artigo
08/07/2023

O sistema operacional chama uma rotina DxgkDdiGetDisplayStateNonIntrusive de um driver de miniporta de exibição para coletar informações de estado de exibição de modo nãotrusivo do driver.

Sintaxe

DXGKDDI_GETDISPLAYSTATENONINTRUSIVE DxgkddiGetdisplaystatenonintrusive;

NTSTATUS DxgkddiGetdisplaystatenonintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATENONINTRUSIVE pArgs
)
{...}

Parâmetros

[in] Context

Ponteiro para um contexto privado retornado por DxgkDdiQueryInterface.

[in/out] pArgs

Ponteiro para uma estrutura DXGKARG_GETDISPLAYSTATENONINTRUSIVE .

Retornar valor

DxgkDdiGetDisplayStateNonIntrusive retornará STATUS_SUCCESS se for bem-sucedido. Caso contrário, ele retornará um código de erro, como um dos seguintes.

Código do Erro	Significado
STATUS_DRIVER_INTERNAL_ERROR	Ocorreu um erro de software genérico dentro do driver.
STATUS_ACCESS_DENIED	O hardware está sendo usado atualmente por outros threads e essa DDI não pode ter acesso a ele.
STATUS_DEVICE_HARDWARE_ERROR	Erro de HW genérico.
STATUS_DEVICE_POWERED_OFF	O dispositivo está desligado.

Comentários

O sistema operacional chama DxgkDdiGetDisplayStateNonIntrusive para coletar informações de estado de exibição do driver. Ao contrário de DxgkDdiGetDisplayStateIntrusive, a rotina DxgkDdiGetDisplayStateNonIntrusive do driver não deve executar nenhuma operação que cause efeitos colaterais visíveis para o usuário e o processo de coleção deve ser relativamente rápido (idealmente em alguns milissegundos). A frequência de chamada dessa rotina será relativamente alta. Além de ser chamado para diagnosticar o estado inválido do usuário, o sistema operacional também pode usar essa rotina para registrar informações de estado histórico do driver para fins de depuração.

Em casos raros em que uma implementação específica da plataforma exige que o driver realize operações intrusivas como parte de uma chamada para DxgkDdiGetDisplayStateNonIntrusive, o driver deve realizar as operações, mas deve definir pArgs-ReturnSubStatus> como DXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCH ou DXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATE adequadamente. Com base no valor ReturnSubStatus , o sistema operacional (SO) pode chamar essa rotina apenas para cenários de erro em um determinado sistema.

O sistema operacional chamará DxgkDdiGetDisplayStateNonIntrusive com frequência (periodicamente ou em outros eventos comuns) para coletar dados de estado do driver para fins de depuração e examinar os linha do tempo históricos. O sistema operacional também chamará essa rotina em cenários de erro específicos (como telas pretas) antes de coletar informações mais detalhadas chamando DxgkDdiGetDisplayStateIntrusive. Dada a possível frequência dessa chamada, os drivers devem concluí-la o mais rápido possível. O sistema operacional chamará esse DDI com NumOfTargets definido como o número máximo de destinos compatíveis com o adaptador gráfico fornecido e VidPnTargetId preenchidos. O driver de miniporte só deve preencher as informações de estado de exibição para destinos nos quais, na verdade, há um monitor conectado. Para um vidpntarget no qual não há nenhum monitor conectado, o miniporto deve apenas preencher DXGK_DIAG_DISPLAY_CONNECTIVITY e o sistema operacional ignorará todos os outros campos para esse destino.

Observação

Os drivers só devem usar ReturnSubStatus para relatar condições de erro e não usar DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED para relatar o estado de conectividade do monitor. A main finalidade de DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED é para chamadas intrusivas em que o sistema operacional não pergunta sobre a conectividade do monitor.

Se o driver atingir uma falha em um determinado vidpntarget durante a coleta de informações, ele deverá usar ReturnSubStatus para definir o estado de erro e prosseguir para o próximo vidpntarget e não falhar na chamada geral, a menos que todos os caminhos atinjam falhas. O ideal é que os drivers registrem erros atingidos durante essa chamada em algum log de erros interno para que, quando o sistema operacional chamar DxgkDdiCollectDiagnosticInfo para coletar informações da caixa preta, esses erros sejam capturados como parte de uma coleção de logs interna para ajudar os IHVs durante a depuração.

O nível de sincronização para essa DDI é sincronização de nível zero.