DXGKDDI_RENDERKM Rückruffunktion (d3dkmddi.h)

Artikel
06/10/2023

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 hat 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-Grafikkernsubsystem das Handle durch den Kontext durch ein Handle für das Gerät. Die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers hat zuvor das Gerätehandle im hDevice-Element 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 Anzeigeminiporttreiber die GDI-Hardwarebeschleunigung unterstützt, verweist pRenderKmArgs-pCommand> 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 die Vervollständigung erforderlich war.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Der aktuelle DMA-Puffer ist erschöpft.
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm erkannte Befehlsparameter, die Grafikhardware nicht unterstützen konnte; Die Grafikhardware kann jedoch die Anweisungen selbst unterstützen. Der Treiber ist nicht erforderlich, um diesen Fehlercode zurückzugeben. Stattdessen kann STATUS_ILLEGAL_INSTRUCTION zurückgegeben werden, wenn nicht unterstützte Befehlsparameter erkannt werden.
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm erkannte, dass Daten oder Anweisungen unter- oder überlaufen wurden. Das heißt, der Treiber erhielt weniger oder mehr Anweisungen oder Daten 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 unter- oder überlaufen werden.
STATUS_INVALID_HANDLE	DxgkDdiRenderKm hat ein ungültiges Handle im Befehlspuffer erkannt.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Der Anzeigeminiporttreiber hat einen Fehler im DMA-Stream erkannt. Das Grafikkontextgerät befindet sich in einem verlorenen Zustand, wenn der Treiber diesen Fehlercode zurückgibt.

Hinweise

Das DirectX-Grafikkernsubsystem ruft die DxgkDdiRenderKm-Funktion des Anzeigeminiporttreibers auf, um einen DMA-Puffer aus dem Befehlspuffer zu generieren, der vom vom Betriebssystem bereitgestellten CdD (Canonical Display Driver) im Kernelmodus übergeben wird. Zusätzlich zum Ausgabe-DMA-Puffer sollte der Anzeigeminiporttreiber 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 Codeschutz try/except .

Der Anzeigeminiporttreiber muss keine Informationen verwenden, die der CDD bereitstellt, wenn er die Informationen optimaler neu erstellen kann. Wenn der pRender-pPatchLocationListIn-Member> beispielsweise leer ist, weil der Benutzermodusanzeigetreiber keine Eingabepatch-Location-Liste bereitgestellt hat, kann der Anzeigeminiporttreiber stattdessen den Inhalt des pRender-pPatchLocationListOut-Members> basierend auf dem Inhalt des Befehlspuffers generieren.

Zusätzlich zum gerätespezifischen Handle stellt das DirectX-Grafikkernsubsystem dem Display-Miniporttreiber die letzte bekannte GPU-Segmentadresse für jede Zuordnung zur Verfügung. Wenn der Zuordnungsindex N derzeit ausgelagert ist, legt das DirectX-Grafikkernsubsystem das SegmentId-Element des Nth-Elements des pAllocationList-Elements von DXGKARG_RENDER auf 0 fest. Wenn das SegmentId-Element des Nth-Elements der Zuordnungsliste nicht auf Null festgelegt ist, muss der Anzeigeminiporttreiber den generierten DMA-Puffer mit den angegebenen Segmentadresseninformationen patchen, bevor das DirectX-Grafikkernsubsystem die DxgkDdiPatch-Funktion aufruft, um den DMA-Puffer erneut zu patchen. Der Treiber muss dieses anfängliche Patching ausführen, wenn er angefordert wird, da das DirectX-Grafikkernsubsystem möglicherweise die DxgkDdiPatch-Funktion für einen DMA-Puffer nicht aufruft, den der Treiber ordnungsgemäß gepatcht haben sollte.

Obwohl die DxgkDdiRenderKm-Funktion des Treibers das anfängliche DMA-Pufferpatching wie weiter oben beschrieben ausführt, muss der Treiber dennoch 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-Grafikkernsubsystem die DxgkDdiPatch-Funktion auf, um den DMA-Puffer erneut zu patchen.

Zum Aufheben der Bindung einer Zuordnung kann der Anzeigeminiporttreiber ein Element in der Zuordnungsliste angeben, das auf ein NULL-Handle verweist, und dann ein Patch-Location-Element verwenden, das auf diese NULL-Zuordnung verweist. In der Regel sollte der Treiber das erste Element der Zuordnungsliste (Element 0) als NULL-Element verwenden.

Wenn der Anzeigeminiporttreiber im garantierten Vertrags-DMA-Modus einen Befehlspuffer in einen DMA-Puffer übersetzt, muss der CDD genügend Ressourcen für den Übersetzungsbefehl garantieren. Wenn nicht genügend Ressourcen für die Übersetzung vorhanden sind, muss der Anzeigeminiporttreiber den DMA-Puffer ablehnen. Weitere Informationen finden Sie unter Verwenden des DMA-Puffermodells für garantierte Verträge.

DxgkDdiRenderKm sollte seitenfähig gemacht werden.