EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START fungsi panggilan balik (sercx.h)

Artikel
08/07/2023

Fungsi panggilan balik peristiwa EvtSerCx2CustomTransmitTransactionStart dipanggil oleh versi 2 dari ekstensi kerangka kerja serial (SerCx2) untuk memulai transaksi pengiriman kustom.

Sintaks

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameter

[in] CustomTransmitTransaction

Handel SERCX2CUSTOMTRANSMITTRANSACTION ke objek transaksi pengiriman kustom. Driver pengontrol serial sebelumnya disebut metode SerCx2CustomTransmitTransactionCreate untuk membuat objek ini.

[in] Request

Handel ke objek permintaan kerangka kerja yang terkait dengan transaksi pengiriman kustom. Driver bertanggung jawab untuk menyelesaikan permintaan ini. Permintaan ini mungkin bukan permintaan IRP_MJ_WRITE yang dikirim oleh klien, dan dengan demikian driver pengontrol serial tidak boleh mencoba menggunakan permintaan ini untuk mengakses buffer tulis. Permintaan ini terutama digunakan untuk pembatalan, penyelesaian, dan penerusan antrean (jika diperlukan). Untuk mengakses buffer tulis untuk permintaan tulis klien, gunakan parameter Mdl, Offset, dan Length .

[in] Mdl

Penunjuk ke MDL yang menjelaskan halaman memori yang dibentangkan oleh buffer tulis untuk transaksi pengiriman kustom. Daftar sebar/kumpulkan untuk transfer DMA akan menggunakan wilayah memori ini yang ditentukan oleh parameter Offset dan Length . Untuk informasi selengkapnya tentang rantai MDL, lihat Menggunakan MDL.

[in] Offset

Offset awal untuk transfer data. Parameter ini adalah offset byte dari awal wilayah buffer yang dijelaskan oleh MDL. Jika MDL menentukan total N byte ruang buffer, kemungkinan nilai Offset berada dalam rentang 0 hingga N–1.

[in] Length

Ukuran, dalam byte, dari transfer data. Jika MDL menentukan total N byte ruang buffer, kemungkinan nilai Panjang berada dalam rentang 1 hingga N–Offset.

Nilai kembali

Tidak ada

Keterangan

Driver pengontrol serial Anda harus menerapkan fungsi ini jika membuat objek transaksi transmisi kustom. Jika diimplementasikan, driver mendaftarkan fungsi dalam panggilan SerCx2CustomTransmitTransactionCreate yang membuat objek ini.

Setelah SerCx2 memanggil fungsi EvtSerCx2CustomTransmitTransactionStart , driver pengontrol serial memulai transaksi dengan memprogram mekanisme transfer data kustom untuk memindahkan data dari buffer dalam permintaan tulis ke transmisi FIFO di perangkat keras pengontrol serial. Kecuali permintaan dapat segera diselesaikan, sebelum fungsi EvtSerCx2CustomTransmitTransactionStart kembali, driver harus memanggil metode seperti WdfRequestMarkCancelableEx untuk menandai permintaan sebagai dapat dibatalkan.

Setelah transaksi selesai dan driver menyelesaikan permintaan tulis yang tertunda, SerCx2 memanggil fungsi panggilan balik peristiwa EvtSerCx2CustomTransmitTransactionCleanup , jika driver menerapkan fungsi ini.

Jika driver pengontrol serial mengimplementasikan fungsi panggilan balik peristiwa EvtSerCx2CustomTransmitTransactionInitialize , SerCx2 memanggil fungsi ini sebelum memanggil fungsi EvtSerCx2CustomTransmitTransactionStart . Tepat sebelum panggilan EvtSerCx2CustomTransmitTransactionStart , dan setelah panggilan EvtSerCx2CustomTransmitTransactionInitialize kembali, SerCx2 memulai timer yang mendeteksi apakah permintaan tulis kehabisan waktu. Untuk informasi selengkapnya, lihat diskusi total waktu habis dalam SERIAL_TIMEOUTS.

Driver pengontrol serial harus menyelesaikan permintaan tulis yang tertunda hanya setelah byte terakhir dalam pengiriman FIFO telah ditransmisikan ke perangkat periferal yang terhubung secara serial. Tidak ada jaminan bahwa data yang ditulis ke pengiriman FIFO akan ditransmisikan tanpa penundaan yang signifikan, dan driver pengontrol serial yang mengasumsikan bahwa jaminan seperti itu ada dapat menyebabkan masalah keandalan bagi driver periferal.

Jika mekanisme transfer data kustom adalah perangkat DMA master bus, fungsi EvtSerCx2CustomTransmitTransactionStart dapat memanggil metode seperti WdfDmaTransactionInitializeUsingOffset untuk memulai transaksi DMA yang menggunakan buffer tulis yang dijelaskan oleh parameter Mdl, Offset, dan Length .

Untuk informasi selengkapnya tentang parameter Mdl, Offset, dan Length , lihat Keterangan di EvtSerCx2CustomTransmitTransactionInitialize.

Jika objek permintaan yang diidentifikasi oleh parameter Permintaan berisi penyimpanan untuk konteks privat, penyimpanan ini mungkin tidak diinisialisasi saat pertama kali driver pengontrol serial mengakses konteks. Pada akses pertama, driver biasanya harus mengisi konteks dengan nol, lalu, jika diperlukan, secara eksplisit mengatur bidang apa pun dalam konteks yang memerlukan nilai awal bukan nol.

Untuk informasi selengkapnya, lihat Transaksi Custom-Transmit SerCx2.

Contoh

Untuk menentukan fungsi panggilan balik EvtSerCx2CustomTransmitTransactionStart , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan fungsi panggilan balik EvtSerCx2CustomTransmitTransactionStart yang diberi nama MyCustomTransmitTransactionStart, gunakan jenis fungsi EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START , seperti yang ditunjukkan dalam contoh kode ini:

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

Jenis fungsi EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START didefinisikan dalam file header Sercx.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver KMDF. Untuk informasi selengkapnya tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.1.
Target Platform	Desktop
Header	sercx.h
IRQL	Dipanggil di IRQL <= DISPATCH_LEVEL.