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

Artigo
02/06/2025

A função kmd (driver de exibição) do modo kernel (KMD) DxgkDdiCreateAllocation cria alocações de memória de sistema ou vídeo.

Sintaxe

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

NTSTATUS DxgkddiCreateallocation(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_CREATEALLOCATION pCreateAllocation
)
{...}

Parâmetros

[in] hAdapter

Um identificador para um bloco de contexto associado a um adaptador de exibição. O KMD forneceu anteriormente esse identificador para Dxgkrnl no parâmetro de saída MiniportDeviceContext da funçãoDxgkDdiAddDevice.

[in/out] pCreateAllocation

Um ponteiro para uma estrutura de DXGKARG_CREATEALLOCATION que contém informações para criar alocações.

Valor de retorno

DxgkDdiCreateAllocation retorna um dos seguintes valores:

Código de retorno	descrição
STATUS_SUCCESS	DxgkDdiCreateAllocation criou com êxito a alocação.
STATUS_INVALID_PARAMETER	Os parâmetros passados continham erros que impediam a conclusão DxgkDdiCreateAllocation.
STATUS_NO_MEMORY	DxgkDdiCreateAllocation não pôde alocar memória necessária para que ela fosse concluída.
STATUS_GRAPHICS_DRIVER_MISMATCH	O KMD não é compatível com o UMD (driver de exibição do modo de usuário) que iniciou a chamada para DxgkDdiCreateAllocation.

Observações

Depois que a UMD chama pfnAllocateCb, Dxgkrnl chama a função DxgkDdiCreateAllocation do KMD para criar as alocações. O KMD deve interpretar os dados privados (no pPrivateDriverData membro da estrutura DXGK_ALLOCATIONINFO para cada alocação) que são passados da UMD e devem determinar a lista de parâmetros necessários para criar cada alocação por meio do gerenciador de memória de vídeo. Para obter mais informações sobre como o KMD fornece esses parâmetros ao gerenciador de memória de vídeo, consulte Especificando segmentos ao criar alocações.

O KMD deve retornar um identificador de alocação, que normalmente é um ponteiro para uma estrutura de dados de driver privado que contém informações sobre a alocação. O UMD pode chamar a função DxgkCbGetHandleData a qualquer momento para recuperar os dados privados de um identificador de alocação. Portanto, o KMD não é necessário para manter uma tabela de identificador de alocação privada. Na verdade, desencorajamos fortemente as tabelas de identificadores privados porque elas podem ficar obsoletas ou fora de sincronia com o subsistema de kernel de elementos gráficos DirectX em cenários de comutador de modo de exibição, como comutador de usuário rápido, desacoplação ativa e assim por diante.

O driver de exibição do modo de usuário atribui uma alocação a um recurso ou a um dispositivo. Para determinar se a alocação pertence a um recurso, o driver de miniporto de exibição pode verificar se o sinalizador de campo de bits do Resource está definido no Flags membro da estrutura DXGKARG_CREATEALLOCATION à qual o parâmetro pCreateAllocation de DxgkDdiCreateAlloc ation aponta. Se a alocação pertencer a um recurso, o driver de miniporto de exibição poderá (mas não é necessário) retornar um identificador de recurso, que normalmente é um ponteiro para uma estrutura de dados de driver privado que descreve o recurso. Se o subsistema de kernel de elementos gráficos DirectX chamar DxgkDdiCreateAllocation para criar uma alocação adicional para um recurso existente, o hResource membro do DXGKARG_CREATEALLOCATION conterá o identificador que foi retornado pelo anterior DxgkDdiCreateAllocation chamada para esse recurso. Se necessário, o driver de miniporto de exibição pode alterar o identificador de recurso durante uma chamada para DxgkDdiCreateAllocation.

Se o driver de exibição do modo de usuário colocar um identificador de recurso em um buffer de comando, o driver de miniporto de exibição poderá recuperar os dados privados chamando DxgkCbGetHandleData. O driver de miniporto de exibição também pode enumerar todas as alocações filho do recurso chamando a função DxgkCbEnumHandleChildren.

A partir do Windows 7, se um driver de miniporto de exibição processar uma chamada para a função DxgkDdiCreateAllocation para criar alocações para aceleração de hardware GDI, o driver deverá definir o tamanho da alocação (incluindo o valor de pitch para alocações visíveis da CPU), pCreateAllocation ->pAllocationInfo->Size.

Os recursos criados no DxgkDdiCreateAllocation chamada pertencem ao adaptador e não ao dispositivo. O driver de miniporto de exibição não deve fazer referência aos dados do dispositivo em qualquer lugar dentro da alocação privada e das estruturas de dados de recurso. Devido ao compartilhamento de superfície, um recurso pode estar em uso após a destruição do dispositivo do qual o driver de exibição no modo de usuário criou o recurso.

DxgkDdiCreateAllocation deve ficar paginável.

Alocando buffers de histórico

A partir do Windows 8.1, quando DxgkDdiCreateAllocation é chamado, o KMD pode definir o DXGK_ALLOCATIONINFOFLAGS.membro do HistoryBuffer para indicar que o driver do modo de usuário pode gerenciar a criação e a destruição de buffers de histórico.