DXGKDDI_RENDER função de retorno de chamada (d3dkmddi.h)

Artigo
01/23/2023
7 minutos para o fim da leitura

A função DxgkDdiRender gera um buffer DMA (acesso direto à memória) do buffer de comando que o driver de exibição no modo de usuário passou.

Sintaxe

DXGKDDI_RENDER DxgkddiRender;

NTSTATUS DxgkddiRender(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRender
)
{...}

Parâmetros

[in] hContext

Um identificador para o contexto do dispositivo para o DMA e buffers de comando. A função DxgkDdiCreateContext do driver de miniporto de exibição retornou anteriormente esse identificador no membro hContext da estrutura DXGKARG_CREATECONTEXT à qual o parâmetro pCreateContext de DxgkDdiCreateContext aponta.

Se o driver não oferecer suporte à criação de contexto, o subsistema de kernel de elementos gráficos do Microsoft DirectX substituirá o identificador para o contexto por um identificador para o dispositivo. A função DxgkDdiCreateDevice do driver de miniporto de exibição retornou anteriormente o identificador do dispositivo no membro hDevice da estrutura DXGKARG_CREATEDEVICE para a qual o parâmetro pCreateDevice de DxgkDdiCreateDevice aponta.

[in/out] pRender

Um ponteiro para uma estrutura de DXGKARG_RENDER que contém informações sobre o DMA e buffers de comando.

Valor retornado

DxgkDdiRender retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	Todo o buffer de comando foi traduzido.
STATUS_NO_MEMORY	O DxgkDdiRender não pôde alocar a memória necessária para que ela fosse concluída.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	O buffer DMA atual está esgotado.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender detectou instruções nãoprivilegadas (ou seja, instruções que acessam a memória além do privilégio do processo de CPU [unidade de processamento central] atual).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender detectou instruções de que não era possível dar suporte ao hardware gráfico.
STATUS_INVALID_PARAMETER	DxgkDdiRender detectou parâmetros de instrução que o hardware gráfico não podia dar suporte; no entanto, o hardware gráfico pode dar suporte às próprias instruções. O driver não é necessário para retornar esse código de erro. Em vez disso, ele pode retornar STATUS_ILLEGAL_INSTRUCTION quando detecta parâmetros de instrução sem suporte.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender detectou dados ou instruções em execução ou sobrecarga. Ou seja, o driver recebeu menos ou mais instruções ou dados do que o esperado. O driver não é necessário para retornar esse código de erro. Em vez disso, ele pode retornar STATUS_ILLEGAL_INSTRUCTION quando detecta dados ou instruções em execução ou sobrecarga.
STATUS_INVALID_HANDLE	DxgkDdiRender detectou um identificador inválido no buffer de comando.
STATUS_GRAPHICS_DRIVER_MISMATCH	O driver de miniporto de exibição não é compatível com o driver de exibição no modo de usuário que iniciou a chamada para DxgkDdiRender (ou seja, enviou o buffer de comando).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	O driver de miniporto de exibição detectou um erro no fluxo DMA. O dispositivo de contexto gráfico será colocado em um estado perdido se o driver retornar esse código de erro.

Comentários

O subsistema de kernel de elementos gráficos DirectX chama a função DxgkDdiRender do driver de miniporto de exibição para gerar um buffer DMA do buffer de comando que o driver de exibição no modo de usuário passou. Quando o driver de miniporto de exibição é convertido do buffer de comando para o buffer DMA, o driver também deve validar o buffer de comando para garantir que o buffer de comando não contenha comandos ou comandos privilegiados que possam ser usados para acessar a memória que não pertence ao processo. Além do buffer de DMA de saída, o driver de miniporto de exibição também deve gerar uma lista de locais de patch de saída. O gerenciador de memória de vídeo usa essa lista para dividir e corrigir buffers DMA adequadamente.

Tanto o pCommand do buffer de comando quanto a lista de locais de patch de entrada pPatchLocationListIn que o driver de exibição no modo de usuário gera são alocados do espaço de endereço no modo de usuário e são passados para o driver de miniporto de exibição intocado. O driver de miniporto de exibição deve usar __try/__except o código em qualquer acesso ao buffer e à lista e deve validar o conteúdo do buffer e da lista antes de copiar o conteúdo para os respectivos buffers de kernel (ou seja, antes de copiar o conteúdo do membro pCommand para o membro pDmaBuffer e o conteúdo do membro pPatchLocationListIn para o membro pPatchLocationListOut , que são todos membros da estrutura DXGKARG_RENDER à qual o parâmetro pRender aponta).

Aqui está um exemplo de como os drivers de miniporto de exibição devem acessar esses buffers usando __try e lógica __except . AllocationListIn aponta para o buffer do modo de usuário.

__try
  {
    for (Index = 0; Index < AllocationListInSize; AllocationTable++, 
           AllocationListIn++, AllocationListOut++, Index++) 
    {
      D3DKMT_HANDLE AllocationHandle = AllocationListIn->hAllocation;
      . . .
    }
  }
__except(EXCEPTION_EXECUTE_HANDLER)
  {
    Status = STATUS_INVALID_PARAMETER;
    SAMPLE_LOG_ERROR(
  "Exception occurred accessing user-mode allocation list. Returning Status=0x%I64x",
      Status);
    goto cleanup;
  }

Observação

O acesso aos buffers de kernel não requer proteção contra try/except código.

O driver de miniporto de exibição não é necessário para usar informações que o driver de exibição no modo de usuário fornece se recriar as informações for mais ideal. Por exemplo, se pPatchLocationListIn estiver vazio porque o driver de exibição no modo de usuário não forneceu uma lista de locais de patch de entrada, o driver de miniporto de exibição poderá gerar o conteúdo de pPatchLocationListOut com base no conteúdo do buffer de comando.

A lista de alocação fornecida pelo driver de exibição no modo de usuário é validada, copiada e convertida em uma lista de alocação no modo kernel durante a transição do kernel. O subsistema de kernel de gráficos DirectX converte cada elemento D3DDDI_ALLOCATIONLIST em um elemento DXGK_ALLOCATIONLIST convertendo o identificador tipo D3DKMT_HANDLE que o driver de exibição no modo de usuário fornece em um identificador específico do dispositivo, que retorna a função DxgkDdiOpenAllocation do driver de miniporto de exibição. O índice de cada alocação e o status de gravação da alocação (ou seja, a configuração do sinalizador de campo de bit WriteOperation ) permanece constante durante a conversão.

Além do identificador específico do dispositivo, o subsistema de kernel de gráficos DirectX fornece o driver de miniporto de exibição com o último endereço de segmento de GPU conhecido para cada alocação. Se o índice de alocação N for excluído no momento, o subsistema de kernel de elementos gráficos DirectX definirá o membro SegmentId do elemento Nth do membro pAllocationList de DXGKARG_RENDER como zero. Se o membro SegmentId do elemento Nth da lista de alocação não estiver definido como zero, o driver de miniporto de exibição deverá corrigir previamente o buffer de DMA gerado com as informações de endereço do segmento fornecidas. O driver deve pré-corrigir quando solicitado porque o subsistema de kernel de elementos gráficos DirectX pode não chamar a função DxgkDdiPatch em um buffer DMA que o driver deve ter corrigido corretamente.

Observação

Embora a função DxgkDdiRender do driver exiba previamente o buffer DMA, o driver ainda deve inserir todas as referências às alocações na lista de locais de patch de saída que o membro pPatchLocationListOut do DXGKARG_RENDER especifica. Essa lista deve conter todas as referências porque os endereços das alocações podem ser alterados antes que o buffer DMA seja enviado para a GPU; Portanto, o subsistema de kernel de elementos gráficos DirectX chamará a função DxgkDdiPatch para fazer o repositório do buffer DMA.

Para desassociar uma alocação, o driver de miniporto de exibição pode especificar um elemento na lista de alocação que faz referência a um identificador NULL e, em seguida, pode usar um elemento de local de patch que faz referência a essa alocação NULL . Normalmente, o driver deve usar o primeiro elemento da lista de alocação (elemento 0) como o elemento NULL .

Quando o driver de miniporto de exibição converte um buffer de comando para um buffer DMA, o driver de miniporto de exibição e o driver de exibição no modo de usuário devem executar as seguintes ações para as seguintes situações:

No modo DMA do contrato garantido (para obter mais informações, consulte Usando o modelo de buffer DMA do contrato garantido), o driver de exibição no modo de usuário deve garantir recursos suficientes para o comando de tradução. Se recursos suficientes não existirem para a tradução, o driver de miniporto de exibição deverá rejeitar o buffer de DMA.
O driver de exibição no modo de usuário sempre deve dividir comandos que podem ser convertidos em mais do que o tamanho de um único buffer DMA porque a função DxgkDdiRender do driver de miniporto de exibição não pode manipular um único comando maior que o tamanho do buffer DMA e que não pode ser dividido.

DxgkDdiRender deve ser tornado pageable.

O suporte para a função DxgkDdiRenderKm foi adicionado a partir do Windows 7 para adaptadores de exibição que dão suporte à Aceleração de Hardware GDI.