DMA_COMPLETION_ROUTINE fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Callback DmaCompletionRoutine rutin memberi tahu driver yang sebelumnya meminta transfer DMA sistem bahwa transfer ini selesai.

Sintaks

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER . Struktur ini adalah objek adaptor yang mewakili saluran DMA sistem driver.

[in] DeviceObject

Penunjuk ke struktur DEVICE_OBJECT . Struktur ini adalah objek perangkat fisik (PDO) yang mewakili perangkat target untuk operasi DMA yang diminta.

[in] CompletionContext

Penunjuk ke konteks yang ditentukan driver untuk rutinitas DmaCompletionRoutine . Konteks ini adalah nilai parameter CompletionContext yang sebelumnya diteruskan driver ke panggilan MapTransferEx yang memulai transfer DMA sistem.

[in] Status

Status penyelesaian transfer DMA. Parameter ini adalah nilai enumerasi DMA_COMPLETION_STATUS yang menunjukkan apakah transfer DMA berhasil diselesaikan.

Nilai kembali

Tidak ada

Keterangan

Sebagai opsi, driver dapat mengimplementasikan rutinitas DmaCompletionRoutine . Ketika driver meminta transfer DMA sistem, driver dapat menyediakan pointer ke rutinitas ini dengan permintaan. Setelah transfer DMA selesai, rutinitas DmaCompletionRoutine secara otomatis dipanggil untuk memberi tahu driver.

Rutinitas DmaCompletionRoutine driver dipanggil hanya jika transfer DMA yang diminta oleh driver menggunakan pengontrol DMA sistem yang dapat menghasilkan gangguan setelah transfer DMA selesai. Driver yang menggunakan perangkat DMA master bus, atau yang menggunakan pengontrol DMA sistem yang tidak menghasilkan gangguan, harus menggunakan cara lain untuk menentukan kapan transfer DMA selesai. Misalnya, driver ini mungkin menggunakan interupsi timer untuk secara berkala melakukan polling status transfer DMA.

Driver dapat menyediakan pointer ke rutinitas DmaCompletionRoutine sebagai parameter opsional ke rutinitas MapTransferEx .

Contoh

Untuk menentukan rutinitas panggilan balik DmaCompletionRoutine , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan rutinitas panggilan balik DmaCompletionRoutine yang diberi nama MyDmaCompletionRoutine, gunakan jenis DMA_COMPLETION_ROUTINE seperti yang ditunjukkan dalam contoh kode ini:

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

Jenis fungsi DMA_COMPLETION_ROUTINE didefinisikan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan _Use_decl_annotations_ anotasi ke definisi fungsi Anda. Anotasi _Use_decl_annotations_ memastikan bahwa anotasi yang diterapkan ke jenis fungsi DMA_COMPLETION_ROUTINE dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang _Use_decl_annotations_, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Dipanggil di DISPATCH_LEVEL.