EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER fungsi panggilan balik (sercx.h)

Artikel
02/29/2024

Fungsi panggilan balik peristiwa EvtSerCx2PioTransmitWriteBuffer dipanggil oleh versi 2 dari ekstensi kerangka kerja serial (SerCx2) untuk menggunakan I/O (PIO) terprogram untuk mentransfer konten buffer tulis ke FIFO transmisi di pengontrol serial.

Sintaks

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

Parameter

[in] PioTransmit

Handel SERCX2PIOTRANSMIT ke objek transmisi PIO. Driver pengontrol serial sebelumnya disebut metode SerCx2PioTransmitCreate untuk membuat objek ini.

[in] Buffer

Penunjuk ke buffer tulis. Parameter ini adalah alamat virtual buffer terkunci dalam memori sistem.

[in] Length

Jumlah byte dalam buffer tulis yang tersedia untuk ditransmisikan.

Nilai kembali

Fungsi EvtSerCx2PioTransmitWriteBuffer mengembalikan jumlah byte data yang berhasil ditransfer dari buffer tulis ke FIFO pengiriman di perangkat keras pengontrol serial.

Keterangan

Driver pengontrol serial Anda harus menerapkan fungsi ini. Driver mendaftarkan fungsi dalam panggilan SerCx2PioTransmitCreate yang membuat objek transmisi PIO.

SerCx2 mungkin memanggil fungsi EvtSerCx2PioTransmitWriteBuffer lebih dari sekali selama transaksi pengiriman PIO. Satu panggilan EvtSerCx2PioTransmitWriteBuffer cukup jika panggilan ini dapat mentransfer konten lengkap buffer tulis ke FIFO transmisi. Jika tidak, SerCx2 terus memanggil fungsi ini, karena lebih banyak ruang tersedia di FIFO transmisi, sampai buffer tulis dikosongkan.

Dimulai dengan byte pertama dalam buffer tulis, fungsi EvtSerCx2PioTransmitWriteBuffer menggunakan PIO untuk mentransfer byte sebanyak mungkin dari buffer ke FIFO transmisi. Fungsi terus mentransfer data dari buffer selama buffer tidak kosong dan daftar status baris (LSR) menunjukkan bahwa FIFO dapat menerima lebih banyak data. Jika LSR menunjukkan bahwa FIFO tidak dapat menerima data lagi, fungsi akan kembali tanpa mengosongkan buffer. Jika tidak, fungsi mentransfer semua byte dalam buffer dan mengembalikan. Dalam kedua kasus, nilai yang dikembalikan oleh fungsi ini adalah jumlah byte data yang berhasil ditransfer dari buffer tulis ke FIFO transmisi.

Biasanya, fungsi EvtSerCx2PioTransmitWriteBuffer tidak mengaktifkan gangguan apa pun. Sebaliknya, jika fungsi tidak dapat mentransfer seluruh konten buffer tulis ke PENGIRIMAN FIFO, SerCx2 memanggil fungsi panggilan balik peristiwa EvtSerCx2PioTransmitEnableReadyNotification untuk mengaktifkan pemberitahuan siap, dan fungsi ini memungkinkan gangguan yang terjadi ketika FIFO transmisi menjadi kosong.

Untuk setiap panggilan berturut-turut ke fungsi EvtSerCx2PioTransmitWriteBuffer , SerCx2 menyesuaikan Buffer untuk menunjuk ke data yang tersisa di buffer, dan mengatur Panjang ke jumlah byte data yang tetap berada di buffer.

Pemberitahuan siap tidak pernah diaktifkan ketika SerCx2 memanggil fungsi EvtSerCx2PioTransmitEnableReadyNotification . Namun, SerCx2 mungkin memanggil fungsi ini dari utas yang sama dari mana driver disebut metode SerCx2PioTransmitReady .

Jika driver mengimplementasikan fungsi EvtSerCx2PioTransmitInitializeTransaction , SerCx2 memanggil fungsi ini pada awal transaksi transmisi PIO, sebelum panggilan pertama ke fungsi EvtSerCx2PioTransmitWriteBuffer . Jika driver mengimplementasikan fungsi EvtSerCx2PioTransmitCleanupTransaction , SerCx2 memanggil fungsi ini di akhir transaksi transmisi PIO, setelah panggilan EvtSerCx2PioTransmitWriteBuffer terakhir, dan setelah panggilan apa pun ke fungsi EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo, dan fungsi EvtSerCx2PioTransmitPurgeFifo , jika diimplementasikan.

Untuk informasi selengkapnya tentang transaksi pengiriman PIO, lihat SerCx2 PIO-Transmit Transactions.

Contoh

Untuk menentukan fungsi panggilan balik EvtSerCx2PioTransmitWriteBuffer , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. 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 EvtSerCx2PioTransmitWriteBuffer yang diberi nama MyPioTransmitWriteBuffer, gunakan jenis fungsi EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER , seperti yang ditunjukkan dalam contoh kode ini:

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

Jenis fungsi EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER ditentukan 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_PIO_TRANSMIT_WRITE_BUFFER 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.