Fungsi WdfCommonBufferCreate (wdfcommonbuffer.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfCommonBufferCreate membuat buffer memori yang dapat diakses oleh driver dan perangkat akses memori langsung (DMA) secara bersamaan.

Sintaks

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

Parameter

[in] DmaEnabler

Handel ke objek pengaktif DMA yang diperoleh driver dengan panggilan sebelumnya ke WdfDmaEnablerCreate.

[in] Length

Ukuran yang diinginkan, dalam byte, dari buffer baru. Ukuran buffer maksimum yang diizinkan adalah (MAXULONG - PAGE_SIZE) byte.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menentukan atribut objek untuk objek buffer umum. (Anggota ParentObject struktur harus NULL.) Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

Penunjuk ke variabel yang diketik WDFCOMMONBUFFER yang menerima handel ke objek buffer umum.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Driver menyediakan parameter yang tidak valid.
STATUS_INSUFFICIENT_RESOURCES	Kerangka kerja tidak dapat mengalokasikan objek buffer umum, atau sistem tidak dapat mengalokasikan buffer.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Metode WdfCommonBufferCreate mengalokasikan memori dan memetakannya sehingga driver dan perangkat dapat mengaksesnya secara bersamaan untuk operasi DMA. Setelah driver Anda memanggil WdfCommonBufferCreate, driver harus:

Panggil WdfCommonBufferGetAlignedVirtualAddress untuk mendapatkan alamat virtual buffer, yang dapat digunakan driver.
Panggil WdfCommonBufferGetAlignedLogicalAddress untuk mendapatkan alamat logis buffer, yang dapat digunakan perangkat.

Driver biasanya memanggil WdfCommonBufferCreate dari dalam fungsi panggilan balik EvtDriverDeviceAdd .

Sebelum driver memanggil WdfDmaEnablerCreate, driver dapat memanggil WdfDeviceSetAlignmentRequirement untuk mengatur persyaratan perataan buffer. Jika driver tidak memanggil WdfDeviceSetAlignmentRequirement, buffer diselaraskan pada batas kata. Jika driver Anda membuat beberapa pengaktif DMA, masing-masing dengan persyaratan penyelarasan buffer yang berbeda, driver dapat memanggil WdfDeviceSetAlignmentRequirement sebelum setiap panggilan ke WdfDmaEnablerCreate.

Untuk membuat buffer umum yang memiliki persyaratan perataan yang berbeda dari persyaratan perataan yang ditentukan driver dengan WdfDeviceSetAlignmentRequirement, driver dapat memanggil WdfCommonBufferCreateWithConfig alih-alihWdfCommonBufferCreate.

Sistem operasi menentukan apakah akan mengaktifkan memori cache dalam buffer umum yang akan dialokasikan. Keputusan itu didasarkan pada arsitektur prosesor dan bus perangkat.

Pada komputer dengan prosesor berbasis x86, berbasis x64, dan berbasis Itanium, memori cache diaktifkan. Pada komputer dengan prosesor berbasis ARM atau ARM 64, sistem operasi tidak secara otomatis mengaktifkan memori cache untuk semua perangkat. Sistem bergantung pada metode ACPI_CCA untuk setiap perangkat untuk menentukan apakah perangkat berkoheren cache.

Objek pengaktif DMA yang ditentukan parameter DmaEnabler dari WdfCommonBufferCreate menjadi objek induk untuk objek buffer umum baru. Driver tidak dapat mengubah induk ini, dan anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES harus NULL. Kerangka kerja menghapus setiap objek buffer umum saat menghapus objek pengaktif DMA induk. Atau, Anda dapat menghapus objek buffer umum secara eksplisit dengan memanggil WdfObjectDelete.

Untuk informasi selengkapnya tentang buffer umum, lihat Menggunakan Buffer Umum.

Contoh

Contoh kode berikut menunjukkan cara mendapatkan buffer umum. Contoh menyimpan informasi tentang buffer umum di ruang konteks yang ditentukan driver yang diidentifikasi oleh penunjuk DevExt .

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfcommonbuffer.h (termasuk WdfCommonBuffer.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)