Bagikan melalui

Enumerasi Dinamis

enumerasi dinamis adalah kemampuan driver untuk mendeteksi dan melaporkan perubahan pada jumlah dan jenis perangkat yang terhubung ke sistem saat sistem berjalan.

Driver bus harus menggunakan enumerasi dinamis jika jumlah atau jenis perangkat yang terhubung ke perangkat induk bergantung pada konfigurasi sistem. Beberapa perangkat ini mungkin selalu terhubung ke sistem, dan beberapa mungkin dicolokkan dan dilepas saat sistem berjalan.

Misalnya, jumlah dan jenis perangkat yang dicolokkan ke bus PCI sistem bergantung pada sistem, tetapi tetap permanen kecuali pengguna mematikan daya, membuka casing, dan menambahkan atau menghapus perangkat dengan menggunakan obeng. Di sisi lain, pengguna dapat menambahkan atau menghapus perangkat USB dengan mencolokkan atau mencopot kabel saat sistem berjalan.

Daftar Anak Dinamis

Kerangka kerja ini memungkinkan driver untuk mendukung enumerasi dinamis dengan menyediakan objek daftar anak kerangka kerja. Setiap objek daftar turunan mewakili daftar perangkat anak yang tersambung ke perangkat induk. Driver bus untuk perangkat induk harus mengidentifikasi perangkat anak dari induk, menambahkannya ke dalam daftar perangkat anak milik induk, dan membuat objek perangkat fisik (PDO) untuk setiap perangkat anak.

Setiap kali seorang driver membuat objek perangkat kerangka kerja yang mewakili FDO untuk suatu perangkat, kerangka kerja tersebut membuat daftar anak perangkat default yang kosong untuk perangkat tersebut. Driver Anda dapat memperoleh handle ke daftar bawaan anak perangkat dengan memanggil WdfFdoGetDefaultChildList. Biasanya, jika Anda menulis driver bus yang menghitung anak perangkat, driver Anda dapat menambahkan anak ke daftar anak default. Jika Anda perlu membuat daftar anak tambahan, driver Anda dapat memanggil WdfChildListCreate.

Sebelum driver dapat menggunakan daftar turunan, driver harus mengonfigurasi objek daftar turunan dengan menginisialisasi struktur WDF_CHILD_LIST_CONFIG dan meneruskan struktur ke WdfFdoInitSetDefaultChildListConfig, untuk daftar turunan default, atau untuk WdfChildListCreate, untuk daftar anak tambahan.

Deskripsi Anak Dinamis

Setiap kali driver bus mengidentifikasi perangkat anak, driver tersebut harus menambahkan deskripsi perangkat anak ke daftar anak. Deskripsi anak terdiri dari deskripsi identifikasi yang diperlukan dan deskripsi alamat opsional.

Deskripsi Identifikasi Deskripsi identifikasi adalah struktur yang berisi informasi yang secara unik mengidentifikasi setiap perangkat yang dihitung driver. Driver mendefinisikan struktur ini, tetapi anggota pertamanya harus merupakan struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER.

Biasanya, deskripsi identifikasi berisi string identifikasi perangkat, mungkin nomor seri, dan informasi tentang lokasi perangkat pada bus, seperti nomor slot.

Driver dapat menyediakan serangkaian fungsi panggilan balik berikut, yang memungkinkan kerangka kerja untuk memanipulasi informasi dalam deskripsi identifikasi:

Biasanya, Anda perlu menyediakan fungsi panggilan balik ini jika struktur deskripsi identifikasi driver Anda berisi penunjuk ke buffer yang dialokasikan secara dinamis. Untuk informasi selengkapnya tentang tujuan fungsi panggilan balik ini, lihat halaman referensinya.

Deskripsi Alamat Deskripsi alamat adalah struktur yang berisi informasi yang diperlukan driver untuk mengakses perangkat di busnya, jika informasi dapat berubah saat perangkat dicolokkan. Driver mendefinisikan struktur ini, tetapi elemen pertamanya harus merupakan struktur WDF_CHILD_ADDRESS_DESCRIPTION_HEADER.

Deskripsi alamat bersifat opsional. Jika informasi alamat perangkat tidak dapat berubah antara waktu perangkat dicolokkan dan waktu dilepas, semua informasi alamat perangkat dapat disimpan dalam deskripsi identifikasi. Misalnya, pengontrol USB menetapkan alamat ke perangkat saat perangkat dicolokkan, dan alamat ini tidak berubah.

Di sisi lain, beberapa bus menggunakan informasi alamat yang dapat berubah. Misalnya, bus IEEE 1394 menggunakan "jumlah generasi", yang merupakan jumlah reset bus yang terjadi. Setiap permintaan I/O asinkron ke perangkat IEEE 1394 harus menyertakan hitung generasi. Karena informasi alamat ini dapat berubah, driver Anda harus menyimpannya dalam deskripsi alamat.

Untuk memanipulasi informasi dalam deskripsi alamat, driver dapat menyediakan serangkaian fungsi panggilan balik berikut:

Biasanya, Anda perlu menyediakan fungsi panggilan balik ini jika struktur deskripsi alamat driver Anda berisi penunjuk ke buffer yang dialokasikan secara dinamis. Untuk informasi selengkapnya tentang tujuan fungsi panggilan balik ini, lihat halaman referensinya.

Menambahkan Perangkat ke Daftar Anak Dinamis

Ketika kerangka kerja memanggil fungsi panggilan balik driver bus EvtDriverDeviceAdd, fungsi panggilan balik harus memanggil WdfDeviceCreate untuk membuat FDO untuk perangkat induk, yang biasanya merupakan adaptor bus. Untuk informasi selengkapnya tentang membuat FDO (Objek Perangkat melalui Driver Fungsi), lihat Membuat Objek Perangkat di Driver Fungsi. Driver kemudian harus menghitung anak perangkat induk dan menambahkan anak ke daftar anak.

Secara opsional, driver dapat memanggil WdfDeviceSetBusInformationForChildren untuk memberikan kerangka kerja dengan informasi tentang bus. Sebaiknya lakukan karena memudahkan perangkat dan aplikasi anak untuk mengidentifikasi bus.

Untuk menambahkan anak ke daftar anak, driver harus memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk setiap perangkat anak yang ditemukannya. Panggilan ini menginformasikan kerangka kerja bahwa driver telah menemukan perangkat anak yang terhubung ke perangkat induk. Saat driver Anda memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent, driver tersebut menyediakan deskripsi identifikasi dan, secara opsional, deskripsi alamat.

Setelah driver memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk melaporkan perangkat baru, kerangka kerja memberi tahu manajer PnP bahwa perangkat baru ada. Manajer PnP membangun tumpukan perangkat dan tumpukan driver untuk perangkat baru. Sebagai bagian dari proses ini, framework ini memanggil fungsi panggilan balik EvtChildListCreateDevice dari driver bus. Fungsi panggilan balik ini harus memanggil WdfDeviceCreate untuk membuat PDO untuk perangkat baru.

Biasanya, beberapa perangkat anak terhubung ke induk, sehingga driver bus perlu memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent beberapa kali. Cara paling efisien untuk melakukan proses ini adalah sebagai berikut:

  1. Panggil WdfChildListBeginScan.

  2. Panggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk setiap perangkat anak.

  3. Panggil WdfChildListEndScan.

Jika Anda mengelilingi enumerasi dinamis driver Anda dengan panggilan ke WdfChildListBeginScan dan WdfChildListEndScan, kerangka kerja menyimpan semua perubahan pada daftar anak. Ini memberi tahu manajer PnP tentang perubahan ketika driver memanggil WdfChildListEndScan. Di waktu yang akan datang, kerangka kerja memanggil fungsi callback EvtChildListCreateDevice driver bus untuk setiap perangkat dalam daftar perangkat anak. Fungsi panggilan balik ini memanggil WdfDeviceCreate untuk membuat PDO untuk setiap perangkat baru.

Ketika driver Anda memanggil WdfChildListBeginScan, kerangka kerja menandai semua perangkat yang dilaporkan sebelumnya karena tidak lagi ada. Oleh karena itu, driver harus memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk semua anak yang dapat dideteksi driver, bukan hanya anak yang baru ditemukan. Untuk menambahkan satu anak ke daftar anak, driver dapat melakukan satu panggilan ke WdfChildListUpdateAllChildDescriptionsAsPresent tanpa terlebih dahulu memanggil WdfChildListBeginScan.

Memperbarui Daftar Anak Dinamis

Untuk memperbarui informasi dalam daftar anak dinamis, gunakan salah satu metode berikut:

  1. Ketika perangkat induk menerima gangguan yang menunjukkan kedatangan atau penghapusan anak, fungsi panggilan balik EvtInterruptDpc driver memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent jika perangkat dicolokkan atau WdfChildListUpdateChildDescriptionAsMissing jika perangkat dicabut.

  2. Driver dapat menyediakan fungsi panggilan balik EvtChildListScanForChildren, yang dipanggil kerangka kerja setiap kali perangkat induk memasuki status kerja (D0). Fungsi panggilan balik ini harus menghitung semua perangkat anak dengan memanggil WdfChildListBeginScan, WdfChildListAddOrUpdateChildDescriptionAsPresent (atau WdfChildListUpdateAllChildDescriptionsAsPresent), dan WdfChildListEndScan.

Anda dapat menggunakan satu atau kedua teknik ini di driver Anda.

Menelusuri Daftar Elemen Anak Dinamis

Untuk memeriksa konten daftar anak, driver Anda dapat melintasi daftar dengan menggunakan salah satu teknik berikut:

  • Untuk mengambil konten dari setiap deskripsi perangkat anak satu per satu, driver dapat:

    1. Panggil WdfChildListBeginIteration.
    2. Panggil WdfChildListRetrieveNextDevicesebanyak yang diperlukan, dan ulangi sesering yang dibutuhkan.
    3. Panggil WdfChildListEndIteration.

    Saat memanggil WdfChildListBeginIteration, driver menentukan flag WDF_RETRIEVE_CHILD_FLAGStipe yang menunjukkan apakah kerangka kerja harus mengambilkan semua deskripsi perangkat atau hanya subset. Ketika WdfChildListRetrieveNextDevice menemukan kecocokan, ia mengambil deskripsi identifikasi dan alamat perangkat anak, ditambah handel ke objek perangkatnya.

  • Untuk mendapatkan deskripsi alamat yang saat ini terkandung dalam deskripsi perangkat anak, driver Anda dapat memanggil WdfChildListRetrieveAddressDescription, menentukan deskripsi identifikasi. Kerangka kerja melintasi daftar anak hingga menemukan perangkat anak dengan deskripsi identifikasi yang cocok. Kemudian ia mengambil deskripsi alamat.

  • Jika Anda perlu mendapatkan handle ke objek perangkat kerangka kerja yang terkait dengan perangkat anak tertentu, driver Anda dapat memanggil WdfChildListRetrievePdo. Kerangka kerja melintasi daftar anak hingga menemukan perangkat anak dengan deskripsi identifikasi yang cocok, lalu mengembalikan handel objek perangkat. Untuk melindungi pemanggil dari penghapusan PnP PDO secara tiba-tiba pada utas lain, bungkus panggilan dengan WdfChildListBeginIteration dan WdfChildListEndIteration.

Mengakses Deskripsi Identifikasi dan Alamat PDO

Driver Anda dapat memanggil metode berikut untuk mengakses deskripsi identifikasi PDO atau deskripsi alamat:

  • WdfPdoRetrieveIdentificationDescription, yang mengambil deskripsi identifikasi yang terkait dengan PDO.

  • WdfPdoRetrieveAddressDescription , yang mengambil deskripsi alamat yang terkait dengan PDO.

  • WdfPdoUpdateAddressDescription , yang memperbarui deskripsi alamat yang terkait dengan PDO.

Menangani permintaan enumerasi ulang

Driver bus berbasis kerangka kerja yang mendukung enumerasi dinamis dapat menerima permintaan reenumerasi perangkat anak tertentu melalui antarmuka REENUMERATE_SELF_INTERFACE_STANDARD. Untuk informasi selengkapnya, lihat Menangani Permintaan Enumerasi.

  • Last updated on