Semantik Operasional MB

2023-06-15

Transaksi Asinkron

Model driver MB mengasumsikan semantik operasional non-pemblokiran antara Layanan MB dan driver miniport dengan menggunakan mekanisme pemberitahuan asinkron yang disediakan dalam NDIS 6.x. Mekanisme ini memungkinkan Layanan MB untuk terus mengirim permintaan OID ke driver miniport untuk diproses tanpa menunggu operasi saat ini selesai.

Transaksi asinkron adalah jabat tangan tiga arah yang dimulai dengan permintaan awal, diikuti dengan respons status permintaan, lalu diselesaikan dengan indikasi transaksional akhir. Respons status permintaan bersifat provisi karena hanya mengakui bahwa driver miniport telah menerima permintaan tersebut. Indikasi asinkron tindak lanjut bersifat transaksional karena menandakan penyelesaian transaksi. Driver miniport mengembalikan kode status serta data yang dihasilkan dalam indikasi transaksi.

Set Asinkron dan Permintaan Kueri

Banyak permintaan OID set dan kueri yang digunakan oleh Layanan MB diproses secara asinkron. Untuk informasi selengkapnya tentang mengatur dan mengkueri permintaan OID, lihat NDIS_OID_REQUEST. Tabel "OID khusus WWAN" dalam topik Model Data MB mengidentifikasi OID mana yang diproses secara asinkron.

Diagram berikut mewakili urutan interaksi untuk transaksi kueri asinkron antara Layanan MB dan driver miniport. Label dalam huruf tebal mewakili pengidentifikasi OID, atau kontrol alur transaksional, dan label dalam teks reguler mewakili bendera penting dalam struktur OID.

Diagram memperlihatkan urutan interaksi untuk transaksi kueri asinkron antara Layanan MB dan driver miniport.

Jabat tangan tiga arah sama untuk kueri dan mengatur permintaan.

Kecuali untuk OID_WWAN_DRIVER_CAPS, semua permintaan OID khusus MB lainnya mengikuti mekanisme transaksi asinkron untuk pertukaran informasi antara driver miniport dan Layanan MB, dengan catatan tambahan berikut:

Driver Miniport harus segera gagal dalam permintaan OID pada kondisi kesalahan apa pun, seperti permintaan OID yang tidak valid.
Driver Miniport harus mengembalikan kondisi kesalahan khusus WWAN dengan kode kesalahan yang benar (misalnya, WWAN_STATUS_XXX) yang ditentukan dalam anggota uStatus dari struktur pemberitahuan peristiwa. Driver Miniport juga harus mengisi anggota yang mengikuti anggota uStatus dengan tepat, sesuai kebutuhan. Misalnya, driver miniport harus mengisi anggota ContextState.uNwError dari struktur NDIS_WWAN_CONTEXT_STATE , jika tersedia. Namun, dalam kasus kegagalan saat memproses OID yang terkait dengan PIN, driver miniport mungkin belum tentu memiliki informasi status PIN saat ini untuk ditentukan dalam anggota PinInfo.PinStatedari NDIS_WWAN_PIN_INFO.
Driver Miniport harus mengembalikan NDIS_STATUS_INDICATION_REQUIRED sebagai respons sementara untuk semua permintaan OID asinkron.
Driver Miniport harus dapat membedakan perubahan status perangkat yang disebabkan oleh permintaan OID dari penyebab lain. Driver Miniport harus mengirim pemberitahuan transaksional untuk perubahan status yang dihasilkan dari permintaan OID, dan mereka harus mengirim pemberitahuan peristiwa yang tidak diminta untuk perubahan status dari penyebab lain.
Driver Miniport bertanggung jawab untuk mengelola memori mode kernel, meskipun Layanan MB awalnya mengalokasikan memori untuk permintaan. Setelah Layanan MB menerima respons dari driver miniport, layanan dapat merilis memori mode pengguna yang dialokasikan untuk permintaan OID.

Diagram berikut mewakili urutan interaksi untuk transaksi set asinkron antara Layanan MB dan driver miniport. Label dalam huruf tebal mewakili pengidentifikasi OID, atau kontrol alur transaksional, dan label dalam teks reguler mewakili bendera penting dalam struktur OID.

Diagram memperlihatkan urutan interaksi untuk transaksi set asinkron antara Layanan MB dan driver miniport.

Respons Asinkron

Spesifikasi NDIS 6.0 (dirilis dengan Windows Vista) memperkenalkan kode status baru, NDIS_STATUS_INDICATION_REQUIRED, bagi driver miniport untuk menyampaikan sifat asinkron transaksi ke Layanan MB dalam respons sementara driver miniport terhadap permintaan OID.

Seperti disebutkan dalam Gambaran Umum Antarmuka MB, Layanan MB tidak memiliki akses langsung ke memori mode kernel yang dialokasikan oleh driver miniport MB. Hasil eksekusi yang disimpan dalam memori mode kernel diasumsikan disalin dan tersedia untuk Layanan MB oleh beberapa perantara, seperti WMI atau driver filter NDIS. Oleh karena itu, driver miniport dapat merilis memori mode kernel yang dialokasikan setelah panggilan fungsi NdisMIndicateStatusEx kembali dalam indikasi transaksional.

Prosedur jabat tangan yang harus diikuti driver miniport dan Layanan MB dijelaskan dalam prosedur berikut.

Prosedur driver miniport MB

Setelah menerima permintaan OID, driver miniport harus melakukan langkah-langkah berikut:

Alokasikan memori dalam mode kernel untuk menyalin konten struktur data NDIS_OID_REQUEST yang terkait dengan permintaan OID.
Di antara parameter permintaan, pastikan bahwa anggota RequestId dan RequestHandle dari struktur permintaan OID juga disalin. Anggota ini akan digunakan nanti dalam indikasi transaksi.
Kembalikan respons status NDIS_STATUS_INDICATION_REQUIRED provisi untuk memberi tahu Layanan MB bahwa driver miniport akan menyelesaikan permintaan secara asinkron.
Setelah menyelesaikan operasi, simpan hasilnya dalam memori lokal atau yang dialokasikan driver, sebagaimana melengkapinya.
Panggil fungsi NdisMIndicateStatusEx untuk memberi tahu Layanan MB bahwa operasi yang beredar telah selesai. Driver miniport harus mengisi anggota struktur NDIS_STATUS_INDICATION sebagai berikut:
1. Atur anggota StatusCode ke jenis pemberitahuan status. Misalnya, NDIS_STATUS_WWAN_XXX.
2. Atur anggota DestinationHandle ke anggota RequestHandle yang diterima dalam struktur data NDIS_OID_REQUEST saat driver miniport menerima permintaan OID yang sesuai.
3. Atur anggota RequestId agar sesuai dengan anggota RequestId dari struktur status NDIS_OID_REQUEST saat driver miniport menerima permintaan OID yang sesuai.
4. Atur anggota StatusBuffer dan StatusBufferSize untuk menunjuk ke memori yang dialokasikan driver miniport dan ukuran buffer memori. Buffer memori ini berisi hasil dari operasi yang telah selesai.
5. Jika operasi berhasil diselesaikan, atur anggota uStatus ke WWAN_STATUS_SUCCESS. Jika tidak, atur anggota uStatus ke nilai WWAN_STATUS_XXX yang sesuai untuk menunjukkan jenis kegagalan.
Ketika panggilan fungsi kembali, driver miniport harus melepaskan memori yang dialokasikan untuk permintaan OID.

Prosedur Layanan MB

Layanan MB memproses transaksi asinkron dengan menggunakan prosedur berikut:

Alokasikan memori buffer untuk permintaan berdasarkan struktur data OID. Isi anggota struktur data dengan nilai yang sesuai.
Panggil fungsi NdisOidRequest dengan anggota InformationBuffer yang menunjuk ke struktur data OID untuk permintaan OID dan tunggu hingga driver miniport merespons.
Setelah menerima respons provisi NDIS_STATUS_INDICATION_REQUIRED dari driver miniport, Layanan MB menyimpan RequestId, merilis memori yang dialokasikan, dan menandai transaksi sebagai terbuka. Pada titik ini, Layanan MB gratis untuk memproses permintaan dan pemberitahuan OID berikutnya.
Setelah menerima pemberitahuan dengan NDIS_STATUS_WWAN_XXX sebagai nilai StatusCode , periksa apakah RequestId cocok dengan transaksi apa pun yang ditandai sebagai terbuka. Jika ada kecocokan, layanan menutup transaksi. Jika tidak ada kecocokan yang ditemukan, perlakukan pemberitahuan sebagai pemberitahuan peristiwa yang tidak diminta.
Proses data yang dikembalikan di anggota StatusBuffer dan buat perubahan status pada Layanan MB yang sesuai.

Indikasi

Ada dua jenis indikasi khusus WWAN yang dapat dihasilkan driver miniport:

Pemberitahuan peristiwa yang dihasilkan dari perubahan status objek di perangkat MB.
Pemberitahuan transaksional yang menandakan penyelesaian operasi asinkron.

Dalam kedua kasus, driver miniport harus memanggil fungsi NdisMIndicateStatusEx.

Notifikasi Kejadian

Pemberitahuan peristiwa tidak diminta dalam arti bahwa driver miniport secara proaktif mengirim indikasi ke Layanan MB sebagai peristiwa perubahan status. Perubahan status disebabkan oleh tindakan dari beberapa entitas selain Layanan MB. Layanan MB mengasumsikan driver miniport dapat mendeteksi penyebab perubahan.

Untuk pemberitahuan peristiwa khusus WWAN, driver miniport harus mengatur anggota RequestId dari struktur NDIS_STATUS_INDICATION ke nol. Anggota StatusCode menentukan objek mana di perangkat MB yang telah berubah. Driver miniport dapat mengatur objek ini ke salah satu nilai berikut:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

NDIS_STATUS_WWAN_HOME_PROVIDER

NDIS_STATUS_WWAN_PREFERRED_PROVIDERS

NDIS_STATUS_WWAN_VISIBLE_PROVIDERS

NDIS_STATUS_WWAN_REGISTER_STATE

NDIS_STATUS_WWAN_PACKET_SERVICE

NDIS_STATUS_WWAN_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

Layanan MB juga dapat memproses pemberitahuan peristiwa lain dari NDIS. Pemberitahuan peristiwa non-MB ini belum tentu tunduk pada persyaratan bahwa nilai RequestId-nya diatur ke nol.

Pemberitahuan Transaksi

Driver Miniport menggunakan pemberitahuan transaksional untuk memberi tahu Layanan MB bahwa transaksi asinkron telah selesai, dan Layanan MB menggunakan pemberitahuan transaksional untuk menutup transaksi terbuka dan memperbarui mesin statusnya.

Layanan MB mengharapkan pemberitahuan transaksi sehingga dapat menutup transaksi terbuka. Ini adalah pertukaran akhir dari jabat tangan tiga arah antara Layanan MB dan driver miniport dalam transaksi asinkron. Nilai anggota RequestId dari NDIS_STATUS_INDICATION dalam pemberitahuan transaksional apa pun harus nonzero, yang disalin dari permintaan yang sesuai dalam transaksi yang sama.

Anda harus mengatur anggota RequestId dari struktur NDIS_STATUS_INDICATION dengan benar agar mekanisme asinkron berfungsi dengan baik. Layanan MB memastikan bahwa nilai RequestId unik dan tidak nol di antara semua permintaan yang luar biasa. Driver Miniport harus mengembalikan nilai RequestId yang sama dalam indikasi yang sesuai agar Layanan MB dapat menghubungkan indikasi dengan transaksi terbuka.

Struktur Indikasi Status

Respons asinkron untuk permintaan OID tertentu dan struktur pemberitahuan peristiwa yang tidak diminta berbagi anggota struktur berikut yang ditunjukkan oleh anggota StatusBuffer dari parameter StatusIndication ke NdisMIndicateStatusEx:

typedef struct _NDIS_WWAN_XXX {
  NDIS_OBJECT_HEADER Header;
  WWAN_STATUS uStatus;
  ULONG uNwError;//Optional. Only used for network operations.
  WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;

Nilai nol dalam anggota RequestId dari struktur NDIS_STATUS_INDICATION berarti itu adalah pemberitahuan peristiwa yang tidak diminta dan dapat terjadi kapan saja.

Jika anggota uStatus dalam indikasi yang dikembalikan dari set atau permintaan OID kueri apa pun tidak sama dengan WWAN_STATUS_SUCCESS anggota struktur NDIS_WWAN_XXX terkait tidak perlu valid.

Dalam kasus pemberitahuan peristiwa yang tidak diminta berdasarkan peristiwa jaringan, driver miniport harus mengisi anggota uNwError sebagaimana mestinya, jika berlaku.

Tabel berikut menunjukkan pendaftaran, packet-attach, dan packet-detach menyebabkan nilai kegagalan kode yang ditentukan dalam Spesifikasi 3GPP TS 24.008 untuk jaringan berbasis GSM:

3GPP 24.008 Kode penyebab	Interpretasi kode penyebab
2 - International Mobile Subscriber Identity (IMSI) tidak diketahui di HLR	SIM atau perangkat tidak diaktifkan, atau langganan telah kedaluwarsa, yang menyebabkan pennonaktifkanan jaringan.
4 - IMSI tidak diketahui di VLR	Fitur roaming tidak berlangganan.
6 - ME Ilegal	MS diblokir oleh jaringan karena laporan yang dicuri.
7 - Layanan GPRS tidak diizinkan	Pengguna tidak memiliki langganan GPRS. Pengguna hanya memiliki langganan koneksi suara.
8 - Layanan GPRS dan non-GPRS tidak diizinkan	Layanan GPRS dan non-GPRS tidak diizinkan.
11 - PLMN tidak diizinkan	Layanan diblokir oleh jaringan karena langganan yang kedaluwarsa atau penyebab lain.
12 - Area lokasi tidak diizinkan	Langganan pengguna tidak mengizinkan akses di area lokasi saat ini.
13 - Roaming tidak diizinkan di area lokasi ini	Langganan mengizinkan roaming, tetapi roaming tidak diizinkan di area lokasi saat ini.
14 - Layanan GPRS tidak diizinkan dalam PLMN ini	Penyedia jaringan yang dipilih tidak menyediakan layanan GPRS ke MS.
15 - Tidak ada sel yang cocok di area lokasi	Tidak ada langganan untuk layanan.
17 - Kegagalan jaringan	Pendaftaran gagal.
22 - Kemacetan	Pendaftaran gagal karena kemacetan jaringan.

Misalnya, jika jaringan memulai peristiwa konteks penonaktifan karena roaming tidak diizinkan di area lokasi, driver miniport harus mengatur anggota uNwError ke 13 sesuai 3GPP TS 24.008 Menyebabkan kode untuk jaringan berbasis GSM.

Logika serupa juga harus diterapkan ke jaringan berbasis CDMA. Namun, tidak ada standar untuk kode kesalahan jaringan berbasis CDMA. Perangkat berbasis CDMA harus menggunakan kode kesalahan khusus jaringan atau perangkat.

Dalam kasus respons asinkron driver miniport terhadap permintaan OID, anggota RequestId dari struktur NDIS_STATUS_INDICATION adalah angka bukan nol yang diteruskan ke driver miniport sebagai bagian dari set atau permintaan kueri . Driver miniport harus mengisi anggota uStatus sebagaimana mestinya. Misalnya, WWAN_STATUS_SUCCESS, atau salah satu nilai kesalahan yang sesuai yang tercantum di bagian berikut. Selain itu, driver miniport harus mengisi anggota uNwError jika sesuai dan tersedia.

Status Pemberitahuan Peristiwa

Tabel berikut mencantumkan kode WWAN_STATUS yang dapat ditentukan driver miniport MB di anggota uStatus dari struktur pemberitahuan peristiwa NDIS_WWAN_XXX.

Nilai	Makna
WWAN_STATUS_SUCCESS	Operasi berhasil.
WWAN_STATUS_FAILURE	Operasi gagal (kegagalan umum).
WWAN_STATUS_BUSY	Operasi gagal karena perangkat sibuk.
WWAN_STATUS_SIM_NOT_INSERTED	Operasi gagal karena kartu SIM tidak dimasukkan sepenuhnya ke dalam perangkat.
WWAN_STATUS_BAD_SIM	Operasi gagal karena kartu SIM buruk dan tidak dapat digunakan lebih lanjut.
WWAN_STATUS_PIN_REQUIRED	Operasi gagal karena PIN harus dimasukkan untuk melanjutkan.
WWAN_STATUS_PIN_DISABLED	Operasi gagal karena PIN dinonaktifkan.
WWAN_STATUS_NOT_REGISTERED	Operasi gagal karena perangkat tidak terdaftar dengan jaringan apa pun.
WWAN_STATUS_PROVIDERS_NOT_FOUND	Operasi gagal karena tidak ada penyedia jaringan yang dapat ditemukan.
WWAN_STATUS_NO_DEVICE_SUPPORT	Operasi gagal karena perangkat tidak mendukung operasi.
WWAN_STATUS_PROVIDER_NOT_VISIBLE	Operasi gagal karena penyedia layanan saat ini tidak terlihat.
WWAN_STATUS_DATA_CLASS_NOT_AVAILABLE	Operasi gagal karena kelas data yang diminta tidak tersedia.
WWAN_STATUS_PACKET_SVC_DETACHED	Operasi gagal karena layanan paket dilepaskan.
WWAN_STATUS_MAX_ACTIVATED_CONTEXTS	Operasi gagal karena jumlah maksimum konteks yang diaktifkan telah tercapai.
WWAN_STATUS_NOT_INITIALIZED	Operasi gagal karena perangkat sedang dalam proses inisialisasi. Coba lagi operasi setelah status siap perangkat berubah menjadi WwanReadyStateInitialized.
WWAN_STATUS_VOICE_CALL_IN_PROGRESS	Operasi gagal karena panggilan suara sedang berlangsung.
WWAN_STATUS_CONTEXT_NOT_ACTIVATED	Operasi gagal karena konteks tidak diaktifkan.
WWAN_STATUS_SERVICE_NOT_ACTIVATED	Operasi gagal karena layanan tidak diaktifkan.
WWAN_STATUS_INVALID_ACCESS_STRING	Operasi gagal karena string akses tidak valid.
WWAN_STATUS_INVALID_USER_NAME_PWD	Operasi gagal karena nama pengguna dan/atau kata sandi yang disediakan tidak valid.
WWAN_STATUS_RADIO_POWER_OFF	Operasi gagal karena radio saat ini dimatikan.
WWAN_STATUS_INVALID_PARAMETERS	Operasi gagal karena parameter yang tidak valid.
WWAN_STATUS_READ_FAILURE	Operasi gagal karena kegagalan baca.
WWAN_STATUS_WRITE_FAILURE	Operasi gagal karena kegagalan penulisan.

Tabel berikut ini memperlihatkan nilai status khusus SMS.

Nilai	Makna
WWAN_STATUS_SMS_OPERATION_NOT_ALLOWED	Operasi SMS gagal karena operasi tidak diizinkan.
WWAN_STATUS_SMS_MEMORY_FAILURE	Operasi SMS gagal karena kegagalan memori.
WWAN_STATUS_SMS_INVALID_MEMORY_INDEX	Operasi SMS gagal karena indeks memori yang tidak valid-- WwanSmsFlagIndex untuk OID_WWAN_SMS_READ.
WWAN_STATUS_SMS_UNKNOWN_SMSC_ADDRESS	Operasi SMS gagal karena nomor pusat layanan tidak valid atau tidak diketahui.
WWAN_STATUS_SMS_NETWORK_TIMEOUT	Operasi SMS gagal karena waktu jaringan habis.
WWAN_STATUS_SMS_MEMORY_FULL	Operasi SMS gagal karena penyimpanan pesan SMS penuh.
WWAN_STATUS_SMS_UNKNOWN_ERROR	Operasi SMS gagal karena kesalahan yang tidak diketahui (kesalahan umum).
WWAN_STATUS_SMS_FILTER_NOT_SUPPORTED	Operasi SMS gagal karena jenis filter yang diminta tidak didukung.
WWAN_STATUS_SMS_MORE_DATA	Transaksi ini belum selesai. Beberapa data telah dikembalikan dan ada lebih banyak data yang akan dikembalikan.
WWAN_STATUS_SMS_LANG_NOT_SUPPORTED	Operasi SMS gagal karena bahasa SMS tidak didukung. Ini hanya berlaku untuk perangkat berbasis CDMA.
WWAN_STATUS_SMS_ENCODING_NOT_SUPPORTED	Operasi SMS gagal karena pengodean SMS tidak didukung. Ini hanya berlaku untuk perangkat berbasis CDMA.
WWAN_STATUS_SMS_FORMAT_NOT_SUPPORTED	Operasi SMS gagal karena format SMS tidak didukung.

Catatan Kode status khusus WWAN ini hanya digunakan untuk transaksi asinkron di anggota uStatus dari struktur NDIS_WWAN_XXX.

Driver Miniport menggunakan pemberitahuan peristiwa untuk memberi tahu Layanan MB tentang perubahan status objek di perangkat MB mereka tanpa terlebih dahulu menerima permintaan OID. Layanan MB menggunakan pemberitahuan peristiwa untuk memperbarui komputer statusnya saja.

Ketahuilah bahwa meskipun NDIS menserialisasikan semua permintaan yang dikirim ke driver miniport, driver miniport mungkin tidak mengembalikan respons dalam urutan yang sama. Ini karena permintaan antrean di driver miniport mungkin diproses secara paralel. Oleh karena itu Layanan MB memastikan bahwa jika dua permintaan bergantung satu sama lain, itu tidak akan mengirim permintaan kedua sampai driver miniport menyelesaikan permintaan pertama.

Pemberitahuan Perubahan Status

Secara umum, driver miniport harus selalu memberi tahu Layanan MB tentang status perangkat MB yang diperbarui baik melalui pemberitahuan transaksional atau melalui pemberitahuan peristiwa yang tidak diminta. Skenario berikut adalah beberapa pengecualian di mana driver miniport tidak seharusnya merespons dengan informasi status yang diperbarui. Layanan MB dapat menentukan status yang diperbarui dari status penyelesaian operasi lain:

Driver Miniport tidak perlu mengirim indikasi peristiwa NDIS_STATUS_WWAN_PIN_LIST ketika perubahan status PIN terjadi karena Layanan MB meminta untuk mengaktifkan atau menonaktifkan PIN.
Driver Miniport tidak perlu mengembalikan daftar terbaru konteks yang disediakan dalam respons transaksi OID_WWAN_PROVISIONED_CONTEXT mengatur operasi.
Driver Miniport tidak perlu merespons dengan daftar penyedia pilihan yang diperbarui dalam respons transaksional untuk OID_WWAN_PREFERRED_PROVIDERS mengatur operasi. Layanan MB dapat menentukan informasi ini berdasarkan daftar awal dan status keberhasilan operasi yang ditetapkan .
Driver Miniport tidak perlu merespons dengan nilai WWAN_SMS_CONFIGURATION saat ini untuk operasi set OID_WWAN_SMS_CONFIGURATION.