Função MmMapLockedPagesSpecifyCache (wdm.h)

Artigo
08/08/2023

A rotina MmMapLockedPagesSpecifyCache mapeia as páginas físicas descritas por um MDL para um endereço virtual e permite que o chamador especifique o atributo de cache usado para criar o mapeamento.

Sintaxe

PVOID MmMapLockedPagesSpecifyCache(
  [in]           PMDL                                                                          MemoryDescriptorList,
  [in]           __drv_strictType(KPROCESSOR_MODE / enum _MODE,__drv_typeConst)KPROCESSOR_MODE AccessMode,
  [in]           __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE                      CacheType,
  [in, optional] PVOID                                                                         RequestedAddress,
  [in]           ULONG                                                                         BugCheckOnFailure,
  [in]           ULONG                                                                         Priority
);

Parâmetros

[in] MemoryDescriptorList

Um ponteiro para o MDL que deve ser mapeado. Esse MDL deve descrever páginas físicas bloqueadas. Um MDL bloqueado pode ser criado pela rotina MmProbeAndLockPages ou MmAllocatePagesForMdlEx . Para mapeamentos para o espaço do usuário, os MDLs criados pela rotina MmBuildMdlForNonPagedPool podem ser usados.

[in] AccessMode

Especifica o modo de acesso no qual mapear o MDL: KernelMode ou UserMode. Quase todos os drivers devem usar KernelMode.

[in] CacheType

Especifica um valor MEMORY_CACHING_TYPE , que indica o atributo de cache a ser usado para mapear o MDL. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] RequestedAddress

Se AccessMode = UserMode, esse parâmetro especificará o endereço virtual do usuário inicial para o qual mapear o MDL ou definir como NULL para permitir que o sistema escolha o endereço inicial. O sistema pode arredondar o endereço solicitado para atender aos requisitos de limite de endereço, portanto, os chamadores devem marcar o valor retornado.

[in] BugCheckOnFailure

Especifica o comportamento da rotina para AccessMode = KernelMode se o MDL não puder ser mapeado devido a recursos de sistema baixos. Se TRUE, o sistema emitirá um bug marcar. Se FALSE, a rotina retornará NULL. Os drivers devem definir esse parâmetro como FALSE.

[in] Priority

Um valor MM_PAGE_PRIORITY que indica a importância do sucesso quando as PTEs (entradas de tabela de página) são escassas. Começando com Windows 8, o valor de prioridade especificado pode ser bit a bit ORed com os sinalizadores MdlMappingNoWrite ou MdlMappingNoExecute para especificar a memória na qual as gravações ou a execução da instrução são desabilitadas. Para obter mais informações sobre os valores possíveis para Priority, consulte MmGetSystemAddressForMdlSafe.

Retornar valor

MmMapLockedPagesSpecifyCache retorna o endereço inicial das páginas mapeadas. Se as páginas não puderem ser mapeadas e BugCheckOnFailure for FALSE, a rotina retornará NULL.

Comentários

Use MmUnmapLockedPages para desmarcar as páginas físicas mapeadas por MmMapLockedPagesSpecifyCache.

Se AccessMode for KernelMode e se MmMapLockedPagesSpecifyCache não puder mapear as páginas especificadas, a rotina retornará NULL (se BugCheckOnFailure = FALSE) ou o sistema operacional emitirá um bug marcar (se BugCheckOnFailure = TRUE).

Se AccessMode for UserMode, lembre-se dos seguintes detalhes:

Se as páginas especificadas não puderem ser mapeadas, a rotina gerará uma exceção. Os chamadores que especificam UserMode devem encapsular a chamada para MmMapLockedPagesSpecifyCache em um bloco try/except . Para obter mais informações, consulte Tratamento de exceções.
A rotina retorna um endereço de usuário válido no contexto do processo no qual o driver está em execução. Por exemplo, se um driver de 64 bits estiver em execução no contexto de um aplicativo de 32 bits, o buffer será mapeado para um endereço no intervalo de endereços de 32 bits do aplicativo.
Um mapeamento não executável sempre é criado quando AccessMode é UserMode. Portanto, usar o sinalizador MdlMappingNoExecute com o parâmetro Priority é desnecessário nesse cenário. No entanto, o sinalizador MdlMappingNoWrite ainda pode ser usado com o parâmetro Priority neste cenário para solicitar um mapeamento somente leitura.
A proteção não executável do mapeamento e qualquer proteção de gravação do mapeamento especificado usando o sinalizador MdlMappingNoWrite com o parâmetro Priority não pode ser alterada pelo código que está em execução no modo de usuário. Por exemplo, se um driver mapear algumas páginas em um processo de usuário e especificar o sinalizador MdlMappingNoWrite , o sistema garantirá que o processo não possa modificar as páginas.

A rotina usará o parâmetro CacheType somente se as páginas descritas pelo MDL ainda não tiverem um tipo de cache associado a elas. No entanto, em quase todos os casos, as páginas já têm um tipo de cache associado e esse tipo de cache é usado pelo novo mapeamento. Uma exceção a essa regra é para páginas alocadas por MmAllocatePagesForMdl, que não têm um tipo de cache específico associado a elas. Para essas páginas, o parâmetro CacheType determina o tipo de cache do mapeamento.

Um driver não deve tentar criar mais de um mapeamento de espaço de endereço do sistema para um MDL. Além disso, como um MDL criado pela rotina MmBuildMdlForNonPagedPool já está mapeado para o espaço de endereço do sistema, um driver não deve tentar mapear esse MDL para o espaço de endereço do sistema novamente usando a rotina MmMapLockedPagesSpecifyCache (embora a criação de mapeamentos de espaço de endereço do usuário seja permitida). Se não se sabe se um MDL bloqueado já tem um mapeamento de espaço de endereço do sistema, um driver pode usar a macro MmGetSystemAddressForMdlSafe em vez de MmMapLockedPagesSpecifyCache. Se o MDL já estiver mapeado para o espaço de endereço do sistema, MmGetSystemAddressForMdlSafe retornará o mapeamento de espaço de endereço do sistema existente em vez de criar um novo mapeamento.

Aviso

Um driver que mapeia a memória do kernel para o espaço de endereço do usuário deve evitar expor dados de kernel potencialmente confidenciais a processos não confiáveis. Buffers não inicializados, como buffers alocados do pool, devem ser preenchidos explicitamente com zeros antes de serem mapeados. Além disso, o tamanho de um buffer de modo de usuário alocado do pool deve ser um múltiplo do tamanho da página de memória virtual para impedir que qualquer parte das páginas no buffer seja usada para outras alocações. Por fim, os buffers não devem ser liberados de volta para o pool enquanto ainda estão mapeados para o espaço de endereço do usuário.

Se AccessMode for UserMode, o chamador deverá estar em execução em IRQL <= APC_LEVEL. Se AccessMode for KernelMode, o chamador deverá estar em execução em IRQL <= DISPATCH_LEVEL.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Consulte a seção Observações.
Regras de conformidade de DDI	HwStorPortProhibitedDDIs(storport)