Funzione ExAllocatePoolWithTag (wdm.h)

  • Articolo

La routine ExAllocatePoolWithTag alloca la memoria del pool del tipo specificato e restituisce un puntatore al blocco allocato.

Avviso

ExAllocatePoolWithTag è stato deprecato in Windows 10 versione 2004 ed è stato sostituito da ExAllocatePool2. Per altre informazioni, vedere Aggiornamento delle chiamate ExAllocatePool 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-ORing con il flag POOL_RAISE_IF_ALLOCATION_FAILURE. Questo flag causa la generazione di 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 in bit per bit-ORing con il flag POOL_COLD_ALLOCATION come hint per il kernel per allocare la memoria dalle pagine che è probabile che venga eseguito rapidamente il paging. 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 da 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 consentire ai debugger e ai verificatori di identificare il percorso del codice.

Valore restituito

ExAllocatePoolWithTag restituisce NULL se nel pool libero non è presente memoria sufficiente per soddisfare la richiesta. In caso contrario, la routine restituisce un puntatore alla memoria allocata.

Commenti

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.

Un'allocazione corretta 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 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.

Il sistema imposta automaticamente determinati oggetti evento standard quando la quantità di pool (paging o non di paging) è elevata o bassa. I driver possono attendere che questi eventi ottimizzano l'utilizzo del pool. Per altre informazioni, vedere Oggetti evento standard.

I chiamanti di ExAllocatePoolWithTag devono essere in esecuzione 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 spazio di intestazione del pool e, in molti casi, indicano un potenziale problema di convalida nel codice chiamante. Per questo motivo, Driver Verifier contrassegna tali allocazioni come possibili 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 allocata da ExAllocatePoolWithTag non è inizializzata. 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).

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)
Regole di conformità DDI CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

Vedi anche

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE