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

Artigo
02/06/2025

Para adaptadores de exibição que dão suporte à aceleração de hardware GDI, a função DxgkDdiRenderKm gera um buffer de DMA (acesso direto à memória) do buffer de comando que o CDD (Driver de Exibição Canônica) no modo kernel passou.

Sintaxe

DXGKDDI_RENDERKM DxgkddiRenderkm;

NTSTATUS DxgkddiRenderkm(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}

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 de 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 miniporto de exibição retornou anteriormente o identificador do dispositivo no hDevice membro da estrutura DXGKARG_CREATEDEVICE à qual o pCreateDevice parâmetro de DxgkDdiCreateDevice aponta.

[in/out] pRenderKmArgs

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

Se o driver de miniporto de exibição der suporte à aceleração de hardware GDI, pRenderKmArgs->pCommand aponta para o buffer de comando DXGK_RENDERKM_COMMAND.

O driver deve converter o buffer de comando de entrada em comandos de buffer de DMA e criar a lista de locais do patch.

Valor de retorno

DxgkDdiRenderKm retorna um dos seguintes valores:

Código de retorno	descrição
STATUS_SUCCESS	Todo o buffer de comando foi traduzido.
STATUS_NO_MEMORY	DxgkDdiRenderKm não foi possível alocar a memória necessária para que ela fosse concluída.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	O buffer DMA atual está esgotado.
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm parâmetros de instrução detectados 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	DxgkDdiRenderKm dados detectados 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	DxgkDdiRenderKm detectou um identificador inválido no 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 de elementos gráficos DirectX chama a função DxgkDdiRenderKm do driver de miniporto de exibição para gerar um buffer DMA do buffer de comando que é passado pelo CDD (Driver de Exibição Canônica) no modo kernel fornecido pelo sistema operacional. 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.

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 CDD fornece se ele pode recriar as informações de forma mais ideal. Por exemplo, se o pRender->pPatchLocationListIn membro 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 do do pRender->membro pPatchLocationListOut com base no conteúdo do buffer de comando.

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 membro pAllocationList de DXGKARG_RENDER como zero. Se o SegmentId membro do elemento Nda lista de alocação não estiver definido como zero, o driver de miniporto de exibição deverá corrigir o buffer de DMA gerado com as informações de endereço de segmento fornecidas antes que o subsistema de kernel de elementos gráficos DirectX chame a função DxgkDdiPatch para repatch o buffer DMA. O driver deve executar essa aplicação de patch inicial 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.

Mesmo que a função DxgkDdiRenderKm do driver execute a aplicação de patch de buffer DMA inicial, conforme descrito anteriormente, o driver ainda deve inserir todas as referências às alocações na lista de local do 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.

No modo DMA de contrato garantido, quando o driver de miniporto de exibição converte um buffer de comando em um buffer de DMA, o CDD 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. Para obter mais informações, consulte Usando o modelo de buffer de DMA de contrato garantido.

DxgkDdiRenderKm deve ficar paginável.