Esecuzione di query sul supporto e l'abilitazione delle funzionalità WDDM
Questo articolo descrive come eseguire query sul supporto e l'abilitazione delle funzionalità wdDM (Windows Display Driver Model). Descrive:
- In che modo i driver di visualizzazione in modalità utente e in modalità kernel (UMD e KMD) possono eseguire query sul sistema operativo per determinare se una funzionalità WDDM è supportata e abilitata in un sistema.
- Come il sistema operativo può determinare se un driver supporta una particolare funzionalità WDDM.
Questo meccanismo di query di funzionalità è stato introdotto a partire da Windows 11 versione 24H2 (WDDM 3.2).
Panoramica delle funzionalità di WDDM
WDDM può essere visualizzato come una raccolta di funzionalità, in cui una funzionalità è una raccolta di API WDDM/DDI che coprono determinate funzionalità.
Una funzionalità viene identificata dal relativo ID funzionalità, costituito da un ID categoria e da un ID secondario per la funzionalità stessa all'interno della categoria.
Ogni funzionalità nota al sistema operativo include informazioni sullo stato associate per determinare se la funzionalità è supportata e/o abilitata nel sistema. Alcune funzionalità possono essere funzionalità del driver. Per abilitare una funzionalità driver è necessario un certo livello di supporto del driver. Dxgkrnl fornisce un meccanismo di handshaking per determinare la configurazione delle funzionalità. Una chiave del Registro di sistema può eseguire l'override della configurazione delle funzionalità in base alle funzionalità per ogni adattatore.
Le funzionalità del driver possono anche avere un'interfaccia di funzionalità che fornisce le DDI del driver correlate alla funzionalità. Supportando singole interfacce di funzionalità, non è più necessario basarsi sull'aggiornamento delle interfacce principali tra il sistema operativo e il KmD, che in precedenza poteva essere espanso solo con le modifiche aggiornate del controllo delle versioni WDDM. Questo approccio offre un mezzo più flessibile per il backporting delle funzionalità ai sistemi operativi precedenti o tramite le versioni moment di Windows senza la necessità di definire un supporto speciale.
Ogni funzionalità può avere un elenco di dipendenze che devono essere supportate anche come prerequisito. Le funzionalità future che richiedono tali dipendenze indicherà le dipendenze necessarie nella relativa documentazione.
Le funzionalità sono con controllo delle versioni e possono avere interfacce o configurazioni diverse per ogni versione supportata.
WDDM introduce un set di API per eseguire query su uno stato di funzionalità specifico. Le API includono:
-
- KmD può eseguire query e usare questa interfaccia per determinare se una particolare funzionalità è supportata e abilitata nel sistema dopo la chiamata di DxgkDdiStartDevice.
- Questo meccanismo sostituisce le DDI esistenti seguenti:
-
- Questo meccanismo consente al sistema operativo di eseguire query su un'interfaccia di funzionalità dal KmD.
-
- Questa funzione è il punto di ingresso nella libreria displib fornita dal sistema.
- KMD può chiamare DxgkIsFeatureEnabled2 dalla routine DriverEntry senza inizializzare Dxgkrnl per determinare se il sistema dispone di una particolare funzionalità abilitata.
-
- Questa API in modalità utente consente a un modulo in modalità utente di determinare se una determinata funzionalità è abilitata.
Quando viene caricato un driver miniport di visualizzazione, il driver di porta WDDM esegue una query su tutte le funzionalità che dipendono dal supporto dei driver.
Il driver può eseguire una query sul driver di porta WDDM per le funzionalità supportate quando viene caricato.
Definizioni di funzionalità WDDM
Una funzionalità viene identificata dal relativo ID funzionalità, rappresentato come valore DXGK_FEATURE_ID . Un valore DXGK_FEATURE_ID ha il formato seguente:
- L'ID categoria della funzionalità è un valore DXGK_FEATURE_CATEGORY che identifica la categoria della funzionalità. Viene archiviato nei 4 bit superiori di DXGK_FEATURE_ID.
- ID secondario della funzionalità che identifica la funzionalità effettiva all'interno della categoria di funzionalità. L'ID secondario viene archiviato nei 28 bit inferiori di DXGK_FEATURE_ID.
Quando DXGK_FEATURE_CATEGORY è DXGK_FEATURE_CATEGORY_DRIVER, l'ID secondario della funzionalità è un valore DXGK_DRIVER_FEATURE che identifica la funzionalità effettiva.
Funzionalità globali di vs adapter
Le singole funzionalità corrispondono a una funzionalità globale o a una funzionalità specifica dell'adattatore. La documentazione di una funzionalità indica se la funzionalità è una funzionalità globale. È importante conoscere queste informazioni quando si esegue una query su se una funzionalità è abilitata, perché potrebbe essere necessario un parametro hAdapter per eseguire query sulla configurazione della funzionalità specifica per tale adattatore o usare il database globale.
Le funzionalità seguenti sono attualmente definite come funzionalità globali:
- DXGK_FEATURE_GPUVAIOMMU
Virtualizzazione
Per GPU-PV, il sistema operativo negozia automaticamente il supporto e l'abilitazione delle funzionalità tra l'host e il guest. Il driver non deve implementare alcun supporto speciale per tali query.
Dipendenze
Ogni funzionalità può specificare un elenco di dipendenze. Queste dipendenze sono associate alla definizione della funzionalità stessa e sono hardcoded in fase di compilazione dal sistema operativo.
Per abilitare una particolare funzionalità, è necessario abilitare anche tutte le relative dipendenze.
Le funzionalità seguenti presentano attualmente dipendenze:
- DXGK_FEATURE_U edizione Standard R_MODE_SUBMISSION
- DXGK_FEATURE_HWSCH
- DXGK_FEATURE_NATIVE_FENCE
La documentazione di una funzionalità specifica se una funzionalità include dipendenze che devono essere abilitate.
Supporto delle funzionalità di query da KMD
Il sistema operativo usa un meccanismo di handshaking per determinare se il sistema operativo e il driver supportano una funzionalità. Questo meccanismo consente alla query iniziale di stabilire se una funzionalità è abilitata per provenire da qualsiasi origine (sistema operativo/Dxgkrnl, KMD, UMD, runtime e così via) e hanno comunque i meccanismi appropriati per il sistema operativo e il driver per negoziare il supporto delle funzionalità.
Il KmD deve implementare l'interfaccia DXGKDDI_FEATURE_INTERFACE affinché il driver di porta eseeseguono query sul supporto delle funzionalità. Il GUID dell'interfaccia è GUID_WDDM_INTERFACE_FEATURE.
Se il driver implementa DXGKDDI_FEATURE_INTERFACE, non è necessario chiamare DxgkCbQueryFeatureSupport per abilitare una funzionalità nel driver di porta in anticipo. Può invece supportare le funzionalità di query su richiesta usando l'interfaccia del DXGKDDI_FEATURE_INTERFACE.
Abilitazione delle funzionalità di query
Questa sezione descrive come un componente controlla se una funzionalità è abilitata nel sistema. La struttura DXGK_ISFEATUR edizione Enterprise NABLED_RESULT definisce i risultati di una query di funzionalità.
Query in modalità utente
Un client in modalità utente chiama D3DKMTIsFeatureEnabled per verificare se una particolare funzionalità WDDM è abilitata.
Query in modalità kernel
Per ottenere il callback per il supporto delle funzionalità di query, kmd deve eseguire query sull'interfaccia DxgkServicesFeature . Per ottenere questa interfaccia, kmd chiama il callback Dxgkrnl dxgkCbQueryServices con ServiceType impostato su un valore DXGK_edizione Standard RVICES di DxgkServicesFeature, come illustrato nel frammento di codice seguente. Il KMD può chiamare DxgkCbQueryServices una volta che ottiene il puntatore di callback in una chiamata a DxgkDdiStartDevice.
DXGK_FEATURE_INTERFACE FeatureInterface = {};
FeatureInterface.Size = sizeof(pDevExt->FeatureInterface);
FeatureInterface.Version = DXGK_FEATURE_INTERFACE_VERSION_1;
Status = DxgkInterface.DxgkCbQueryServices(DxgkInterface.DeviceHandle, DxgkServicesFeature, (PINTERFACE)&FeatureInterface);
Verifica della presenza di una funzionalità prima dell'inizializzazione di Dxgkrnl
DxgkIsFeatureEnabled2 è definito nella libreria del driver della porta di visualizzazione (displib.h). Di conseguenza, KMD può chiamare DxgkIsFeatureEnabled2 per verificare la presenza di una funzionalità prima che Dxgkrnl venga inizializzato.
Poiché questa chiamata deve essere usata in DriverEntry, è possibile eseguire una query solo su un subset di funzionalità globali. Questo subset include attualmente:
- DXGK_FEATURE_GPUVAIOMMU
Override del Registro di sistema
È possibile eseguire l'override delle configurazioni delle funzionalità nel Registro di sistema durante lo sviluppo e il test dei driver. Questa funzionalità è utile per forzare l'uso di una particolare funzionalità in un ambiente di sviluppo quando la configurazione predefinita della funzionalità potrebbe indicare che non è supportata.
Un driver non deve definire alcuna di queste chiavi del Registro di sistema nel proprio INF durante l'installazione del driver. Queste chiavi sono destinate solo a scopi di test e sviluppo e non a eseguire l'override su larga scala di una funzionalità specifica.
La configurazione delle funzionalità di un driver viene archiviata nella chiave software PNP per l'adattatore, in una chiave XXXX\Features\YYYY, dove XXXX è l'identificatore del dispositivo assegnato da PnP quando il dispositivo viene installato e YYYY rappresenta l'ID funzionalità. Un esempio è HKLM\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}\0000\Features\4.
Nelle sezioni seguenti vengono descritte le sostituzioni che possono essere specificate per una funzionalità.
Nome chiave del Registro di sistema: Abilitato
| Nome | Type | Valore | Descrizione |
|---|---|---|---|
| Attivata | DWORD | 0 (non supportato) o 1 (supportato). Il valore predefinito è dipendente dalla funzionalità. | Esegue l'override del supporto del sistema operativo per la funzionalità. |
Nonostante il nome, questa voce sostituisce solo il supporto lato sistema operativo di una funzionalità. Non forza l'abilitazione sempre della funzionalità, ovvero non garantisce che una chiamata a IsFeatureEnabled(ID) restituisca Enabled=TRUE. La negoziazione sul lato driver corretta è ancora necessaria per le funzionalità del driver.
Nome chiave del Registro di sistema: MinVersion
| Nome | Type | Valore | Descrizione |
|---|---|---|---|
| MinVersion | DWORD | Dipendente dalla funzionalità | Vincola la versione minima supportata per questa funzionalità per essere più restrittiva rispetto alla versione minima predefinita. |
Questo valore non può essere usato per forzare il supporto del sistema operativo per supportare una versione inferiore alla versione minima predefinita supportata (poiché questo valore minimo predefinito viene scelto a causa del supporto dell'implementazione). Questa chiave può invece vincolare la versione minima supportata a un valore superiore a quello predefinito.
Questa configurazione è utile per risolvere un bug che potrebbe essere presente in una versione specifica dell'implementazione della funzionalità.
Se si specifica MinVersion , è necessario specificare anche MaxVersion .
Nome chiave del Registro di sistema: MaxVersion
| Nome | Type | Valore | Descrizione |
|---|---|---|---|
| MaxVersion | DWORD | Dipendente dalla funzionalità | Vincola la versione massima supportata per questa funzionalità per essere più restrittiva rispetto alla versione massima predefinita. |
Questo valore non può essere usato per forzare il supporto del sistema operativo per supportare una versione superiore alla versione massima predefinita supportata(poiché questo valore massimo predefinito viene scelto a causa del supporto dell'implementazione). Questa chiave può invece vincolare la versione massima supportata a un valore inferiore al valore predefinito.
Questa configurazione è particolarmente utile per risolvere un bug che potrebbe essere presente in una versione specifica dell'implementazione della funzionalità.
Se è specificato MaxVersion , è necessario specificare anche MinVersion .
Nome chiave del Registro di sistema: AllowExperimental
| Nome | Type | Valore | Descrizione |
|---|---|---|---|
| AllowExperimental | DWORD | 0 (il supporto sperimentale non è consentito) o 1 (supportato). Il valore predefinito è definito dal ramo. | Forza il sistema operativo a consentire il caricamento delle versioni sperimentali di questa funzionalità, anche se la compilazione non lo consente per impostazione predefinita. |
Il sistema operativo definisce in genere il supporto sperimentale. Per impostazione predefinita, il supporto sperimentale viene definito in base alle funzionalità, con un override globale disponibile nelle build di sviluppo (ad esempio, le build interne degli sviluppatori consentono sempre il supporto sperimentale per tutte le funzionalità, mentre le build non definitive possono consentire solo il supporto per funzionalità specifiche).
Questo valore consente di eseguire l'override della definizione del sistema operativo per un ID funzionalità specifico. Può anche essere usato nelle build di rilascio per attivare il supporto dei driver sperimentali in un sistema operativo che supporta la funzionalità, ma mantenere la funzionalità disabilitata in un ambiente di vendita al dettaglio.
Estensione del debugger: dxgkdx
L'estensione del debugger del kernel dxgkdx implementa un !feature comando in grado di eseguire query sullo stato di varie funzionalità.
I comandi attualmente supportati (con output di esempio) sono:
!feature list
Lists features with descriptor information
2: kd> !dxgkdx.feature list
Id FeatureName Supported Version VirtMode Global Driver
0 HWSCH Yes 1-1 Negotiate - X
1 HWFLIPQUEUE Yes 1-1 Negotiate - X
2 LDA_GPUPV Yes 1-1 Negotiate - X
3 KMD_SIGNAL_CPU_EVENT Yes 1-1 Negotiate - X
4 USER_MODE_SUBMISSION Yes 1-1 Negotiate - X
5 SHARE_BACKING_STORE_WITH_KMD Yes 1-1 HostOnly - X
32 PAGE_BASED_MEMORY_MANAGER No 1-1 Negotiate - X
33 KERNEL_MODE_TESTING Yes 1-1 Negotiate - X
34 64K_PT_DEMOTION_FIX Yes 1-1 DeferToHost - -
35 GPUPV_PRESENT_HWQUEUE Yes 1-1 DeferToHost - -
36 GPUVAIOMMU Yes 1-1 None X -
37 NATIVE_FENCE Yes 1-1 Negotiate - X
!feature config
Lists the current configuration information for each feature. In most cases, this will be unspecified/default values if not overriden.
2: kd> !dxgkdx.feature config
Id FeatureName Enabled Version AllowExperimental
0 HWSCH -- -- -
1 HWFLIPQUEUE -- -- -
2 LDA_GPUPV -- -- -
3 KMD_SIGNAL_CPU_EVENT -- -- -
4 USER_MODE_SUBMISSION -- -- -
5 SHARE_BACKING_STORE_WITH_KMD -- -- -
32 PAGE_BASED_MEMORY_MANAGER -- -- -
33 KERNEL_MODE_TESTING -- -- -
34 64K_PT_DEMOTION_FIX -- -- -
35 GPUPV_PRESENT_HWQUEUE -- -- -
36 GPUVAIOMMU -- -- -
37 NATIVE_FENCE -- -- -
!feature state
Lists the current state of each feature. Features that have bnot been queried will have an unknown state
2: kd> !dxgkdx.feature state
Id FeatureName Enabled Version Driver Config
0 HWSCH No 0 No No
1 HWFLIPQUEUE No 0 No No
2 LDA_GPUPV No 0 No No
3 KMD_SIGNAL_CPU_EVENT Yes 1 Yes Yes
4 USER_MODE_SUBMISSION No 0 No No
5 SHARE_BACKING_STORE_WITH_KMD Unknown -- -- --
32 PAGE_BASED_MEMORY_MANAGER No 0 No No
33 KERNEL_MODE_TESTING No 0 No No
34 64K_PT_DEMOTION_FIX Unknown -- -- --
35 GPUPV_PRESENT_HWQUEUE Unknown -- -- --
36 GPUVAIOMMU Unknown -- -- --
37 NATIVE_FENCE No 0 No No
Implementazione di esempio
Per semplificare il supporto, segue un'implementazione di esempio barebones. I driver possono usare questo codice come punto di partenza per la propria implementazione ed espandersi con funzionalità aggiuntive, ad esempio associando modi per eseguire l'override delle funzionalità.
#include "precomp.h"
#pragma code_seg("PAGE")
#define VERSION_RANGE(Min, Max) Min, Max
#define DEFINE_FEATURE_INTERFACE(Name, Version, InterfaceStruct) InterfaceStruct Name##_Interface_##Version =
#define DEFINE_FEATURE_INTERFACE_TABLE(Name) const DRIVER_FEATURE_INTERFACE_TABLE_ENTRY Name##_InterfaceTable[] =
#define FEATURE_INTERFACE_ENTRY(Name, Version) { &Name##_Interface_##Version, sizeof(Name##_Interface_##Version) }
#define NO_FEATURE_INTERFACE { nullptr, 0 }
#define FEATURE_INTERFACE(Name, Version) { &Name##_Interface_##Version, sizeof(Name##_Interface_##Version) }
#define FEATURE_INTERFACE_TABLE(Name) { Name##_InterfaceTable, ARRAYSIZE(Name##_InterfaceTable) }
#define NO_FEATURE_INTERFACE_TABLE { nullptr, 0 }
struct DRIVER_FEATURE_INTERFACE_TABLE_ENTRY
{
const void* Interface;
SIZE_T InterfaceSize;
};
struct DRIVER_FEATURE_INTERFACE_TABLE
{
const DRIVER_FEATURE_INTERFACE_TABLE_ENTRY* Entries;
SIZE_T Count;
};
//
// Interfaces
//
DEFINE_FEATURE_INTERFACE(FEATURE_SAMPLE, 4, DXGKDDIINT_FEATURE_SAMPLE_4)
{
DdiFeatureSample_AddValue,
};
DEFINE_FEATURE_INTERFACE(FEATURE_SAMPLE, 5, DXGKDDIINT_FEATURE_SAMPLE_5)
{
DdiFeatureSample_AddValue,
DdiFeatureSample_SubtractValue,
};
DEFINE_FEATURE_INTERFACE_TABLE(FEATURE_SAMPLE)
{
NO_FEATURE_INTERFACE, // Version 3
FEATURE_INTERFACE(FEATURE_SAMPLE, 4), // Version 4
FEATURE_INTERFACE(FEATURE_SAMPLE, 5), // Version 5
};
static const DRIVER_FEATURE_INTERFACE_TABLE g_FeatureInterfaceTables[] =
{
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_HWSCH
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_HWFLIPQUEUE
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_LDA_GPUPV
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_KMD_SIGNAL_CPU_EVENT
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_USER_MODE_SUBMISSION
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_SHARE_BACKING_STORE_WITH_KMD
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
NO_FEATURE_INTERFACE_TABLE, // Reserved
FEATURE_INTERFACE_TABLE(FEATURE_SAMPLE), // DXGK_FEATURE_SAMPLE
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_PAGE_BASED_MEMORY_MANAGER
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_KERNEL_MODE_TESTING
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_64K_PT_DEMOTION_FIX
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_GPUPV_PRESENT_HWQUEUE
NO_FEATURE_INTERFACE_TABLE, // DXGK_FEATURE_NATIVE_FENCE
};
static_assert(ARRAYSIZE(g_FeatureInterfaceTables) == DXGK_FEATURE_MAX, "New feature must define an interface table");
#define VERSION_RANGE(Min, Max) Min, Max
//
// TODO: This table may be defined independently for each supported hardware or architecture,
// or may be completely overriden dynamically at runtime during DRIVER_ADAPTER::InitializeFeatureConfiguration
//
static const DRIVER_FEATURE_DESC g_FeatureDefaults[] =
{
// SupportedOnConfig
// VersionRange Supported | Experimental
// | | | |
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_HWSCH
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_HWFLIPQUEUE
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_LDA_GPUPV
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_KMD_SIGNAL_CPU_EVENT
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_USER_MODE_SUBMISSION
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_SHARE_BACKING_STORE_WITH_KMD
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // Reserved
{ VERSION_RANGE(3, 5), { TRUE, TRUE, FALSE, }, }, // DXGK_FEATURE_TEST_FEATURE_SAMPLE
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_PAGE_BASED_MEMORY_MANAGER
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_KERNEL_MODE_TESTING
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_64K_PT_DEMOTION_FIX
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_GPUPV_PRESENT_HWQUEUE
{ VERSION_RANGE(0, 0), { FALSE, FALSE, FALSE, }, }, // DXGK_FEATURE_NATIVE_FENCE
};
static_assert(ARRAYSIZE(g_FeatureDefaults) == DXGK_FEATURE_MAX, "New feature requires a descriptor");
const DRIVER_FEATURE_DESC*
DRIVER_ADAPTER::GetFeatureDesc(
DXGK_FEATURE_ID FeatureId
) const
{
PAGED_CODE();
if(FeatureId >= DXGK_FEATURE_MAX)
{
return nullptr;
}
return &m_FeatureDescs[FeatureId];
}
void
DRIVER_ADAPTER::InitializeFeatureConfiguration(
)
{
//
// Choose correct default table to use here, or override manually below
//
static_assert(sizeof(DRIVER_ADAPTER::m_FeatureDescs) == sizeof(g_FeatureDefaults));
memcpy(m_FeatureDescs, g_FeatureDefaults, sizeof(g_FeatureDefaults));
//
// Example overrides
//
//
// While this is a sample feature and not tied to any architectural support, this is
// an example of how a feature can be marked as supported by the driver in the table
// above, and then dynamically enabled on this configuration here.
//
// The same can be done for hardware features, such as hardware scheduling
//
if(IsSampleFeatureSupportedOnThisGPU())
{
m_FeatureDescs[DXGK_FEATURE_TEST_FEATURE_SAMPLE].SupportedOnConfig = TRUE;
}
}
NTSTATUS
DdiQueryFeatureSupport(
IN_CONST_HANDLE hAdapter,
INOUT_PDXGKARG_QUERYFEATURESUPPORT pArgs
)
{
PAGED_CODE();
//
// Start by assuming the feature is unsupported
//
pArgs->SupportedByDriver = FALSE;
pArgs->SupportedOnCurrentConfig = FALSE;
pArgs->MinSupportedVersion = 0;
pArgs->MaxSupportedVersion = 0;
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
const DRIVER_FEATURE_DESC* pFeatureDesc = pAdapter->GetFeatureDesc(pArgs->FeatureId);
if(pFeatureDesc == nullptr)
{
//
// Unknown feature
//
return STATUS_INVALID_PARAMETER;
}
if(pFeatureDesc->Supported)
{
if(pFeatureDesc->Experimental == FALSE ||
pArgs->AllowExperimental)
{
pArgs->SupportedByDriver = TRUE;
pArgs->SupportedOnCurrentConfig = pFeatureDesc->SupportedOnConfig;
pArgs->MinSupportedVersion = pFeatureDesc->MinSupportedVersion;
pArgs->MaxSupportedVersion = pFeatureDesc->MaxSupportedVersion;
}
}
return STATUS_SUCCESS;
}
NTSTATUS
DdiQueryFeatureInterface(
IN_CONST_HANDLE hAdapter,
INOUT_PDXGKARG_QUERYFEATUREINTERFACE pArgs
)
{
PAGED_CODE();
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
UINT16 InterfaceSize = pArgs->InterfaceSize;
pArgs->InterfaceSize = 0;
const DRIVER_FEATURE_DESC* pFeatureDesc = pAdapter->GetFeatureDesc(pArgs->FeatureId);
if(pFeatureDesc == nullptr)
{
//
// Unknown feature
//
return STATUS_INVALID_PARAMETER;
}
if(pFeatureDesc->Supported == FALSE)
{
//
// Cannot query a feature interface for an unsupported feature.
//
return STATUS_UNSUCCESSFUL;
}
if(pArgs->Version < pFeatureDesc->MinSupportedVersion ||
pArgs->Version > pFeatureDesc->MaxSupportedVersion)
{
//
// Invalid feature version.
//
return STATUS_UNSUCCESSFUL;
}
const DRIVER_FEATURE_INTERFACE_TABLE* pInterfaceTable = &g_FeatureInterfaceTables[pArgs->FeatureId];
if(pInterfaceTable->Entries == nullptr)
{
//
// This feature does not have any interfaces. It's unclear why the driver is asking for it,
// but the size should be zero and we will not return any data for it.
//
return STATUS_SUCCESS;
}
if((SIZE_T)(pArgs->Version - pFeatureDesc->MinSupportedVersion) >= pInterfaceTable->Count)
{
//
// The interface table should have an entry for every supported version. This is
// a bug in the OS, and the feature interface table must be updated for this feature!
//
NT_ASSERT(FALSE);
//
// Invalid feature version.
//
return STATUS_UNSUCCESSFUL;
}
UINT32 InterfaceTableIndex = pArgs->Version - pFeatureDesc->MinSupportedVersion;
const DRIVER_FEATURE_INTERFACE_TABLE_ENTRY* pInterfaceEntry = &pInterfaceTable->Entries[InterfaceTableIndex];
if(pInterfaceEntry->Interface == nullptr)
{
//
// This feature does not have any interfaces. It's unclear why the OS is asking for one.
//
return STATUS_INVALID_PARAMETER;
}
if(InterfaceSize < pInterfaceEntry->InterfaceSize)
{
//
// The driver-provided buffer is too small to store the interface for this feature and version
//
return STATUS_BUFFER_TOO_SMALL;
}
//
// We have an interface!
//
RtlCopyMemory(pArgs->Interface, pInterfaceEntry->Interface, pInterfaceEntry->InterfaceSize);
if(InterfaceSize != pInterfaceEntry->InterfaceSize)
{
//
// Zero out remainder of interface in case the provided buffer was larger than
// the actual interface. This may be done in cases where multiple interface versions
// are supported simultaneously (e.g. in a unioned structure). Only the requested
// interface should be valid.
//
RtlZeroMemory((BYTE*)pArgs->Interface + pInterfaceEntry->InterfaceSize, InterfaceSize - pInterfaceEntry->InterfaceSize);
}
//
// Write back the interface size
//
pArgs->InterfaceSize = (UINT16)pInterfaceEntry->InterfaceSize;
return STATUS_SUCCESS;
}
static void DdiReferenceFeatureInterfaceNop(PVOID pMiniportDeviceContext)
{
PAGED_CODE();
}
//
// DRIVER_INITIALIZATION_DATA::DxgkDdiQueryInterface
//
NTSTATUS
DdiQueryInterface(
IN_CONST_PVOID pMiniportDeviceContext,
IN_PQUERY_INTERFACE pQueryInterface
)
{
DDI_FUNCTION();
PAGED_CODE();
if(pQueryInterface->Version == DXGK_FEATURE_INTERFACE_VERSION_1)
{
PDXGKDDI_FEATURE_INTERFACE Interface = (PDXGKDDI_FEATURE_INTERFACE)pQueryInterface->Interface;
Interface->Version = DXGK_FEATURE_INTERFACE_VERSION_1;
Interface->Context = pMiniportDeviceContext;
Interface->Size = sizeof(DXGKDDI_FEATURE_INTERFACE);
//
// Returned interface shouldn't be larger than size provided for Interface
//
if (Interface->Size > pQueryInterface->Size)
{
return STATUS_BUFFER_TOO_SMALL;
}
Interface->InterfaceReference = DdiReferenceFeatureInterfaceNop;
Interface->InterfaceDereference = DdiReferenceFeatureInterfaceNop;
Interface->QueryFeatureSupport = DdiQueryFeatureSupport;
Interface->QueryFeatureInterface = DdiQueryFeatureInterface;
return STATUS_SUCCESS;
}
else
{
return STATUS_INVALID_PARAMETER;
}
}
//
// These two functions act as hooks for when the OS doesn't support the feature functionality.
// If DxgkInterface.DxgkCbQueryServices(DxgkServicesFeature) returns a failure, it may mean
// we're running on an older OS, and we can fake the interface implementation using these
// functions instead.
//
// See DdiStartDevice sample code for how this is used
//
NTSTATUS
LegacyIsFeatureEnabled(
IN_CONST_PVOID hDevice,
INOUT_PDXGKARGCB_ISFEATUREENABLED2 pArgs
)
{
PAGED_CODE();
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
pArgs->Result = {};
if (pAdapter->m_WddmVersion >= DXGKDDI_WDDMv2_9 &&
pAdapter->m_DxgkInterface.Version >= DXGKDDI_INTERFACE_VERSION_WDDM2_9)
{
//
// QueryFeatureSupport should be available.
//
DXGKARGCB_QUERYFEATURESUPPORT Args = {};
Args.DeviceHandle = pAdapter->m_DxgkInterface.DeviceHandle;
Args.FeatureId = pArgs->FeatureId;
//
// Example experimental status
//
/*
switch(pArgs->FeatureId)
{
case DXGK_FEATURE_HWFLIPQUEUE:
{
Args.DriverSupportState = DXGK_FEATURE_SUPPORT_EXPERIMENTAL;
break;
}
default:
{
Args.DriverSupportState = DXGK_FEATURE_SUPPORT_STABLE;
break;
}
}
*/
NTSTATUS Status = pAdapter->m_DxgkInterface.DxgkCbQueryFeatureSupport(&Args);
if(NT_SUCCESS(Status))
{
if(Args.Enabled)
{
pArgs->Result.Enabled = Args.Enabled;
pArgs->Result.Version = 1;
pArgs->Result.SupportedByDriver = TRUE;
pArgs->Result.SupportedOnCurrentConfig = TRUE;
}
}
return Status;
}
else
{
return STATUS_NOT_SUPPORTED;
}
}
//
// Sample code for DdiStartDevice
//
NTSTATUS
DdiStartDevice(
IN_CONST_PVOID pMiniportDeviceContext,
IN_PDXGK_START_INFO pDxgkStartInfo,
IN_PDXGKRNL_INTERFACE pDxgkInterface,
OUT_PULONG pNumberOfVideoPresentSources,
OUT_PULONG pNumberOfChildren
)
{
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
...
//
// Check fi the OS supports the feature interface.
//
pAdapter->m_FeatureInterface.Size = sizeof(pAdapter->m_FeatureInterface);
pAdapter->m_FeatureInterface.Version = DXGK_FEATURE_INTERFACE_VERSION_1;
Status = pAdapter->m_DxgkInterface.DxgkCbQueryServices(pAdapter->m_DxgkInterface.DeviceHandle, DxgkServicesFeature, (PINTERFACE)&pAdapter->m_FeatureInterface);
if(!NT_SUCCESS(Status))
{
//
// OS interface unavailable. This forwards calls to the Legacy functions defined above
// when not available, which hard codes support for the handful of existing features
// at the time (optionally going through DxgkCbQueryFeatureSupport).
//
// Doing this is optional, but may keep the driver code cleaner.
//
pAdapter->m_FeatureInterface.Context = pAdapter;
pAdapter->m_FeatureInterface.InterfaceReference = nullptr;
pAdapter->m_FeatureInterface.InterfaceDereference = nullptr;
//
// Use legacy function above.
//
pAdapter->m_FeatureInterface.IsFeatureEnabled = LegacyIsFeatureEnabled;
//
// QueryFeatureInterface is only used by the OS to query an interface for a feature,
// but the OS doesn't support this. Any attempt to call this function implies
// the driver is calling it themselves, which makes no sense.
//
pAdapter->m_FeatureInterface.QueryFeatureInterface = nullptr;
Status = STATUS_SUCCESS;
}
Status = pAdapter->InitializeFeatureConfiguration();
if(!NT_SUCCESS(Status))
{
goto cleanup;
}
...
}
DRIVER_FEATURE_RESULT
DRIVER_ADAPTER::IsFeatureEnabled(
DXGK_FEATURE_ID FeatureId
)
{
PAGED_CODE();
DRIVER_FEATURE_RESULT Result = {};
DXGKARGCB_ISFEATUREENABLED2 Args = {};
Args.FeatureId = FeatureId;
//
// Will either call the OS, or the LegacyIsFeatureEnabled function above
// depending on whether this is supported on the OS.
//
if(NT_SUCCESS(FeatureInterface.IsFeatureEnabled(DxgkInterface.DeviceHandle, &Args)))
{
Result.Enabled = Args.Result.Enabled;
Result.Version = Args.Result.Version;
}
return Result;
}
Il codice seguente implementa le interfacce per la funzionalità FEATURE_SAMPLE .
//
// This file implements the interfaces for the FEATURE_SAMPLE feature
//
#include "precomp.h"
//
// The OS supports 3 versions of the feature: 3, 4, and 5.
//
// - v3 has no interface
// - v4 has an interface that defines an "Add" function
// - v5 has an interface that defines both "Add" and "Subtract" functions
//
NTSTATUS
APIENTRY CALLBACK
DdiFeatureSample_AddValue(
IN_CONST_HANDLE hAdapter,
INOUT_PDXGKARG_FEATURE_SAMPLE_ADDVALUE pArgs
)
{
PAGED_CODE();
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
if(pAdapter->m_FeatureState.SampleFeatureVersion < 4)
{
//
// Unexpected. This function should only be called for v4 and above of this feature
//
return STATUS_INVALID_PARAMETER;
}
DXGKARGCB_FEATURE_SAMPLE_GETVALUE GetValueArgs = {};
NTSTATUS Status = pAdapter->m_FeatureState.SampleFeatureInterface.GetValue(pAdapter->m_DxgkInterface.DeviceHandle, &GetValueArgs);
if(!NT_SUCCESS(Status))
{
return Status;
}
pArgs->OutputValue = pArgs->InputValue + GetValueArgs.Value;
return STATUS_SUCCESS;
}
NTSTATUS
APIENTRY CALLBACK
DdiFeatureSample_SubtractValue(
IN_CONST_HANDLE hAdapter,
INOUT_PDXGKARG_FEATURE_SAMPLE_SUBTRACTVALUE pArgs
)
{
PAGED_CODE();
DRIVER_ADAPTER* pAdapter = GetAdapterFromHandle(hAdapter);
if(pAdapter->m_FeatureState.SampleFeatureVersion < 5)
{
//
// Unexpected. This function should only be called for v5 and above of this feature
//
return STATUS_INVALID_PARAMETER;
}
DXGKARGCB_FEATURE_SAMPLE_GETVALUE GetValueArgs = {};
NTSTATUS Status = pAdapter->m_FeatureState.SampleFeatureInterface.GetValue(pAdapter->m_DxgkInterface.DeviceHandle, &GetValueArgs);
if(!NT_SUCCESS(Status))
{
return Status;
}
pArgs->OutputValue = pArgs->InputValue - GetValueArgs.Value;
return STATUS_SUCCESS;
}