PALLOCATE_COMMON_BUFFER função de retorno de chamada (wdm.h)
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.
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) |