Macro MmLockPagableCodeSection (wdm.h)

Articolo
02/27/2024

La routine MmLockPagableCodeSection blocca una sezione del codice driver, contenente un set di routine driver contrassegnate con una direttiva del compilatore speciale, nello spazio di sistema.

Sintassi

void MmLockPagableCodeSection(
  [in]  Address
);

Parametri

[in] Address

Specifica un indirizzo simbolico. Questo indirizzo è in genere il nome di una funzione driver all'interno di una sezione del codice driver contrassegnato con qualcosa di simile a #pragma alloc_text (PAGExxxx, driverfunction). Tutte le funzioni nella sezione PAGExxxx vengono quindi bloccate quando questa funzione viene restituita.

Valore restituito

nessuno

Osservazioni

MmLockPagableCodeSection restituisce un valore opaco usato dal sistema operativo per identificare questa sezione del codice del driver. Questo valore opaco può essere passato successivamente a MmLockPagableSectionByHandle (se il driver si sblocca e successivamente riblocca la sezione) o a MmUnlockPagableImageSection.

La routine MmLockPagableCodeSection e MmUnlockPagableImageSection (la routine che esegue l'azione opposta) supportano i driver che possono eseguire le operazioni seguenti:

Rinviare il caricamento di un sottoinsieme di routine del driver in memoria residente fino a quando le richieste di I/O in ingresso per i dispositivi del driver rendono necessario che queste routine elaborino i runtime di integrazione.
Rendere lo stesso subset di routine driver disponibili per il paging quando hanno completato l'elaborazione delle richieste di I/O e non sono attualmente previste richieste aggiuntive per i dispositivi del driver.

MmLockPagableCodeSection, MmLockPagableSectionByHandle e MmUnlockPagableImageSection sono destinati all'uso da parte di driver intermedi e di dispositivo con le caratteristiche seguenti:

Il driver include percorsi di codice che potrebbero non essere necessari durante l'esecuzione del sistema, ma, se necessario, il codice del driver deve risiedere perché viene eseguito in un contesto di thread arbitrario o in IRQL >= DISPATCH_LEVEL.
Il driver può determinare esattamente quando devono essere caricate le routine di paging e quando possono essere distribuiti di nuovo.

Ad esempio, il driver del disco a tolleranza di errore fornito dal sistema supporta la creazione di set di mirror, set di striping e set di volumi. Tuttavia, un particolare computer può essere configurato solo con un set di mirroring, solo con un set di striping, solo con un set di volumi o con qualsiasi combinazione di queste tre opzioni possibili. In queste circostanze, il driver ftdisk di sistema riduce le dimensioni dell'immagine caricata contrassegnando routine che supportano in modo esplicito set di mirror, strip e volume come appartenenti a sezioni di codice di paging. Durante l'inizializzazione del driver, le sezioni di codice di paging vengono rese residenti solo se l'utente ha configurato i dischi in modo che abbiano set di mirroring, strip o volumi. Se l'utente ripartiziona i dischi in modo dinamico, il driver ftdisk blocca eventuali sezioni di codice paginabili aggiuntive necessarie per supportare qualsiasi set di mirror, strip o volume richiesto dall'utente.

Come altri esempi, i driver seriali e paralleli forniti dal sistema hanno routine DispatchCreate e DispatchClose che vengono chiamate quando viene aperta una determinata porta per l'I/O esclusivo e quando viene rilasciato l'handle per una porta aperta, rispettivamente. Tuttavia, le richieste di I/O seriali e parallele sono sporadiche, determinate dalle applicazioni attualmente in esecuzione dall'utente finale e dalle opzioni dell'applicazione attualmente eseguite dall'utente finale. In queste circostanze, i driver seriali e paralleli di sistema riducono le dimensioni delle immagini caricate contrassegnando molte routine come appartenenti a una sezione di codice di paging che la routine DispatchCreate rende residente solo quando la prima porta viene aperta per I/O.

Si noti che ognuno dei driver di sistema precedenti soddisfa entrambi i criteri per avere sezioni di paging: il driver dispone di percorsi di codice che potrebbero non essere necessari durante l'esecuzione del sistema e il driver può determinare esattamente quando deve essere caricata la relativa sezione di paging e può essere terminata di nuovo la pagina.

Poiché si tratta di un'operazione costosa per bloccare una sezione, se un driver blocca una sezione di codice impaginabile in più posizioni, usare MmLockPagableCodeSection per la prima richiesta. Effettuare richieste di blocco successive chiamando MmLockPagableSectionByHandle passando l'handle restituito da MmLockPagableCodeSection. Il blocco tramite handle migliora significativamente le prestazioni del driver perché gestione memoria usa il valore restituito opaco per individuare rapidamente la sezione pertinente anziché eseguire una ricerca in un elenco di moduli caricati. Una sezione bloccata viene sbloccata chiamando MmUnlockPagableImageSection.

Ogni routine del driver all'interno di una sezione codici di paging deve essere contrassegnata con la direttiva del compilatore seguente:

#pragma alloc_text(PAGExxxx, DriverRoutine)

dove xxxx è un identificatore univoco facoltativo di quattro caratteri per la sezione di paging del chiamante e DriverRoutine è un punto di ingresso da includere nella sezione del codice di paging. La parola chiave PAGE e il suffisso determinato dal driver, che può essere composto da un massimo di quattro caratteri, fanno distinzione tra maiuscole e minuscole; vale a dire, PAGE deve essere maiuscola.

Una singola chiamata a MmLockPagableCodeSection in, ad esempio, la routine DispatchCreate di un driver fa sì che l'intera sezione, contenente ogni routine driver contrassegnata con lo stesso identificatore PAGExxxx , venga bloccata nello spazio di sistema.

Alcuni tipi di routine del driver non possono essere inseriti nella sezione di paging di un driver, tra cui:

Non rendere mai visualizzabile un ISR. È possibile che un driver di dispositivo riceva un interrupt spurio anche se il dispositivo non è in uso, in particolare se il vettore di interrupt potrebbe essere condiviso. In generale, anche se un driver può disabilitare in modo esplicito gli interrupt nel dispositivo, un ISR non deve essere reso visualizzabile.
Non rendere mai visualizzabile una routine DPC se il driver non può controllare quando il DPC è in coda, ad esempio qualsiasi routine DpcForIsr o CustomDpc che potrebbe essere accodata da un ISR. In generale, le routine del driver eseguite in IRQL >= DISPATCH_LEVEL e che possono essere chiamate in un contesto di thread arbitrario o in risposta a un evento esterno casuale non devono essere rese pageable.
Non rendere mai impaginabile la routine DispatchRead o DispatchWrite in qualsiasi driver che potrebbe far parte del percorso di I/O di paging del sistema. Il driver di un disco che potrebbe contenere il file di pagina di sistema deve avere routine DispatchRead e DispatchWrite residenti mentre il sistema è in esecuzione, come devono tutti i driver a più livelli sopra un driver del disco di questo tipo.

Si noti che le routine in una sezione impaginabile contrassegnate con la direttiva del compilatore #pragma alloc_text(PAGExxxx, ...) differiscono da routine contrassegnate con la direttiva del compilatore #pragma alloc_text(INIT, ...). Le routine nella sezione INIT non sono impaginabili e vengono eliminate non appena il driver torna dalla routine DriverEntry o reinizializzazione , se presente.

Gestione memoria gestisce un conteggio dei blocchi interni nella sezione di paging di qualsiasi driver. Le chiamate a MmLockPagableCodeSection incrementano questo conteggio e il reciproco MmUnlockPagableImageSection decrementa il conteggio. La sezione impaginabile di un driver non è disponibile per il paging, a meno che questo conteggio non sia zero.

Per altre informazioni sulla creazione di sezioni di codice di paging, vedere Creazione di driver paginabili.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=APC_LEVEL