EVT_SERCX2_PIO_RECEIVE_READ_BUFFER fungsi panggilan balik (sercx.h)

Artikel
03/05/2024

Fungsi panggilan balik peristiwa EvtSerCx2PioReceiveReadBuffer dipanggil oleh versi 2 dari ekstensi kerangka kerja serial (SerCx2) untuk menggunakan I/O (PIO) terprogram untuk mentransfer data dari FIFO penerima di pengontrol serial ke buffer baca.

Sintaks

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Parameter

[in] PioReceive

Handel SERCX2PIORECEIVE ke objek penerima PIO. Driver pengontrol serial sebelumnya disebut metode SerCx2PioReceiveCreate untuk membuat objek ini.

[out] Buffer

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

[in] Length

Jumlah byte dalam buffer baca yang tersedia untuk menyimpan data yang diterima.

Nilai kembali

Fungsi EvtSerCx2PioReceiveReadBuffer mengembalikan jumlah byte data yang berhasil ditransfer dari FIFO penerimaan di perangkat keras pengontrol serial ke buffer baca.

Keterangan

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

SerCx2 mungkin memanggil fungsi EvtSerCx2PioReceiveReadBuffer lebih dari sekali selama transaksi penerimaAN PIO. Satu panggilan EvtSerCx2PioReceiveReadBuffer cukup jika panggilan ini dapat mengisi buffer baca dengan data dari FIFO penerima. Jika tidak, SerCx2 terus memanggil fungsi ini, karena lebih banyak data tersedia di FIFO penerima, sampai buffer baca terisi.

Fungsi EvtSerCx2PioReceiveReadBuffer menggunakan PIO untuk mentransfer byte sebanyak mungkin dari FIFO penerima ke buffer baca. Fungsi terus mentransfer data dari FIFO selama buffer yang diteruskan ke fungsi ini tidak penuh dan daftar status baris (LSR) menunjukkan bahwa lebih banyak data tersedia dari FIFO. Jika LSR menunjukkan bahwa FIFO kosong, fungsi akan kembali tanpa mengisi buffer. Jika tidak, fungsi mengisi buffer dan mengembalikan. Dalam kedua kasus, nilai yang dikembalikan oleh fungsi ini adalah jumlah byte data yang berhasil ditransfer ke buffer baca dari FIFO penerima.

Biasanya, fungsi EvtSerCx2PioReceiveReadBuffer tidak mengaktifkan interupsi apa pun. Sebaliknya, jika FIFO penerima kehabisan data sebelum fungsi dapat mengisi buffer baca, SerCx2 memanggil fungsi panggilan balik peristiwa EvtSerCx2PioReceiveEnableReadyNotification untuk mengaktifkan pemberitahuan siap, dan fungsi ini memungkinkan gangguan yang terjadi ketika lebih banyak data tersedia di FIFO penerimaan.

Untuk setiap panggilan berturut-turut ke fungsi EvtSerCx2PioReceiveReadBuffer , SerCx2 menyesuaikan Buffer untuk menunjuk ke wilayah buffer berikutnya yang akan diisi, dan mengatur Panjang ke jumlah byte ruang yang tidak terisi yang tersisa di buffer.

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

Jika driver menerapkan fungsi EvtSerCx2PioReceiveInitializeTransaction , SerCx2 memanggil fungsi ini pada awal transaksi transmisi PIO, sebelum panggilan pertama ke fungsi EvtSerCx2PioReceiveReadBuffer . Jika driver mengimplementasikan fungsi EvtSerCx2PioReceiveCleanupTransaction , SerCx2 memanggil fungsi ini di akhir transaksi penerima PIO, setelah panggilan akhir ke fungsi EvtSerCx2PioReceiveReadBuffer .

Selain memanggil fungsi EvtSerCx2PioReceiveReadBuffer selama transaksi penerima PIO, SerCx2 memanggil fungsi ini untuk menyimpan status MENERIMA FIFO tepat sebelum pengontrol serial keluar dari status daya perangkat D0. Untuk informasi selengkapnya, lihat SerCx2SaveReceiveFifoOnD0Exit.

Untuk informasi selengkapnya tentang transaksi penerima PIO, lihat Transaksi PIO-Receive SerCx2.

Contoh

Untuk menentukan fungsi panggilan balik EvtSerCx2PioReceiveReadBuffer , 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 EvtSerCx2PioReceiveReadBuffer yang diberi nama MyPioReceiveReadBuffer, gunakan jenis fungsi EVT_SERCX2_PIO_RECEIVE_READ_BUFFER , seperti yang ditunjukkan dalam contoh kode ini:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

Jenis fungsi EVT_SERCX2_PIO_RECEIVE_READ_BUFFER 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_PIO_RECEIVE_READ_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.