Partilhar via


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.
Para usar a memória do sistema residente economicamente, 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 de Comprimentosolicitado. Depois de uma alocação bem-sucedida solicitando menos de PAGE_SIZE bytes, o chamador pode acessar apenas o de Comprimentosolicitado. Após uma alocação bem-sucedida solicitando mais do que um múltiplo integral de PAGE_SIZE bytes, todos os bytes restantes na última página alocada ficam 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 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.

Requisitos

Requisito Valor
de cliente com suporte mínimo Disponível a partir do Windows 2000.
da 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)

Consulte também

DMA_ADAPTER

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter