Funzione MmMapLockedPagesSpecifyCache (wdm.h)

Articolo
02/27/2024

La routine MmMapLockedPagesSpecifyCache esegue il mapping delle pagine fisiche descritte da un MDL a un indirizzo virtuale e consente al chiamante di specificare l'attributo cache utilizzato per creare il mapping.

Sintassi

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

Parametri

[in] MemoryDescriptorList

Puntatore all'MDL da eseguire il mapping. Questo MDL deve descrivere le pagine fisiche bloccate. Un MDL bloccato può essere compilato dalla routine MmProbeAndLockPages o MmAllocatePagesForMdlEx . Per i mapping allo spazio utente, è possibile usare mdls compilati dalla routine MmBuildMdlForNonPagedPool .

[in] AccessMode

Specifica la modalità di accesso in cui eseguire il mapping del file MDL: KernelMode o UserMode. Quasi tutti i driver devono usare KernelMode.

[in] CacheType

Specifica un valore MEMORY_CACHING_TYPE , che indica l'attributo della cache da usare per eseguire il mapping dell'MDL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] RequestedAddress

SeAccessMode UserMode = , questo parametro specifica l'indirizzo virtuale dell'utente iniziale in cui eseguire il mapping di MDL a o impostato su NULL per consentire al sistema di scegliere l'indirizzo iniziale. Il sistema potrebbe arrotondare l'indirizzo richiesto per soddisfare i requisiti di limite, pertanto i chiamanti devono controllare il valore restituito.

[in] BugCheckOnFailure

Specifica il comportamento della routine perAccessMode KernelMode = se non è possibile eseguire il mapping di MDL a causa di risorse di sistema basse. Se TRUE, il sistema genera un controllo di bug. Se FALSE, la routine restituisce NULL. I driver devono impostare questo parametro su FALSE.

[in] Priority

Valore MM_PAGE_PRIORITY che indica l'importanza dell'esito positivo quando le voci della tabella di pagina (PTE) sono scarse. A partire da Windows 8, il valore di priorità specificato può essere bit per bit-ORed con i flag MdlMappingNoWrite o MdlMappingNoExecute per specificare la memoria in cui l'esecuzione di scritture o istruzioni è disabilitata. Per altre informazioni sui valori possibili per Priority, vedere MmGetSystemAddressForMdlSafe.

Valore restituito

MmMapLockedPagesSpecifyCache restituisce l'indirizzo iniziale delle pagine mappate. Se le pagine non possono essere mappate e BugCheckOnFailure è FALSE, la routine restituisce NULL.

Commenti

Usare MmUnmapLockedPages per annullare il mapping delle pagine fisiche mappate da MmMapLockedPagesSpecifyCache.

Se AccessMode è KernelMode e se MmMapLockedPagesSpecifyCache non è in grado di eseguire il mapping delle pagine specificate, la routine restituisceNULL (se BugCheckOnFailure = FALSE) o il sistema operativo genera un bug check (se BugCheckOnFailure = TRUE).

Se AccessMode è UserMode, tenere presente i dettagli seguenti:

Se non è possibile eseguire il mapping delle pagine specificate, la routine genera un'eccezione. I chiamanti che specificano UserMode devono eseguire il wrapping della chiamata a MmMapLockedPagesSpecifyCache in un blocco try/eccezione . Per altre informazioni, vedere Gestione delle eccezioni.
La routine restituisce un indirizzo utente valido nel contesto del processo in cui è in esecuzione il driver. Ad esempio, se un driver a 64 bit è in esecuzione nel contesto di un'applicazione a 32 bit, il buffer viene mappato a un indirizzo nell'intervallo di indirizzi a 32 bit dell'applicazione.
Un mapping non eseguibile viene sempre creato quando AccessMode è UserMode. Pertanto, l'uso del flag MdlMappingNoExecute con il parametro Priority non è necessario in questo scenario. Tuttavia, il flag MdlMappingNoWrite può comunque essere usato con il parametro Priority in questo scenario per richiedere un mapping di sola lettura.
La protezione non eseguibile del mapping e qualsiasi protezione in scrittura del mapping specificata usando il flag MdlMappingNoWrite con il parametro Priority non può essere modificato dal codice in esecuzione in modalità utente. Ad esempio, se un driver esegue il mapping di alcune pagine in un processo utente e specifica il flag MdlMappingNoWrite , il sistema garantisce che il processo non possa modificare le pagine.

La routine usa il parametro CacheType solo se le pagine descritte dall'MDL non hanno già un tipo di cache associato. Tuttavia, in quasi tutti i casi, le pagine hanno già un tipo di cache associato e questo tipo di cache viene usato dal nuovo mapping. Un'eccezione a questa regola è per le pagine allocate da MmAllocatePagesForMdl, che non hanno un tipo di cache specifico associato. Per tali pagine, il parametro CacheType determina il tipo di cache del mapping.

Un driver non deve provare a creare più di un mapping dello spazio indirizzi di sistema per un MDL. Inoltre, poiché una MDL compilata dalla routine MmBuildMdlForNonPagedPool è già mappata allo spazio degli indirizzi di sistema, un driver non deve provare a eseguire di nuovo il mapping di questo MDL nello spazio degli indirizzi di sistema usando la routine MmMapLockedPagesSpecifyCache (anche se è consentita la creazione di mapping dello spazio indirizzi utente). Se non è noto se un MDL bloccato ha già un mapping dello spazio indirizzi di sistema, un driver può usare la macro MmGetSystemAddressForMdlSafe anziché MmMapLockedPagesSpecifyCache. Se mDL è già mappato nello spazio degli indirizzi di sistema, MmGetSystemAddressForMdlSafe restituirà il mapping dello spazio indirizzi di sistema esistente anziché creare un nuovo mapping.

Avviso

Un driver che esegue il mapping della memoria del kernel nello spazio degli indirizzi utente deve evitare di esporre i dati del kernel potenzialmente sensibili ai processi non attendibili. I buffer non inizializzati, ad esempio i buffer allocati dal pool, devono essere riempiti in modo esplicito con zero prima che vengano mappati. Inoltre, le dimensioni di un buffer in modalità utente allocata dal pool devono essere un multiplo delle dimensioni della pagina di memoria virtuale per impedire l'uso di qualsiasi parte delle pagine nel buffer per altre allocazioni. Infine, i buffer non devono essere liberati nel pool mentre sono ancora mappati allo spazio indirizzi utente.

Se AccessMode è UserMode, il chiamante deve essere in esecuzione in IRQL <= APC_LEVEL. Se AccessMode è KernelMode, il chiamante deve essere in esecuzione in IRQL <= DISPATCH_LEVEL.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Vedere La sezione Osservazioni.
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport)