Menulis driver klien MBBCx
Peringatan
Diagram urutan dalam topik ini hanya untuk tujuan ilustrasi. Mereka bukan kontrak publik dan dapat berubah di masa depan.
File INF untuk driver klien MBBCx
File INF untuk driver klien MBBCx sama dengan driver klien NetAdapterCx lainnya. Untuk informasi selengkapnya, lihat File INF untuk driver klien NetAdapterCx.
Ikuti panduan Universal untuk memastikan bahwa file INF memenuhi persyaratan Universal.
Menginisialisasi perangkat
Selain tugas-tugas yang diperlukan oleh NetAdapterCx untuk inisialisasi perangkat NetAdapter, driver klien MBB juga harus melakukan tugas-tugas berikut dalam fungsi panggilan balik EvtDriverDeviceAdd :
Panggil MBB_DEVICE_CONFIG_INIT setelah memanggil NetDeviceInitConfig tetapi sebelum memanggil WdfDeviceCreate, mereferensikan objek WDFDEVICE_INIT yang sama yang diteruskan oleh kerangka kerja.
Panggil MbbDeviceInitialize untuk mendaftarkan fungsi panggilan balik khusus perangkat MBB menggunakan struktur MBB_DEVICE_CONFIG yang diinisialisasi dan objek WDFDEVICE yang diperoleh dari WdfDeviceCreate.
Contoh berikut menunjukkan cara menginisialisasi perangkat MBB. Penanganan kesalahan telah dibiarkan untuk kejelasan.
status = NetDeviceInitConfig(deviceInit);
status = MbbDeviceInitConfig(deviceInit);
// Set up other callbacks such as Pnp and Power policy
status = WdfDeviceCreate(&deviceInit, &deviceAttributes, &wdfDevice);
MBB_DEVICE_CONFIG mbbDeviceConfig;
MBB_DEVICE_CONFIG_INIT(&mbbDeviceConfig,
EvtMbbDeviceSendMbimFragment,
EvtMbbDeviceReceiveMbimFragment,
EvtMbbDeviceSendServiceSessionData,
EvtMbbDeviceCreateAdapter);
status = MbbDeviceInitialize(wdfDevice, &mbbDeviceConfig);
Tidak seperti jenis driver NetAdapterCx lainnya, driver klien MBB tidak boleh membuat objek NETADAPTER dari dalam fungsi panggilan balik EvtDriverDeviceAdd . Sebaliknya, akan diinstruksikan oleh MBBCx untuk melakukannya nanti.
Selanjutnya, driver klien harus memanggil MbbDeviceSetMbimParameters, biasanya dalam fungsi panggilan balik EvtDevicePrepareHardware yang mengikuti.
Diagram alur pesan ini menggambarkan proses inisialisasi.
Diagram alur pesan ini menggambarkan proses inisialisasi.
Menangani pesan kontrol MBIM
MBBCx menggunakan perintah kontrol MBIM standar yang ditentukan dalam spesifikasi MBIM Rev 1.0, bagian 8, 9, dan 10, untuk sarana kontrol. Perintah dan respons ditukar melalui serangkaian fungsi panggilan balik yang disediakan oleh driver klien dan API yang disediakan oleh MBBCx. MBBCx meniru model operasional perangkat MBIM, seperti yang didefinisikan dalam spesifikasi MBIM Rev 1.0, bagian 5.3, dengan menggunakan panggilan fungsi ini:
- MBBCx mengirim pesan perintah MBIM ke driver klien dengan memanggil fungsi panggilan balik EvtMbbDeviceSendMbimFragment . Driver klien secara asinkron menyelesaikan permintaan pengiriman ini dengan memanggil MbbRequestComplete.
- Driver klien memberi sinyal ketersediaan hasil dengan memanggil MbbDeviceResponseAvailable.
- MBBCx mengambil pesan respons MBIM dari driver klien dengan memanggil fungsi panggilan balik EvtMbbDeviceReceiveMbimFragment . Driver klien secara asinkron menyelesaikan permintaan get-response ini dengan memanggil MbbRequestCompleteWithInformation.
- Driver klien MBB dapat memberi tahu MBBCx tentang peristiwa perangkat yang tidak diminta dengan memanggil MbbDeviceResponseAvailable. MBBCx kemudian mengambil informasi dari driver klien yang mirip dengan cara mengambil pesan respons MBIM.
Diagram berikut mengilustrasikan alur pertukaran pesan driver klien MBBCx.
Sinkronisasi pesan kontrol MBIM
Kerangka kerja MBBCx selalu menserialisasikan panggilan ke fungsi panggilan balik EvtMbbDeviceSendMbimFragment dan EvtMbbDeviceReceiveMbimFragment driver klien. Tidak ada panggilan baru yang akan dilakukan oleh kerangka kerja sampai driver klien memanggil MbbRequestComplete atau MbbRequestCompleteWithInformation.
Meskipun driver klien dijamin tidak menerima panggilan balik EvtMbbDeviceSendMbimFragment atau EvtMbbDeviceReceiveMbimFragment yang tumpang tindih, ia mungkin menerima beberapa panggilan kepada mereka berturut-turut sebelum respons untuk perintah sebelumnya tersedia dari perangkat.
Jika perangkat tidak dalam status D0 , kerangka kerja MBBCx akan terlebih dahulu membawa perangkat ke D0 (dengan kata lain, perangkat memanggil EvtDeviceD0Entry) sebelum memanggil EvtMbbDeviceSendMbimFragment atau EvtMbbDeviceReceiveMbimFragment. Kerangka kerja MBBCx juga menjamin bahwa ia akan menyimpan perangkat dalam status D0, yang berarti tidak akan memanggil EvtDeviceD0Exit, sampai klien memanggil MbbRequestComplete atau MbbRequestCompleteWithInformation.
Membuat antarmuka NetAdapter untuk pembawa konteks PDP/EPS
Sebelum membuat sesi data, MBBCx akan menginstruksikan driver klien untuk membuat objek NETADAPTER, dan akan digunakan oleh MBBCx untuk mewakili antarmuka jaringan untuk sesi data yang diaktifkan. Hal ini dicapai dengan MBBCx memanggil fungsi panggilan balik EvtMbbDeviceCreateAdapter driver klien.
Dalam implementasi fungsi panggilan balik EvtMbbDeviceCreateAdapter , driver klien MBBCx harus terlebih dahulu melakukan tugas yang sama yang diperlukan untuk membuat objek NETADAPTER sebagai driver klien NetAdapterCx apa pun. Selain itu, ini juga harus melakukan tugas tambahan berikut:
Panggil MbbAdapterInitialize pada objek NETADAPTER yang dibuat oleh NetAdapterCreate.
Setelah memanggil MbbAdapterinitialize, panggil MbbAdapterGetSessionId untuk mengulangi ID sesi data yang ingin digunakan MBBCx untuk menggunakan objek NETADAPTER ini. Misalnya, jika nilai yang dikembalikan adalah 0, itu berarti MBBCx akan menggunakan antarmuka NETADAPTER ini untuk sesi data yang ditetapkan oleh konteks PDP utama/pembawa EPS default.
Kami menyarankan agar driver klien MBBCx menyimpan pemetaan internal antara objek NETADAPTER yang dibuat dan SessionId yang dikembalikan. Ini membantu melacak hubungan objek sesi-ke-NETADAPTER data, yang sangat berguna ketika beberapa konteks PDP/pembawa EPS telah diaktifkan.
Sebelum kembali dari EvtMbbDeviceCreateAdapter, driver klien harus memulai adaptor dengan memanggil NetAdapterStart. Secara opsional, mereka juga dapat mengatur kemampuan adaptor dengan memanggil satu atau beberapa fungsi ini sebelum panggilan ke NetAdapterStart:
MBBCx memanggil fungsi panggilan balik ini setidaknya sekali, jadi selalu ada satu objek NETADPATER untuk konteks PDP utama/pembawa EPS default. Jika beberapa konteks PDP/pembawa EPS diaktifkan, MBBCx mungkin memanggil fungsi panggilan balik ini lebih banyak kali, sekali untuk setiap sesi data dibuat. Harus ada hubungan satu-ke-satu antara antarmuka jaringan yang diwakili oleh objek NETADAPTER dan sesi data, seperti yang ditunjukkan dalam diagram berikut.
Contoh berikut menunjukkan cara membuat objek NETADAPTER untuk sesi data. Perhatikan bahwa penanganan kesalahan dan kode yang diperlukan untuk menyiapkan kemampuan adaptor dibiarkan untuk keringkasan dan kejelasan.
NTSTATUS
EvtMbbDeviceCreateAdapter(
WDFDEVICE Device,
PNETADAPTER_INIT AdapterInit
)
{
// Get the client driver defined per-device context
PMY_DEVICE_CONTEXT deviceContext = MyGetDeviceContext(Device);
// Set up the client driver defined per-adapter context
WDF_OBJECT_ATTRIBUTES adapterAttributes;
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&adapterAttributes,
MY_NETADAPTER_CONTEXT);
// Create the NETADAPTER object
NETADAPTER netAdapter;
NTSTATUS status = NetAdapterCreate(AdapterInit,
&adapterAttributes,
&netAdapter);
// Initialize the adapter for MBB
status = MbbAdapterInitialize(netAdapter);
// Retrieve the Session ID and use an array to store
// the session <-> NETADAPTER object mapping
ULONG sessionId;
PMY_NETADAPTER_CONTEXT netAdapterContext = MyGetNetAdapterContext(netAdapter);
netAdapterContext->NetAdapter = netAdapter;
sessionId = MbbAdapterGetSessionId(netAdapter);
netAdapterContext->SessionId = sessionId;
deviceContext->Sessions[sessionId].NetAdapterContext = netAdapterContext;
//
// Optional: set adapter capabilities
//
...
NetAdapterSetDatapathCapabilities(netAdapter,
&txCapabilities,
&rxCapabilities);
...
NetAdapterSetLinkLayerCapabilities(netAdapter,
&linkLayerCapabilities);
...
NetAdapterSetLinkLayerMtuSize(netAdapter,
MY_MAX_PACKET_SIZE - ETHERNET_HEADER_LENGTH);
//
// Required: start the adapter
//
status = NetAdapterStart(netAdapter);
return status;
}
Untuk contoh kode pengaturan kemampuan jalur data, lihat Manajemen buffer data jaringan.
MBBCx menjamin bahwa ia memanggil EvtMbbDeviceCreateAdapter sebelum meminta MBIM_CID_CONNECT dengan ID sesi yang sama. Diagram alur berikut menunjukkan interaksi antara driver klien dan ekstensi kelas dalam membuat objek NETADAPTER.
Alur untuk membuat objek NETADAPTER untuk konteks PDP utama/pembawa EPS default dimulai oleh MBBCx ketika EvtDevicePrepareHardware telah berhasil diselesaikan.
Alur untuk membuat objek NETADAPTER untuk konteks PDP sekunder/pembawa EPS khusus dipicu oleh WwanSvc setiap kali koneksi sesuai permintaan diminta oleh aplikasi.
Masa pakai objek NETADAPTER
Objek NETADAPTER yang dibuat oleh driver klien akan secara otomatis dihancurkan oleh MBBCx ketika tidak lagi digunakan. Misalnya, ini terjadi setelah konteks PDP tambahan/pembawa EPS dinonaktifkan. Driver klien MBBCx tidak boleh memanggil WdfObjectDelete pada objek NETADAPTER yang mereka buat.
Jika driver klien perlu membersihkan data konteks yang terkait dengan objek NETADAPTER, driver klien harus menyediakan fungsi EvtDestroyCallback dalam struktur atribut objek saat memanggil NetAdapterCreate.
Manajemen daya perangkat MBB
Untuk manajemen daya, driver klien harus menggunakan objek NETPOWERSETTINGS seperti jenis driver klien NetAdapterCx lainnya.
Menangani sesi layanan perangkat
Ketika aplikasi mengirim data DSS ke perangkat modem, MBBCx memanggil fungsi panggilan balik EvtMbbDeviceSendSendServiceSessionData driver klien. Driver klien kemudian harus mengirim data secara asinkron ke perangkat dan memanggil MbbDeviceSendDeviceServiceSessionDataComplete setelah pengiriman selesai, sehingga MBBCx kemudian dapat membebaskan memori yang dialokasikan untuk data.
Sebaliknya, driver klien memanggil MbbDeviceReceiveDeviceServiceSessionData untuk meneruskan data apa pun hingga aplikasi melalui MBBCx.
Persyaratan yang Sesuai dengan Driver Windows
- Mematuhi Prinsip Desain DCH
- Ikuti prinsip Isolasi Paket Driver
- Ikuti Persyaratan Lapisan API
- Sertifikasi dengan Proses Sertifikasi Program Kompatibilitas Perangkat Keras Windows menggunakan Kit Lab Perangkat Keras
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