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

Artigo
02/06/2025

A função DxgkDdiRender gera um buffer de DMA (acesso direto à memória) do buffer de comando que o driver de exibição do 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 hContext membro da estrutura DXGKARG_CREATECONTEXT para a qual o parâmetro pCreateContext DxgkDdiCreateContext.

Se o driver não der 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 miniport de exibição retornou anteriormente o identificador do dispositivo no hDevice membro da estrutura DXGKARG_CREATEDEVICE à 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 de retorno

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ãoprivilegiadas (ou seja, instruções que acessam a memória além do privilégio do processo atual da unidade de processamento central [CPU]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender detectou instruções de que o hardware gráfico não podia dar suporte.
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 subexecutivas ou excedentes. 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 subexecutivas ou excedentes.
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 de DMA. O dispositivo de contexto gráfico será colocado em um estado perdido se o driver retornar esse código de erro.

Observações

O subsistema de kernel gráfico DirectX chama a função DxgkDdiRender do driver de miniport de exibição para gerar um buffer DMA do buffer de comando que o driver de exibição do modo de usuário passou. Quando o driver de miniporto de exibição é convertido do buffer de comando para o buffer de DMA, o driver também deve validar o buffer de comando para garantir que o buffer de comandos 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 de DMA adequadamente.

Tanto o buffer de comando pCommand 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 do 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 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).

Veja um exemplo de como os drivers de miniporto de exibição devem acessar esses buffers usando __try e __except lógica. 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;
  }

Nota

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 do modo de usuário fornece se recriar as informações é 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 gráfico DirectX converte cada elemento D3DDDI_ALLOCATIONLIST em um elemento DXGK_ALLOCATIONLIST convertendo o identificador tipo D3DKMT_HANDLE que o driver de exibição do modo de usuário fornece em um identificador específico do dispositivo, que a função DxgkDdiOpenAllocation DxgkDdiOpenAllocation do driver de exibição retorna. O índice de cada alocação e o status de gravação da alocação (ou seja, a configuração do sinalizador WriteOperation campo de bits) permanece constante durante a conversão.

Além do identificador específico do dispositivo, o subsistema de kernel de elementos 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 Ndo pAllocationList membro do DXGKARG_RENDER como zero. Se o SegmentId membro do Nth elemento da lista de alocação não estiver definido como zero, o driver de miniporto de exibição deverá pré-corrigir 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.

Nota

Embora a função DxgkDdiRender do driver pré-patches do 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 pPatchLocationListOut membro 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 de 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 de NULL e, em seguida, pode usar um elemento de local de patch que faz referência a esse alocação de NULL. Normalmente, o driver deve usar o primeiro elemento da lista de alocação (elemento 0) como o elemento NULL elemento.

Quando o driver de miniporto de exibição converte um buffer de comando em 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 de 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 deve sempre dividir comandos que podem se traduzir 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 lidar com um único comando maior que o tamanho do buffer DMA e que não pode ser dividido.

DxgkDdiRender deve ficar paginável.

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