Suporte de contêiner para APIs não-DX

2025-05-30

O Windows 10 adicionou recursos que afetam significativamente as APIs não DX e os detalhes de arquitetura WDDM de nível inferior nos quais eles dependem:

Adaptadores WDDM paravirtualizados
Os utilizadores agora têm controlo sobre o adaptador usado por aplicações que não fazem discriminação
Drivers universais introduzem um novo conjunto de princípios de design

Manter a compatibilidade com os recursos mais recentes do Windows 10 requer as modificações descritas nas seções abaixo.

Modificações do driver INF

O driver deve registrar tempos de execução não-DX nos locais de registro apropriados para instalar seus binários nos subdiretórios system32 e syswow64 da instalação do Windows. Na instalação INF, o driver pode definir vários valores nas seguintes subchaves da chave do Registro do adaptador gráfico:

CopyToVmOverwrite
CopiarParaVmSeMaisRecente
CopyToVmOverwriteWow64
CopyToVmWhenNewerWow64

As primeiras subchaves modificam o diretório system32, enquanto as últimas subchaves modificam o diretório syswow64. Cada tipo de valor sob uma subchave deve ser REG_MULTI_SZ ou REG_SZ. Se o tipo de valor for REG_MULTI_SZ, deve haver no máximo 2 cadeias de caracteres no valor. Isso implica que cada valor define um par de cadeias de caracteres, onde a segunda cadeia de caracteres pode estar vazia. O primeiro nome em um par é um caminho para um arquivo no armazenamento de driver. O caminho é relativo à raiz do repositório de drivers e pode conter subdiretórios. O segundo nome em um par é o nome do arquivo como ele aparecerá no diretório system32 ou syswow64. O segundo nome deve ser apenas o nome do arquivo, não incluindo o caminho. Se o segundo nome estiver vazio, o nome do arquivo será o mesmo que no armazenamento de driver (excluindo subdiretórios). Isso permite que o controlador tenha nomes diferentes no armazenamento de controladores do host e no convidado.

Os arquivos listados nas subchaves de registro do adaptador gráfico CopyToVmWhenNewer e CopyToVmWhenNewerWow64 só substituem os arquivos de destino quando eles satisfazem os critérios "mais recentes".

No Windows 10 versão 2004, o critério "mais recente" compara duas informações:

Quando o arquivo de destino termina com o sufixo .dll ou .exe, o FileVersion é usado como o valor de comparação mais significativo onde a versão maior é considerada "mais recente".

Quando o arquivo de destino não termina com o .dll nem .exe sufixo OU os dois FileVersion são iguais, então LastWriteTime é usado como os valores de comparação menos significativos onde a data/hora posterior é considerada "mais recente".

Nas versões do Windows 10 anteriores a 2004, os critérios "mais recentes" comparavam apenas o ChangeTime dos ficheiros.

Exemplo 1

Secção INF [DDInstall]
HKR, "softgpukmd\CopyToVmOverwrite", SoftGpuFiles, %REG_MULTI_SZ%, "CopyToVm\softgpu1.dll", "softgpu2.dll"

O sistema operacional copiará <DriverStorePath>\CopyToVm\softgpu1.dll to %windir%\system32\softgpu2.dll

Exemplo 2

Secção INF [DDInstall]:
HKR, "CopyToVmOverwrite", SoftGpuFiles1, %REG_MULTI_SZ%, "softgpu1.dll", "softgpu.dll"
HKR, "CopyToVmOverwrite", SoftGpuFiles2, %REG_SZ%, "softgpu2.dll"

A diretiva criará a chave do Registro na chave do software (adaptador):
"HKLM\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}\<number>\CopyToVmOverwrite", SoftGpuFiles1 = REG_MULTI_SZ, "softgpu1.dll", "softgpu.dll"
"HKLM\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}\<number>\CopyToVmOverwrite", SoftGpuFiles = REG_SZ, "softgpu2.dll"

O sistema operacional copiará <DriverStorePath>\softgpu1.dll to %windir%\system32\softgpu.dll e <DriverStorePath>\softgpu2.dll to %windir%\system32\softgpu2.dll

Exemplo 3

Secção INF [DDInstall]:
HKR, "CopyToVmOverwriteWow64", SoftGpuFiles, %REG_MULTI_SZ%, "Subdir1\Subdir2\softgpu2wow64.dll", "softgpu.dll"

O sistema operacional copiará <DriverStorePath>\Subdir1\Subdir2\softgpu2wow64.dll to %windir%\syswow64\softgpu.dll

Modificações de driver no Registro e caminhos de arquivo

Dentro de contentores, o repositório de drivers não está consistentemente localizado no mesmo caminho canónico onde normalmente está. Para usar consistentemente o caminho ajustado corretamente, o registo e o armazenamento de driver devem ser acessados indiretamente por meio de D3DKMTQueryAdapterInfo com KMTQAITYPE_QUERYREGISTRY e D3DDDI_QUERYREGISTRY_INFO.

Configuração padrão do adaptador Honor OS

O adaptador padrão deve respeitar a escolha do usuário que está armazenada no sistema operacional, o que requer:

Enumerando adaptadores através do IDXGIFactory::EnumAdapters do DXGI, visto que o DXGI respeita a escolha do utilizador. O adaptador 0 muda com base nas configurações do usuário.
Corresponda a ordem do adaptador obtida através de D3DKMTEnumAdapters2 com a do DXGI. As identidades do adaptador podem ser combinadas correlacionando o LUID entre ambas as técnicas de enumeração. DXGI retorna seu LUID através de IDXGIAdapter::GetDesc.

Modificações no projeto DCHU

Honre o maior número de princípios de design do driver universal possíveis, que podem variar conforme o dispositivo específico que está a ser suportado.

Cabeçalhos D3DKMT

Os cabeçalhos que incluem os métodos e tipos mencionados anteriormente estão disponíveis no SDK do Windows para Windows 10 versão 2004 e posterior, em vez de estarem disponíveis exclusivamente no WDK.

Uma opção para incluir corretamente os cabeçalhos necessários é a seguinte. Outras opções também podem existir.

// Turn off NTSTATUS codes within windows.h, so that the more exhaustive ntstatus.h can be used.
#define UMDF_USING_NTSTATUS
#include <windows.h> // For the vast majority of Windows functionality
#include <winternl.h> // For NT_SUCCESS
#include <ntstatus.h> // For the most exhaustive list of NTSTATUS codes
#include <d3dkmthk.h> // For D3DKMT support