ALLOCATE_FUNCTION_EX 콜백 함수(wdm.h)

아티클
03/08/2023

LookasideListAllocateEx 루틴은 클라이언트가 비어 있는 lookaside 목록에서 항목을 요청할 때 새 lookaside-list 항목에 대한 스토리지를 할당합니다.

구문

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

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

매개 변수

[in] PoolType

새 lookaside-list 항목에 할당할 스토리지 유형을 지정합니다. 호출자는 이 매개 변수를 유효한 POOL_TYPE 열거형 값으로 설정하고, 다음 플래그 비트 중 하나를 사용하여 이 값을 비트로 설정합니다.

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

POOL_RAISE_IF_ALLOCATION_FAILURE 플래그에 대한 자세한 내용은 ExAllocatePoolWithTag를 참조하세요. POOL_QUOTA_FAIL_INSTEAD_OF_RAISE 플래그에 대한 자세한 내용은 ExAllocatePoolWithQuotaTag를 참조하세요.

lookaside 목록을 초기화한 ExInitializeLookasideListEx 호출에서 Flags 매개 변수가 0인 경우 LookasideListAllocateEx 루틴이 수신하는 PoolType 매개 변수는 ExInitializeLookasideListEx에 전달된 것과 동일한 PoolType 매개 변수 값입니다.

ExInitializeLookasideListEx 호출에서 Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL LookasideListAllocateEx 루틴이 수신하는 PoolType 매개 변수가 POOL_RAISE_IF_ALLOCATION_FAILURE 비트 OR이고 ExInitializeLookasideListEx에 전달된 PoolType 매개 변수 값입니다. LookasideListAllocateEx 루틴은 수정 없이 해당 PoolType 매개 변수 값을 ExAllocatePoolWithTag 루틴에 전달할 수 있습니다.

ExInitializeLookasideListEx 호출에서 Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE LookasideListAllocateEx 루틴이 수신하는 PoolType 매개 변수가 POOL_QUOTA_FAIL_INSTEAD_OF_RAISE 비트 OR이고 ExInitializeLookasideListEx에 전달된 PoolType 값입니다. LookasideListAllocateEx 루틴은 수정 없이 PoolType 매개 변수 값을 ExAllocatePoolWithQuotaTag 루틴에 전달할 수 있습니다.

[in] NumberOfBytes

할당할 lookaside-list 항목의 크기(바이트)를 지정합니다.

[in] Tag

새 lookaside-list 항목에 할당된 스토리지를 표시하는 데 사용할 4바이트 풀 태그를 지정합니다. 풀 태그에 대한 자세한 내용은 ExAllocatePoolWithTag의 Tag 매개 변수에 대한 설명을 참조하세요.

[in, out] Lookaside

lookaside 목록을 설명하는 LOOKASIDE_LIST_EX 구조체에 대한 포인터입니다. 이 구조는 이전에 ExInitializeLookasideListEx 루틴에 의해 초기화되었습니다.

반환 값

LookasideListAllocateEx 는 할당된 lookaside-list 항목에 대한 포인터를 반환합니다. 루틴이 항목을 할당할 수 없는 경우 NULL을 반환합니다.

설명

lookaside 목록을 만드는 드라이버는 LookasideListAllocateEx 루틴을 구현하여 목록에 대한 버퍼를 동적으로 할당할 수 있습니다. 사용하지 않는 버퍼는 목록에 항목으로 저장됩니다. lookaside 목록의 모든 항목은 목록이 초기화될 때 드라이버가 지정하는 균일한 크기의 버퍼입니다.

드라이버는 lookaside 목록을 초기화하는 ExInitializeLookasideListEx 호출에서 입력 매개 변수로 사용자 지정 LookasideListAllocateEx 루틴에 대한 포인터를 제공합니다. 드라이버가 이 매개 변수를 NULL로 설정하는 경우 lookaside 목록은 기본 할당 루틴을 대신 사용합니다.

드라이버는 ExAllocateFromLookasideListEx 루틴을 호출하여 lookaside 목록에서 항목을 할당합니다. 목록이 비어 있는 경우(항목이 없음) ExAllocateFromLookasideListEx는LookasideListAllocateEx 를 호출하여 새 항목에 대한 스토리지를 동적으로 할당합니다. 할당이 성공하면 LookasideListAllocateEx 는 새로 할당된 항목에 대한 포인터를 반환합니다. 그렇지 않으면 NULL을 반환합니다.

PoolType, NumberOfBytes, Tag 및 Lookaside 매개 변수에는 lookaside 목록을 초기화한 ExInitializeLookasideListEx 호출에서 입력 매개 변수로 전달된 것과 동일한 값이 포함됩니다.

LookasideListAllocateEx 루틴은 Lookaside 매개 변수를 사용하여 드라이버가 lookaside 목록과 연결된 프라이빗 컨텍스트 데이터에 액세스할 수 있습니다. 자세한 내용은 ExInitializeLookasideListEx의 코드 예제를 참조하세요.

lookaside 목록에 대한 자세한 내용은 Lookaside Lists 사용을 참조하세요.

LookasideListAllocateEx 루틴은 항목을 요청하는 ExAllocateFromLookasideListEx 호출과 동일한 IRQL에서 호출됩니다. 페이징된 메모리에 있는 항목을 요청하는 호출의 경우 호출자가 IRQL <= APC_LEVEL 실행 중이어야 합니다. 페이지가 지정되지 않은 메모리에 있는 항목을 요청하는 호출의 경우 호출자는 IRQL <= DISPATCH_LEVEL 실행해야 합니다.

예제

LookasideListAllocateEx 콜백 루틴을 정의하려면 먼저 정의 중인 콜백 루틴의 유형을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾는 데 도움이 되며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 라는 MyLookasideListAllocateExLookasideListAllocateEx 콜백 루틴을 정의하려면 이 코드 예제와 같이 FREE_FUNCTION_EX 형식을 사용합니다.

FREE_FUNCTION_EX MyLookasideListFreeEx;

그런 다음 다음과 같이 콜백 루틴을 구현합니다.

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

FREE_FUNCTION_EX 함수 형식은 Wdm.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 _Use_decl_annotations_ 주석을 추가해야 합니다. 주석을 _Use_decl_annotations_ 사용하면 헤더 파일의 FREE_FUNCTION_EX 함수 형식에 적용되는 주석이 사용됩니다. 함수 선언에 대한 요구 사항에 대한 자세한 내용은 WDM 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. 에 대한 _Use_decl_annotations_자세한 내용은 함수 동작 주석 지정을 참조하세요.