DXGKDDI_RENDER función de devolución de llamada (d3dkmddi.h)

Artículo
03/08/2023

La función DxgkDdiRender genera un búfer de acceso directo a memoria (DMA) desde el búfer de comandos que pasó el controlador de visualización en modo de usuario.

Sintaxis

DXGKDDI_RENDER DxgkddiRender;

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

Parámetros

[in] hContext

Identificador del contexto del dispositivo para los búferes de comandos y DMA. La función DxgkDdiCreateContext del controlador de miniporte para mostrar devolvió previamente este identificador en el miembro hContext de la estructura DXGKARG_CREATECONTEXT a la que apunta el parámetro pCreateContext de DxgkDdiCreateContext .

Si el controlador no admite la creación de contexto, el subsistema del kernel de gráficos de Microsoft DirectX reemplaza el identificador al contexto por un identificador para el dispositivo. La función DxgkDdiCreateDevice del controlador de miniporte de pantalla devolvió previamente el identificador del dispositivo en el miembro hDevice de la estructura DXGKARG_CREATEDEVICE a la que apunta el parámetro pCreateDevice de DxgkDdiCreateDevice .

[in/out] pRender

Puntero a una estructura DXGKARG_RENDER que contiene información sobre los búferes de comandos y DMA.

Valor devuelto

DxgkDdiRender devuelve uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	Se ha traducido todo el búfer de comandos.
STATUS_NO_MEMORY	DxgkDdiRender no pudo asignar memoria necesaria para que se completara.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	El búfer DMA actual está agotado.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender detectó instrucciones no privilegiadas (es decir, instrucciones que acceden a la memoria más allá del privilegio del proceso de la unidad de procesamiento central [CPU] actual).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender detectó instrucciones que el hardware gráfico no podía admitir.
STATUS_INVALID_PARAMETER	DxgkDdiRender detectó parámetros de instrucción que el hardware gráfico no podía admitir; sin embargo, el hardware gráfico puede admitir las instrucciones. El controlador no es necesario para devolver este código de error. En su lugar, puede devolver STATUS_ILLEGAL_INSTRUCTION cuando detecta parámetros de instrucción no admitidos.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender detectó datos o instrucciones bajo ejecución o saturación. Es decir, el controlador recibió menos o más instrucciones o datos de los esperados. El controlador no es necesario para devolver este código de error. En su lugar, puede devolver STATUS_ILLEGAL_INSTRUCTION cuando detecta datos o instrucciones infrarun o overrun.
STATUS_INVALID_HANDLE	DxgkDdiRender detectó un identificador no válido en el búfer de comandos.
STATUS_GRAPHICS_DRIVER_MISMATCH	El controlador de minipuerto de pantalla de pantalla no es compatible con el controlador de pantalla en modo de usuario que inició la llamada a DxgkDdiRender (es decir, envió el búfer de comandos).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	El controlador de minipuerto de pantalla detectó un error en la secuencia DMA. El dispositivo de contexto gráfico se coloca en un estado perdido si el controlador devuelve este código de error.

Comentarios

El subsistema del kernel de gráficos directX llama a la función DxgkDdiRender del controlador de miniporte de pantalla para generar un búfer DMA desde el búfer de comandos que pasó el controlador de pantalla en modo de usuario. Cuando el controlador de minipuerto de pantalla se traduce del búfer de comandos al búfer DMA, el controlador también debe validar el búfer de comandos para asegurarse de que el búfer de comandos no contiene comandos con privilegios o comandos que se pueden usar para tener acceso a la memoria que no pertenece al proceso. Además del búfer DMA de salida, el controlador de minipuerto de pantalla también debe generar una lista de ubicaciones de revisión de salida. El administrador de memoria de vídeo usa esta lista para dividir y aplicar revisiones adecuadamente a los búferes DMA.

Tanto el búfer de comandos pCommand como la lista de revisiones de entrada pPatchLocationListIn que genera el controlador de pantalla en modo de usuario se asignan desde el espacio de direcciones del modo de usuario y se pasan al controlador de miniporte de pantalla sin modificar. El controlador de miniporte de pantalla debe usar __try/__except código en cualquier acceso al búfer y la lista y debe validar el contenido del búfer y la lista antes de copiar el contenido en los búferes de kernel respectivos (es decir, antes de copiar el contenido del miembro pCommand al miembro pDmaBuffer y el contenido del miembro pPatchLocationListIn al miembro pPatchLocationListOut , que son todos los miembros de la estructura DXGKARG_RENDER a la que apunta el parámetro pRender ).

Este es un ejemplo de cómo los controladores de minipuerto de visualización deben acceder a estos búferes mediante __try y __except lógica. AllocationListIn apunta al búfer en modo de usuario.

__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

El acceso a los búferes de kernel no requiere protección contra try/except el código.

El controlador de minipuerto de pantalla no es necesario para usar la información que proporciona el controlador de pantalla en modo de usuario si la recreación de la información es más óptima. Por ejemplo, si pPatchLocationListIn está vacío porque el controlador de pantalla en modo de usuario no proporcionó una lista de revisiones de revisión de entrada, el controlador de miniporte de pantalla puede generar el contenido de pPatchLocationListOut en función del contenido del búfer de comandos en su lugar.

La lista de asignación que proporciona el controlador de visualización en modo de usuario se valida, copia y convierte en una lista de asignación en modo kernel durante la transición del kernel. El subsistema del kernel de gráficos directX convierte cada elemento D3DDDI_ALLOCATIONLIST en un elemento DXGK_ALLOCATIONLIST convirtiendo el identificador con tipo D3DKMT_HANDLE que proporciona el controlador de pantalla en modo de usuario en un identificador específico del dispositivo, que devuelve la función DxgkDdiOpenAllocation del controlador de miniporte de pantalla. El índice de cada asignación y el estado de escritura de la asignación (es decir, el valor de la marca de campo de bits WriteOperation ) permanece constante durante la conversión.

Además del identificador específico del dispositivo, el subsistema del kernel de gráficos de DirectX proporciona el controlador de miniporte de pantalla con la última dirección de segmento de GPU conocida para cada asignación. Si el índice de asignación N se pagina actualmente, el subsistema del kernel de gráficos directX establece el miembro SegmentId del elemento Ndel miembro pAllocationList de DXGKARG_RENDER en cero. Si el miembro SegmentId del elemento Nºde la lista de asignación no está establecido en cero, el controlador de minipuerto de pantalla debe revisar previamente el búfer DMA generado con la información de dirección del segmento proporcionada. El controlador debe aplicar una revisión previa cuando se solicite porque es posible que el subsistema del kernel de gráficos de DirectX no llame a la función DxgkDdiPatch en un búfer DMA que el controlador debe tener correctamente revisado previamente.

Nota

Aunque la función DxgkDdiRender del controlador aplica revisiones previas al búfer DMA, el controlador debe seguir insertando todas las referencias a las asignaciones en la lista de ubicación de revisión de salida que especifica el miembro pPatchLocationListOut de DXGKARG_RENDER . Esta lista debe contener todas las referencias porque las direcciones de las asignaciones pueden cambiar antes de enviar el búfer DMA a la GPU; por lo tanto, el subsistema del kernel de gráficos de DirectX llamará a la función DxgkDdiPatch para volver a guardar el búfer DMA.

Para desenlazar una asignación, el controlador de minipuerto de pantalla puede especificar un elemento de la lista de asignación que haga referencia a un identificador NULL y, a continuación, puede usar un elemento patch-location que haga referencia a esa asignación NULL . Normalmente, el controlador debe usar el primer elemento de la lista de asignación (elemento 0) como elemento NULL .

Cuando el controlador de minipuerto de pantalla traduce un búfer de comandos a un búfer DMA, el controlador de minipuerto de pantalla y el controlador de pantalla en modo de usuario deben realizar las siguientes acciones para las situaciones siguientes:

En el modo DMA de contrato garantizado (para obtener más información, vea Using the Guaranteed Contract DMA Buffer Model), el controlador de pantalla en modo de usuario debe garantizar suficientes recursos para el comando de traducción. Si no existen suficientes recursos para la traducción, el controlador de minipuerto de pantalla debe rechazar el búfer DMA.
El controlador de pantalla en modo de usuario siempre debe dividir los comandos que pueden traducirse a más del tamaño de un único búfer DMA porque la función DxgkDdiRender del controlador de miniporte de pantalla no puede controlar un solo comando que sea mayor que el tamaño del búfer DMA y que no se pueda dividir.

DxgkDdiRender debe ser paginable.

La compatibilidad con la función DxgkDdiRenderKm se agregó a partir de Windows 7 para adaptadores de pantalla que admiten la aceleración de hardware GDI.