WdfMemoryCreate 함수(wdfmemory.h)
[KMDF 및 UMDF에 적용]
WdfMemoryCreate 메서드는 프레임워크 메모리 개체를 만들고 지정된 크기의 메모리 버퍼를 할당합니다.
구문
NTSTATUS WdfMemoryCreate(
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[in] POOL_TYPE PoolType,
[in, optional] ULONG PoolTag,
[in] size_t BufferSize,
[out] WDFMEMORY *Memory,
[out, optional] PVOID *Buffer
);
매개 변수
[in, optional] Attributes
새 메모리 개체에 대한 개체 특성을 포함하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.
[in] PoolType
할당할 메모리 유형을 지정하는 POOL_TYPE 형식의 값입니다.
[in, optional] PoolTag
할당된 메모리에 대한 드라이버 정의 풀 태그입니다. 디버거는 이 태그를 표시합니다. 드라이버는 일반적으로 한 따옴표로 구분된 최대 4자의 문자 문자열을 역순으로 지정합니다(예: 'dcba'). 태그에 있는 각 문자의 ASCII 값은 0에서 127 사이여야 합니다. 각 풀 태그가 고유한 경우 드라이버를 디버깅하는 것이 더 쉽습니다.
PoolTag가 0인 경우 프레임워크는 드라이버 커널 모드 서비스 이름의 처음 4자를 사용하는 기본 풀 태그를 제공합니다. 서비스 이름이 "WDF"로 시작하는 경우(이름은 대/소문자를 구분하지 않고 따옴표를 포함하지 않음) 다음 네 문자가 사용됩니다. 4자 미만의 문자를 사용할 수 있는 경우 "FxDr"이 사용됩니다.
KMDF 버전 1.5 이상에서는 드라이버가 WDF_DRIVER_CONFIG 구조체의 DriverPoolTag 멤버를 사용하여 기본 풀 태그를 지정할 수 있습니다.
[in] BufferSize
버퍼의 0이 아닌 지정된 크기(바이트)입니다.
[out] Memory
새 메모리 개체에 대한 핸들을 받는 위치에 대한 포인터입니다.
[out, optional] Buffer
새 메모리 개체와 연결된 버퍼에 대한 포인터를 받는 위치에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.
반환 값
WdfMemoryCreate 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
잘못된 매개 변수가 감지되었습니다. |
|
메모리가 부족했습니다. |
WdfMemoryCreate 메서드가 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.
이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.
설명
WdfMemoryCreate 메서드는 BufferSize 매개 변수가 지정하는 크기의 버퍼를 할당하고 버퍼를 나타내는 프레임워크 메모리 개체를 만듭니다.
버퍼의 주소를 얻으려면 드라이버가 WdfMemoryCreate 함수의 Buffer 매개 변수에 NULL이 아닌 값을 제공하거나 드라이버가 WdfMemoryGetBuffer를 호출할 수 있습니다.
특히 중요한 정보를 공개하지 않도록 신뢰할 수 없는 위치(사용자 모드, 네트워크를 통해 등)로 복사되는 할당의 경우 메모리 할당을 위해 메모리를 0으로 지정하는 것이 좋습니다. WdfMemoryCreate 는 기본적으로 할당된 메모리를 초기화하지 않습니다.
할당된 메모리의 드라이버 사용 패턴에 따라 드라이버 작성기에 대한 권장 사항은 다음을 고려하는 것입니다.
- WdfMemoryCreate를 호출한 직후 RtlZeroMemory
- 또는 커널 모드에 할당 0 API(ExAllocatePool2, ExAllocatePoolZero)를 사용합니다. 사용자 모드에 대한 HEAP_ZERO_MEMORY 플래그가 있는 HeapAlloc) 뒤에 WdfMemoryCreatePreallocated가 잇습니다. 미리 할당된 버퍼는 WDFMEMORY 또는 해당 부모 삭제의 일부로 자동으로 삭제되지 않으므로 가장 좋은 방법은 아닙니다.
각 메모리 개체의 기본 부모 개체는 WdfMemoryCreate라는 드라이버를 나타내는 프레임워크 드라이버 개체입니다. 드라이버가 특정 디바이스 개체, 요청 개체 또는 기타 프레임워크 개체와 함께 사용하는 메모리 개체를 만드는 경우 메모리 개체의 부모를 적절하게 설정해야 합니다. 부모 개체가 삭제되면 메모리 개체와 해당 버퍼가 삭제됩니다. 기본 부모 개체를 변경하지 않으면 I/O 관리자가 드라이버를 언로드할 때까지 메모리 개체와 버퍼가 유지됩니다.
또한 드라이버는 WdfObjectDelete를 호출하여 메모리 개체와 해당 버퍼를 삭제할 수 있습니다.
BufferSize가 PAGE_SIZE 미만이면 운영 체제는 호출자에게 요청된 메모리 바이트 수를 정확하게 제공합니다. 버퍼는 반드시 페이지 정렬은 아니지만 Ntdef.h에서 MEMORY_ALLOCATION_ALIGNMENT 상수가 지정하는 바이트 수에 따라 정렬됩니다.
BufferSize가 PAGE_SIZE 이상인 경우 KMDF의 경우 시스템에서만 페이지 정렬 버퍼를 할당합니다. PoolType 매개 변수가 NonPagedPool인 경우 시스템은 모든 바이트를 보유하는 데 필요한 페이지 수를 할당합니다. 마지막으로 할당된 페이지에서 사용되지 않는 바이트는 기본적으로 낭비됩니다.
프레임워크 메모리 개체에 대한 자세한 내용은 메모리 버퍼 사용을 참조하세요.
드라이버가 PoolType에 PagedPool을 지정하는 경우 IRQL <= APC_LEVEL WdfMemoryCreate 메서드를 호출해야 합니다. 그렇지 않으면 IRQL <= DISPATCH_LEVEL 메서드를 호출할 수 있습니다.
예제
다음 코드 예제에서는 프레임워크 메모리 개체를 만들고 크기가 WRITE_BUFFER_SIZE 버퍼를 할당합니다. 메모리 개체의 부모는 요청 개체입니다.
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY writeBufferMemHandle;
PVOID writeBufferPointer;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
WRITE_BUFFER_SIZE,
&writeBufferMemHandle,
&writeBufferPointer
);
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 최소 KMDF 버전 | 1.0 |
| 최소 UMDF 버전 | 2.0 |
| 머리글 | wdfmemory.h(Wdf.h 포함) |
| 라이브러리 | Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF) |
| IRQL | 설명 섹션을 참조하십시오. |
| DDI 규정 준수 규칙 | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |