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 tipizzato ULONG64 che specifica il tipo di memoria del pool insieme agli attributi obbligatori e facoltativi. È possibile combinare più valori di flag usando OR bit-wise. Per i valori possibili, vedere POOL_FLAGS.
NumberOfBytes
Specifica un numero diverso da zero di byte da allocare.
Tag
Tag del pool da usare per la memoria allocata. Specificare il tag del pool come valore letterale 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 compreso nell'intervallo 0x20 (spazio) per 0x7E (tilde). Ogni percorso del codice di allocazione deve usare un tag 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 fanno sì che la funzione restituisca NULL per impostazione predefinita. Se viene specificato POOL_FLAG_RAISE_ON_FAILURE, la funzione genera un'eccezione.
- Memoria insufficiente
- tag è impostato su 0 o sono specificate POOL_FLAGS non valide
Osservazioni
Se si sta creando un driver destinato a versioni di Windows precedenti a Windows 10, versione 2004, usare ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZeroo ExAllocatePoolQuotaUninitialized.
Questa routine presenta le differenze seguenti rispetto alle routine di allocazione precedenti (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):
La memoria è zero inizializzata a meno che non venga 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 del pool, vedere POOL_FLAGS.
Se NumberOfBytes è PAGE_SIZE o superiore, viene allocato un buffer allineato alla pagina. Le allocazioni di memoria di PAGE_SIZE o meno vengono allocate all'interno di una pagina e non superano i limiti di pagina. Le allocazioni di memoria di meno di PAGE_SIZE non sono necessariamente allineate alla pagina, 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 NumberOfBytes sono stati allocati in modo esplicito. L'accesso alla memoria al di fuori 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 in WDK, tiene traccia della memoria in base al tag del pool.
Il valore di Tag viene archiviato e talvolta 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 negli strumenti.
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 si accede alla memoria dal codice in esecuzione in DISPATCH_LEVEL, è comunque necessario allocare memoria non di paging.
In un'architettura multiprocessore NUMA (Non Uniform Memory Access) 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 che ExAllocatePool2 alloca è zero inizializzata. I driver in modalità kernel non devono rifiutare esplicitamente di zero le allocazioni che verranno copiate in un percorso non attendibile (modalità utente, in rete e così via) per evitare di divulgare informazioni riservate.
Fabbisogno
| 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 | HwStorPortProhibitedDDIs, SpNoWait, StorPortStartIo |