fungsi panggilan balik EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER (sercx.h)

Artikel
30/10/2024

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

Sintaksis

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.

Mengembalikan nilai

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

Komentar

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 pengiriman, 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 pengiriman.

Biasanya, fungsi EvtSerCx2PioTransmitWriteBuffer tidak mengaktifkan gangguan apa pun. Sebagai gantinya, jika fungsi tidak dapat mentransfer seluruh konten buffer tulis ke fungsi pengiriman FIFO, SerCx2 memanggil EvtSerCx2PioTransmitEnableReadyNotification fungsi panggilan balik peristiwa untuk mengaktifkan pemberitahuan siap, dan fungsi ini memungkinkan interupsi yang terjadi ketika FIFO pengiriman 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 tersisa di buffer.

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

Jika driver menerapkan fungsi EvtSerCx2PioTransmitInitializeTransaction, SerCx2 memanggil fungsi ini pada awal transaksi pengiriman PIO, sebelum panggilan pertama ke fungsi EvtSerCx2PioTransmitWriteBuffer. Jika driver menerapkan fungsi EvtSerCx2PioTransmitCleanupTransaction, SerCx2 memanggil fungsi ini di akhir transaksi pengiriman PIO, setelah terakhir EvtSerCx2PioTransmitWriteBuffer panggilan, dan setelah panggilan ke EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo, dan fungsi EvtSerCx2PioTransmitPurgeFi fo, jika diimplementasikan.

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

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 bernama 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 dengan 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 Anotasi Perilaku Fungsi.