DXGKDDI_RENDER Rückruffunktion (d3dkmddi.h)

Artikel
02/26/2024

Die DxgkDdiRender-Funktion generiert einen DMA-Puffer (Direct Memory Access) aus dem Befehlspuffer, den der Benutzermodusanzeigetreiber übergeben hat.

Syntax

DXGKDDI_RENDER DxgkddiRender;

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

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-Grafikkernsystem das Handle im 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 zeigt.

[in/out] pRender

Ein Zeiger auf eine DXGKARG_RENDER-Struktur , die Informationen zu den DMA- und Befehlspuffern enthält.

Rückgabewert

DxgkDdiRender gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der gesamte Befehlspuffer wurde übersetzt.
STATUS_NO_MEMORY	DxgkDdiRender konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Der aktuelle DMA-Puffer ist erschöpft.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender hat nicht privilegierte Anweisungen erkannt (d. h. Anweisungen, die über die Berechtigungen des aktuellen CPU-Prozesses hinaus auf den Arbeitsspeicher zugreifen).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender hat Anweisungen erkannt, die grafikhardware nicht unterstützen konnte.
STATUS_INVALID_PARAMETER	DxgkDdiRender hat Befehlsparameter erkannt, 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 Anweisungsparameter erkannt werden.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender hat erkannt, dass Daten oder Anweisungen unter- oder überlaufen wurden. Das heißt, der Treiber hat weniger oder mehr Anweisungen oder Daten als erwartet erhalten. 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	DxgkDdiRender hat ein ungültiges Handle im Befehlspuffer erkannt.
STATUS_GRAPHICS_DRIVER_MISMATCH	Der Anzeige-Miniporttreiber ist nicht kompatibel mit dem Benutzermodus-Anzeigetreiber, der den Aufruf von DxgkDdiRender initiiert hat (d. h. den Befehlspuffer übermittelt).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Der Anzeige-Miniporttreiber hat einen Fehler im DMA-Stream erkannt. Das Grafikkontextgerät wird in einen verlorenen Zustand versetzt, wenn der Treiber diesen Fehlercode zurückgibt.

Hinweise

Das DirectX-Grafikkernsubsystem ruft die DxgkDdiRender-Funktion des Anzeigeminiporttreibers auf, um einen DMA-Puffer aus dem Befehlspuffer zu generieren, den der Benutzermodusanzeigetreiber übergeben hat. Wenn der Anzeige-Miniporttreiber vom Befehlspuffer in den DMA-Puffer übersetzt wird, sollte der Treiber auch den Befehlspuffer überprüfen, um sicherzustellen, dass der Befehlspuffer keine privilegierten Befehle oder Befehle enthält, die für den Zugriff auf Arbeitsspeicher verwendet werden können, der nicht zum Prozess gehört. Zusätzlich zum DMA-Ausgabepuffer sollte der Anzeige-Miniporttreiber auch eine Liste der Ausgabepatchspeicherorte generieren. Der Videospeicher-Manager verwendet diese Liste, um DMA-Puffer entsprechend aufzuteilen und zu patchen.

Sowohl der Befehlspuffer pCommand als auch die eingabe patch-location list pPatchLocationListIn , die der Benutzermodusanzeigetreiber generiert, werden aus dem Adressraum des Benutzermodus zugeordnet und an den Anzeigeminiporttreiber unverändert übergeben. Der Anzeige-Miniporttreiber muss Code für jeden Zugriff auf den Puffer und die Liste verwenden __try/__except und den Inhalt des Puffers und der Liste überprüfen, bevor der Inhalt in die jeweiligen Kernelpuffer kopiert wird (d. a. vor dem Kopieren des Inhalts des pCommand-Elements in das pDmaBuffer-Element und des pPatchLocationListIn-Elements in das pPatchLocationListOut-Element , Dies sind alle Member der DXGKARG_RENDER Struktur, auf die der pRender-Parameter zeigt).

Hier sehen Sie ein Beispiel dafür, wie Anzeige-Miniporttreiber mithilfe __try von logik und __except auf diese Puffer zugreifen sollten. AllocationListIn verweist auf den Benutzermoduspuffer.

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

Hinweis

Für den Zugriff auf die Kernelpuffer ist kein Schutz vor try/except Code erforderlich.

Der Anzeige-Miniporttreiber muss keine Informationen verwenden, die der Benutzermodus-Anzeigetreiber bereitstellt, wenn die Neuerstellung der Informationen optimaler ist. Wenn z. B. pPatchLocationListIn leer ist, weil der Benutzermodusanzeigetreiber keine Eingabeliste für patch-location bereitgestellt hat, kann der Anzeige-Miniporttreiber den Inhalt von pPatchLocationListOut basierend auf dem Inhalt des Befehlspuffers generieren.

Die Zuordnungsliste, die der Anzeigetreiber für den Benutzermodus bereitstellt, wird während des Kernelübergangs überprüft, kopiert und in eine Kernelmoduszuordnungsliste konvertiert. Das DirectX-Grafikkernsubsystem konvertiert jedes D3DDDI_ALLOCATIONLIST Element in ein DXGK_ALLOCATIONLIST-Element , indem das D3DKMT_HANDLE typisierte Handle, das der Benutzermodusanzeigetreiber bereitstellt, in ein gerätespezifisches Handle konvertiert wird, das die DxgkDdiOpenAllocation-Funktion des Anzeigeminiporttreibers zurückgibt. Der Index jeder Zuordnung und der schreibgeschützte status der Zuordnung (d. h. die Einstellung des WriteOperation-Bitfeldflags) bleiben während der Konvertierung konstant.

Zusätzlich zum gerätespezifischen Handle stellt das DirectX-Grafikkernsubsystem dem Anzeige-Miniporttreiber die letzte bekannte GPU-Segmentadresse für jede Zuordnung bereit. Wenn der Zuordnungsindex N derzeit ausgelagert ist, legt das DirectX-Grafikkernsubsystem das SegmentId-Element des Nth-Elements des pAllocationList-Elements von DXGKARG_RENDER auf Null fest. Wenn das SegmentId-Element des N-tenElements der Zuordnungsliste nicht auf 0 festgelegt ist, muss der Anzeige-Miniporttreiber den generierten DMA-Puffer vorab mit den angegebenen Segmentadressinformationen patchen. Der Treiber muss auf Anforderung vorab gepatcht werden, da das DirectX-Grafikkernsubsystem die DxgkDdiPatch-Funktion möglicherweise nicht für einen DMA-Puffer aufruft, den der Treiber ordnungsgemäß vorgepatcht haben sollte.

Hinweis

Obwohl die DxgkDdiRender-Funktion des Treibers den DMA-Puffer vorab patcht, muss der Treiber trotzdem alle Verweise auf Zuordnungen in die Ausgabe-Patchspeicherortliste einfügen, die das pPatchLocationListOut-Element 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.

Um die Bindung einer Zuordnung aufzuheben, kann der Anzeige-Miniporttreiber 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 Anzeige-Miniporttreiber einen Befehlspuffer in einen DMA-Puffer übersetzt, sollten der Anzeige-Miniporttreiber und der Benutzermodusanzeigetreiber die folgenden Aktionen für die folgenden Situationen ausführen:

Im garantierten Vertrags-DMA-Modus (weitere Informationen finden Sie unter Verwenden des DMA-Puffermodells für garantierte Verträge) muss der Anzeigetreiber im Benutzermodus 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.
Der Anzeigetreiber für den Benutzermodus sollte immer Befehle aufteilen, die möglicherweise in mehr als die Größe eines einzelnen DMA-Puffers übersetzt werden können, da die DxgkDdiRender-Funktion des Anzeigeminiporttreibers keinen einzelnen Befehl verarbeiten kann, der größer als die Größe des DMA-Puffers ist und nicht aufgeteilt werden kann.

DxgkDdiRender sollte ausgelagert werden.

Unterstützung für die DxgkDdiRenderKm-Funktion wurde ab Windows 7 für Grafikkarten hinzugefügt, die die GDI-Hardwarebeschleunigung unterstützen.