Funzione ExInitializeNPagedLookasideList (wdm.h)

Articolo
03/08/2023

La routine ExInitializeNPagedLookasideList inizializza un elenco lookaside per voci non di paging delle dimensioni specificate.

Sintassi

void ExInitializeNPagedLookasideList(
  [out]          PNPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION     Allocate,
  [in, optional] PFREE_FUNCTION         Free,
  [in]           ULONG                  Flags,
  [in]           SIZE_T                 Size,
  [in]           ULONG                  Tag,
  [in]           USHORT                 Depth
);

Parametri

[out] Lookaside

Puntatore alla struttura NPAGED_LOOKASIDE_LIST da inizializzare. Il chiamante deve usare lo spazio di sistema non in pagine per la struttura. Nelle piattaforme a 64 bit questa struttura deve essere allineata a 16 byte.

[in, optional] Allocate

Puntatore a una funzione fornita dal chiamante per l'allocazione di una voce quando l'elenco lookaside è vuoto o su NULL. Se non NULL, il puntatore è a una funzione con il prototipo:

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // NonPagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Se il parametro Allocate è NULL, le chiamate successive a ExAllocateFromNPagedLookasideList allocano automaticamente le voci ogni volta che l'elenco lookaside è vuoto.

[in, optional] Free

Puntatore a una funzione fornita dal chiamante per liberare una voce ogni volta che l'elenco lookaside è pieno o null. Se non NULL, il puntatore è a una funzione con il prototipo:

VOID XxxFree(
  __in PVOID  Buffer
);

Se il parametro Free è NULL, le chiamate successive a ExFreeToNPagedLookasideList rilasciano automaticamente la voce specificata nel pool non di paging ogni volta che l'elenco è pieno, ovvero mantenendo il numero massimo di voci determinato dal sistema.

[in] Flags

A partire da Windows 8, questo parametro specifica un valore di flag facoltativo per modificare il comportamento predefinito della routine ExInitializeNPagedLookasideList. I bit dei flag compatibili includono quanto segue.

Flag bit	Significato	Valore
POOL_RAISE_IF_ALLOCATION_FAILURE	Se l'allocazione non riesce, generare un'eccezione.	16
POOL_NX_ALLOCATION	Allocare memoria non eseguibile.	512

Prima di Windows 8, questo parametro non viene usato e deve essere zero.

[in] Size

Specifica le dimensioni, in byte, per ogni voce non di paging da allocare successivamente. Questo parametro non deve essere inferiore alla dimensione minima richiesta, LOOKASIDE_MINIMUM_BLOCK_SIZE, definita nel file di intestazione Wdm.h.

[in] Tag

Specifica il tag del pool da utilizzare per l'allocazione delle voci dell'elenco lookaside. Per altre informazioni sui tag del pool, vedere il parametro Tag di ExAllocatePoolWithTag.

[in] Depth

Riservato. Deve essere zero.

Valore restituito

nessuno

Osservazioni

Dopo aver chiamato ExInitializeNPagedLookasideList, i blocchi di memoria della dimensione specificata dal chiamante possono essere allocati e liberati all'elenco lookaside con chiamate a ExAllocateFromNPagedLookasideList e ExFreeToNPagedLookasideList, rispettivamente. Tali voci allocate e liberate in modo dinamico possono essere qualsiasi struttura di dati o buffer a dimensione fissa usata dal chiamante durante l'esecuzione del sistema, in particolare se il chiamante non può predeterminato il numero di voci in uso in un determinato momento. Il layout e il contenuto di ogni voce a dimensione fissa sono determinati dal chiamante.

ExInitializeNPagedLookasideList inizializza lo stato del sistema per tenere traccia dell'utilizzo dell'elenco lookaside specificato, come indicato di seguito:

Inizializza zero i contatori da mantenere per le voci.
Archivia i punti di ingresso delle routine XxxAllocate e XxxFree fornite dal chiamante, se presenti, o imposta questi punti di ingresso rispettivamente su ExAllocatePoolWithTag e ExFreePool.
Inizializza un blocco di rotazione di sistema per controllare le allocazioni da e libera all'elenco lookaside in modo sicuro, se necessario.
Archivia la voce fornita dal chiamante Dimensioni e tag elenco.
Imposta i limiti determinati dal sistema (minimo e massimo) sul numero di voci da mantenere nell'elenco lookaside, che possono essere modificati successivamente se la domanda a livello di sistema per le voci è superiore o inferiore al previsto.
Configura i flag determinati dal sistema, che controllano il tipo di memoria da cui verranno allocate le voci successivamente.

Il sistema gestisce un set di tutti gli elenchi lookaside attualmente in uso. Poiché la richiesta di voci di elenco lookaside e in memoria non di paging disponibile varia durante l'esecuzione del sistema, il sistema modifica i limiti per il numero di voci da mantenere in ogni elenco lookaside non a pagina in modo dinamico.

I driver devono sempre liberare esplicitamente tutti gli elenchi lookaside creati prima dello scaricamento. In caso contrario, si tratta di un errore di programmazione grave. Utilizzare ExDeleteNPagedLookasideList per liberare l'elenco.

ExInitializeNPagedLookasideList configura l'intestazione elenco opaca nella posizione fornita dal chiamante, ma non prealloca memoria per le voci di elenco. Successivamente, le voci iniziali vengono allocate in modo dinamico man mano che si verificano chiamate a ExAllocateFromNPagedLookasideList e queste voci iniziali vengono mantenute nell'elenco lookaside man mano che si verificano chiamate reciproche a ExFreeToNPagedLookasideList . Le voci vengono raccolte nell'elenco lookaside specificato fino a quando non viene raggiunto il valore massimo determinato dal sistema, in base alla quale vengono restituite eventuali voci aggiuntive nel pool non di paging man mano che vengono liberate. Se l'elenco diventa vuoto, le richieste di allocazione vengono soddisfatte dalla funzione XxxAllocate specificata in fase di inizializzazione dell'elenco o da ExAllocatePoolWithTag.

È più efficiente passare puntatori NULL per i parametri Allocate e Free di ExInitializeNPagedLookasideList ogni volta che l'utente di un elenco lookaside non esegue altro che allocare e rilasciare voci di dimensioni fisse. Tuttavia, qualsiasi componente che usa un elenco lookaside potrebbe fornire queste funzioni per eseguire un'elaborazione aggiuntiva determinata dal chiamante, ad esempio per tenere traccia del proprio utilizzo di memoria dinamica mantenendo lo stato relativo al numero di voci allocate e libere.

Se il chiamante di ExInitializeNPagedLookasideList fornisce una funzione XxxAllocate , tale routine deve allocare voci per l'elenco lookaside usando i parametri di input specificati quando chiama ExAllocatePoolWithTag.

A partire da Windows Vista, una routine simile, ExInitializeLookasideListEx, inizializza un elenco lookaside descritto da una struttura LOOKASIDE_LIST_EX . A differenza delle routine XxxAllocate e XxxFree per un elenco lookaside che utilizza una struttura NPAGED_LOOKASIDE_LIST , le routine di allocazione e deallocazione per un elenco lookaside che utilizza la struttura LOOKASIDE_LIST_EX ricevono un puntatore di contesto come parametro di input. Queste routine possono usare questo contesto per archiviare i dati privati per l'elenco lookaside. Se il driver deve essere eseguito solo in Windows Vista e versioni successive di Windows, è consigliabile usare ExInitializeLookasideListEx anziché ExInitializeNPagedLookasideList. Per altre informazioni, vedere Uso delle Elenchi Lookaside.

I chiamanti di ExInitializeNPagedLookasideList possono essere eseguiti in IRQL <= DISPATCH_LEVEL, ma in genere vengono eseguiti in IRQL = PASSIVE_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	IRQL <= DISPATCH_LEVEL (vedere la sezione Osservazioni)