ALLOCATE_FUNCTION_EX funzione di callback (wdm.h)

Articolo
02/27/2024

La routine LookasideListAllocateEx alloca lo spazio di archiviazione per una nuova voce lookaside-list quando un client richiede una voce da un elenco lookaside vuoto.

Sintassi

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parametri

[in] PoolType

Specifica il tipo di archiviazione da allocare per la nuova voce lookaside-list. Il chiamante imposta questo parametro su un valore di enumerazione POOL_TYPE valido e possibilmente gli OR bit per bit questo valore con uno dei bit di flag seguenti:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Per altre informazioni sul flag di POOL_RAISE_IF_ALLOCATION_FAILURE, vedere ExAllocatePoolWithTag. Per altre informazioni sul flag POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, vedere ExAllocatePoolWithQuotaTag.

Se, nella chiamata di ExInitializeLookasideListEx che ha inizializzato l'elenco lookaside, il parametro Flags è zero, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è lo stesso valore del parametro PoolType passato a ExInitializeLookasideListEx.

Se, nella chiamata di ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è l'OR bit per bit di POOL_RAISE_IF_ALLOCATION_FAILURE e il valore del parametro PoolType passato a ExInitializeLookasideListEx. La routine LookasideListAllocateEx può passare il valore del parametro PoolType , senza alcuna modifica, alla routine ExAllocatePoolWithTag .

Se, nella chiamata di ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è l'OR bit per bit di POOL_QUOTA_FAIL_INSTEAD_OF_RAISE e il valore PoolType passato a ExInitializeLookasideListEx. La routine LookasideListAllocateEx può passare il valore del parametro PoolType , senza alcuna modifica, alla routine ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Specifica le dimensioni, in byte, della voce lookaside-list da allocare.

[in] Tag

Specifica il tag del pool a quattro byte da usare per contrassegnare lo spazio di archiviazione allocato per la nuova voce lookaside-list. Per altre informazioni sui tag del pool, vedere la descrizione del parametro Tag in ExAllocatePoolWithTag.

[in, out] Lookaside

Puntatore a una struttura LOOKASIDE_LIST_EX che descrive l'elenco lookaside. Questa struttura è stata inizializzata in precedenza dalla routine ExInitializeLookasideListEx .

Valore restituito

LookasideListAllocateEx restituisce un puntatore alla voce lookaside-list allocata. Se la routine non può allocare una voce, restituisce NULL.

Commenti

Un driver che crea un elenco lookaside può implementare una routine LookasideListAllocateEx per allocare dinamicamente i buffer per l'elenco. Un buffer non in uso viene archiviato come voce nell'elenco. Tutte le voci di un elenco lookaside sono buffer di una dimensione uniforme, che il driver specifica quando viene inizializzato l'elenco.

Il driver fornisce un puntatore a una routine LookasideListAllocateEx personalizzata come parametro di input nella chiamata ExInitializeLookasideListEx che inizializza l'elenco lookaside. Se il driver imposta questo parametro su NULL, l'elenco lookaside usa invece una routine di allocazione predefinita.

Un driver chiama la routine ExAllocateFromLookasideListEx per allocare una voce da un elenco lookaside. Se l'elenco è vuoto (non contiene voci), ExAllocateFromLookasideListEx chiama LookasideListAllocateEx per allocare dinamicamente la risorsa di archiviazione per una nuova voce. LookasideListAllocateEx restituisce un puntatore alla voce appena allocata se l'allocazione ha esito positivo. In caso contrario, restituisce NULL.

I parametri PoolType, NumberOfBytes, Tag e Lookaside contengono gli stessi valori passati come parametri di input nella chiamata ExInitializeLookasideListEx che ha inizializzato l'elenco lookaside.

La routine LookasideListAllocateEx può utilizzare il parametro Lookaside per accedere ai dati di contesto privati associati al driver all'elenco lookaside. Per altre informazioni, vedere l'esempio di codice in ExInitializeLookasideListEx.

Per altre informazioni sugli elenchi lookaside, vedere Uso di lookaside Elenchi.

La routine LookasideListAllocateEx viene chiamata allo stesso IRQL della chiamata a ExAllocateFromLookasideListEx che richiede la voce. Per una chiamata che richiede una voce che risiede nella memoria di paging, il chiamante deve eseguire IRQL <= APC_LEVEL. Per una chiamata che richiede una voce che risiede nella memoria non in pagine, il chiamante deve eseguire IRQL <= DISPATCH_LEVEL.

Esempio

Per definire una routine di callback LookasideListAllocateEx , è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback LookasideListAllocateEx denominataMyLookasideListAllocateEx, usare il tipo FREE_FUNCTION_EX come illustrato nell'esempio di codice seguente:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

Il tipo di funzione FREE_FUNCTION_EX è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione _Use_decl_annotations_ alla definizione della funzione. L'annotazione _Use_decl_annotations_ garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione FREE_FUNCTION_EX nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.