Fonction MmMapLockedPagesSpecifyCache (wdm.h)

Article
08/08/2023

La routine MmMapLockedPagesSpecifyCache mappe les pages physiques décrites par un MDL à une adresse virtuelle et permet à l’appelant de spécifier l’attribut de cache utilisé pour créer le mappage.

Syntaxe

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
);

Paramètres

[in] MemoryDescriptorList

Pointeur vers le MDL à mapper. Cette MDL doit décrire les pages physiques verrouillées. Une mdL verrouillée peut être créée par la routine MmProbeAndLockPages ou MmAllocatePagesForMdlEx . Pour les mappages à l’espace utilisateur, vous pouvez utiliser des listes MDL créées par la routine MmBuildMdlForNonPagedPool .

[in] AccessMode

Spécifie le mode d’accès dans lequel mapper le MDL : KernelMode ou UserMode. Presque tous les pilotes doivent utiliser KernelMode.

[in] CacheType

Spécifie une valeur MEMORY_CACHING_TYPE , qui indique l’attribut de cache à utiliser pour mapper le MDL. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] RequestedAddress

Si AccessMode = UserMode, ce paramètre spécifie l’adresse virtuelle de l’utilisateur de départ à laquelle mapper le MDL, ou défini sur NULL pour permettre au système de choisir l’adresse de départ. Le système peut arrondir l’adresse demandée pour répondre aux exigences de limite d’adresse. Les appelants doivent donc case activée la valeur de retour.

[in] BugCheckOnFailure

Spécifie le comportement de la routine pour AccessMode = KernelMode si le MDL ne peut pas être mappé en raison de faibles ressources système. Si la valeur EST TRUE, le système émet un bogue case activée. Si la valeur est FALSE, la routine retourne NULL. Les pilotes doivent définir ce paramètre sur FALSE.

[in] Priority

Valeur MM_PAGE_PRIORITY qui indique l’importance de la réussite lorsque les entrées de table de page (PTE) sont rares. À compter de Windows 8, la valeur de priorité spécifiée peut être ORed au niveau du bit avec les indicateurs MdlMappingNoWrite ou MdlMappingNoExecute pour spécifier la mémoire dans laquelle l’exécution des écritures ou des instructions est désactivée. Pour plus d’informations sur les valeurs possibles pour Priority, consultez MmGetSystemAddressForMdlSafe.

Valeur retournée

MmMapLockedPagesSpecifyCache retourne l’adresse de départ des pages mappées. Si les pages ne peuvent pas être mappées et que BugCheckOnFailure a la valeur FALSE, la routine retourne NULL.

Remarques

Utilisez MmUnmapLockedPages pour annuler le mappage des pages physiques qui ont été mappées par MmMapLockedPagesSpecifyCache.

Si AccessMode est KernelMode et si MmMapLockedPagesSpecifyCache ne peut pas mapper les pages spécifiées, la routine retourne NULL (si BugCheckOnFailure = FALSE) ou le système d’exploitation émet un bogue case activée (si BugCheckOnFailure = TRUE).

Si AccessMode est UserMode, tenez compte des détails suivants :

Si les pages spécifiées ne peuvent pas être mappées, la routine génère une exception. Les appelants qui spécifient UserMode doivent encapsuler l’appel à MmMapLockedPagesSpecifyCache dans un bloc try/except . Pour plus d’informations, consultez Gestion des exceptions.
La routine retourne une adresse utilisateur valide dans le contexte du processus dans lequel le pilote est en cours d’exécution. Par exemple, si un pilote 64 bits s’exécute dans le contexte d’une application 32 bits, la mémoire tampon est mappée à une adresse dans la plage d’adresses 32 bits de l’application.
Un mappage non exécutable est toujours créé quand AccessMode est UserMode. Par conséquent, l’utilisation de l’indicateur MdlMappingNoExecute avec le paramètre Priority n’est pas nécessaire dans ce scénario. Toutefois, l’indicateur MdlMappingNoWrite peut toujours être utilisé avec le paramètre Priority dans ce scénario pour demander un mappage en lecture seule.
La protection non exécutable du mappage et toute protection en écriture du mappage spécifié à l’aide de l’indicateur MdlMappingNoWrite avec le paramètre Priority ne peuvent pas être modifiées par le code qui s’exécute en mode utilisateur. Par exemple, si un pilote mappe certaines pages dans un processus utilisateur et spécifie l’indicateur MdlMappingNoWrite , le système garantit que le processus ne peut pas modifier les pages.

La routine utilise le paramètre CacheType uniquement si les pages décrites par le MDL n’ont pas déjà de type de cache associé. Toutefois, dans presque tous les cas, les pages ont déjà un type de cache associé, et ce type de cache est utilisé par le nouveau mappage. Une exception à cette règle concerne les pages allouées par MmAllocatePagesForMdl, qui n’ont pas de type de cache spécifique associé. Pour ces pages, le paramètre CacheType détermine le type de cache du mappage.

Un pilote ne doit pas essayer de créer plusieurs mappages d’espace d’adressage système pour une MDL. En outre, étant donné qu’un MDL qui est créé par la routine MmBuildMdlForNonPagedPool est déjà mappé à l’espace d’adressage système, un pilote ne doit pas essayer de mapper à nouveau cette MDL dans l’espace d’adressage système à l’aide de la routine MmMapLockedPagesSpecifyCache (bien que la création de mappages d’espace d’adressage utilisateur soit autorisée). Si l’on ne sait pas si un MDL verrouillé possède déjà un mappage d’espace d’adressage système, un pilote peut utiliser la macro MmGetSystemAddressForMdlSafe au lieu de MmMapLockedPagesSpecifyCache. Si le MDL est déjà mappé dans l’espace d’adressage système, MmGetSystemAddressForMdlSafe retourne le mappage d’espace d’adressage système existant au lieu de créer un nouveau mappage.

Avertissement

Un pilote qui mappe la mémoire du noyau dans l’espace d’adressage utilisateur doit éviter d’exposer des données de noyau potentiellement sensibles à des processus non approuvés. Les mémoires tampons non initialisées, telles que les mémoires tampons allouées à partir du pool, doivent être explicitement remplies avec des zéros avant d’être mappées. En outre, la taille d’une mémoire tampon en mode utilisateur allouée à partir du pool doit être un multiple de la taille de la page de mémoire virtuelle pour empêcher toute partie des pages de la mémoire tampon d’être utilisée pour d’autres allocations. Enfin, les mémoires tampons ne doivent pas être libérées dans le pool tant qu’elles sont toujours mappées à l’espace d’adressage utilisateur.

Si AccessMode est UserMode, l’appelant doit s’exécuter à IRQL <= APC_LEVEL. Si AccessMode est KernelMode, l’appelant doit s’exécuter à IRQL <= DISPATCH_LEVEL.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Consultez la section Notes.
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)