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

A rotina AllocateCommonBufferEx aloca memória para um buffer comum e mapeia essa memória para que ela possa ser acessada pelo processador e por um dispositivo que executa operações de DMA.

Sintaxe

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER . Essa estrutura é o objeto do adaptador que representa o dispositivo DMA master barramento do driver ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter .

[in, optional] MaximumAddress

Um ponteiro para uma variável que contém o endereço lógico máximo para o buffer comum. Esse parâmetro indica que o buffer deve ser alocado da memória abaixo desse endereço. Esse parâmetro é opcional e pode ser especificado como NULL para indicar que não há endereço máximo.

[in] Length

O tamanho, em bytes, do buffer comum a ser alocado para a operação de DMA.

[out] LogicalAddress

Um ponteiro para uma variável na qual essa rotina grava o endereço lógico que o dispositivo pode usar para acessar o buffer comum. O dispositivo DMA deve usar esse endereço lógico em vez do endereço físico retornado por uma rotina como MmGetPhysicalAddress.

[in] CacheEnabled

Se a rotina deve habilitar ou desabilitar a memória armazenada em cache no buffer comum a ser alocado. Se TRUE, o cache estará habilitado. Se FALSE, ele será desabilitado. Se a plataforma de hardware não impor a coerência de cache para operações de DMA, passe FALSE. Para obter informações sobre esse parâmetro em computadores de destino de processadores baseados em ARM ou ARM 64, consulte Comentários.

[in] PreferredNode

O nó NUMA preferencial do qual a memória deve ser alocada. Se N for o número de nós NUMA em um sistema multiprocessador, PreferredNode será um número no intervalo de 0 a N–1. Para um sistema de um processador ou um sistema multiprocessador não NUMA, defina PreferredNode como zero.

Retornar valor

AllocateCommonBufferEx retorna o endereço virtual da memória alocada para o buffer comum. Se o buffer não puder ser alocado, NULL será retornado.

Comentários

AllocateCommonBufferEx não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada pelo 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.

AllocateCommonBufferEx é uma versão estendida da rotina AllocateCommonBuffer . A lista a seguir resume os recursos que estão disponíveis apenas na versão estendida:

• O chamador pode especificar um endereço lógico máximo para o buffer comum a ser alocado.

• O chamador pode especificar um nó NUMA preferencial no qual o buffer comum deve ser alocado.

Em computadores com processadores baseados em ARM ou ARM 64, as configurações de cache no ACPI do sistema têm uma precedência maior do que o valor do parâmetro CacheEnabled passado pelo driver. Se a ACPI _CCA método indicar que o dispositivo não é coerente em cache, o sistema operacional desabilita o cache mesmo que o driver aloque memória armazenada em cache com CacheEnabled definido como TRUE.

Em computadores com processadores baseados em ARM ou ARM 64, o sistema operacional aloca um buffer comum não armazenado em cache como Memória do Dispositivo. Para obter mais informações sobre o buffer, consulte as seções A3.5.1 e A3.5.6 do Manual de Referência de Arquitetura ARMv7.

O processador não permite acesso desalinhado à Memória do Dispositivo. Seu driver sempre deve acessar dados do buffer comum usando operações alinhadas naturalmente. A maioria das rotinas de kernel não aceita Memória do Dispositivo como parâmetros de entrada. Por exemplo, um driver de rede não pode passar Memória do Dispositivo para NdisMIndicateReceiveNetBufferLists. Se o driver precisar passar dados de um buffer comum de DMA para uma rotina de kernel, aloque o buffer com CacheEnabled definido como TRUE ou copie os dados do buffer comum não armazenado em cache em uma alocação temporária do pool.

Para obter mais informações sobre operações de DMA que usam um buffer comum, consulte os seguintes tópicos:

Usando buffers comuns

Usando Common-Buffer Bus-Master DMA

Usando o DMA do sistema Common-Buffer

Requisitos

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

Confira também

AllocateCommonBuffer

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

MmGetPhysicalAddress