DXGKDDI_RENDER função de retorno de chamada (d3dkmddi.h)
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 miniporta de exibição retornou anteriormente esse identificador no membro hContext da estrutura DXGKARG_CREATECONTEXT para a qual o parâmetro pCreateContext de DxgkDdiCreateContext aponta.
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.
[in/out] pRender
Um ponteiro para uma estrutura DXGKARG_RENDER que contém informações sobre o AMD e os buffers de comando.
Retornar valor
DxgkDdiRender retorna um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
| STATUS_SUCCESS | O buffer de comando inteiro 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 de AMD atual está esgotado. |
| STATUS_PRIVILEGED_INSTRUCTION | DxgkDdiRender detectou instruções não privilegiadas (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 aos quais 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 | O DxgkDdiRender 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 subexecutar ou ultrapassar. |
| STATUS_INVALID_HANDLE | DxgkDdiRender detectou um identificador inválido no buffer de comando. |
| STATUS_GRAPHICS_DRIVER_MISMATCH | O driver de miniporta de exibição não é compatível com o driver de exibição do 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 miniporta 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 DxgkDdiRender do driver de miniporta 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 miniporta 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 miniporta 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 pCommand do buffer de comando e a lista de locais de patch de entrada pPatchLocationListIn que o driver de exibição do 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 inalterado. O driver de miniporta 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 para a qual o parâmetro pRender aponta).
Aqui está um exemplo de como os drivers de miniporta de exibição devem acessar esses buffers usando __try a lógica e __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 miniporta 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 for mais ideal. Por exemplo, se pPatchLocationListIn estiver vazio porque o driver de exibição do 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 que o driver de exibição do modo de usuário fornece é validada, copiada e convertida em uma lista de alocação no modo kernel durante a transição do kernel. O subsistema de kernel de elementos gráficos DirectX converte cada elemento D3DDDI_ALLOCATIONLIST em um elemento DXGK_ALLOCATIONLIST convertendo o identificador de tipo D3DKMT_HANDLE que o driver de exibição do modo de usuário fornece em um identificador específico do dispositivo, que retorna a função DxgkDdiOpenAllocation do driver de miniporta de exibição. O índice de cada alocação e a status de gravação da alocação (ou seja, a configuração do sinalizador de campo de bits WriteOperation) permanece constante durante a conversão.
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 Nelemento do membro pAllocationList de DXGKARG_RENDER como zero. Se o membro SegmentId do nºelemento da lista de alocação não estiver definido como zero, o driver de miniporto de exibição deverá corrigir previamente o buffer DMA gerado com as informações de endereço do segmento fornecidas. O driver deve corrigir previamente 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 pré-corrija 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 de DMA seja enviado para a GPU; Portanto, o subsistema de kernel de elementos gráficos DirectX chamará a função DxgkDdiPatch para recompensar o 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 faz referência a 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 .
Quando o driver de miniporta de exibição converte um buffer de comando em um buffer DMA, o driver de miniporta de exibição e o driver de exibição do modo de usuário devem executar as seguintes ações para as seguintes situações:
No modo de DMA de contrato garantido (para obter mais informações, consulte Usando o modelo de buffer de DMA de contrato garantido), o driver de exibição do modo de usuário deve garantir recursos suficientes para o comando de tradução. Se não existirem recursos suficientes para a tradução, o driver de miniporto de exibição deverá rejeitar o buffer de DMA.
O driver de exibição do modo de usuário sempre deve dividir comandos que possam ser convertidos em mais do que o tamanho de um único buffer de DMA porque a função DxgkDdiRender do driver de miniporta de exibição não pode manipular um único comando maior que o tamanho do buffer de DMA e que não pode ser dividido.
DxgkDdiRender deve ser tornado paginável.
O suporte para a função DxgkDdiRenderKm foi adicionado a partir do Windows 7 para adaptadores de vídeo que dão suporte à Aceleração de Hardware GDI.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows Vista |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | d3dkmddi.h |
| IRQL | PASSIVE_LEVEL |