PCREATE_COMMON_BUFFER_FROM_MDL função de retorno de chamada (wdm.h)

Artigo
08/08/2023

A rotina CreateCommonBufferFromMdl tentará criar um buffer comum de um MDL testando a compatibilidade de acesso do dispositivo e potencialmente mapeando a memória para um intervalo lógico contíguo, dependendo do tipo de tradução. Como todas as outras funções comuns de alocação de buffer, essa função não fornece uma garantia de progresso futuro.

Sintaxe

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parâmetros

[in] DmaAdapter

Fornece um ponteiro para o Adaptador de DMA que está executando a operação.

[in] Mdl

Fornece o MDL que será mapeado para um buffer comum.

Para que um MDL possa fazer backup de um buffer comum, as seguintes condições devem ser atendidas:

O MDL deve ter páginas que sempre residem durante o tempo de vida do buffer comum e que são mapeadas para o espaço de endereço do sistema. Isso pode ser feito pelas seguintes abordagens:
O MDL é criado a partir de um buffer no pool não paginado por meio de MmBuildMdlForNonPagedPool.
O MDL foi bloqueado por meio de MmProbeAndLockPages e mapeado para o espaço do sistema por meio de MmGetSystemAddressForMdlSafe.
As páginas físicas do MDL foram alocadas por meio de MmAllocatePagesForMdlEx e mapeadas para o espaço do sistema por meio de MmGetSystemAddressForMdlSafe.
O MDL deve representar uma região alinhada à página e ser um múltiplo de PAGE_SIZE.
- Se a configuração estendida SubSection estiver sendo usada, a parte do MDL que está sendo usada deverá ser alinhada à página e ser um múltiplo de PAGE_SIZE.
O MDL não deve ser um MDL encadeado.
- Se a configuração estendida SubSection estiver sendo usada, um MDL encadeado poderá ser fornecido, mas a parte do MDL que está sendo usada deverá estar contida em um único MDL na cadeia.
Se a Remapeamento de DMA não estiver sendo usada, o MDL deverá representar memória fisicamente contígua e ser acessível ao dispositivo.

[in] ExtendedConfigs

Fornece uma matriz opcional de estruturas de DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION para configurar ainda mais a criação do buffer comum com backup de MDL.

Se várias configurações do mesmo DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE forem fornecidas na matriz, a criação falhará.

[in] ExtendedConfigsCount

Fornece o número de configurações estendidas na matriz ExtendedConfigs .

[out] LogicalAddress

Em caso de êxito, fornece o endereço lógico do buffer comum resultante.

Retornar valor

CreateCommonBufferFromMdl retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O chamador forneceu uma configuração MDL ou estendida incompatível.
STATUS_NOT_SUPPORTED	O chamador forneceu uma configuração estendida que não tem suporte no sistema atual.
STATUS_INSUFFICIENT_RESOURCES	O sistema não tem memória suficiente para criar metadados de registro e mapeamento.

Comentários

CreateCommonBufferFromMdl não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada por ponteiro do endereço retornado em uma estrutura DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

Um buffer comum criado por CreateCommonBufferFromMdl será removido por meio do FreeCommonBuffer. O chamador deve fornecer o endereço virtual do sistema como o endereço virtual para garantir que o buffer comum seja removido corretamente das estruturas comuns de contabilidade do buffer do Adaptador. O driver ainda é responsável por desbloquear e liberar o MDL e suas páginas de backup.

Para criar um buffer comum em que o HAL é responsável por manter a memória de backup, use AllocateCommonBufferWithBounds.