функция обратного вызова DXGKDDI_RENDER (d3dkmddi.h)

Статья
02/26/2024

Функция DxgkDdiRender создает буфер прямого доступа к памяти (DMA) из буфера команд, переданного драйвером отображения пользовательского режима.

Синтаксис

DXGKDDI_RENDER DxgkddiRender;

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

Параметры

[in] hContext

Дескриптор контекста устройства для буферов DMA и команд. Функция DxgkDdiCreateContext драйвера miniport для отображения ранее возвращала этот дескриптор в элементе hContextструктуры DXGKARG_CREATECONTEXT , на которую указывает параметр pCreateContextобъекта DxgkDdiCreateContext .

Если драйвер не поддерживает создание контекста, подсистема ядра графики Microsoft DirectX заменяет дескриптор контекста дескриптором для устройства. Функция DxgkDdiCreateDevice драйвера мини-порта дисплея ранее возвращала дескриптор устройства в элементе hDeviceструктуры DXGKARG_CREATEDEVICE , на которую указывает параметр pCreateDeviceобъекта DxgkDdiCreateDevice .

[in/out] pRender

Указатель на структуру DXGKARG_RENDER , содержащую сведения о DMA и буферах команд.

Возвращаемое значение

DxgkDdiRender возвращает одно из следующих значений:

Код возврата	Описание
STATUS_SUCCESS	Был переведен весь буфер команд.
STATUS_NO_MEMORY	DxgkDdiRender не удалось выделить память, необходимую для ее завершения.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Текущий буфер DMA исчерпан.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender обнаружил непривилегированные инструкции (т. е. инструкции, которые получают доступ к памяти за пределами привилегий текущего процесса центрального процессора [ЦП]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender обнаружил инструкции, которые не поддерживает графическое оборудование.
STATUS_INVALID_PARAMETER	DxgkDdiRender обнаружил параметры инструкций, которые не поддерживает графическое оборудование; однако графическое оборудование может поддерживать сами инструкции. Драйвер не обязан возвращать этот код ошибки. Вместо этого он может возвращать STATUS_ILLEGAL_INSTRUCTION при обнаружении неподдерживаемых параметров инструкций.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender обнаружил данные или инструкции, которые были недостаточно запущены или перезагрущены. То есть драйвер получил меньше или больше инструкций или данных, чем ожидалось. Драйвер не обязан возвращать этот код ошибки. Вместо этого он может возвращать STATUS_ILLEGAL_INSTRUCTION при обнаружении данных или инструкций, недостаточно запущенных или переполненных.
STATUS_INVALID_HANDLE	DxgkDdiRender обнаружил недопустимый дескриптор в буфере команд.
STATUS_GRAPHICS_DRIVER_MISMATCH	Драйвер мини-порта дисплея несовместим с драйвером отображения пользовательского режима, который инициировал вызов DxgkDdiRender (то есть отправил буфер команд).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Драйвер мини-порта дисплея обнаружил ошибку в потоке DMA. Если драйвер возвращает этот код ошибки, устройство графического контекста помещается в потерянное состояние.

Подсистема графического ядра DirectX вызывает функцию DxgkDdiRender драйвера мини-порта дисплея для создания буфера DMA из буфера команд, переданного драйвером отображения пользовательского режима. Когда драйвер мини-порта отображения преобразуется из буфера команд в буфер DMA, драйвер также должен проверить буфер команд, чтобы убедиться, что буфер команд не содержит привилегированных команд или команд, которые можно использовать для доступа к памяти, которая не принадлежит процессу. Помимо выходного буфера DMA, драйвер мини-порта дисплея также должен создавать список расположений выходного исправления. Диспетчер видеопамятки использует этот список для правильного разделения и исправления буферов DMA.

И буфер команд pCommand , и входной список исправлений pPatchLocationListIn , создаваемый драйвером отображения пользовательского режима, выделяются из адресного пространства пользовательского режима и передаются драйверу мини-порта дисплея без изменения. Драйвер мини-порта отображения должен использовать __try/__except код при любом доступе к буферу и списку и проверять содержимое буфера и списка перед копированием содержимого в соответствующие буферы ядра (то есть перед копированием содержимого элемента pCommand в элемент pDmaBuffer и содержимого элемента pPatchLocationListIn в элемент pPatchLocationListOut . которые являются членами структуры DXGKARG_RENDER , на которую указывает параметр pRender ).

Ниже приведен пример того, как драйверы мини-порта для отображения должны обращаться к этим буферам с помощью __try логики и __except . AllocationListIn указывает на буфер пользовательского режима.

__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;
  }

Примечание

Доступ к буферам ядра не требует защиты от try/except кода.

Драйвер мини-порта дисплея не требуется для использования сведений, которые предоставляет драйвер дисплея пользовательского режима, если повторное создание информации является более оптимальным. Например, если pPatchLocationListIn пуст, так как драйвер отображения в пользовательском режиме не предоставил входной список расположения исправлений, драйвер мини-порта дисплея может создать содержимое pPatchLocationListOut на основе содержимого буфера команд.

Список выделения, предоставляемый драйвером отображения пользовательского режима, проверяется, копируется и преобразуется в список выделения в режиме ядра во время перехода ядра. Подсистема графического ядра DirectX преобразует каждый элемент D3DDDI_ALLOCATIONLIST в элемент DXGK_ALLOCATIONLIST путем преобразования D3DKMT_HANDLE типизированного дескриптора, предоставляемого драйвером отображения пользовательского режима, в дескриптор для конкретного устройства, который возвращает функция DxgkDdiOpenAllocation драйвера мини-порта дисплея. Индекс каждого выделения и состояние записи выделения (т. е. параметр флага битового поля WriteOperation ) остаются постоянными во время преобразования.

В дополнение к дескриптору для конкретного устройства подсистема ядра графики DirectX предоставляет драйверу мини-порта дисплея последний известный адрес сегмента GPU для каждого выделения. Если индекс распределения N в настоящее время выстраивать, подсистема графического ядра DirectX устанавливает элемент SegmentIdN-гоэлемента элемента pAllocationListDXGKARG_RENDER равным нулю. Если элемент SegmentIdN-гоэлемента списка выделения не равен нулю, драйвер мини-порта дисплея должен предварительно исправить созданный буфер DMA указанными сведениями об адресе сегмента. По запросу драйвер должен быть предварительно исправлен, так как подсистема графического ядра DirectX может не вызывать функцию DxgkDdiPatch в буфере DMA, который драйвер должен правильно предварительно исправить.

Примечание

Несмотря на то, что функция DxgkDdiRender драйвера предварительно исправляет буфер DMA, драйвер должен по-прежнему вставлять все ссылки на выделения в выходной список расположений исправлений, указанный членом pPatchLocationListOutDXGKARG_RENDER . Этот список должен содержать все ссылки, так как адреса выделений могут измениться до отправки буфера DMA в GPU; Поэтому подсистема ядра графики DirectX вызовет функцию DxgkDdiPatch для повторного исправления буфера DMA.

Чтобы отменить привязку выделения, драйвер мини-порта отображения может указать элемент в списке выделения, который ссылается на дескриптор NULL , а затем использовать элемент patch-location, который ссылается на это выделение NULL . Как правило, драйвер должен использовать первый элемент списка выделения (элемент 0) в качестве элемента NULL .

Когда драйвер мини-порта дисплея преобразует буфер команд в буфер DMA, драйвер мини-порта дисплея и драйвер дисплея в пользовательском режиме должны выполнять следующие действия в следующих ситуациях:

В режиме DMA с гарантированным контрактом (дополнительные сведения см. в разделе Использование модели буфера DMA с гарантированным контрактом) драйвер отображения пользовательского режима должен гарантировать достаточно ресурсов для выполнения команды преобразования. Если для преобразования недостаточно ресурсов, драйвер мини-порта дисплея должен отклонить буфер DMA.
Драйвер отображения пользовательского режима всегда должен разделять команды, которые могут преобразоваться в размер, превышающий размер одного буфера DMA, так как функция DxgkDdiRender драйвера мини-порта дисплея не может обрабатывать одну команду, которая больше размера буфера DMA и которую нельзя разделить.

DxgkDdiRender следует сделать страничной.

Начиная с Windows 7 добавлена поддержка функции DxgkDdiRenderKm для адаптеров дисплея, поддерживающих аппаратное ускорение GDI.

Требования

Требование	Значение
Минимальная версия клиента	Доступно, начиная с Windows Vista
Целевая платформа	Персональный компьютер
Верхняя часть	d3dkmddi.h
IRQL	PASSIVE_LEVEL