Fungsi WdfDmaEnablerCreate (wdfdmaenabler.h)

  • Artikel

[Hanya berlaku untuk KMDF]

Metode WdfDmaEnablerCreate membuat objek pengaktif DMA.

Sintaks

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] Config

Penunjuk ke struktur WDF_DMA_ENABLER_CONFIG . Driver harus menginisialisasi struktur ini dengan memanggil WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menentukan atribut objek untuk objek pengaktif DMA baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Handel ke objek pengaktif DMA baru.

Nilai kembali

WdfDmaEnablerCreate mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut.

Menampilkan kode Deskripsi
STATUS_INVALID_PARAMETER
 Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES

Memori tidak cukup untuk membuat objek pengaktif DMA baru.
STATUS_INFO_LENGTH_MISMATCH
 Ukuran struktur WDF_DMA_ENABLER_CONFIG salah.
STATUS_NOT_SUPPORTED
 Driver meminta DMA versi 3 pada sistem operasi yang lebih lama dari Windows 8.
 

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

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Driver berbasis kerangka kerja harus memanggil WdfDmaEnablerCreate sebelum membuat transaksi DMA untuk perangkat.

Sebelum driver memanggil WdfDmaEnablerCreate, driver harus memanggil WdfDeviceSetAlignmentRequirement.

Objek perangkat kerangka kerja yang ditentukan parameter PerangkatWdfDmaEnablerCreate selalu menjadi objek induk untuk objek pengaktif DMA baru. Jika driver menentukan induk yang berbeda di anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES , kerangka kerja mengabaikan nilai ini. Kerangka kerja menghapus objek pengaktif DMA saat menghapus objek induk.

Ketika dipanggil dengan parameter Konfigurasi yang meminta profil DMA mode sistem, WdfDmaEnablerCreate membuat pengaktif DMA yang diinisialisasi sebagian. Driver kemudian harus memanggil WdfDmaEnablerConfigureSystemProfile untuk menyiapkan pengaturan DMA untuk saluran yang mendasar.

Untuk informasi selengkapnya tentang objek pengaktif DMA dan WdfDmaEnablerCreate, lihat Mengaktifkan Transaksi DMA.

Contoh

Contoh kode berikut berasal dari driver sampel PLX9x5x . Contoh ini menetapkan persyaratan perangkat untuk perataan buffer, menginisialisasi struktur WDF_DMA_ENABLER_CONFIG, dan memanggil WdfDmaEnablerCreate.

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

Persyaratan

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

Lihat juga

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement