Funzione ExInitializePagedLookasideList (wdm.h)

Articolo
02/29/2024

La routine ExInitializePagedLookasideList inizializza un elenco lookaside per le voci impaginabili delle dimensioni specificate.

Sintassi

void ExInitializePagedLookasideList(
  [out]          PPAGED_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 PAGED_LOOKASIDE_LIST da inizializzare. Il chiamante deve usare lo spazio di sistema non di paging per la struttura, anche se le voci di questo elenco lookaside verranno allocate dalla memoria di paging. 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,           // PagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Se il parametro Allocate è NULL, le chiamate successive a ExAllocateFromPagedLookasideList 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 ExFreeToPagedLookasideList rilasciano automaticamente la voce specificata nel pool con paging ogni volta che l'elenco è pieno, ovvero 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 ExInitializePagedLookasideList. I bit dei flag compatibili includono quanto segue.

Flag bit	Significato
POOL_RAISE_IF_ALLOCATION_FAILURE	Se l'allocazione non riesce, generare un'eccezione.

La specifica del flag di POOL_NX_ALLOCATION non ha alcun effetto. Tutta la memoria pagable viene allocata come NX.

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

[in] Size

Specifica le dimensioni in byte di ogni voce nell'elenco lookaside.

[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 ExInitializePagedLookasideList, i blocchi delle dimensioni specificate dal chiamante possono essere allocati e liberati all'elenco lookaside con chiamate a ExAllocateFromPagedLookasideList e ExFreeToPagedLookasideList, 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.

ExInitializePagedLookasideList 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 in uso. Poiché la richiesta di voci di elenco lookaside e nella memoria di paging disponibile varia durante l'esecuzione del sistema, il sistema regola i limiti per il numero di voci da mantenere in ogni elenco di lookaside in modo dinamico.

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

ExInitializePagedLookasideList 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 ExAllocateFromPagedLookasideList e queste voci iniziali vengono mantenute nell'elenco lookaside man mano che si verificano chiamate reciproche a ExFreeToPagedLookasideList . Le voci vengono raccolte nell'elenco lookaside specificato fino a quando non viene raggiunto il valore massimo determinato dal sistema, in cui vengono restituite tutte le voci aggiuntive al pool 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 ExInitializePagedLookasideList 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 ExInitializePagedLookasideList fornisce una funzione XxxAllocate , tale funzione 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 di PAGED_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é ExInitializePagedLookasideList. Per altre informazioni, vedere Uso delle Elenchi Lookaside.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlExApcLte2(wdm)