Funzione ExAllocatePool2 (wdm.h)
La routine ExAllocatePool2 alloca la memoria del pool del tipo specificato e restituisce un puntatore al blocco allocato.
Sintassi
DECLSPEC_RESTRICT PVOID ExAllocatePool2(
POOL_FLAGS Flags,
SIZE_T NumberOfBytes,
ULONG Tag
);
Parametri
Flags
Valore ULONG64 tipizzato che specifica il tipo di memoria del pool insieme agli attributi obbligatori e facoltativi. È possibile combinare più valori di flag usando OR con bit. Per i valori possibili, vedere POOL_FLAGS .
NumberOfBytes
Specifica un numero non zero di byte da allocare.
Tag
Tag del pool da usare per la memoria allocata. Specificare il tag del pool come valore letterale di carattere diverso da zero di uno a quattro caratteri delimitati da virgolette singole (ad esempio, Tag1). La stringa viene in genere specificata in ordine inverso , ad esempio 1gaT. Ogni carattere ASCII nel tag deve essere un valore nell'intervallo 0x20 (spazio) per 0x7E (tilde). Ogni percorso del codice di allocazione deve usare un tag di pool univoco per aiutare i debugger e i verificatori a identificare il percorso del codice.
Valore restituito
ExAllocatePool2 restituisce un puntatore alla memoria allocata.
Le condizioni seguenti causano la restituzione di NULL per impostazione predefinita. Se viene specificato POOL_FLAG_RAISE_ON_FAILURE , la funzione genera un'eccezione.
- Memoria insufficiente
- I tag sono impostati su 0 o POOL_FLAGS non validi
Commenti
Se si sta creando un driver destinato alle versioni di Windows prima di Windows 10, versione 2004, usare ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero o ExAllocatePoolQuotaUninitialized.
Questa routine presenta le differenze seguenti delle routine di allocazione precedenti (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTag):
La memoria è zero inizializzata a meno che non sia specificata POOL_FLAG_UNINITIALIZED .
Comportamento restituito in caso di allocazione non riuscita. ExAllocatePoolWithQuotaTag genera un'eccezione per impostazione predefinita.
I tag con valore 0 non sono validi.
Quando si sostituisce ExAllocatePoolWithQuotaTag con ExAllocatePool2, è necessario specificare il flag di POOL_FLAG_USE_QUOTA . Per altre informazioni sui flag di pool, vedere POOL_FLAGS.
Se NumberOfBytes è PAGE_SIZE o maggiore, viene allocato un buffer allineato alla pagina. Le allocazioni di memoria di o meno vengono allocate all'interno di PAGE_SIZE una pagina e non superano i limiti di pagina. Le allocazioni di memoria di meno PAGE_SIZE di non sono necessariamente allineate a pagine, ma sono allineate ai limiti a 8 byte nei sistemi a 32 bit e ai limiti a 16 byte nei sistemi a 64 bit.
I driver possono usare solo fino al numeroOfByte allocato in modo esplicito. L'accesso alla memoria all'esterno di questo intervallo può danneggiare il pool e causare l'arresto anomalo del sistema.
Il sistema associa il tag del pool alla memoria allocata. Gli strumenti di programmazione, ad esempio WinDbg, possono visualizzare il tag del pool associato a ogni buffer allocato. Gflags, uno strumento incluso in Strumenti di debug per Windows, attiva una funzionalità di sistema che richiede l'allocazione da un pool speciale per un tag di pool specifico. Poolmon, incluso nel WDK, tiene traccia della memoria in base al tag del pool.
Il valore di Tag viene archiviato e a volte visualizzato, in ordine inverso (little-endian). Ad esempio, se un chiamante passa Fred come tag, viene visualizzato come derF in un dump del pool e nel rilevamento dell'utilizzo del pool nel debugger e, come 0x64657246 nel Registro di sistema e nello strumento, viene visualizzato.
Il buffer allocato può essere liberato con ExFreePool o ExFreePoolWithTag.
I chiamanti di ExAllocatePool2 devono essere in esecuzione in IRQL <= DISPATCH_LEVEL. Un chiamante in esecuzione in DISPATCH_LEVEL deve specificare POOL_FLAG_NON_PAGED o POOL_FLAG_NON_PAGED_EXECUTABLE per flag. Un chiamante in esecuzione in IRQL <= APC_LEVEL può specificare POOL_FLAG_PAGED, ma se la memoria verrà accessibile dal codice in esecuzione in DISPATCH_LEVEL, è necessario allocare ancora memoria non a pagina.
In un'architettura multiprocessore (NUMA) non uniforme, ExAllocatePool2 tenta di allocare memoria locale al processore che chiama ExAllocatePool2. Se non è disponibile alcuna memoria locale, ExAllocatePool2 alloca la memoria disponibile più vicina.
La memoria allocata da ExAllocatePool2 è zero inizializzata. I driver in modalità kernel non devono rifiutare esplicitamente di zero per le allocazioni che verranno copiate in una posizione non attendibile (modalità utente, tramite la rete e così via) per evitare la divulgazione di informazioni riservate.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 10, versione 2004 |
| 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) |
| Regole di conformità DDI | HwStorPortProhibitedDDDIs, SpNoWait, StorPortStartIo |