ALLOCATE_FUNCTION_EX Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die LookasideListAllocateEx Routine weist den Speicher für einen neuen Lookaside-Listeneintrag zu, wenn ein Client einen Eintrag aus einer leeren Lookaside-Liste anfordert.

Syntax

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

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

Parameter

[in] PoolType

Gibt den Speichertyp an, der für den neuen Lookaside-List-Eintrag zugewiesen werden soll. Der Aufrufer legt diesen Parameter auf einen gültigen POOL_TYPE Enumerationswert und möglicherweise bitweise ORs mit einem der folgenden Flagbits fest:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Weitere Informationen zum POOL_RAISE_IF_ALLOCATION_FAILURE-Flag finden Sie unter ExAllocatePoolWithTag. Weitere Informationen zum POOL_QUOTA_FAIL_INSTEAD_OF_RAISE-Flag finden Sie unter ExAllocatePoolWithQuotaTag.

If, in the ExInitializeLookasideListEx call that initialized the lookaside list, der parameter Flags ist null, der PoolType Parameter, den die LookasideListAllocateEx Routine empfängt, ist derselbe PoolType Parameterwert, der an ExInitializeLookasideListExübergeben wurde.

If, in the ExInitializeLookasideListEx call, Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, ist der PoolType Parameter, den die LookasideListAllocateEx Routine empfängt, das bitweise OR von POOL_RAISE_IF_ALLOCATION_FAILURE und der PoolType Parameterwert, der an ExInitializeLookasideListExübergeben wurde. Die LookasideListAllocateEx-Routine kann ihren PoolType Parameterwert ohne Änderung an die ExAllocatePoolWithTag Routine übergeben.

If, in the ExInitializeLookasideListEx call, Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, the PoolType parameter that the LookasideListAllocateEx routine is the bitwise OR of POOL_QUOTA_FAIL_INSTEAD_OF_RAISE and the PoolType value that was passed to ExInitializeLookasideListEx. Die LookasideListAllocateEx--Routine kann ihren PoolType Parameterwert ohne Änderung an die ExAllocatePoolWithQuotaTag Routine übergeben.

[in] NumberOfBytes

Gibt die Größe des zuzuordnenden Lookaside-List-Eintrags in Bytes an.

[in] Tag

Gibt das Vier-Byte-Pooltag an, das zum Markieren des zugewiesenen Speichers für den neuen Lookaside-List-Eintrag verwendet werden soll. Weitere Informationen zu Pooltags finden Sie in der Beschreibung des parameters Tag in ExAllocatePoolWithTag.

[in, out] Lookaside

Ein Zeiger auf eine LOOKASIDE_LIST_EX Struktur, die die Lookaside-Liste beschreibt. Diese Struktur wurde zuvor von der ExInitializeLookasideListEx Routine initialisiert.

Rückgabewert

LookasideListAllocateEx gibt einen Zeiger auf den zugewiesenen Lookaside-List-Eintrag zurück. Wenn die Routine einen Eintrag nicht zuordnen kann, wird NULL-zurückgegeben.

Bemerkungen

Ein Treiber, der eine Lookaside-Liste erstellt, kann eine LookasideListAllocateEx Routine implementieren, um Puffer für die Liste dynamisch zuzuweisen. Ein nicht verwendeter Puffer wird als Eintrag in der Liste gespeichert. Alle Einträge in einer Lookaside-Liste sind Puffer einer einheitlichen Größe, die der Treiber angibt, wann die Liste initialisiert wird.

Der Treiber stellt einen Zeiger auf eine benutzerdefinierte LookasideListAllocateEx Routine als Eingabeparameter im ExInitializeLookasideListEx Aufruf bereit, der die Lookaside-Liste initialisiert. Wenn der Treiber diesen Parameter auf NULL-festlegt, verwendet die Lookaside-Liste stattdessen eine Standardzuordnungsroutine.

Ein Treiber ruft die ExAllocateFromLookasideListEx- Routine auf, um einen Eintrag aus einer Lookaside-Liste zuzuweisen. Wenn die Liste leer ist (enthält keine Einträge), ExAllocateFromLookasideListEx aufruft LookasideListAllocateEx, um den Speicher für einen neuen Eintrag dynamisch zuzuweisen. LookasideListAllocateEx gibt einen Zeiger auf den neu zugewiesenen Eintrag zurück, wenn die Zuordnung erfolgreich ist. Andernfalls wird NULL-zurückgegeben.

Die parameter PoolType, NumberOfBytes, Tagund Lookaside Parameter enthalten dieselben Werte, die als Eingabeparameter im ExInitializeLookasideListEx Aufruf übergeben wurden, der die Lookaside-Liste initialisiert hat.

Die LookasideListAllocateEx Routine kann den Lookaside Parameter verwenden, um auf private Kontextdaten zuzugreifen, die der Treiber der Lookaside-Liste zugeordnet hat. Weitere Informationen finden Sie im Codebeispiel in ExInitializeLookasideListEx.

Weitere Informationen zu Lookaside-Listen finden Sie unter Using Lookaside Lists.

Die LookasideListAllocateEx Routine wird an derselben IRQL aufgerufen wie der Aufruf von ExAllocateFromLookasideListEx, die den Eintrag anfordert. Für einen Aufruf, der einen Eintrag anfordert, der sich im ausgelagerten Speicher befindet, muss der Aufrufer IRQL-<= APC_LEVEL ausführen. Für einen Aufruf, der einen Eintrag anfordert, der sich im nicht ausseitigen Speicher befindet, muss der Aufrufer IRQL-<= DISPATCH_LEVEL ausführen.

Beispiele

Um eine LookasideListAllocateEx- Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine LookasideListAllocateEx- Rückrufroutine definieren möchten, die MyLookasideListAllocateExheißt, verwenden Sie den FREE_FUNCTION_EX Typ, wie in diesem Codebeispiel gezeigt:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

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

Der FREE_FUNCTION_EX Funktionstyp wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den FREE_FUNCTION_EX Funktionstyp in der Headerdatei angewendet werden, verwendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.