Fungsi WdfMemoryCreate (wdfmemory.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfMemoryCreate membuat objek memori kerangka kerja dan mengalokasikan buffer memori dengan ukuran tertentu.

Sintaks

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
);

Parameter

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang berisi atribut objek untuk objek memori baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[in] PoolType

Nilai POOL_TYPE-typed yang menentukan jenis memori yang akan dialokasikan.

[in, optional] PoolTag

Tag kumpulan yang ditentukan driver untuk memori yang dialokasikan. Debugger menampilkan tag ini. Driver biasanya menentukan string karakter hingga empat karakter, dibatasi oleh tanda kutip tunggal, dalam urutan terbalik (misalnya, 'dcba'). Nilai ASCII dari setiap karakter dalam tag harus antara 0 dan 127. Penelusuran kesalahan driver Anda lebih mudah jika setiap tag kumpulan unik.

Jika PoolTag nol, kerangka kerja menyediakan tag kumpulan default yang menggunakan empat karakter pertama dari nama layanan mode kernel driver Anda. Jika nama layanan dimulai dengan "WDF" (namanya tidak peka huruf besar/kecil dan tidak menyertakan tanda kutip), empat karakter berikutnya akan digunakan. Jika kurang dari empat karakter tersedia, "FxDr" digunakan.

Untuk KMDF versi 1.5 dan yang lebih baru, driver Anda dapat menggunakan anggota DriverPoolTag dari struktur WDF_DRIVER_CONFIG untuk menentukan tag kumpulan default.

[in] BufferSize

Ukuran yang ditentukan bukan nol, dalam byte, dari buffer.

[out] Memory

Penunjuk ke lokasi yang menerima handel ke objek memori baru.

[out, optional] Buffer

Penunjuk ke lokasi yang menerima penunjuk ke buffer yang terkait dengan objek memori baru. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfMemoryCreate mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfMemoryCreate , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Keterangan

Metode WdfMemoryCreate mengalokasikan buffer ukuran yang ditentukan parameter BufferSize dan membuat objek memori kerangka kerja yang mewakili buffer.

Untuk mendapatkan alamat buffer, driver Anda dapat menyediakan nilai non-NULL untuk parameter Buffer fungsi WdfMemoryCreate, atau driver dapat memanggil WdfMemoryGetBuffer.

Ini adalah praktik yang baik untuk nol memori untuk alokasi memori, terutama untuk alokasi yang akan disalin ke lokasi yang tidak tepercaya (mode pengguna, melalui jaringan, dll.) untuk menghindari pengungkapan informasi sensitif. WdfMemoryCreate tidak nol menginisialisasi memori yang dialokasikan secara default.

Berdasarkan pola penggunaan driver dari memori yang dialokasikan, rekomendasi untuk penulis driver adalah mempertimbangkan:

RtlZeroMemory segera setelah memanggil WdfMemoryCreate
Atau, gunakan API alokasi nol (ExAllocatePool2, ExAllocatePoolZero untuk mode kernel; HeapAlloc dengan bendera HEAP_ZERO_MEMORY untuk mode pengguna), diikuti oleh WdfMemoryCreatePreallocated. Karena buffer yang telah dialokasikan sebelumnya tidak dihapus secara otomatis sebagai bagian dari WDFMEMORY atau penghapusan induknya, ini bukan pendekatan terbaik.

Objek induk default untuk setiap objek memori adalah objek driver kerangka kerja yang mewakili driver yang disebut WdfMemoryCreate. Jika driver Anda membuat objek memori yang digunakannya dengan objek perangkat tertentu, objek permintaan, atau objek kerangka kerja lainnya, itu harus mengatur induk objek memori dengan tepat. Objek memori dan buffernya akan dihapus ketika objek induk dihapus. Jika Anda tidak mengubah objek induk default, objek memori dan buffernya akan tetap ada sampai manajer I/O membongkar driver Anda.

Driver juga dapat menghapus objek memori dan buffernya dengan memanggil WdfObjectDelete.

Jika BufferSize kurang dari PAGE_SIZE, sistem operasi memberi pemanggil jumlah byte memori yang diminta. Buffer belum tentu selaras dengan halaman, tetapi selaras dengan jumlah byte yang ditentukan konstanta MEMORY_ALLOCATION_ALIGNMENT di Ntdef.h.

Jika BufferSize PAGE_SIZE atau lebih besar, untuk KMDF hanya sistem yang mengalokasikan buffer yang selaras dengan halaman. Jika parameter PoolType adalah NonPagedPool, sistem mengalokasikan jumlah halaman yang diperlukan untuk menahan semua byte. Setiap byte yang tidak digunakan pada halaman yang dialokasikan terakhir pada dasarnya terbuang sia-sia.

Untuk informasi selengkapnya tentang objek memori kerangka kerja, lihat Menggunakan Buffer Memori.

Jika driver Anda menentukan PagedPool untuk PoolType, metode WdfMemoryCreate harus dipanggil di IRQL <= APC_LEVEL. Jika tidak, metode dapat dipanggil di IRQL <= DISPATCH_LEVEL.

Contoh

Contoh kode berikut membuat objek memori kerangka kerja dan mengalokasikan buffer yang ukurannya WRITE_BUFFER_SIZE. Induk objek memori adalah objek permintaan.

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
                         );

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfmemory.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf)