Transaksi Custom-Receive SerCx2

  • Artikel

Beberapa perangkat keras pengontrol serial mungkin menerapkan mekanisme transfer data selain PIO atau DMA sistem untuk membaca data dari pengontrol serial. Driver pengontrol serial dapat mendukung transaksi penerimaan kustom untuk membuat mekanisme transfer data ini tersedia untuk digunakan oleh SerCx2.

Untuk memulai transaksi penerimaan kustom, SerCx2 memanggil fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionStart driver dan menyediakan sebagai parameter permintaan baca (IRP_MJ_READ) dan deskripsi buffer baca untuk transaksi. Dalam panggilan ini, fungsi memulai transaksi dan mengembalikan. Driver kemudian bertanggung jawab untuk menyelesaikan transaksi dan menyelesaikan permintaan baca.

Membuat objek penerima kustom

Sebelum SerCx2 dapat memanggil salah satu fungsi EvtSerCx2CustomReceiveTransactionXxx** driver harus memanggil metode SerCx2CustomReceiveTransactionCreate untuk mendaftarkan fungsi ini dengan SerCx2. Metode ini menerima, sebagai parameter input, pointer ke struktur SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG yang berisi pointer ke fungsi EvtSerCx2CustomReceiveTransactionXxx** driver.

Driver harus menerapkan dua fungsi berikut:

Sebagai opsi, driver dapat menerapkan salah satu atau semua dari tiga fungsi berikut:

Metode SerCx2CustomReceiveTransactionCreate membuat objek penerima kustom dan memasok driver panggilan dengan handel SERCX2CUSTOMRECEIVETRANSACTION ke objek ini. Fungsi EvtSerCx2CustomReceiveTransactionXxx** driver semuanya mengambil handel ini sebagai parameter pertama mereka. Metode SerCx2 berikut menangani ini sebagai parameter pertamanya:

Inisialisasi dan pembersihan perangkat keras

Beberapa driver pengontrol serial mungkin perlu menginisialisasi perangkat keras pengontrol serial pada awal transaksi penerimaan kustom, atau untuk membersihkan status perangkat keras pengontrol serial pada akhir transaksi.

Jika driver mengimplementasikan fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 memanggil fungsi ini untuk menginisialisasi pengontrol serial sebelum memulai transaksi. Jika diimplementasikan, fungsi EvtSerCx2CustomReceiveTransactionInitialize harus memanggil metode SerCx2CustomReceiveTransactionInitializeComplete untuk memberi tahu SerCx2 ketika driver selesai menginisialisasi pengontrol serial.

Jika driver menerapkan fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionCleanup , SerCx2 memanggil fungsi ini untuk membersihkan status perangkat keras setelah transaksi berakhir. Jika diimplementasikan, fungsi EvtSerCx2CustomReceiveTransactionInitialize harus memanggil metode SerCx2CustomReceiveTransactionCleanupComplete untuk memberi tahu SerCx2 ketika driver selesai membersihkan pengontrol serial.

Pemberitahuan data baru

Sebagai opsi, driver pengontrol serial dapat mengimplementasikan fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . Jika diimplementasikan, SerCx2 menggunakan fungsi ini untuk mengelola batas waktu interval yang terjadi secara efisien selama penanganan permintaan baca yang diproses sebagai transaksi penerima kustom.

Batas waktu interval terjadi jika interval antara dua byte berturut-turut yang diterima oleh pengontrol serial melebihi waktu maksimum yang ditentukan klien. Setelah driver periferal mengirim permintaan baca ke SerCx2, batas waktu interval tidak dapat terjadi sampai setidaknya satu byte data diterima dari perangkat periferal yang terhubung secara serial. Waktu antara kedatangan permintaan baca dan penerimaan byte data pertama dari perangkat periferal mungkin jauh lebih lama daripada waktu yang diperlukan untuk menerima data lainnya untuk permintaan baca setelah byte pertama diterima. Untuk informasi selengkapnya, lihat SERIAL_TIMEOUTS.

SerCx2 memanggil fungsi EvtSerCx2CustomReceiveTransactionEnableNewDataNotification , jika diimplementasikan, untuk mengaktifkan pemberitahuan data baru. Jika pemberitahuan ini diaktifkan dan pengontrol serial menerima satu atau beberapa byte data baru dari perangkat periferal, atau sudah memiliki data dalam FIFO penerimanya, driver pengontrol serial harus memanggil metode SerCx2CustomReceiveTransactionNewDataNotification untuk memberi tahu SerCx2.

Untuk mendeteksi kemungkinan waktu habis interval, SerCx2 secara berkala memanggil fungsi panggilan balik peristiwa EvtSerCx2CustomReceiveTransactionQueryProgress untuk memeriksa apakah ada data yang diterima selama interval sebelumnya. Bagaimana SerCx2 mendeteksi penerimaan byte pertama data tergantung pada apakah driver pengontrol serial mengimplementasikan fungsi EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . Jika fungsi ini diimplementasikan, SerCx2 memanggil fungsi untuk mengaktifkan pemberitahuan data baru, dan diberi tahu oleh driver ketika byte pertama data diterima. Jika tidak, SerCx2 secara berkala memanggil fungsi EvtSerCx2CustomReceiveTransactionQueryProgress untuk mendeteksi penerimaan byte pertama, dan mungkin perlu membangunkan prosesor secara berkala untuk melakukan panggilan ini. Dengan demikian, driver yang mengimplementasikan fungsi EvtSerCx2CustomReceiveTransactionEnableNewDataNotification dapat mengurangi konsumsi daya dengan tidak mengharuskan prosesor untuk bangun sesering mungkin.

SerCx2 tidak secara eksplisit membatalkan pemberitahuan data baru yang tertunda untuk transaksi penerima kustom. Namun, driver pengontrol serial mungkin perlu secara implisit membatalkan pemberitahuan data baru jika pemberitahuan diaktifkan dan driver harus menyelesaikan permintaan baca terkait karena salah satu alasan berikut:

  • Waktu permintaan baca habis atau dibatalkan.
  • Pengontrol serial akan keluar dari status daya perangkat D0 untuk memasuki status daya rendah.

Driver biasanya memanggil metode seperti WdfRequestComplete untuk menyelesaikan permintaan. Driver tidak boleh memanggil SerCx2CustomReceiveTransactionNewDataNotification setelah permintaan selesai.

Mengakses objek permintaan

Untuk memulai transaksi penerimaan kustom, SerCx2 memanggil fungsi EvtSerCx2CustomReceiveTransactionStart driver dan meneruskan permintaan baca terkait (dienkapsulasi dalam handel objek WDFREQUEST) ke fungsi ini sebagai parameter. Driver bertanggung jawab untuk memanggil metode seperti WdfRequestComplete untuk menyelesaikan permintaan ini ketika transaksi selesai. Kecuali permintaan dapat segera diselesaikan, sebelum fungsi EvtSerCx2CustomReceiveTransactionStart kembali, driver harus memanggil metode seperti WdfRequestMarkCancelableEx untuk menandai permintaan sebagai dapat dibatalkan.

Driver pengontrol serial tidak boleh menggunakan metode seperti WdfRequestRetrieveOutputBuffer untuk mengakses buffer data dalam permintaan baca. Sebagai gantinya, driver harus menggunakan nilai parameter Mdl, Offset, dan Length yang diteruskan ke fungsi EvtSerCx2CustomReceiveTransactionStart untuk mengakses buffer ini.

Selama transaksi penerima kustom, driver mungkin perlu menyimpan informasi tentang transaksi dalam konteks yang dilampirkan ke objek permintaan. Jika demikian, fungsi panggilan balik peristiwa EvtDriverDeviceAdd driver dapat memanggil metode WdfDeviceInitSetRequestAttributes untuk mengatur atribut yang akan digunakan untuk objek permintaan. Atribut ini mencakup nama dan ukuran alokasi yang akan digunakan untuk konteks permintaan. Atribut permintaan yang ditentukan dalam panggilan ini harus cocok dengan atribut permintaan yang ditentukan driver dalam panggilan ke metode SerCx2InitializeDevice . Atribut ini ditentukan dalam anggota RequestAttributes dari struktur SERCX2_CONFIG yang diteruskan driver ke SerCx2InitializeDevice. Untuk informasi selengkapnya, lihat SERCX2_CONFIG.

Untuk permintaan baca yang diterima driver pengontrol serial pada awal transaksi penerimaan kustom, konteks permintaan yang dialokasikan oleh kerangka kerja driver tidak diinisialisasi. Driver harus, sebagai praktik terbaik, memanggil rutinitas RtlZeroMemory untuk menginisialisasi konteks permintaan ini ke semua nol.