Funzione MmGetSystemAddressForMdlSafe (wdm.h)

Articolo
02/27/2024

La macro MmGetSystemAddressForMdlSafe restituisce un indirizzo virtuale dello spazio di sistema non di paging per il buffer descritto dall'MDL specificato.

Sintassi

PVOID MmGetSystemAddressForMdlSafe(
  [in] PMDL  Mdl,
  [in] ULONG Priority
);

Parametri

[in] Mdl

Puntatore a un buffer il cui indirizzo virtuale di base corrispondente deve essere mappato.

[in] Priority

Specifica un valore MM_PAGE_PRIORITY che indica l'importanza dell'esito positivo in condizioni PTE a disponibilità bassa. Specificare il valore di priorità LowPagePriority, NormalPagePriority o HighPagePriority. A partire da Windows 8, il valore di priorità specificato può essere bit per bit ORed con i flag MdlMappingNoWrite o MdlMappingNoExecute.

LowPagePriority indica che la richiesta di mapping può avere esito negativo se il sistema è piuttosto basso nelle risorse. Un esempio di questa situazione è una connessione di rete non critica in cui il driver può gestire l'errore di mapping.
NormalPagePriority indica che la richiesta di mapping può avere esito negativo se il sistema è molto basso nelle risorse. Un esempio di questa situazione è una richiesta di file system locale non critica.
HighPagePriority indica che la richiesta di mapping non deve avere esito negativo, a meno che il sistema non sia completamente esaurito dalle risorse. Un esempio di questa situazione è il percorso del file di paging in un driver.
MdlMappingNoWrite indica che le pagine fisiche mappate devono essere configurate come memoria senza scrittura (sola lettura). A partire da Windows 8, questo bit di flag può essere bit per bit ORed con il valore MM_PAGE_PRIORITY per specificare la memoria in cui le scritture sono disabilitate.
MdlMappingNoExecute indica che le pagine fisiche mappate devono essere configurate come memoria senza esecuzione. A partire da Windows 8, questo bit di flag può essere bit per bit ORed con il valore MM_PAGE_PRIORITY per specificare la memoria in cui l'esecuzione delle istruzioni è disabilitata. Come procedura consigliata, i driver scritti per Windows 8 e versioni successive di Windows devono sempre specificare la memoria senza esecuzione, a meno che la memoria eseguibile non sia richiesta in modo esplicito.

Valore restituito

MmGetSystemAddressForMdlSafe restituisce l'indirizzo virtuale dello spazio di sistema di base che esegue il mapping delle pagine fisiche descritte dall'MDL specificato. Se le pagine non sono già mappate allo spazio indirizzi di sistema e il tentativo di eseguirne il mapping ha esito negativo, viene restituito NULL .

Commenti

Questa routine esegue il mapping delle pagine fisiche descritte dal file MDL specificato nello spazio indirizzi del sistema, se non sono già mappate allo spazio indirizzi del sistema.

I driver di dispositivi DI I/O programmati chiamano questa routine per eseguire il mapping di un buffer in modalità utente, descritto da MDL in Irp-MdlAddress> e che è già mappato a un intervallo di indirizzi virtuali in modalità utente, a un intervallo nello spazio indirizzi di sistema.

Nella voce di questa routine, il file MDL specificato deve descrivere le pagine fisiche bloccate. È possibile compilare un MDL bloccato usando la routine MmProbeAndLockPages, MmBuildMdlForNonPagedPool, IoBuildPartialMdl o MmAllocatePagesForMdlEx .

Quando il mapping dello spazio indirizzi di sistema restituito da MmGetSystemAddressForMdlSafe non è più necessario, deve essere rilasciato. I passaggi necessari per rilasciare il mapping dipendono dalla modalità di compilazione del file MDL. Questi sono i quattro casi possibili:

Se MDL è stato compilato da una chiamata alla routine MmProbeAndLockPages , non è necessario rilasciare in modo esplicito il mapping dello spazio indirizzi di sistema. Al contrario, una chiamata alla routine MmUnlockPages rilascia il mapping, se ne è stato allocato uno.
Se MDL è stato compilato da una chiamata alla routine MmBuildMdlForNonPagedPool , MmGetSystemAddressForMdlSafe riutilizza il mapping dello spazio indirizzi di sistema esistente anziché crearne uno nuovo. In questo caso, non è necessaria alcuna pulizia, ovvero lo sblocco e l'annullamento del mapping non sono necessari.
Se MDL è stato compilato da una chiamata alla routine IoBuildPartialMdl , il driver deve chiamare la routine MmPrepareMdlForReuse o la routine IoFreeMdl per rilasciare il mapping dello spazio indirizzi di sistema.
Se MDL è stato compilato da una chiamata alla routine MmAllocatePagesForMdlEx , il driver deve chiamare la routine MmUnmapLockedPages per rilasciare il mapping dello spazio degli indirizzi di sistema. Se MmGetSystemAddressForMdlSafe viene chiamato più volte per un MDL, le successive chiamate MmGetSystemAddressForMdlSafe restituiscono semplicemente il mapping creato dalla prima chiamata. Una chiamata a MmUnmapLockedPages è sufficiente per rilasciare questo mapping.

A partire da Windows 7 e Windows Server 2008 R2, non è necessario chiamare in modo esplicito MmUnmapLockedPages per un MDL creato da MmAllocatePagesForMdlEx. Al contrario, una chiamata alla routine MmFreePagesFromMdl rilascia il mapping dello spazio indirizzi di sistema, se è stato allocato.

Per creare un nuovo mapping dello spazio indirizzi di sistema, MmGetSystemAddressForMdlSafe chiama MmMapLockedPagesSpecifyCache con il parametro CacheType impostato su MmCached. Un driver che richiede un tipo di cache diverso da MmCached deve chiamare MmMapLockedPagesSpecifyCache direttamente anziché chiamare MmGetSystemAddressForMdlSafe. Per altre informazioni sul parametro CacheType , vedere MmMapLockedPagesSpecifyCache.

In una chiamata a MmMapLockedPagesSpecifyCache, il tipo di cache specificato viene utilizzato solo se le pagine descritte dal linguaggio MDL non dispongono già di 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 riguarda le pagine allocate da MmAllocatePagesForMdl, che imposta il tipo di cache su MmCached indipendentemente dal tipo di cache originale delle pagine.

Solo un thread alla volta può chiamare in modo sicuro MmGetSystemAddressForMdlSafe per un determinato MDL perché questa routine presuppone che il thread chiamante sia proprietario del file MDL. Tuttavia, MmGetSystemAddressForMdlSafe può essere chiamato più volte per lo stesso MDL effettuando tutte le chiamate dallo stesso thread o, se le chiamate provengono da più thread, sincronizzando in modo esplicito le chiamate.

Se un driver deve suddividere una richiesta in richieste più piccole, il driver può allocare altri mdls oppure il driver può usare la routine IoBuildPartialMdl .

L'indirizzo di base restituito ha lo stesso offset dell'indirizzo virtuale nel file MDL.

Windows 98 non supporta MmGetSystemAddressForMdlSafe. Usare invece MmGetSystemAddressForMdl .

Poiché questa macro chiama MmMapLockedPagesSpecifyCache, l'uso potrebbe richiedere il collegamento a NtosKrnl.lib.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000
Intestazione	wdm.h
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)