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

Artigo
06/10/2023

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) do 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 miniport de exibição retornou anteriormente esse identificador no membro hContext da estrutura DXGKARG_CREATECONTEXT para a qual o parâmetro pCreateContext de DxgkDdiCreateContext aponta para.

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 miniporta 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 para.

[in/out] pRenderKmArgs

Um ponteiro para uma estrutura 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> apontará 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.

Retornar valor

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 pôde alocar 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 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	DxgkDdiRenderKm detectou dados ou instruções em execução ou estouro. 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 estouro.
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.

Comentários

O subsistema de kernel de elementos gráficos DirectX chama a função DxgkDdiRenderKm do driver de miniporte 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 as informações que o CDD fornece se ele pode recriar as informações de forma mais ideal. Por exemplo, se o membro pRender-pPatchLocationListIn> estiver vazio porque o driver de exibição do modo de usuário não forneceu uma lista de localização de patch de entrada, o driver de miniporto de exibição poderá gerar o conteúdo do membro pRender-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 ao driver de miniporto de exibição o último endereço de segmento de GPU conhecido para cada alocação. Se o índice de alocação N estiver paginado no momento, o subsistema de kernel de elementos gráficos DirectX definirá o membro SegmentId do n th elemento do membro pAllocationList de DXGKARG_RENDER como zero. Se o membro SegmentId do nth elemento da lista de alocação não estiver definido como zero, o driver de miniporto de exibição deverá corrigir o buffer 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 do 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 de DMA que o driver deve ter corrigido corretamente.

Embora 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 localização de patch de saída especificada pelo membro pPatchLocationListOut do DXGKARG_RENDER . 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 repatch do buffer de DMA.

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

No modo DMA do contrato garantido, quando o driver de miniporto de exibição converte um buffer de comando para um buffer 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 do contrato garantido.

DxgkDdiRenderKm deve ser tornado paginável.