Funzione ExAllocatePoolWithTag (wdm.h)
La routine ExAllocatePoolWithTag alloca la memoria del pool del tipo specificato e restituisce un puntatore al blocco allocato.
Avvertimento
ExAllocatePoolWithTag è stato deprecato in Windows 10 versione 2004 ed è stato sostituito da ExAllocatePool2. Per altre informazioni, vedere Aggiornamento di chiamate ExAllocatePool deprecatePool deprecate a ExAllocatePool2 e ExAllocatePool3.
Sintassi
PVOID ExAllocatePoolWithTag(
[in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag
);
Parametri
[in] PoolType
Tipo di memoria del pool da allocare. Per una descrizione dei tipi di memoria del pool disponibili, vedere POOL_TYPE.
È possibile modificare il valore poolType bit per bit con questo valore con il flag di POOL_RAISE_IF_ALLOCATION_FAILURE. Questo flag genera un'eccezione se la richiesta non può essere soddisfatta. L'uso del flag di POOL_RAISE_IF_ALLOCATION_FAILURE non è consigliato perché è costoso.
Analogamente, è possibile modificare il valore poolType bit per bit con questo valore con il flag POOL_COLD_ALLOCATION come hint al kernel per allocare la memoria dalle pagine che probabilmente verranno visualizzate rapidamente. Per ridurre la quantità di memoria del pool residente il più possibile, non è consigliabile fare riferimento a queste allocazioni di frequente. Il flag POOL_COLD_ALLOCATION è solo consultivo.
[in] NumberOfBytes
Numero di byte da allocare.
[in] 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
exAllocatePoolWithTag restituisce NULL se nel pool libero è presente memoria insufficiente per soddisfare la richiesta. In caso contrario, la routine restituisce un puntatore alla memoria allocata.
Osservazioni
Questa routine viene utilizzata per l'allocazione generale della memoria del pool.
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 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.
Una corretta allocazione che richiede NumberOfBytes< PAGE_SIZE di pool non di paging fornisce al chiamante esattamente il numero di byte richiesti di memoria. Se una richiesta di allocazione per NumberOfBytes> PAGE_SIZE ha esito positivo e NumberOfBytes non è un multiplo esatto di PAGE_SIZE, l'ultima pagina nell'allocazione contiene byte che non fanno parte dell'allocazione del chiamante. Se possibile, l'allocatore del pool usa questi byte. Per evitare di danneggiare i dati appartenenti ad altri componenti in modalità kernel, i driver devono accedere solo agli indirizzi di archiviazione allocati in modo esplicito.
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 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 visualizza.
Il buffer allocato può essere liberato con exFreePool o ExFreePoolWithTag.
Il sistema imposta automaticamente determinati oggetti evento standard quando la quantità di pool (di paging o non di paging) è elevata o bassa. I driver possono attendere che questi eventi possano ottimizzare l'utilizzo del pool. Per altre informazioni, vedere oggetti evento standard.
I chiamanti di ExAllocatePoolWithTag devono essere eseguiti in IRQL <= DISPATCH_LEVEL. Un chiamante in esecuzione in DISPATCH_LEVEL deve specificare un valore NonPagedXxx per PoolType. Un chiamante in esecuzione in IRQL <= APC_LEVEL può specificare qualsiasi valore POOL_TYPE, ma è necessario considerare anche IRQL e ambiente per determinare il tipo di pagina.
Non impostare NumberOfBytes = 0. Evitare allocazioni di lunghezza zero perché sprecano lo spazio di intestazione del pool e, in molti casi, indicano un potenziale problema di convalida nel codice chiamante. Per questo motivo, Driver Verifier flag tali allocazioni il più possibile errori.
In un'architettura multiprocessore NUMA (Non Uniform Memory Access), ExAllocatePoolWithTag tenta di allocare memoria locale al processore che chiama ExAllocatePoolWithTag. Se non è disponibile alcuna memoria locale, ExAllocatePoolWithTag alloca la memoria disponibile più vicina.
La memoria che ExAllocatePoolWithTag alloca viene annullata. Un driver in modalità kernel deve prima zero questa memoria se lo rende visibile al software in modalità utente (per evitare la perdita di contenuti potenzialmente privilegiati).
Fabbisogno
| 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) |
| regole di conformità DDI | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |