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

  • Artigo

A rotina AllocateCommonBuffer aloca memória e a mapeia para que ela seja simultaneamente acessível do processador e de um dispositivo para operações de DMA.

Sintaxe

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Parâmetros

[in] DmaAdapter

Ponteiro para a estrutura DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador de master de barramento ou o controlador de DMA.

[in] Length

Especifica o número de bytes de memória a serem alocados.

[out] LogicalAddress

Ponteiro para uma variável que recebe o endereço lógico que o dispositivo pode usar para acessar o buffer alocado. Use esse endereço em vez de chamar MmGetPhysicalAddress porque o sistema pode levar em conta quaisquer restrições de memória específicas da plataforma.

[in] CacheEnabled

Especifica se a memória alocada pode ser armazenada em cache.

Este parâmetro é ignorado. O sistema operacional determina se a memória armazenada em cache deve ser habilitada no buffer comum a ser alocado. Essa decisão é baseada na arquitetura do processador e no barramento de dispositivo.

Em computadores com processadores baseados em x86, baseados em x64 e itanium, a memória armazenada em cache é habilitada. Supõe-se que todas as operações de DMA executadas por um dispositivo sejam coerentes com os caches de CPU relevantes, o que pode estar armazenando essa memória em cache. Se o driver precisar desabilitar o cache, chame AllocateCommonBufferEx .

Em computadores com processadores arm ou ARM 64, o sistema operacional não habilita automaticamente a memória armazenada em cache para todos os dispositivos. O sistema depende do método ACPI_CCA para cada dispositivo determinar se o dispositivo é coerente com cache.

Retornar valor

AllocateCommonBuffer retorna o endereço virtual base do intervalo alocado. Se o buffer não puder ser alocado, ele retornará NULL.

Comentários

AllocateCommonBuffer não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina pode ser chamada somente por ponteiro do endereço retornado em uma estrutura de DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter.

AllocateCommonBuffer dá suporte ao DMA no qual o dispositivo e o processador se comunicam continuamente por meio da memória do sistema, como em uma estrutura de controle para um dispositivo DMA master barramento.

AllocateCommonBuffer também dá suporte a dispositivos subordinados cujos drivers usam o modo de inicialização automática de um controlador de DMA do sistema.

AllocateCommonBuffer faz o seguinte:

  • Aloca memória que pode ser acessada do processador e do dispositivo. Essa memória parece contígua para o dispositivo.
  • Aloca registros de mapa para mapear o buffer, se necessário pelo sistema.
  • Configura uma tradução para o dispositivo, incluindo o carregamento de registros de mapa, se necessário.
Para usar economicamente a memória do sistema residente, os drivers devem alocar o menor número possível desses buffers por dispositivo. AllocateCommonBuffer aloca pelo menos uma página de memória, independentemente do Comprimento solicitado. Após uma alocação bem-sucedida solicitando menos de PAGE_SIZE bytes, o chamador pode acessar apenas o Comprimento solicitado. Depois que uma alocação bem-sucedida solicitar mais do que um múltiplo integral de bytes PAGE_SIZE, todos os bytes restantes na última página alocada ficarão inacessíveis para o chamador.

Se um driver precisar de várias páginas de espaço em buffer comum, mas as páginas não precisarem ser contíguas, o driver deverá fazer várias solicitações de uma página para AllocateCommonBuffer em vez de uma solicitação grande. Essa abordagem conserva a memória contígua.

Normalmente, os drivers chamam AllocateCommonBuffer como parte da inicialização do dispositivo durante a resposta a uma solicitação de IRP_MN_START_DEVICE PnP. Após a inicialização, é possível que apenas solicitações de uma página sejam bem-sucedidas, se houver.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows 2000.
Plataforma de Destino Área de Trabalho
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL PASSIVE_LEVEL
Regras de conformidade de DDI IrqlDispatch(wdm)

Confira também

DMA_ADAPTER

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter