Bagikan melalui

Permintaan I/O SPB

  • Artikel

Makro CTL_CODE yang disediakan sistem, yang dijelaskan dalam Menentukan Kode Kontrol I/O, digunakan untuk menentukan kode kontrol IOCTL_SPB_* di Spb.h.

IOCTL_SPB_EXECUTE_SEQUENCE kode kontrol

Kode kontrol I/O IOCTL_SPB_EXECUTE_SEQUENCE memungkinkan klien (driver periferal) driver pengontrol SPB untuk melakukan urutan transfer (baca dan tulis) sebagai operasi atomik tunggal dengan satu permintaan I/O. Perangkat yang ditunjuk pada bus adalah target untuk semua transfer secara berurutan.

Dengan menentukan urutan transfer panjang tetap sebagai operasi atom tunggal, permintaan kontrol I/O IOCTL_SPB_EXECUTE_SEQUENCE memungkinkan driver pengontrol untuk mengoptimalkan transfer I/O dan meningkatkan performa.

Klien mengirimkan permintaan kontrol I/O ini ke objek file untuk perangkat target.

Driver pengontrol SPB mendaftarkan fungsi panggilan balik EvtSpbControllerIoSequence untuk melakukan transfer bus untuk urutan transfer I/O. Ekstensi kerangka kerja SPB (SpbCx) memanggil fungsi ini untuk meneruskan permintaan IOCTL_SPB_EXECUTE_SEQUENCE ke driver pengontrol SPB untuk diproses.

IOCTL_SPB_EXECUTE_SEQUENCE buffer input

Buffer input adalah struktur SPB_TRANSFER_LIST, yang berisi daftar penunjuk ke buffer data klien. Daftar ini berisi buffer data untuk setiap transfer (baca atau tulis) dalam urutan transfer I/O.

IOCTL_SPB_EXECUTE_SEQUENCE panjang buffer input

Ukuran struktur SPB_TRANSFER_LIST.

IOCTL_SPB_EXECUTE_SEQUENCE blok status

Jika operasi berhasil, driver pengontrol mengatur anggota Status ke STATUS_SUCCESS, dan mengatur anggota Informasi ke jumlah total byte yang ditransfer selama urutan.

Operasi ini mungkin gagal karena berbagai alasan, yang dapat mencakup sumber daya rendah, input klien yang tidak valid, dan kerusakan perangkat.

Jika driver pengontrol mulai memproses permintaan I/O, tetapi kesalahan terjadi selama salah satu transfer dalam urutan (misalnya, perangkat target memberi sinyal NACK untuk menolak transfer), driver pengontrol membatalkan transfer yang tersisa dalam urutan. Driver kemudian mengatur status penyelesaian ke STATUS_SUCCESS, mengatur anggota Informasi ke jumlah byte yang berhasil ditransfer sebelum kesalahan terjadi, dan menyelesaikan permintaan.

IOCTL_SPB_FULL_DUPLEX kode kontrol

Kode kontrol IOCTL_SPB_FULL_DUPLEX digunakan oleh klien (driver periferal) untuk meminta operasi I/O dupleks penuh. Operasi I/O dupleks penuh didukung oleh pengontrol untuk bus seperti SPI yang dapat membaca dan menulis data secara bersamaan. Makro CTL_CODE yang disediakan sistem, yang dijelaskan dalam Menentukan Kode Kontrol I/O, digunakan untuk menentukan IOCTL_SPB_FULL_DUPLEX sebagai berikut.

Driver mode pengguna atau driver mode kernel untuk perangkat di bus mengirimkan permintaan kontrol I/O ini ke objek file untuk perangkat target.

IOCTL ini hanya didukung oleh driver pengontrol SPB untuk bus, seperti SPI, yang dapat membaca dan menulis data secara bersamaan.

Buffer tulis dan baca untuk transfer dupleks penuh dijelaskan oleh struktur SPB_TRANSFER_LIST. Struktur ini harus menggunakan format berikut:

  • Array struktur SPB_TRANSFER_LIST_ENTRY berisi tepat dua elemen. Elemen pertama menjelaskan buffer tulis (Direction = SpbTransferDirectionToDevice). Elemen kedua menjelaskan buffer baca (Arah = SpbTransferDirectionFromDevice).

  • Anggota DelayInUs dari dua struktur SPB_TRANSFER_LIST_ENTRY harus nol. Format buffer untuk buffer tulis dan buffer baca dapat berupa salah satu hal berikut:

    • SpbTransferBufferFormatSimple
    • SpbTransferBufferFormatList
    • SpbTransferBufferFormatSimpleNonPaged
    • SpbTransferBufferFormatMdl

    Dua format terakhir dalam daftar sebelumnya hanya dapat digunakan oleh klien mode kernel. Format untuk buffer tulis dan baca tidak diharuskan sama. Untuk informasi selengkapnya tentang format buffer ini, lihat SPB_TRANSFER_BUFFER_FORMAT.

Operasi yang berhasil dapat mengatur anggota Informasi ke nilai yang kurang dari jumlah ukuran buffer tulis dan buffer baca, yang dapat terjadi jika permintaan dibatalkan, atau jika operasi tidak dapat menulis konten lengkap buffer tulis ke perangkat, atau sepenuhnya mengisi buffer baca dengan data yang dibaca dari perangkat.

Ukuran buffer tulis dan baca tidak diharuskan sama. Jika buffer tulis lebih besar dari buffer baca, operasi terus menulis data dari buffer tulis setelah buffer baca penuh. Jika buffer baca lebih besar dari buffer tulis, operasi terus mengisi buffer baca setelah buffer tulis dikosongkan.

Jika driver pengontrol SPB mendaftarkan fungsi panggilan balik EvtSpbControllerIoOther, ekstensi kerangka kerja SPB (SpbCx) memanggil fungsi ini untuk meneruskan permintaan IOCTL_SPB_FULL_DUPLEX ke driver pengontrol SPB untuk diproses. SpbCx tidak melakukan pemeriksaan parameter, validasi daftar transfer, atau pemrosesan lainnya untuk permintaan IOCTL_SPB_FULL_DUPLEX.

Untuk informasi selengkapnya tentang bagaimana driver pengontrol SPB menerapkan dukungan untuk IOCTL ini, lihat Menangani Permintaan IOCTL_SPB_FULL_DUPLEX.

IOCTL_SPB_FULL_DUPLEX buffer input

Penunjuk ke struktur SPB_TRANSFER_LIST yang berisi penunjuk ke buffer data input dan output klien. Struktur ini berisi array Transfer dari tepat dua elemen. Elemen pertama menjelaskan buffer yang berisi data untuk ditulis ke perangkat. Elemen kedua menjelaskan buffer yang digunakan untuk menahan data yang dibaca dari perangkat. Untuk informasi selengkapnya tentang bagaimana driver pengontrol SPB menerapkan permintaan kontrol I/O kustom (IOCTL) yang menggunakan struktur SPB_TRANSFER_LIST untuk menjelaskan buffer, lihat Menggunakan Struktur SPB_TRANSFER_LIST untuk IOCTL Kustom.

IOCTL_SPB_FULL_DUPLEX panjang buffer input

Ukuran struktur SPB_TRANSFER_LIST.

IOCTL_SPB_FULL_DUPLEX blok status

Jika operasi berhasil, driver pengontrol mengatur anggota Status ke STATUS_SUCCESS, dan mengatur anggota Informasi ke jumlah total byte yang ditransfer (byte baca plus byte ditulis) selama operasi dupleks penuh.

Operasi ini mungkin gagal karena berbagai alasan, yang dapat mencakup sumber daya rendah, input klien yang tidak valid, dan kerusakan perangkat.

IOCTL_SPB_LOCK_CONNECTION kode kontrol

Kode kontrol IOCTL_SPB_LOCK_CONNECTION digunakan oleh klien (driver periferal) untuk memperoleh kunci koneksi pada perangkat target yang terhubung dengan SPB yang dibagikan dengan klien lain. Saat klien memegang kunci koneksi, klien ini memiliki akses eksklusif ke perangkat. Makro CTL_CODE yang disediakan sistem, yang dijelaskan dalam Menentukan Kode Kontrol I/O, digunakan untuk menentukan IOCTL_SPB_LOCK_CONNECTION sebagai berikut.

Permintaan IOCTL_SPB_LOCK_CONNECTION dan IOCTL_SPB_UNLOCK_CONNECTION memperoleh dan melepaskan kunci koneksi pada perangkat target yang dilampirkan ke bus periferal sederhana. Sebagian besar klien tidak menggunakan permintaan kontrol I/O ini. Permintaan ini hanya digunakan jika dua klien berbagi akses ke perangkat target yang sama. Untuk informasi selengkapnya, lihat Kunci Koneksi SPB.

Dua klien dapat membuka koneksi logis terpisah ke perangkat target yang sama dan menggunakan kunci koneksi ketika salah satu klien memerlukan akses eksklusif ke perangkat. Ketika satu klien memegang kunci, permintaan I/O ke perangkat dari klien kedua secara otomatis ditangguhkan hingga klien pertama melepaskan kunci.

Klien dapat secara bersamaan menahan kunci koneksi pada perangkat target dan kunci pengontrol pada pengontrol SPB. Permintaan IOCTL_SPB_LOCK_CONTROLLER dan IOCTL_SPB_UNLOCK_CONTROLLER memperoleh dan melepaskan kunci pengontrol. Klien harus memperoleh kunci koneksi sebelum memperoleh kunci pengontrol, dan harus melepaskan kunci pengontrol sebelum melepaskan kunci koneksi. Klien menggunakan kunci pengontrol untuk melakukan serangkaian transfer bus yang diurutkan (operasi baca dan tulis) sebagai operasi bus atom tunggal. Untuk informasi selengkapnya, lihat Urutan Transfer I/O.

Kunci koneksi secara otomatis dihentikan jika permintaan IRP_MJ_CLEANUP dikirim ke perangkat target saat koneksi dikunci pada perangkat. Permintaan pembersihan dikirim ke perangkat target ketika klien menutup handel filenya ke perangkat.

IOCTL_SPB_LOCK_CONNECTION blok status

Jika operasi berhasil, anggota Status diatur ke STATUS_SUCCESS.

Jika operasi gagal, anggota Status diatur ke kode status kesalahan yang sesuai.

Jika klien sudah memegang kunci koneksi pada perangkat target atau kunci pengontrol pada pengontrol SPB, operasi ini gagal dengan Status = STATUS_INVALID_DEVICE_REQUEST. Operasi ini mungkin gagal karena alasan lain, yang dapat mencakup sumber daya rendah, input klien yang tidak valid, dan kerusakan perangkat.

IOCTL_SPB_LOCK_CONTROLLER kode kontrol

Kode kontrol IOCTL_SPB_LOCK_CONTROLLER digunakan oleh klien (driver periferal) untuk mengunci pengontrol SPB. Saat pengontrol dikunci, klien memiliki penggunaan bus secara eksklusif untuk mengakses perangkat target yang ditentukan untuk kunci. Makro CTL_CODE yang disediakan sistem, yang dijelaskan dalam Menentukan Kode Kontrol I/O, digunakan untuk menentukan IOCTL_SPB_LOCK_CONTROLLER sebagai berikut.

Untuk mendapatkan penggunaan bus secara eksklusif untuk mengakses perangkat target, klien (driver periferal) mengirimkan IOCTL ini ke objek file untuk target. Setelah IOCTL ini selesai, pengontrol dikunci, dan semua transfer I/O (baca atau tulis) pada bus mengakses target yang ditunjuk. Di antara transfer, pengontrol menjaga perangkat target tetap dipilih tetapi menghentikan jam.

Pengontrol tetap terkunci sampai klien mengirim permintaan IOCTL_SPB_UNLOCK_CONTROLLER untuk membuka kunci pengontrol. Ketika urutan transfer klien ke atau dari perangkat target selesai, klien harus membuka pengontrol sehingga pengontrol dapat memproses permintaan I/O untuk target lain di bus.

Kunci secara otomatis dihentikan jika permintaan IRP_MJ_CLEANUP dikirim ke perangkat target saat pengontrol dikunci pada target. Permintaan pembersihan dikirim ke target ketika klien menutup handelnya ke target.

Pengontrol SPB tidak diperlukan untuk mendukung permintaan IOCTL_SPB_LOCK_CONTROLLER dan IOCTL_SPB_UNLOCK_CONTROLLER, dan driver perangkat periferal tidak boleh berasumsi bahwa mereka didukung.

Jika driver pengontrol SPB mendaftarkan fungsi panggilan balik EvtSpbControllerLock, ekstensi kerangka kerja SPB (SpbCx) memanggil fungsi ini untuk meneruskan permintaan IOCTL_SPB_LOCK_CONTROLLER ke driver pengontrol SPB untuk diproses.

IOCTL_SPB_LOCK_CONTROLLER blok status

Jika operasi berhasil, anggota Status diatur ke STATUS_SUCCESS. IOCTL ini dapat mengembalikan status kesalahan karena sejumlah alasan, termasuk kegagalan untuk mengonfigurasi pengontrol untuk beroperasi dalam mode akses eksklusif. Dalam mode ini, pengontrol menjaga perangkat target tetap dipilih sehingga merupakan target eksklusif untuk semua transfer I/O di bus. Pengontrol tetap dalam mode ini hingga dibuka kuncinya.

IOCTL_SPB_UNLOCK_CONNECTION kode kontrol

Kode kontrol I/O IOCTL_SPB_UNLOCK_CONNECTION digunakan oleh klien (driver periferal) untuk melepaskan kunci koneksi pada perangkat target yang terhubung dengan SPB yang dibagikan dengan klien lain. Klien sebelumnya mengirim permintaan IOCTL_SPB_LOCK_CONNECTION untuk memperoleh akses eksklusif ke perangkat.

Permintaan IOCTL_SPB_LOCK_CONNECTION dan IOCTL_SPB_UNLOCK_CONNECTION memperoleh dan melepaskan kunci koneksi pada perangkat target yang dilampirkan ke bus periferal sederhana. Sebagian besar klien tidak menggunakan permintaan kontrol I/O ini. Permintaan ini hanya digunakan jika dua klien berbagi akses ke perangkat target yang sama. Untuk informasi selengkapnya, lihat Kunci Koneksi SPB.

Setelah klien (driver periferal) mengirim permintaan IOCTL_SPB_LOCK_CONNECTION ke perangkat target di bus, dan permintaan berhasil diselesaikan, koneksi tetap terkunci sampai klien mengirim permintaan IOCTL_SPB_UNLOCK_CONNECTION untuk membuka kunci koneksi.

Klien mengirimkan permintaan IOCTL_SPB_UNLOCK_CONNECTION untuk melepaskan kunci koneksi ke perangkat target ketika klien tidak lagi memerlukan akses eksklusif ke perangkat. Koneksi harus dibuka kuncinya sehingga klien lain dapat mengakses perangkat.

IOCTL_SPB_UNLOCK_CONNECTION blok status

Jika operasi berhasil, anggota Status diatur ke STATUS_SUCCESS.

Jika operasi gagal, anggota Status diatur ke kode status kesalahan yang sesuai. Jika klien tidak menahan kunci koneksi pada perangkat target, atau jika klien masih memegang kunci koneksi pada pengontrol SPB, operasi ini gagal dengan Status = STATUS_INVALID_DEVICE_REQUEST. Operasi ini mungkin gagal karena alasan lain, yang dapat mencakup sumber daya rendah, input klien yang tidak valid, dan kerusakan perangkat.

IOCTL_SPB_UNLOCK_CONTROLLER kode kontrol

Kode kontrol I/O IOCTL_SPB_UNLOCK_CONTROLLER digunakan oleh klien (driver periferal) untuk membuka kunci pengontrol SPB. Klien sebelumnya mengunci pengontrol untuk mendapatkan penggunaan bus secara eksklusif untuk mengakses perangkat target di bus.

Setelah klien (driver periferal) mengirim permintaan kontrol I/O IOCTL_SPB_LOCK_CONTROLLER ke perangkat target di bus, pengontrol tetap terkunci sampai klien mengirim permintaan kontrol I/O IOCTL_SPB_UNLOCK_CONTROLLER untuk membuka kunci pengontrol. Klien mengirimkan permintaan kontrol I/O ini ke objek file untuk perangkat target.

Klien mengirimkan permintaan IOCTL_SPB_UNLOCK_CONTROLLER ketika telah menyelesaikan urutan transfer di bus dan ingin merilis perangkat target. Pengontrol harus dibuka kuncinya sehingga dapat memproses permintaan I/O untuk target lain di bus.

Pengontrol SPB tidak diperlukan untuk mendukung permintaan IOCTL_SPB_LOCK_CONTROLLER dan IOCTL_SPB_UNLOCK_CONTROLLER, dan driver perangkat periferal tidak boleh berasumsi bahwa mereka didukung.

Ekstensi kerangka kerja SPB (SpbCx) memanggil fungsi panggilan balik EvtSpbControllerUnlock opsional driver pengontrol SPB untuk meneruskan permintaan IOCTL_SPB_LOCK_CONTROLLER ke driver pengontrol SPB untuk diproses.

IOCTL_SPB_UNLOCK_CONTROLLER blok status

Jika operasi berhasil, anggota Status diatur ke STATUS_SUCCESS.

IOCTL ini hanya dapat gagal jika dikirim oleh klien yang tidak memiliki pengontrol yang dikunci untuk akses eksklusif ke target yang ditunjuk.