PALLOCATE_COMMON_BUFFER função de retorno de chamada (wdm.h)
O AllocateCommonBuffer rotina aloca memória e mapeia-a 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 de DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador mestre do barramento ou o controlador 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.
Esse 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 está habilitada. Supõe-se que todas as operações de DMA executadas por um dispositivo sejam coerentes com os caches de CPU relevantes, que podem estar armazenando essa memória em cache. Se o driver precisar desabilitar o cache, chame AllocateCommonBufferEx em vez disso.
Em computadores com processadores baseados em 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.
Valor de retorno
AllocateCommonBuffer retorna o endereço virtual base do intervalo alocado. Se o buffer não puder ser alocado, ele retornará NULL.
Observações
AllocateCommonBuffer 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 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 mestre de barramento.
AllocateCommonBuffer também dá suporte a dispositivos subordinados cujos drivers usam o modo de inicialização automática de um controlador DMA do sistema.
AllocateCommonBuffer faz o seguinte:
- Aloca memória que pode ser acessada do processador e do dispositivo. Essa memória aparece 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.
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 memória contígua.
Os drivers normalmente 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.