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 permanen kecuali pengguna mematikan daya, membuka casing, dan menambahkan atau menghapus perangkat dengan menggunakan obeng. Di sisi lain, pengguna dapat menambahkan atau melepas 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 induk, menambahkannya ke daftar anak perangkat induk, dan membuat objek perangkat fisik (PDO) untuk setiap anak.
Setiap kali driver membuat objek perangkat kerangka kerja yang mewakili FDO untuk perangkat, kerangka kerja membuat daftar anak default kosong untuk perangkat. Driver Anda dapat memperoleh handel ke daftar anak default perangkat dengan memanggil WdfFdoGetDefaultChildList. Biasanya, jika Anda menulis driver bus yang menghitung anak perangkat, driver Anda dapat menambahkan anak-anak ke daftar anak default. Jika Anda perlu membuat daftar anak tambahan, driver Anda dapat memanggil WdfChildListCreate.
Sebelum driver dapat menggunakan daftar anak, driver harus mengonfigurasi objek daftar turunan dengan menginisialisasi struktur WDF_CHILD_LIST_CONFIG dan meneruskan struktur ke WdfFdoInitSetDefaultChildListConfig, untuk daftar anak default, atau ke 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 dijumlahkan driver. Driver mendefinisikan struktur ini, tetapi anggota pertamanya harus merupakan struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER .
Biasanya, deskripsi identifikasi berisi string identifikasi perangkat perangkat, mungkin nomor seri, dan informasi tentang lokasi perangkat di bus, seperti nomor slot.
Driver dapat menyediakan serangkaian fungsi panggilan balik berikut, yang memungkinkan kerangka kerja untuk memanipulasi informasi dalam deskripsi identifikasi:
EvtChildListIdentificationDescriptionCompare, yang membandingkan konten dua struktur deskripsi identifikasi.
EvtChildListIdentificationDescriptionCopy, yang menyalin konten dari satu struktur deskripsi identifikasi ke struktur deskripsi identifikasi lainnya.
EvtChildListIdentificationDescriptionDuplicate, yang membuat deskripsi identifikasi baru dengan menduplikasi struktur deskripsi identifikasi yang ada dan, jika perlu, mengalokasikan buffer tambahan.
EvtChildListIdentificationDescriptionCleanup, yang membatalkan alokasi buffer yang dialokasikan oleh fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate .
Biasanya, Anda harus menyediakan fungsi panggilan balik ini jika struktur deskripsi identifikasi driver Anda berisi pointer 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 sehingga dapat mengakses perangkat di busnya, jika informasi dapat berubah saat perangkat dicolokkan. Driver mendefinisikan struktur ini, tetapi anggota 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 telah terjadi. Setiap permintaan I/O asinkron ke perangkat IEEE 1394 harus menyertakan jumlah pembuatan. Karena informasi alamat ini dapat berubah, driver Anda harus menyimpannya dalam deskripsi alamat.
Driver dapat menyediakan serangkaian fungsi panggilan balik berikut untuk memanipulasi informasi dalam deskripsi alamat:
EvtChildListAddressDescriptionCopy, yang menyalin konten dari satu struktur deskripsi alamat ke struktur deskripsi alamat lainnya.
EvtChildListAddressDescriptionDuplicate, yang membuat deskripsi alamat baru dengan menduplikasi struktur deskripsi alamat yang ada dan, jika perlu, mengalokasikan buffer tambahan.
EvtChildListAddressDescriptionCleanup, yang membatalkan alokasi buffer yang dialokasikan oleh fungsi panggilan balik EvtChildListAddressDescriptionDuplicate .
Biasanya, Anda harus menyediakan fungsi panggilan balik ini jika struktur deskripsi alamat driver Anda berisi pointer ke buffer yang dialokasikan secara dinamis. Untuk informasi selengkapnya tentang tujuan fungsi panggilan balik ini, lihat halaman referensinya.
Menambahkan Perangkat ke Daftar Anak Dinamis
Saat kerangka kerja memanggil fungsi panggilan balik EvtDriverDeviceAdd driver bus, fungsi panggilan balik harus memanggil WdfDeviceCreate untuk membuat FDO untuk perangkat induk, yang biasanya merupakan adaptor bus. Untuk informasi selengkapnya tentang membuat FDO, lihat Membuat Objek Perangkat di Driver Fungsi. Driver kemudian harus menghitung turunan perangkat induk dan menambahkan anak ke daftar anak.
Secara opsional, driver dapat memanggil WdfDeviceSetBusInformationForChildren untuk memberikan kerangka kerja dengan informasi tentang bus. Melakukannya disarankan 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. Ketika 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 kemudian membangun tumpukan perangkat dan tumpukan driver untuk perangkat baru. Sebagai bagian dari proses ini, kerangka kerja memanggil fungsi panggilan balik EvtChildListCreateDevice 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 ini adalah sebagai berikut:
Panggil WdfChildListBeginScan.
Panggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk setiap perangkat anak.
Panggil WdfChildListEndScan.
Jika Anda mengelilingi enumerasi dinamis driver Anda dengan panggilan ke WdfChildListBeginScan dan WdfChildListEndScan, kerangka kerja menyimpan semua perubahan pada daftar anak, dan memberi tahu manajer PnP tentang perubahan saat driver memanggil WdfChildListEndScan. Di lain waktu, kerangka kerja memanggil fungsi panggilan balik EvtChildListCreateDevice driver bus untuk setiap perangkat dalam daftar anak. Fungsi panggilan balik ini memanggil WdfDeviceCreate untuk membuat PDO untuk setiap perangkat baru.
Saat 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-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
Ada dua cara umum untuk memperbarui informasi dalam daftar anak dinamis:
Ketika perangkat induk menerima interupsi yang menunjukkan kedatangan atau penghapusan anak, fungsi panggilan balik EvtInterruptDpc driver memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent jika perangkat telah dicolokkan atau WdfChildListUpdateChildDescriptionAsMissing jika perangkat telah dicabut.
Driver dapat menyediakan fungsi panggilan balik EvtChildListScanForChildren , yang dipanggil kerangka kerja setiap kali perangkat induk memasuki status berfungsi (D0). Fungsi panggilan balik ini harus menghitung semua perangkat anak dengan memanggil WdfChildListBeginScan, WdfChildListAddOrUpdateChildDescriptionAsPresent (atau WdfChildListUpdateAllChildDescriptionsAsPresent), dan WdfChildListEndScan.
Anda dapat menggunakan salah satu atau kedua teknik ini di driver Anda.
Melintas Daftar Anak Dinamis
Jika Anda ingin driver Memeriksa konten daftar anak, driver dapat melintasi daftar dengan menggunakan salah satu teknik berikut:
Untuk mendapatkan konten setiap deskripsi perangkat anak, satu per satu, driver dapat:
- Panggil WdfChildListBeginIteration.
- Panggil WdfChildListRetrieveNextDevice, sebanyak yang diperlukan.
- Panggil WdfChildListEndIteration.
Saat memanggil WdfChildListBeginIteration, driver menentukan bendera jenis WDF_RETRIEVE_CHILD_FLAGS yang menunjukkan apakah kerangka kerja harus mengambil semua deskripsi perangkat atau hanya subset. Ketika WdfChildListRetrieveNextDevice menemukan kecocokan, WdfChildListRetrieveNextDevice mengambil deskripsi identifikasi dan alamat perangkat anak, ditambah handel ke objek perangkatnya.
Jika Anda perlu 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, lalu mengambil deskripsi alamat.
Jika Anda perlu mendapatkan handel 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. Pastikan untuk membungkus panggilan dengan WdfChildListBeginIteration dan WdfChildListEndIteration untuk melindungi pemanggil dari penghapusan PnP PDO secara tiba-tiba di utas lain.
Mengakses Identifikasi PDO dan Deskripsi Alamat
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 untuk menghitung ulang perangkat anak tertentu melalui antarmuka REENUMERATE_SELF_INTERFACE_STANDARD . Untuk informasi selengkapnya, lihat Menangani Permintaan Enumerasi
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk