DXGKDDI_RENDERKM funzione di callback (d3dkmddi.h)

Articolo
02/06/2025

Per le schede di visualizzazione che supportano l'accelerazione hardware GDI, la funzione DxgkDdiRenderKm genera un buffer DMA (Direct Memory Access) dal buffer dei comandi passato dal driver cdD (Canonical Display Driver) in modalità kernel.

Sintassi

DXGKDDI_RENDERKM DxgkddiRenderkm;

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

Parametri

[in] hContext

Handle per il contesto del dispositivo per DMA e buffer dei comandi. La funzione di DxgkDdiCreateContext del driver miniport 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 per il dispositivo. La funzione dxgkDdiCreateDevice del driver del miniport di visualizzazione ha precedentemente restituito l'handle del dispositivo nel membro hDevice della struttura DXGKARG_CREATEDEVICE a cui punta il parametro pCreateDevice di DxgkDdiCreateDevice.

[in/out] pRenderKmArgs

Puntatore a una struttura DXGKARG_RENDER che contiene informazioni sul buffer DMA e su un buffer dei comandi formattato.

Se il driver miniport di visualizzazione supporta l'accelerazione hardware GDI, pRenderKmArgs->pCommand punta al buffer dei comandi DXGK_RENDERKM_COMMAND.

Il driver deve convertire il buffer dei comandi di input in comandi buffer DMA e compilare l'elenco dei percorsi delle patch.

Valore restituito

DxgkDdiRenderKm restituisce uno dei valori seguenti:

codice restituito	Descrizione
STATUS_SUCCESS	L'intero buffer dei comandi è stato convertito.
STATUS_NO_MEMORY	DxgkDdiRenderKm non è stato in grado di allocare memoria necessaria per il completamento.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Il buffer DMA corrente è esaurito.
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm rilevato parametri di istruzione non supportati dall'hardware grafico; 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	DxgkDdiRenderKm rilevati dati o istruzioni sottoposti a sovraccarico o sovraccarico. 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 sottoposti a sovraccarico o sovraccarico.
STATUS_INVALID_HANDLE	DxgkDdiRenderKm rilevato un handle non valido nel buffer dei comandi.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Il driver miniport di visualizzazione ha rilevato un errore nel flusso DMA. Il dispositivo di contesto grafico viene inserito in uno stato perso se il driver restituisce questo codice di errore.

Osservazioni

Il sottosistema kernel della grafica DirectX chiama la funzione dxgkDdiRenderKm del driver miniport di visualizzazione per generare un buffer DMA dal buffer dei comandi passato dal driver di visualizzazione canonico (CDD) in modalità kernel fornito dal sistema operativo. Oltre al buffer DMA di output, anche il driver miniport di visualizzazione dovrebbe generare un elenco di percorsi delle patch di output. Gestione memoria video usa questo elenco per suddividere e applicare patch ai buffer DMA in modo appropriato.

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

Il driver miniport di visualizzazione non è necessario per usare le informazioni fornite dal CDD se può ricreare le informazioni in modo ottimale. Ad esempio, se il pRender->membro pPatchLocationListIn è vuoto perché il driver di visualizzazione in modalità utente non ha fornito un elenco di percorsi patch di input, il driver miniport di visualizzazione può generare il contenuto del pRender->pPatchLocationListOut membro in base al contenuto del buffer dei comandi.

Oltre all'handle specifico del dispositivo, il sottosistema kernel grafico DirectX fornisce il driver miniport di visualizzazione con l'ultimo indirizzo del segmento GPU noto per ogni allocazione. Se l'indice di allocazione N è attualmente in fase di paging, il sottosistema kernel della grafica DirectX imposta il membro segmentid del Nelemento del pAllocationList membro di DXGKARG_RENDER su zero. Se il SegmentId membro del Nelemento dell'elenco di allocazioni non è impostato su zero, il driver del miniport di visualizzazione deve applicare patch al buffer DMA generato con le informazioni sull'indirizzo del segmento fornito prima che il sottosistema del kernel grafico DirectX chiami la funzione DxgkDdiPatch per recuperare il buffer DMA. Il driver deve eseguire questa patch iniziale quando richiesto perché il sottosistema del kernel grafico DirectX potrebbe non chiamare la funzione DxgkDdiPa tch in un buffer DMA che il driver deve avere correttamente patch.

Anche se la funzione di dxgkDdiRenderKm del driver esegue l'applicazione iniziale di patch del buffer DMA come descritto in precedenza, il driver deve comunque inserire tutti i riferimenti alle allocazioni nell'elenco dei percorsi patch di output specificati dal pPatchLocationListOut membro 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 funzionedxgkDdiPatchper recuperare il buffer DMA.

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

In modalità DMA del contratto garantita, quando il driver miniport di visualizzazione converte un buffer dei comandi in un buffer DMA, il CDD deve garantire risorse sufficienti per il comando di conversione. Se non esistono risorse sufficienti per la traduzione, il driver miniport di visualizzazione deve rifiutare il buffer DMA. Per altre informazioni, vedere Using the Guaranteed Contract DMA Buffer Model.

DxgkDdiRenderKm deve essere reso impaginabile.