Fungsi WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfCommonBufferCreateWithConfig membuat buffer memori yang dapat diakses oleh driver dan perangkat akses memori langsung (DMA) secara bersamaan, dan metode ini juga menentukan informasi konfigurasi buffer.

Sintaks

NTSTATUS WdfCommonBufferCreateWithConfig(
  [in]           WDFDMAENABLER             DmaEnabler,
  [in]           size_t                    Length,
  [in]           PWDF_COMMON_BUFFER_CONFIG Config,
  [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.

[in] Config

Penunjuk ke struktur WDF_COMMON_BUFFER_CONFIG yang berisi informasi konfigurasi tentang buffer.

[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

WdfCommonBufferCreateWithConfig 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 WdfCommonBufferCreateWithConfig mengalokasikan memori dan memetakannya sehingga driver dan perangkat dapat mengaksesnya secara bersamaan untuk operasi DMA.

Selain itu, WdfCommonBufferCreateWithConfig memungkinkan driver Anda menentukan persyaratan perataan buffer untuk buffer. Persyaratan perataan buffer menggantikan persyaratan perataan buffer yang ditentukan driver saat disebut WdfDeviceSetAlignmentRequirement. Driver Anda dapat menggunakan WdfCommonBufferCreateWithConfig, alih-alihWdfCommonBufferCreate, jika Anda ingin driver membuat buffer yang memiliki persyaratan perataan yang berbeda dari yang ditentukan WdfDeviceSetAlignmentRequirement .

Setelah driver Anda memanggil WdfCommonBufferCreateWithConfig, 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 WdfCommonBufferCreateWithConfig dari dalam fungsi panggilan balik EvtDriverDeviceAdd .

Sistem operasi menentukan apakah akan mengaktifkan memori cache di 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.

Untuk informasi selengkapnya tentang buffer umum, lihat Menggunakan Buffer Umum

Contoh

Contoh kode berikut menginisialisasi struktur WDF_COMMON_BUFFER_CONFIG lalu membuat buffer 10 byte yang selaras pada batas 32 byte.

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1.1
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)