Função MmAllocateNodePagesForMdlEx (wdm.h)

Artigo
03/08/2023

A rotina MmAllocateNodePagesForMdlEx aloca memória física nãopagada de um nó ideal e aloca uma estrutura MDL para descrever essa memória.

Sintaxe

PMDL MmAllocateNodePagesForMdlEx(
  [in] PHYSICAL_ADDRESS    LowAddress,
  [in] PHYSICAL_ADDRESS    HighAddress,
  [in] PHYSICAL_ADDRESS    SkipBytes,
  [in] SIZE_T              TotalBytes,
  [in] MEMORY_CACHING_TYPE CacheType,
  [in] ULONG               IdealNode,
  [in] ULONG               Flags
);

Parâmetros

[in] LowAddress

O endereço físico do início do primeiro intervalo de endereços do qual as páginas alocadas podem vir. Se MmAllocateNodePagesForMdlEx não puder alocar o número solicitado de bytes no primeiro intervalo de endereços, a rotina itera por meio de intervalos de endereços adicionais para obter mais páginas. Em cada iteração, MmAllocateNodePagesForMdlEx adiciona o valor de SkipBytes ao endereço inicial anterior para calcular o início do próximo intervalo de endereços.

[in] HighAddress

O endereço físico do final do primeiro intervalo de endereços do qual as páginas alocadas podem vir.

[in] SkipBytes

O número de bytes a serem ignorados do início do intervalo de endereços anterior do qual as páginas alocadas podem vir. SkipBytes deve ser um número inteiro múltiplo do tamanho da página de memória virtual, em bytes.

[in] TotalBytes

O número total de bytes a serem alocados para o MDL.

[in] CacheType

Um valor MEMORY_CACHING_TYPE , que indica o tipo de cache permitido para a memória solicitada.

[in] IdealNode

O número ideal do nó. Se um sistema multiprocessador contiver N nós, os números de nó válidos estarão no intervalo de 0 a N-1. Seu driver pode chamar a rotina KeQueryHighestNodeNumber para obter o número de nó mais alto. Um sistema multiprocessador de processador único ou não NUMA tem apenas um nó, nó 0, do qual alocar memória. Para um sistema multiprocessador NUMA, a alocação é feita do nó ideal, se possível. Se a memória insuficiente estiver disponível no nó ideal para atender à solicitação de alocação e o chamador não definir o sinalizador MM_ALLOCATE_FROM_LOCAL_NODE_ONLY, MmAllocateNodePagesForMdlEx tentará alocar memória de outros nós.

[in] Flags

Sinalizadores para esta operação. Defina esse parâmetro como zero ou como o OR bit a bit de um ou mais dos seguintes bits de sinalizador:

MM_DONT_ZERO_ALLOCATION
MM_ALLOCATE_FROM_LOCAL_NODE_ONLY
MM_ALLOCATE_FULLY_REQUIRED
MM_ALLOCATE_NO_WAIT
MM_ALLOCATE_PREFER_CONTIGUOUS
MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS
MM_ALLOCATE_AND_HOT_REMOVE

Para obter mais informações sobre esses sinalizadores, consulte MM_ALLOCATE_XXX.

Retornar valor

MmAllocateNodePagesForMdlEx retornará um ponteiro para uma estrutura MDL se for bem-sucedida. Caso contrário, se a rotina não alocar memória, a rotina retornará NULL.

Um valor retornado de NULL indica que nenhuma página de memória física está disponível nos intervalos de endereços especificados ou que não há pool de memória suficiente disponível para alocar a estrutura MDL.

Se a rotina alocar com êxito alguns, mas não todos, da memória solicitada, o MDL descreve a quantidade de memória física que a rotina foi capaz de alocar.

Comentários

Em um sistema multiprocessador NUMA (acesso à memória) não uniforme, o chamador pode especificar um nó ideal do qual alocar a memória. Um nó é uma coleção de processadores que compartilham acesso rápido a uma região de memória. Em um multiprocessador não NUMA ou em um sistema de processador único, MmAllocateNodePagesForMdlEx trata toda a memória como pertencente a um único nó e aloca memória desse nó.

Por padrão, as páginas de memória física que MmAllocateNodePagesForMdlEx retorna não são páginas contíguas. Os chamadores podem substituir o comportamento padrão dessa rotina definindo o bit de sinalizador MM_ALLOCATE_PREFER_CONTIGUOUS ou MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS no parâmetro Flags .

MmAllocateNodePagesForMdlEx não mapeia a memória física alocada para memória virtual. Se necessário, o chamador pode chamar uma rotina como MmMapLockedPagesSpecifyCache para mapear as páginas de memória física descritas pelo MDL.

MmAllocateNodePagesForMdlEx foi projetado para drivers no modo kernel que não precisam de endereços virtuais correspondentes (ou seja, eles precisam de páginas físicas e não precisam que sejam fisicamente contíguos) e para drivers no modo kernel que podem obter ganhos substanciais de desempenho se a memória física de um dispositivo for alocada em um intervalo de endereços físico específico (por exemplo, um cartão gráficos do AGP).

Dependendo da quantidade de memória física disponível atualmente nos intervalos solicitados, MmAllocateNodePagesForMdlEx pode retornar um MDL que descreve menos memória do que foi solicitado. A rotina também poderá retornar NULL se nenhuma memória tiver sido alocada. O chamador deve marcar a quantidade de memória que é realmente alocada, conforme descrito pelo MDL.

O chamador deve usar MmFreePagesFromMdl para liberar as páginas de memória descritas por um MDL que foi criado por MmAllocateNodePagesForMdlEx. Depois de chamar MmFreePagesFromMdl, o chamador também deve chamar ExFreePool para liberar a memória alocada para a estrutura MDL.

Por padrão, MmAllocateNodePagesForMdlEx preenche as páginas alocadas com zeros. O chamador pode especificar o sinalizador MM_DONT_ZERO_ALLOCATION para substituir esse padrão e possivelmente melhorar o desempenho.

A memória alocada por MmAllocateNodePagesForMdlEx será não inicializada se você especificar o sinalizador MM_DONT_ZERO_ALLOCATION. Um driver de modo kernel deve primeiro zero essa memória se o driver vai tornar a memória visível para o software do modo de usuário (para evitar vazamento de conteúdo potencialmente privilegiado). Para obter mais informações sobre esse sinalizador, consulte MM_ALLOCATE_XXX.

A quantidade máxima de memória que MmAllocateNodePagesForMdlEx pode alocar em uma única chamada é (4 gigabytes - PAGE_SIZE). A rotina só poderá atender a uma solicitação de alocação para esse valor se páginas suficientes estiverem disponíveis.

MmAllocateNodePagesForMdlEx é executado em IRQL <= APC_LEVEL. Se necessário, o driver pode chamar MmAllocateNodePagesForMdlEx em DISPATCH_LEVEL. No entanto, você pode melhorar o desempenho do driver chamando em APC_LEVEL ou abaixo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (consulte a seção Comentários.)