DXGKDDI_RENDER funzione di callback (d3dkmddi.h)

Articolo
08/07/2023

La funzione DxgkDdiRender genera un buffer DMA (Direct Memory Access) dal buffer di comando passato dal driver di visualizzazione in modalità utente.

Sintassi

DXGKDDI_RENDER DxgkddiRender;

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

Parametri

[in] hContext

Handle al contesto del dispositivo per i buffer dei comandi e DMA. La funzione DxgkDdiCreateContext del driver di visualizzazione ha restituito in precedenza questo handle nel membro hContext della struttura DXGKARG_CREATECONTEXT a cui punta il parametro pCreateContext di DxgkDdiCreateContext .

Se il driver non supporta la creazione del contesto, il sottosistema kernel della grafica Microsoft DirectX sostituisce l'handle nel contesto con un handle al dispositivo. La funzione DxgkDdiCreateDevice del driver di visualizzazione ha restituito in precedenza l'handle del dispositivo nel membro hDevice della struttura DXGKARG_CREATEDEVICE a cui punta il parametro pCreateDevice di DxgkDdiCreateDevice.

[in/out] pRender

Puntatore a una struttura DXGKARG_RENDER che contiene informazioni sui buffer di comando e DMA.

Valore restituito

DxgkDdiRender restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'intero buffer dei comandi è stato convertito.
STATUS_NO_MEMORY	DxgkDdiRender non è stato in grado di allocare memoria necessaria per il completamento.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Il buffer DMA corrente è esaurito.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender ha rilevato istruzioni non privilegiate, ovvero istruzioni che accedono alla memoria oltre il privilegio del processo di elaborazione centrale corrente [CPU].
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender ha rilevato istruzioni che l'hardware grafico non è riuscito a supportare.
STATUS_INVALID_PARAMETER	DxgkDdiRender ha rilevato parametri di istruzione che l'hardware grafico non è riuscito a supportare; tuttavia, l'hardware grafico può supportare le istruzioni stesse. Il driver non è necessario per restituire questo codice di errore. Può invece restituire STATUS_ILLEGAL_INSTRUCTION quando rileva parametri di istruzione non supportati.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender ha rilevato dati o istruzioni in esecuzione o overrun. Ovvero, il driver ha ricevuto meno o più istruzioni o dati del previsto. Il driver non è necessario per restituire questo codice di errore. Può invece restituire STATUS_ILLEGAL_INSTRUCTION quando rileva dati o istruzioni in esecuzione o overrun.
STATUS_INVALID_HANDLE	DxgkDdiRender ha rilevato un handle non valido nel buffer dei comandi.
STATUS_GRAPHICS_DRIVER_MISMATCH	Il driver miniport visualizzato non è compatibile con il driver di visualizzazione in modalità utente che ha avviato la chiamata a DxgkDdiRender (ovvero, inviato il buffer dei comandi).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Il driver miniport visualizzato ha rilevato un errore nel flusso DMA. Il dispositivo contesto grafico viene inserito in uno stato perso se il driver restituisce questo codice di errore.

Commenti

Il sottosistema kernel della grafica DirectX chiama la funzione dxgkDdiRender del driver di visualizzazione per generare un buffer DMA dal buffer di comando passato dal driver di visualizzazione in modalità utente. Quando il driver miniport visualizzato converte dal buffer dei comandi al buffer DMA, il driver deve anche convalidare il buffer dei comandi per assicurarsi che il buffer dei comandi non contenga comandi o comandi con privilegi che possono essere usati per accedere alla memoria che non appartiene al processo. Oltre al buffer DMA di output, il driver miniport visualizzato deve generare anche un elenco di posizioni delle patch di output. Gestione memoria video usa questo elenco per dividere e applicare patch ai buffer DMA in modo appropriato.

Sia il buffer dei comandi pCommand che l'elenco di patch di input pPatchLocationListIn che il driver di visualizzazione in modalità utente genera vengono allocati dallo spazio indirizzi in modalità utente e vengono passati al driver miniport visualizzato non modificato. Il driver miniport visualizzato deve usare __try/__except il codice per qualsiasi accesso al buffer e all'elenco e deve convalidare il contenuto del buffer e dell'elenco prima di copiare il contenuto nei rispettivi buffer del kernel, ovvero prima di copiare il contenuto del membro pCommand nel membro pDmaBuffer e il contenuto del membro pPatchLocationListIn al membro pPatchLocationListOut, che sono tutti membri della struttura DXGKARG_RENDER a cui punta il parametro pRender.

Ecco un esempio di come visualizzare i driver miniport devono accedere a questi buffer usando __try e __except logica. AllocationListIn punta al buffer in modalità utente.

__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

L'accesso ai buffer del kernel non richiede la protezione dal try/except codice.

Il driver miniport visualizzato non è necessario per usare le informazioni fornite dal driver di visualizzazione in modalità utente se si ricreano le informazioni è più ottimale. Ad esempio, se pPatchLocationListIn è vuoto perché il driver di visualizzazione in modalità utente non ha fornito un elenco di patch di input, il driver miniport visualizzato può generare il contenuto di pPatchLocationListOut in base al contenuto del buffer dei comandi.

L'elenco di allocazione fornito dal driver di visualizzazione in modalità utente viene convalidato, copiato e convertito in un elenco di allocazioni in modalità kernel durante la transizione del kernel. Il sottosistema kernel della grafica DirectX converte ogni elemento D3DDDI_ALLOCATIONLIST in un elemento DXGK_ALLOCATIONLIST convertendo l'handle D3DKMT_HANDLE tipizzato fornito dal driver di visualizzazione in modalità utente in un handle specifico del dispositivo, che viene restituito dalla funzione DxgkDdiOpenAllocation del driver di visualizzazione. L'indice di ogni allocazione e lo stato di scrittura dell'allocazione, ovvero l'impostazione del flag di campo di bit WriteOperation , rimane costante durante la conversione.

Oltre all'handle specifico del dispositivo, il sottosistema del kernel grafico DirectX fornisce il driver miniport visualizzato con l'ultimo indirizzo del segmento GPU noto per ogni allocazione. Se l'indice di allocazione N è attualmente in pagina, il sottosistema del kernel grafico DirectX imposta il membro SegmentId dell'elemento Ndel membro pAllocationList di DXGKARG_RENDER su zero. Se il membro SegmentId dell'elemento Ndell'elenco di allocazione non è impostato su zero, il driver miniport visualizzato deve eseguire la pre-patch del buffer DMA generato con le informazioni sull'indirizzo del segmento specificato. Il driver deve eseguire la pre-patch quando richiesto perché il sottosistema del kernel di grafica DirectX potrebbe non chiamare la funzione DxgkDdiPatch in un buffer DMA che il driver deve avere pre-patch corretto.

Nota

Anche se la funzione DxgkDdiRender del driver pre-patch il buffer DMA, il driver deve comunque inserire tutti i riferimenti alle allocazioni nell'elenco di patch di output specificato dal membro pPatchLocationListOut di DXGKARG_RENDER . Questo elenco deve contenere tutti i riferimenti perché gli indirizzi delle allocazioni potrebbero cambiare prima che il buffer DMA venga inviato alla GPU; pertanto, il sottosistema kernel della grafica DirectX chiamerà la funzione DxgkDdiPatch per eseguire il repository del buffer DMA.

Per annullare l'associazione di un'allocazione, il driver miniport visualizzato può specificare un elemento nell'elenco di allocazione che fa riferimento a un handle NULL e quindi può usare un elemento patch-location che fa riferimento all'allocazione NULL . In genere, il driver deve usare il primo elemento dell'elenco di allocazione (elemento 0) come elemento NULL .

Quando il driver miniport visualizzato converte un buffer di comandi in un buffer DMA, il driver di visualizzazione in modalità miniport e il driver di visualizzazione in modalità utente devono eseguire le azioni seguenti per le situazioni seguenti:

In modalità DMA del contratto garantito (per altre informazioni, vedere Uso del modello buffer DMA contratto garantito), il driver di visualizzazione in modalità utente deve garantire risorse sufficienti per il comando di traduzione. Se per la traduzione non esistono risorse sufficienti, il driver miniport visualizzato deve rifiutare il buffer DMA.
Il driver di visualizzazione in modalità utente deve sempre suddividere i comandi che potrebbero essere convertiti in più delle dimensioni di un singolo buffer DMA perché la funzione DxgkDdiRender del driver di visualizzazione non può gestire un singolo comando maggiore delle dimensioni del buffer DMA e che non può essere suddiviso.

DxgkDdiRender deve essere reso paginabile.

Il supporto per la funzione DxgkDdiRenderKm è stato aggiunto a partire da Windows 7 per schede di visualizzazione che supportano l'accelerazione hardware GDI.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows Vista
Piattaforma di destinazione	Desktop
Intestazione	d3dkmddi.h
IRQL	PASSIVE_LEVEL