Bagikan melalui

Menggunakan Item Kerja Kerangka Kerja

  • Artikel

Item kerja adalah tugas yang dilakukan driver dalam fungsi panggilan balik peristiwa EvtWorkItem. Fungsi-fungsi ini berjalan secara asinkron, di IRQL = PASSIVE_LEVEL, dalam konteks utas pekerja sistem.

Driver berbasis kerangka kerja biasanya menggunakan item kerja jika fungsi EvtInterruptDpc atau EvtDpcFunc , yang berjalan pada IRQL = DISPATCH_LEVEL, harus melakukan pemrosesan tambahan di IRQL = PASSIVE_LEVEL.

Dengan kata lain, driver dapat menggunakan item kerja jika fungsi yang berjalan di IRQL = DISPATCH_LEVEL harus memanggil fungsi yang hanya dapat dipanggil di IRQL = PASSIVE_LEVEL.

Biasanya, fungsi panggilan balik EvtInterruptDpc atau EvtDpcFunc driver membuat objek item kerja dan menambahkannya ke antrean item kerja sistem. Selanjutnya, utas pekerja sistem menghapus antrean objek dan memanggil fungsi panggilan balik EvtWorkItem item kerja.

Contoh Driver yang Menggunakan Item Kerja

Contoh driver berbasis kerangka kerja yang menggunakan item kerja meliputi 1394, AMCC5933, PCIDRV, dan Toaster.

Menyiapkan Item Kerja

Untuk menyiapkan item kerja, driver Anda harus:

  1. Buat item kerja.

    Driver Anda memanggil WdfWorkItemCreate untuk membuat objek item kerja dan mengidentifikasi fungsi panggilan balik EvtWorkItem yang akan memproses item kerja.

  2. Simpan informasi tentang item kerja.

    Biasanya, driver menggunakan memori konteks objek item kerja untuk menyimpan informasi tentang tugas yang harus dilakukan fungsi panggilan balik EvtWorkItem . Ketika fungsi panggilan balik EvtWorkItem dipanggil, fungsi tersebut dapat mengambil informasi dengan mengakses memori konteks ini. Untuk informasi tentang cara mengalokasikan dan mengakses memori konteks, lihat Ruang Konteks Objek Kerangka Kerja.

  3. Tambahkan item kerja ke antrean item kerja sistem.

    Driver Anda memanggil WdfWorkItemEnqueue, yang menambahkan item kerja driver ke antrean item kerja.

Saat driver Anda memanggil WdfWorkItemCreate, driver harus menyediakan handel ke objek perangkat kerangka kerja atau objek antrean kerangka kerja. Ketika sistem menghapus objek tersebut, sistem juga menghapus item kerja yang ada yang terkait dengan objek . Objek item kerja akan dibuang dan panggilan balik item kerja terkait akan dibersihkan sebelum panggilan balik EvtCleanupCallback objek induk dipanggil.

Untuk informasi selengkapnya tentang aturan pembersihan untuk hierarki objek kerangka kerja, lihat Siklus Hidup Objek Kerangka Kerja.

Menggunakan Fungsi Panggilan Balik Work-Item

Setelah item kerja ditambahkan ke antrean item kerja, item tersebut tetap dalam antrean hingga utas pekerja sistem tersedia. Utas pekerja sistem menghapus item kerja dari antrean lalu memanggil fungsi panggilan balik EvtWorkItem driver, meneruskan objek item kerja sebagai input.

Biasanya, fungsi panggilan balik EvtWorkItem melakukan langkah-langkah berikut:

  1. Mendapatkan informasi yang disediakan driver tentang item kerja dengan mengakses memori konteks objek item kerja.

  2. Melakukan tugas yang Anda tentukan. Jika perlu, fungsi panggilan balik dapat memanggil WdfWorkItemGetParentObject untuk menentukan objek induk item kerja.

  3. Memanggil WdfObjectDelete untuk menghapus objek item kerja atau, jika driver akan mengantre ulang item kerja, menunjukkan bahwa handel ke item kerja sekarang tersedia untuk digunakan kembali.

Tugas yang dilakukan setiap fungsi panggilan balik item kerja harus relatif singkat. Sistem operasi menyediakan sejumlah utas pekerja sistem yang terbatas, sehingga driver Anda dapat menghambat performa sistem jika menggunakan fungsi panggilan balik item kerja untuk melakukan tugas yang memakan waktu.

Membuat dan Menghapus Item Kerja

Driver dapat menggunakan salah satu dari dua teknik berikut untuk membuat dan menghapus item kerja:

  • Gunakan setiap item kerja sekali: buat item kerja saat Anda membutuhkannya dan hapus segera setelah digunakan.

    Teknik ini berguna untuk driver yang jarang digunakan (kurang sering daripada sekali per menit) dari sejumlah kecil item kerja.

    Misalnya, fungsi panggilan balik EvtInterruptDpc driver dapat memanggil WdfWorkItemCreate lalu WdfWorkItemEnqueue, dan fungsi panggilan balik EvtWorkItem item kerja dapat memanggil WdfObjectDelete.

    Jika driver Anda mengikuti skenario ini, dan jika fungsi panggilan balik EvtInterruptDpc menerima nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari WdfWorkItemCreate, driver harus dapat menunda pekerjaan yang diperlukan sampai sumber daya sistem (biasanya memori) tersedia.

  • Buat satu atau beberapa item kerja yang diantrekan ulang driver Anda seperlunya.

    Teknik ini berguna untuk driver yang sering menggunakan item kerja (lebih sering daripada sekali per menit), atau jika fungsi panggilan balik EvtInterruptDpc driver Anda tidak dapat dengan mudah menangani nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari WdfWorkItemCreate.

    Sistem tidak mengalokasikan utas pekerja ke item kerja hingga driver memanggil WdfWorkItemEnqueue. Oleh karena itu, meskipun utas pekerja sistem adalah sumber daya yang terbatas, membuat item kerja saat menginisialisasi perangkat menggunakan sejumlah kecil memori tetapi tidak memengaruhi performa sistem.

    Langkah-langkah berikut menjelaskan kemungkinan skenario:

    1. Fungsi panggilan balik EvtDriverDeviceAdd driver memanggil WdfWorkItemCreate untuk mendapatkan handel item kerja.
    2. Fungsi panggilan balik EvtInterruptDpc driver membuat daftar tindakan yang harus dilakukan fungsi panggilan balik EvtWorkItem lalu memanggil WdfWorkItemEnqueue, menggunakan handel dari langkah 1.
    3. Fungsi panggilan balik EvtWorkItem driver melakukan daftar tindakan dan mengatur bendera untuk menunjukkan bahwa fungsi panggilan balik telah berjalan.

    Selanjutnya, setiap kali fungsi panggilan balik EvtInterruptDpc driver disebut harus menentukan apakah fungsi panggilan balik EvtWorkItem telah berjalan. Jika fungsi panggilan balik EvtWorkItem belum berjalan, fungsi panggilan balik EvtInterruptDpc tidak memanggil WdfWorkItemEnqueue, karena item kerja masih diantrekan. Dalam hal ini, fungsi panggilan balik EvtInterruptDpc hanya memperbarui daftar tindakan untuk fungsi panggilan balik EvtWorkItem .

    Setiap item kerja dikaitkan dengan perangkat atau antrean. Ketika perangkat atau antrean terkait dihapus, kerangka kerja menghapus semua item kerja terkait, jadi jika Anda menggunakan teknik ini, driver tidak perlu memanggil WdfObjectDelete.

Beberapa driver mungkin perlu memanggil WdfWorkItemFlush untuk membersihkan item kerja mereka dari antrean item kerja. Untuk contoh penggunaan WdfWorkItemFlush, lihat halaman referensi metode.

Jika driver memanggil WdfObjectDelete pada item kerja yang luar biasa, hasilnya tergantung pada status item kerja:

Status item kerja Hasil
Dibuat tetapi tidak diantrekan Item kerja segera dibersihkan.
Diantrekan Panggilan ke WdfObjectDelete menunggu hingga item kerja selesai dieksekusi, lalu item kerja dibersihkan
Mengeksekusi Jika driver memanggil WdfObjectDelete dari dalam EvtWorkItem (pada utas yang sama), WdfObjectDelete akan segera kembali. Setelah EvtWorkItem selesai, item kerja akan dibersihkan. Jika tidak, WdfObjectDelete menunggu EvtWorkItem selesai.