Antarmuka driver WDI IHV

Miniport WDI IHV seperti driver miniport NDIS lainnya dan akan mengikuti praktik pengembangan dan dokumentasi untuk miniport NDIS apa pun. Tanggung jawab driver Miniport WLAN bawaan untuk handler NDIS dibagi antara Komponen Microsoft dan driver WDI IHV. Komponen Microsoft WLAN mengurus persyaratan NDIS yang berlaku untuk semua miniport Wi-Fi sehingga setiap IHV tidak perlu mengulangi semua pekerjaan tersebut. Pemetaan dan perubahan perilaku penangan NDIS untuk Native WLAN IHV miniport saat diterapkan ke miniport WDI IHV dapat ditemukan di bawah ini.

Driver installation

Tidak ada perubahan pada cara driver miniport WDI IHV dimuat dan diinstal pada sistem. Proses INF dan penginstalan mirip dengan driver miniport IHV Native WLAN. Seperti driver NDIS yang sudah ada, ketika driver dari IHV perlu dimuat untuk bekerja dengan adaptor WLAN miliknya, sistem operasi akan memanggil rutin DriverEntry dari driver miniport IHV.

DriverEntry

Sistem operasi secara langsung memanggil rutinitas DriverEntry dari driver miniport WDI IHV. Miniport IHV mengikuti sebagian besar pedoman rutin DriverEntry dari miniport NDIS biasa. Satu pengecualian adalah bahwa alih-alih memanggil NdisMRegisterMiniportDriver, miniport IHV memanggil NdisMRegisterWdiMiniportDriver untuk memberi tahu sistem operasi untuk mengaktifkan komponen Microsoft WLAN.

Berikut ini adalah parameter utama NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: Ini adalah struktur NDIS asli yang digunakan miniport Native Wi-Fi untuk mendaftar dengan NDIS. Untuk model WDI, sebagian besar parameter handler bersifat opsional. Satu-satunya handler yang diperlukan adalah MINIPORT_OID_REQUEST_HANDLER dan MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER digunakan untuk meneruskan pesan WDI ke driver IHV. Jika ada handler lain yang ditentukan, komponen Microsoft WLAN umumnya memanggil handler setelah melakukan pemrosesannya sendiri untuk handler.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: Ini adalah set handler baru yang harus diterapkan oleh driver miniport WDI. Ini digunakan oleh driver IHV untuk mendaftarkan handler tambahan pada jalur kontrol, serta seluruh rangkaian handler pada jalur data.

Saat miniport IHV memanggil NdisMRegisterWdiMiniportDriver, komponen Microsoft WLAN memperbarui penanganan NDIS_MINIPORT_DRIVER_CHARACTERISTICS dan memanggil NdisMRegisterMiniportDriver NDIS. Pembaruan dilakukan sehingga komponen Microsoft WLAN dapat mencegat handler yang dapat memberikan bantuan/penyederhanaan pada driver miniport WDI IHV.

Di bawah ini adalah alur umum dari proses DriverEntry untuk driver miniport WDI IHV

alur WDI DriverEntry.

Untuk informasi selengkapnya tentang DriverEntry, lihat Driver Miniport NDIS.

MiniportSetOptions

Seperti yang ditunjukkan pada diagram DriverEntry di atas, jika miniport WDI IHV telah mendaftarkan handler MiniportSetOptions, sistem operasi memanggil fungsi tersebut dalam konteks driver miniport yang memanggil NdisMRegisterWdiMiniportDriver.

Jika driver miniport IHV mendaftarkan handler opsi apa pun menggunakan NdisSetOptionalHandlers, handler tersebut mungkin tidak diserialisasikan melalui lapisan WDI oleh komponen Microsoft. Oleh karena itu, komponen IHV bertanggung jawab untuk menangani setiap persyaratan sinkronisasi untuk pengolah tersebut.

MiniportInitializeEx

Model WDI membagi perilaku MiniportInitializeEx menjadi beberapa panggilan antarmuka WDI.

  1. Call MiniportWdiAllocateAdapter.

    Ketika sistem operasi menemukan instans perangkat keras IHV, ini adalah panggilan pertama ke driver miniport WDI IHV. Dalam panggilan ini, miniport WDI melakukan tindakan yang diperlukan untuk membuat representasi perangkat lunak (MiniportAdapterContext) perangkat. Ini juga menentukan informasi tentang perangkat untuk mengisi struktur NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES . Inisialisasi aktual perangkat dan tumpukan Wi-Fi dilakukan nanti ketika komponen Microsoft mengirim perintah WDI ke bawah untuk melakukan inisialisasi tertentu.

    Menggunakan data yang diperoleh dari driver miniport WDI IHV, komponen Microsoft memanggil NdisMSetMiniportAttributes dan mengatur NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES di NDIS. Sebagian besar bidang NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES diisi dengan default oleh komponen Microsoft. Driver IHV harus mengisi bidang MiniportAdapterContext dan InterfaceType .

    Setelah panggilan ini kembali dari driver miniport IHV, ia mulai menerima perintah WDI melalui handler MiniportOidRequest-nya . Selama panggilan ini, komponen Microsoft mungkin tidak dapat melakukan operasi reset/pemulihan, sehingga aktivitas apa pun yang dilakukan di sini harus cepat dan dapat diandalkan.

  2. Call MiniportWdiOpenAdapter.

    Setelah MiniportWdiAllocateAdapter, komponen Microsoft memanggil MiniportWdiOpenAdapter untuk memuat firmware dan menginisialisasi perangkat keras.

  3. Beberapa perintah WDI menggunakan MiniportOidRequest.

    Setelah MiniportWdiOpenAdapter, komponen Microsoft mengirimkan tugas/properti/panggilan berikut ke miniport IHV.

    1. Panggil MiniportWdiTalTxRxInitialize untuk menginisialisasi jalur data dan penangan pertukaran.
    2. Panggil OID_WDI_GET_ADAPTER_CAPABILITIES untuk mendapatkan kemampuan adaptor.
    3. Panggil OID_WDI_SET_ADAPTER_CONFIGURATION untuk mengonfigurasi adaptor.
    4. Panggil OID_WDI_TASK_SET_RADIO_STATE untuk mengatur status radio awal jika belum dalam status yang diharapkan.
    5. Panggil MiniportWdiTalTxRxStart untuk menyiapkan jalur data.
    6. Panggil OID_WDI_TASK_CREATE_PORT untuk membuat port awal.

    Perintah lain juga dapat dikirim ke komponen IHV sebagai bagian dari pemrosesan MiniportInitializeEx dari Komponen Microsoft. Namun, sampai MiniportWdiStartOperation dipanggil, komponen Microsoft tidak mengirim tugas apa pun yang membutuhkan komunikasi over-the-air. Kecuali OID_WDI_TASK_OPEN selalu dikirimkan pertama kali, urutan perintah/panggilan lainnya dapat berubah.

    Menggunakan data yang diperoleh dari driver miniport WDI IHV, komponen Microsoft memanggil NdisMSetMiniportAttributes dan mengatur NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES dan NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES di NDIS.

  4. Call MiniportWdiStartOperation.

    Ini adalah handler miniport WDI opsional di dalam NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS yang dapat digunakan driver IHV untuk melakukan tugas MiniportInitializeEx tambahan. Ini juga dapat digunakan oleh miniport IHV sebagai petunjuk bahwa komponen Microsoft telah selesai menginisialisasi miniport dan miniport dapat memulai aktivitas latar belakang yang diperlukan.

    Diagram di bawah ini menunjukkan alur MiniportInitializeEx.

    alur inisialisasi WDI miniport.

    Jika operasi perantara gagal, komponen Microsoft membatalkan operasi sebelumnya dan menggagalkan pemunculan miniport. Misalnya, jika OID_WDI_TASK_CREATE_PORT gagal, jalur data dibersihkan, OID_WDI_TASK_CLOSE dikirim, dan miniport gagal.

MiniportHaltEx

Dalam miniport Native Wi-Fi, MiniportHaltEx digunakan untuk memberitahukan miniport agar berhenti beroperasi dan membersihkan instance adaptor. Dalam model WDI, komponen Microsoft menangani panggilan MiniportHaltEx asli dan membaginya menjadi beberapa panggilan antarmuka WDI.

  1. Call MiniportWdiStopOperation.

    Ini adalah handler miniport WDI opsional di dalam NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS yang dapat digunakan driver IHV untuk membatalkan operasi yang dilakukannya di MiniportWdiStartOperation.

  2. Beberapa Perintah WDI menggunakan MiniportOidRequest.

    Setelah MiniportWdiStopOperation, komponen Microsoft mengirim tugas/properti ke miniport IHV untuk membersihkan status driver IHV saat ini. Pembersihan ini mungkin termasuk yang berikut ini.

    1. Panggil OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP untuk memutuskan koneksi yang ada.
    2. Panggil OID_WDI_TASK_DELETE_PORT untuk menghapus semua port yang dibuat.
    3. Panggil MiniportWdiTalTxRxStop untuk menghentikan jalur data.
    4. Panggil MiniportWdiTalTxRxDeinitialize untuk mengakhiri inisialisasi jalur data.
    5. Panggil untuk membersihkan status perangkat keras. Ini dikirim ke IHV menggunakan MiniportWdiCloseAdapter yang telah diregistrasikan oleh driver IHV.

  3. Setelah semua perintah di atas dipanggil, komponen Microsoft memanggil MiniportWdiFreeAdapter untuk meminta driver IHV menghapus status perangkat lunak apa pun yang mungkin dimilikinya.

Diagram di bawah ini menunjukkan alur MiniportHaltEx.

wdi miniport menghentikan aliran.

Pemrosesan MiniportHaltEx tidak dilakukan jika perangkat dihapus secara mendadak atau jika sistem dimatikan. Untuk penghapusan mendadak, lihat perilaku handler MiniportDevicePnPEventNotify . Untuk mematikan sistem, lihat perilaku handler MiniportShutdownEx .

MiniportDriverUnload

MiniportDriverUnload adalah handler yang dipanggil sebelum miniport WDI IHV dimuat keluar. Driver miniport WDI IHV memanggil komponen Microsoft untuk membatalkan pendaftaran itu sendiri. Komponen Microsoft memanggil NdisMDeregisterMiniportDriver.

Diagram di bawah ini memperlihatkan alur MiniportDriverUnload.

alur pemutusan driver WDI miniport.

MiniportPause

Persyaratan NDIS MiniportPause ditangani oleh komponen Microsoft. Sebagai bagian dari MiniportPause, komponen Microsoft menghentikan jalur data dan menunggunya dibersihkan. Miniport WDI IHV dapat secara opsional mendaftar untuk panggilan balik MiniportWdiPostAdapterPause yang dipanggil oleh komponen Microsoft setelah menyelesaikan pembersihan jalur data.

Diagram di bawah ini menunjukkan alur MiniportPause.

penghentian aliran miniport WDI.

MiniportRestart

Persyaratan NDIS MiniportRestart ditangani oleh komponen Microsoft. Sebagai bagian dari MiniportRestart, komponen Microsoft membatalkan kembali pekerjaan penghentian jalur data yang dilakukannya sebagai bagian dari MiniportPause. Miniport WDI IHV dapat secara opsional mendaftar untuk panggilan balik MiniportWdiPostAdapterRestart yang dipanggil oleh komponen Microsoft setelah selesai memulai ulang jalur data.

Diagram di bawah ini menunjukkan alur MiniportRestart.

alur hidupkan ulang wdi miniport.

MiniportResetEx

MiniportResetEx tidak ditangani oleh komponen Microsoft. Miniport WDI IHV dapat secara opsional mendaftar untuk panggilan balik MiniportResetEx yang dipanggil oleh komponen Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify digunakan untuk memberi tahu driver NDIS tentang peristiwa PNP seperti penghapusan kejutan perangkat. Ketika NDIS mengirim pemberitahuan ini, pertama-tama diteruskan ke miniport WDI IHV untuk diproses. Setelah komponen IHV selesai memprosesnya, komponen Microsoft melakukan pemrosesan yang sesuai untuk peristiwa ini. Panggilan yang diteruskan ke komponen IHV tidak diserialisasikan dengan tugas dan panggilan balik lainnya.

Diagram di bawah ini menunjukkan alur MiniportDevicePnPEventNotify.

alur pemberitahuan pnp WDI miniport drive.

MiniportShutdownEx

MiniportShutdownEx digunakan untuk memberi tahu driver NDIS tentang peristiwa penonaktifan sistem. Ketika NDIS mengirim pemberitahuan ini, pertama-tama ditangani oleh komponen Microsoft. Setelah komponen Microsoft selesai memprosesnya, komponen tersebut meneruskan peristiwa ke miniport WDI IHV untuk diproses.

Diagram di bawah ini menunjukkan alur MiniportShutdownEx.

alur matikan miniport wdi.

MiniportOidRequest

Handler MiniportOidRequest adalah handler yang diperlukan yang harus diterapkan miniport WDI IHV. Ini digunakan oleh komponen Microsoft untuk mengirimkan perintah WDI ke miniport IHV. Ini juga digunakan untuk meneruskan OID yang tidak ditangani komponen Microsoft ke miniport IHV.

Panggilan MiniportOidRequest ke miniport WDI IHV harus dianggap sebagai pesan M1 untuk perintah WDI. Penyelesaian OID (baik melalui NdisMOidRequestComplete atau melalui pengembalian non-PENDING dari MiniportOidRequest) harus dianggap sebagai pesan M3 untuk tugas/perintah WDI.

Untuk setiap perintah WDI, ada dua bidang potensial di mana kode NDIS_STATUS dapat dikembalikan untuk operasi -- kode status dari panggilan MiniportOidRequest (atau NdisMOidRequestComplete), dan kode status di bidang WDI_MESSAGE_HEADER (baik pada penyelesaian OID atau melalui NdisMIndicateStatusEx). Komponen Microsoft selalu melihat NDIS_STATUS dari penyelesaian OID sebelum melihat bidang WDI_MESSAGE_HEADERStatus . Harapan komponen IHV untuk pemrosesan OID WDI adalah sebagai berikut.

  1. OID WDI dikirimkan ke komponen IHV menggunakan NDIS_OID_REQUESTRequestType dari NdisRequestMethod, dan pesan dan panjang pesan yang sesuai ada di DATA. METHOD_INFORMATION. InformationBuffer dan DATA. METHOD_INFORMATION. Bidang InputBufferLength masing-masing.
  2. Komponen IHV melaporkan kesalahan dalam penyelesaian OID jika ada kesalahan saat memproses perintah, dan mengatur bidang Status WDI_MESSAGE_HEADER ke tidak berhasil jika mengalami kegagalan tingkat Wi-Fi.
  3. Untuk tugas dan properti, nomor port untuk permintaan berada dalam WDI_MESSAGE_HEADERPortId bidang. PortNumber dalam NDIS_OID_REQUEST selalu diatur ke 0.
  4. Untuk penyelesaian OID, dapat diterima bagi MiniportOidRequest untuk mengembalikan NDIS_STATUS_PENDING dan menyelesaikan OID nanti (secara sinkron atau asinkron) dengan NdisMOidRequestComplete.
  5. Jika komponen IHV menyelesaikan OID dengan NDIS_STATUS_SUCCESS, komponen tersebut harus mengisi bidang BytesWritten dari permintaan OID dengan jumlah byte yang sesuai, termasuk ruang untuk WDI_MESSAGE_HEADER.
  6. Jika komponen IHV tidak memiliki kapasitas yang cukup dalam DATA.METHOD_INFORMATION.OutputBufferLength untuk mengisi respons, komponen menyelesaikan OID dengan NDIS_STATUS_BUFFER_TOO_SHORT dan mengisi DATA.METHOD_INFORMATION.BytesNeeded. Komponen Microsoft dapat mencoba mengalokasikan buffer dengan ukuran yang diminta dan mengirimkan permintaan baru ke IHV.
  7. Jika ini adalah tugas, M4 dari tugas (NdisMIndicateStatusEx) harus hanya ditandai jika tugas dilaporkan telah berhasil dimulai -- yaitu ketika penyelesaian OID berhasil dan Status dalam WDI_MESSAGE_HEADER pada penyelesaian OID menunjukkan keberhasilan.

Diagram di bawah ini menunjukkan contoh permintaan OID NDIS yang memetakan menjadi satu perintah WDI. Ketika permintaan OID dikirimkan oleh sistem operasi, komponen Microsoft mengonversinya ke permintaan OID WDI dan mengirimkan permintaan WDI OID ke miniport IHV. Ketika miniport IHV menyelesaikan OID, komponen Microsoft menyelesaikan permintaan OID asli dengan tepat.

urutan permintaan OID miniport WDI untuk perintah WDI tunggal.

Jika OriginalOidRequest memetakan ke beberapa WDI OidRequests dan salah satu permintaan WDI gagal, OriginalOidRequest juga gagal. Jika subset operasi perantara sudah selesai, komponen Microsoft mencoba membatalkan operasi yang mendukung pembersihan.

Diagram di bawah ini menunjukkan contoh permintaan OID NDIS yang diselesaikan sepenuhnya oleh komponen Microsoft. Ketika permintaan OID dikirimkan oleh sistem operasi, komponen Microsoft memproses dan menyelesaikan OID. OID ini tidak diteruskan ke miniport WDI IHV.

urutan permintaan miniport oid WDI untuk oid yang ditangani oleh komponen Microsoft.

OID yang tidak dipahami oleh komponen Microsoft diteruskan langsung ke komponen IHV untuk diproses.

urutan permintaan WDI miniport OID untuk OID yang tidak ditangani oleh Komponen Microsoft.

Perilaku MiniportOidRequest tidak berubah untuk driver miniport WDI IHV (dibandingkan dengan miniport Native Wi-Fi). Panggilan diserialisasikan dan miniport IHV dapat menyelesaikannya secara sinkron atau asinkron dengan panggilan ke NdisMOidRequestComplete.

MiniportCancelOidRequest

Ini adalah handler opsional yang digunakan oleh miniport WDI IHV yang perlu menangani OID yang tidak dipetakan ke pesan WDI. Handler ini tidak digunakan untuk OID WDI apa pun. OID WDI harus diselesaikan dengan cepat dan tidak perlu driver miniport IHV untuk mencoba membatalkan OID yang tertunda. Penanganan pembatalan tugas WDI dilakukan dengan menggunakan permintaan OID yang sesuai untuk membatalkan tugas. Untuk OID yang tidak dipetakan, perilaku yang diharapkan ditentukan oleh NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx digunakan oleh miniport WDI IHV untuk mengirim indikasi ke komponen Microsoft. Indikasi tersebut mungkin berupa indikasi yang tidak diminta seperti kegagalan TKIP MIC, atau indikasi yang diminta untuk penyelesaian tugas (M4).

Diagram di bawah ini menunjukkan contoh indikasi WDI yang memiliki indikasi NDIS/Native Wi-Fi yang sesuai. Ketika indikasi dikirimkan oleh miniport IHV ke komponen Microsoft, komponen Microsoft mengonversinya ke indikasi yang ada dan meneruskannya ke sistem operasi.

alur indikasi status miniport WDI.

Diagram di bawah menunjukkan contoh indikasi WDI yang tidak memiliki indikasi NDIS/Native Wi-Fi yang sepadan. Ini ditangani oleh komponen Microsoft.

Indikasi status WDI tanpa pemetaan langsung ke NDIS.

Diagram di bawah ini menunjukkan indikasi yang tidak dikenali oleh komponen Microsoft. Indikasi diteruskan as-is ke sistem operasi.

indikasi status wdi tidak dikenali oleh komponen microsoft.

Perilaku NdisMIndicateStatusEx tidak berubah untuk driver miniport WDI IHV (dibandingkan dengan miniport Native Wi-Fi).

MiniportDirectOidRequest

Ini adalah handler opsional yang didaftarkan oleh driver miniport WDI IHV jika diperlukan untuk menangani Direct OIDs yang tidak dipetakan ke pesan WDI. Semua OID Langsung yang ada untuk Wi-Fi Direct dipetakan ke pesan WDI, sehingga handler ini tidak diperlukan untuk mendukung fungsionalitas tersebut. OID Langsung yang tidak didukung tidak diserialisasikan oleh komponen Microsoft.

MiniportCancelDirectOidRequest

Ini adalah handler opsional yang digunakan oleh sebuah miniport WDI IHV yang perlu menangani Direct OIDs yang tidak dipetakan ke pesan WDI. Untuk OID yang tidak dipetakan, perilaku yang diharapkan ditentukan oleh NDIS.

MiniportSendNetBufferLists

Handler ini tidak digunakan dalam driver miniport WDI IHV dan tidak boleh disediakan. Komponen Microsoft menggunakan penangan jalur data yang didaftarkan melalui NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS untuk mengirimkan paket kirim ke miniport IHV.

MiniportCancelSend

Handler ini tidak digunakan dalam driver miniport WDI IHV dan tidak boleh disediakan.

MiniportReturnNetBufferLists

Handler ini tidak digunakan dalam driver WDI IHV Miniport dan tidak boleh disediakan. Komponen Microsoft menggunakan penangan jalur data yang didaftarkan melalui NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS untuk mengembalikan paket yang diterima ke miniport IHV.

Handler WDI: MiniportWdiOpenAdapter

Handler MiniportWdiOpenAdapter digunakan oleh komponen Microsoft untuk memulai operasi Tugas Terbuka pada driver IHV. Panggilan ini harus diselesaikan dengan cepat dan jika operasi terbuka telah berhasil dimulai, IHV harus mengembalikan NDIS_STATUS_SUCCESS pada panggilan ini dan memanggil handler OpenAdapterComplete yang diteruskan ke parameter NDIS_WDI_INIT_PARAMETERSMiniportWdiAllocateAdapter.

Pengendali WDI: MiniportWdiCloseAdapter

Handler MiniportWdiCloseAdapter digunakan oleh komponen Microsoft untuk memulai operasi Tutup Tugas pada driver IHV. Panggilan ini harus diselesaikan dengan cepat dan jika operasi terbuka telah berhasil dimulai, IHV harus mengembalikan NDIS_STATUS_SUCCESS pada panggilan ini dan memanggil handler CloseAdapterComplete yang diteruskan ke parameter NDIS_WDI_INIT_PARAMETERSMiniportWdiAllocateAdapter.

  • Last updated on