EVT_SPB_CONTROLLER_SEQUENCE fungsi panggilan balik (spbcx.h)

Artikel
08/07/2023

Fungsi panggilan balik peristiwa EvtSpbControllerIoSequence driver pengontrol SPB melakukan urutan transfer data antara perangkat target yang ditentukan dan buffer yang disediakan dengan permintaan urutan.

Sintaks

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Parameter

[in] Controller

Handel WDFDEVICE ke objek perangkat kerangka kerja yang mewakili pengontrol SPB.

[in] Target

SPBTARGET menangani target untuk permintaan I/O ini. Targetnya adalah perangkat periferal atau port yang terpasang pada bus. Ekstensi kerangka kerja SPB (SpbCx) sebelumnya menetapkan handel ini ke target dalam panggilan balik EvtSpbTargetConnect yang membuka koneksi ke target.

[in] Request

SPBREQUEST menangani permintaan I/O. Driver pengontrol SPB Anda harus menyelesaikan permintaan ini baik dengan melakukan operasi yang diminta atau dengan mengembalikan status kesalahan. Untuk informasi selengkapnya, lihat Keterangan.

[in] TransferCount

Jumlah transfer individu dalam urutan transfer I/O ini. Setiap transfer individu adalah operasi baca atau tulis sederhana.

Nilai kembali

Tidak ada

Keterangan

SpbCx mengelola antrean I/O untuk pengontrol SPB. SpbCx memanggil fungsi panggilan balik EvtSpbControllerIoSequence driver pengontrol SPB ketika klien (driver periferal) pengontrol SPB mengirimkan permintaan IOCTL_SPB_EXECUTE_SEQUENCE ke perangkat target yang dilampirkan ke bus. Nilai parameter Permintaan adalah handel yang merangkum permintaan ini.

Panggilan balik EvtSpbControllerIoSequence tidak mengembalikan nilai status. Sebaliknya, driver pengontrol SPB menunjukkan status operasi urutan dalam status penyelesaian untuk permintaan I/O.

Panggilan balik EvtSpbControllerIoSequence tidak sinkron. Artinya, fungsi panggilan balik harus memulai operasi urutan yang diminta (atau bagian pertama dari urutan) dan kemudian kembali tanpa menunggu operasi selesai. Kemudian, driver pengontrol SPB terus memproses permintaan atau menyelesaikannya selama mengganggu DPC atau DPC timer.

Driver pengontrol SPB dapat mengambil nilai parameter dari permintaan I/O untuk menentukan panjang maksimum transfer dalam urutan. Driver dapat menggunakan panjang ini untuk mengalokasikan sumber daya DMA yang dapat digunakan kembali untuk setiap transfer dalam urutan.

Driver pengontrol SPB dapat memanggil metode SpbRequestGetTransferParameters untuk mengambil parameter kontrol dan buffer data untuk setiap transfer secara berurutan. Buffer adalah objek WDFMEMORY yang, dalam implementasi saat ini, merangkum MDL berantai. Untuk informasi selengkapnya tentang MDL berantai, lihat Menggunakan MDL.

Pengontrol SPB harus menjaga perangkat target tetap dipilih untuk seluruh operasi urutan. Jika target dipilih oleh baris yang dipilih perangkat, baris dapat ditegaskan terus menerus dari awal transfer pertama dalam urutan hingga transfer terakhir berakhir. Baris ini dapat ditegaskan sedini operasi penguncian pada awal urutan dan dapat tetap ditegaskan sampai operasi buka kunci di akhir urutan.

Penundaan opsional dapat ditentukan untuk setiap transfer secara berurutan. Driver pengontrol SPB bertanggung jawab untuk menunda setidaknya jumlah mikrodetik sebelum memulai transfer. Jika transfer pertama dalam urutan memiliki penundaan terkait, driver harus terlebih dahulu mengirimkan alamat atau menegaskan baris yang dipilih perangkat dari perangkat target, lalu menunda untuk waktu yang ditentukan sebelum memulai transfer data. Selama penundaan ini, target harus tetap dipilih tetapi pengontrol tidak boleh menjalankan jam pada bus.

Jika perangkat target memberi sinyal NACK selama transfer secara berurutan, pengontrol SPB menghentikan urutan. (Artinya, pengontrol tidak mencoba kembali transfer yang gagal dan tidak mencoba melakukan transfer yang tersisa dalam urutan.) Jika ini terjadi, driver pengontrol SPB harus mengatur status penyelesaian permintaan I/O ke STATUS_SUCCESS, atur bidang Informasi di blok status I/O ke jumlah byte yang benar-benar ditransfer (tidak menghitung data yang hilang dalam transfer yang menerima NACK), dan menyelesaikan permintaan.

Driver pengontrol SPB harus menyelesaikan permintaan I/O dengan kode status kesalahan hanya jika salah satu kondisi berikut terjadi:

Pengontrol SPB tidak dapat memilih perangkat target (misalnya, perangkat target pada bus I²C memberi sinyal NACK saat pengontrol mengirimkan byte alamat).
Driver pengontrol SPB mendapatkan status kesalahan dari panggilan ke layanan WDF atau WDM saat memproses operasi urutan.

Untuk mendaftarkan fungsi panggilan balik EvtSpbControllerIoSequence , panggil metode SpbDeviceInitialize .

Contoh

Untuk menentukan fungsi panggilan balik EvtSpbControllerIoSequence , 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 EvtSpbControllerIoSequence yang bernama MyEvtSpbControllerIoSequence, gunakan jenis fungsi EVT_SPB_CONTROLLER_SEQUENCE, seperti yang ditunjukkan dalam contoh kode ini:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

Jenis fungsi EVT_SPB_CONTROLLER_SEQUENCE didefinisikan dalam file header Spbcx.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_SPB_CONTROLLER_SEQUENCE 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	Didukung dimulai dengan Windows 8.
Target Platform	Desktop
Header	spbcx.h
IRQL	Dipanggil di IRQL <= DISPATCH_LEVEL.

Share via