DXGKDDI_ACQUIRESWIZZLINGRANGE função de retorno de chamada (d3dkmddi.h)

Artigo
02/06/2025

A função DxgkDdiAcquireSwizzlingRange torna uma alocação acessível por meio da abertura da CPU (unidade de processamento central) para o segmento determinado.

Sintaxe

DXGKDDI_ACQUIRESWIZZLINGRANGE DxgkddiAcquireswizzlingrange;

NTSTATUS DxgkddiAcquireswizzlingrange(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_ACQUIRESWIZZLINGRANGE pAcquireSwizzlingRange
)
{...}

Parâmetros

[in] hAdapter

Um identificador para um bloco de contexto associado a um adaptador de exibição. O driver de miniporto de exibição forneceu anteriormente esse identificador para o subsistema de kernel de elementos gráficos do Microsoft DirectX na função MiniportDeviceContext da função DxgkDdiAddDevice.

[in/out] pAcquireSwizzlingRange

Um ponteiro para uma estrutura de DXGKARG_ACQUIRESWIZZLINGRANGE que contém informações para tornar uma alocação acessível por meio da abertura da CPU.

Valor de retorno

DxgkDdiAcquireSwizzlingRange retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	DxgkDdiAcquireSwizzlingRange tornou a alocação acessível com êxito.
STATUS_GRAPHICS_UNSWIZZLING_APERTURE_UNSUPPORTED	DxgkDdiAcquireSwizzlingRange não pôde programar o intervalo de swizzling para a alocação. O gerenciador de memória de vídeo não consegue adquirir o intervalo de swizzling sem fazer novas tentativas.
STATUS_GRAPHICS_UNSWIZZLING_APERTURE_UNAVAILABLE	DxgkDdiAcquireSwizzlingRange não pôde programar o intervalo de swizzling para a alocação porque outro intervalo de swizzling está usando atualmente os recursos de GPU (unidade de processamento gráfico) necessários. O gerenciador de memória de vídeo tenta liberar um intervalo que está em uso no momento e tenta configurar o intervalo de swizzling novamente.

Observações

A função DxgkDdiAcquireSwizzlingRange é chamada depois que o driver de exibição no modo de usuário solicita um endereço virtual que faz referência aos bits de uma alocação (ou seja, depois que o driver de exibição do modo de usuário chamar a função pfnLockCb com o AcquireAperture sinalizador de campo de bits definido no Flags membro da estrutura D3DDDICB_LOCK e enquanto a alocação estiver localizada atualmente em um segmento de memória acessível à CPU). Se o AcquireAperture sinalizador de campo de bit não estiver definido na chamada para pfnLockCb, DxgkDdiAcquireSwizzlingRange não for chamado e a alocação deverá estar em um formato que o driver de exibição no modo de usuário ou um aplicativo possa processar.

Quando DxgkDdiAcquireSwizzlingRange é chamado, o driver de miniporto de exibição deve tornar a alocação especificada (ou seja, o hAllocation membro da estrutura DXGKARG_ACQUIRESWIZZLINGRANGE à qual o parâmetro pAcquireSwizzlingRange aponta para) acessível por meio da abertura da CPU para o segmento especificado (ou seja, o SegmentId membro do DXGKARG_ACQUIRESWIZZLINGRANGE). A alocação deve aparecer exatamente como aparece na memória do computador após uma remoção desordeira.

Nem todas as solicitações do driver de exibição no modo de usuário são acessíveis para o driver de miniporto de exibição. Os intervalos de swizzling adquiridos pelo gerenciador de memória de vídeo são armazenados em cache com base na alocação à qual estão associados e nos dados privados especificados. Na primeira solicitação do driver de exibição no modo de usuário para acessar uma alocação, a função DxgkDdiAcquireSwizzlingRange do driver de exibição é chamada para tornar a alocação acessível. Em solicitações subsequentes com dados privados correspondentes, o mapeamento de configuração anterior é usado para acessar a alocação.

O gerenciador de memória de vídeo chama a função DxgkDdiReleaseSwizzlingRange do driver de exibição para liberar um intervalo de swizzling quando uma alocação é removida ou destruída ou quando outra alocação requer uma abertura. Uma alocação pode ser associada a qualquer número de intervalos de swizzling (por exemplo, uma abertura por nível de MIP).

O número de intervalos de swizzling que um adaptador dá suporte é exposto pelo driver no NumberOfSwizzlingRanges membro da estrutura DXGK_DRIVERCAPS quando a função DxgkDdiQueryAdapterInfo do driver é chamada. Todos os intervalos são iguais (ou seja, qualquer intervalo pode deswizzle ou untile qualquer tipo de swizzling ou tiling). O gerenciador de memória de vídeo arbitra os intervalos de swizzling disponíveis entre todos os aplicativos que exigem eles.

O driver deve usar OM (E/S) mapeado pela memória para configurar um intervalo de swizzling. Esses acessos de intervalo de swizzling não devem interferir na execução da GPU (ou seja, a GPU não deve ficar ociosa quando DxgkDdiAcquireSwizzlingRange for chamado).

Todas as chamadas para DxgkDdiAcquireSwizzlingRange são serializadas entre si, mas não com qualquer outra função DDI.

Se a GPU der suporte a intervalos de swizzling que redirecionam acessos de CPU a segmentos de memória não acessíveis à CPU ou memória do sistema, o driver de exibição do modo de usuário pode definir a combinação de AcquireAperture e UseAlternateVA sinalizadores de campo de bit no Flags membro da estrutura D3DDDICB_LOCK em uma chamada para a função pfnLockCb para bloquear a alocação. Nessa situação, o gerenciador de memória de vídeo chama a função DxgkDdiAcquireSwizzlingRange do driver de exibição para adquirir um intervalo de swizzling para a alocação, embora a alocação esteja localizada em um segmento de memória não acessível à CPU ou em um segmento de abertura. Os intervalos de swizzling são associados a alguns recursos de GPU (por exemplo, intervalos de abertura de PCI) que o driver gerencia e não são acessíveis ou contabilizados pelo gerenciador de memória de vídeo.

Uma chamada para DxgkDdiAcquireSwizzlingRange para adquirir um intervalo de swizzling pode falhar porque um recurso gerenciado pelo driver acabou. Embora o próprio intervalo de swizzling seja gratuito, ele pode não ser utilizável devido ao recurso ausente. O driver pode indicar que um intervalo de swizzling não está disponível para o gerenciador de memória de vídeo retornando STATUS_GRAPHICS_UNSWIZZLING_APERTURE_UNAVAILABLE de DxgkDdiAcquireSwizzlingRange. O gerenciador de memória de vídeo tenta lançar um intervalo giratório que está em uso no momento e, em seguida, chama a função DxgkDdiAcquireSwizzlingRange do driver novamente para configurar o novo intervalo de swizzling. Se todos os intervalos de swizzling forem liberados e o driver ainda falhar com STATUS_GRAPHICS_UNSWIZZLING_APERTURE_UNAVAILABLE, o gerenciador de memória de vídeo não conseguirá adquirir um intervalo de swizzling para a alocação.

DxgkDdiAcquireSwizzlingRange deve ser tornada paginável.