DXGKDDI_RENDERKM Rückruffunktion (d3dkmddi.h)

Artikel
06.02.2025

Für Grafikkarten, die die GDI-Hardwarebeschleunigung unterstützen, generiert die DxgkDdiRenderKm--Funktion einen DMA-Puffer (Direct Memory Access) aus dem Befehlspuffer, den der kernelmodus (Canonical Display Driver, CDD) übergeben hat.

Syntax

DXGKDDI_RENDERKM DxgkddiRenderkm;

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

Parameter

[in] hContext

Ein Handle für den Gerätekontext für die DMA- und Befehlspuffer. Die DxgkDdiCreateContext-Funktion des Anzeigeminiporttreibers dieses Handle zuvor im hContext Element der DXGKARG_CREATECONTEXT Struktur zurückgegeben, auf die der pCreateContext Parameter von DxgkDdiCreateContext verweist.

Wenn der Treiber die Kontexterstellung nicht unterstützt, ersetzt das Microsoft DirectX-Grafik-Kernel-Subsystem das Handle in den Kontext durch ein Handle für das Gerät. Die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers hat zuvor den Gerätehandle im hDevice- Member der DXGKARG_CREATEDEVICE Struktur zurückgegeben, auf die der pCreateDevice Parameter von DxgkDdiCreateDevice verweist.

[in/out] pRenderKmArgs

Ein Zeiger auf eine DXGKARG_RENDER Struktur, die Informationen zum DMA-Puffer und einen formatierten Befehlspuffer enthält.

Wenn der Miniporttreiber die GDI-Hardwarebeschleunigung unterstützt, pRenderKmArgs–>pCommand- verweist auf den DXGK_RENDERKM_COMMAND Befehlspuffer.

Der Treiber muss den Eingabebefehlspuffer in DMA-Pufferbefehle übersetzen und die Patchspeicherortliste erstellen.

Rückgabewert

DxgkDdiRenderKm gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der gesamte Befehlspuffer wurde übersetzt.
STATUS_NO_MEMORY	DxgkDdiRenderKm- konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Der aktuelle DMA-Puffer ist erschöpft.
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm anweisungsparameter erkannt, die grafikhardware nicht unterstützt werden konnte; Die Grafikhardware kann jedoch die Anweisungen selbst unterstützen. Der Treiber ist nicht erforderlich, um diesen Fehlercode zurückzugeben. Stattdessen kann sie STATUS_ILLEGAL_INSTRUCTION zurückgeben, wenn nicht unterstützte Anweisungsparameter erkannt werden.
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm erkannten Daten oder Anweisungen unterlaufen oder überlaufen. Das heißt, der Treiber hat weniger oder mehr Anweisungen oder Daten erhalten als erwartet. Der Treiber ist nicht erforderlich, um diesen Fehlercode zurückzugeben. Stattdessen kann STATUS_ILLEGAL_INSTRUCTION zurückgegeben werden, wenn Daten oder Anweisungen erkannt werden, die unterlaufen oder überlaufen werden.
STATUS_INVALID_HANDLE	DxgkDdiRenderKm ein ungültiges Handle im Befehlspuffer erkannt.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Der Anzeigeminiporttreiber hat einen Fehler im DMA-Datenstrom erkannt. Das Grafikkontextgerät wird in einen verlorenen Zustand versetzt, wenn der Treiber diesen Fehlercode zurückgibt.

Bemerkungen

Das DirectX-Grafik-Kernel-Subsystem ruft die DxgkDdiRenderKm--Funktion des Anzeigeminiporttreibers auf, um einen DMA-Puffer aus dem Befehlspuffer zu generieren, der vom vom Betriebssystem bereitgestellten Kernelmodus-Anzeigetreiber (Canonical Display Driver, CDD) übergeben wird. Zusätzlich zum Ausgabe-DMA-Puffer sollte der Anzeige-Miniporttreiber auch eine Liste der Ausgabepatchspeicherorte generieren. Der Videospeicher-Manager verwendet diese Liste, um DMA-Puffer entsprechend aufzuteilen und zu patchen.

Der Zugriff auf die Kernelpuffer erfordert keinen Schutz vor try/except Code.

Der Miniporttreiber für die Anzeige ist nicht erforderlich, um Informationen zu verwenden, die der CDD bereitstellt, wenn er die Informationen optimaler erstellen kann. Wenn beispielsweise der pRender->pPatchLocationListIn Member leer ist, da der Anzeigetreiber für den Benutzermodus keine Eingabepatchspeicherortliste bereitgestellt hat, kann der Miniporttreiber den Inhalt des pRender-generieren –>pPatchLocationListOut Member basierend auf dem Inhalt des Befehlspuffers.

Zusätzlich zum gerätespezifischen Handle stellt das DirectX-Grafik-Kernel-Subsystem den Anzeige-Miniporttreiber mit der letzten bekannten GPU-Segmentadresse für jede Zuordnung bereit. Wenn der Zuordnungsindex N- zurzeit ausgelagert wird, legt das DirectX-Grafik-Kernelsubsystem den SegmentId Member des Nth-Elements des pAllocationList Member von DXGKARG_RENDER auf Null fest. Wenn das SegmentId Mitglied des Nth-Elements der Zuordnungsliste nicht auf Null festgelegt ist, muss der Anzeigeminiporttreiber den generierten DMA-Puffer mit den bereitgestellten Abschnittsadresseninformationen patchen, bevor das DirectX-Grafikkernsubsystem die DxgkDdiPatch--Funktion aufruft, um den DMA-Puffer neu zu beheben. Der Treiber muss dieses anfängliche Patching ausführen, wenn er angefordert wird, da das DirectX-Grafik-Kernelsubsystem möglicherweise nicht die DxgkDdiPatch--Funktion in einem DMA-Puffer aufruft, den der Treiber ordnungsgemäß gepatcht haben sollte.

Obwohl die DxgkDdiRenderKm-Funktion des Treibers die anfängliche DMA-Pufferpatching wie zuvor beschrieben durchführt, muss der Treiber weiterhin alle Verweise auf Zuordnungen in die Ausgabepatch-Location-Liste einfügen, die das pPatchLocationListOut Mitglied von DXGKARG_RENDER angibt. Diese Liste muss alle Verweise enthalten, da sich die Adressen der Zuordnungen ändern können, bevor der DMA-Puffer an die GPU übermittelt wird; Daher ruft das DirectX-Grafik-Kernelsubsystem die DxgkDdiPatch--Funktion auf, um den DMA-Puffer neu zu patchen.

Um eine Zuordnung aufzuheben, kann der Anzeigeminiporttreiber ein Element in der Zuordnungsliste angeben, das auf ein NULL- Handle verweist, und dann ein Patchspeicherortelement verwenden, das auf NULL Zuordnung verweist. In der Regel sollte der Treiber das erste Element der Zuordnungsliste (Element 0) als NULL--Element verwenden.

Wenn der Anzeige-Miniporttreiber im garantierten Vertrags-DMA-Modus einen Befehlspuffer in einen DMA-Puffer übersetzt, muss die CDD genügend Ressourcen für den Übersetzungsbefehl garantieren. Wenn für die Übersetzung nicht genügend Ressourcen vorhanden sind, muss der Anzeige-Miniporttreiber den DMA-Puffer ablehnen. Weitere Informationen finden Sie unter Using the Guaranteed Contract DMA Buffer Model.

DxgkDdiRenderKm sollte seitenfähig gemacht werden.