IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Artikel
08/08/2023

Driver untuk fungsi virtual PCI Express (PCIe) (VF) mengeluarkan kode kontrol I/O IOCTL_VPCI_WRITE_BLOCK (IOCTL) untuk menulis data ke blok konfigurasi VF. Driver mengeluarkan IOCTL ini ke driver berikutnya yang lebih rendah di tumpukan driver.

Catatan Permintaan IOCTL ini dikeluarkan oleh driver PCIe VF pada perangkat yang mendukung antarmuka virtualisasi I/O root tunggal (SR-IOV).

Ketika driver mengeluarkan IOCTL IOCTL_VPCI_WRITE_BLOCK , driver harus mengikuti langkah-langkah berikut:

Menyiapkan Struktur Paket Permintaan I/O

Menyiapkan Struktur Lokasi Tumpukan I/O

Mengeluarkan Permintaan IOCTL

Hasil Penyelesaian Permintaan IOCTL

Untuk informasi selengkapnya tentang mengeluarkan IOCTL antara driver mode kernel, lihat Membuat Permintaan IOCTL di Driver.

Kode utama

IRP_MJ_DEVICE_CONTROL

Blok status

Irp-IoStatus.Status> diatur ke STATUS_SUCCESS jika permintaan berhasil.

Jika tidak, Status ke kondisi kesalahan yang sesuai sebagai kode NTSTATUS.

Untuk informasi selengkapnya, lihat [XREF-LINK:NTSTATUS Values].

Keterangan

Menyiapkan Struktur Paket Permintaan I/O

Driver harus terlebih dahulu mengalokasikan atau menggunakan kembali paket permintaan I/O (IRP). Anda dapat menggunakan rutinitas IoBuildDeviceIoControlRequest untuk secara khusus mengalokasikan IOCTL IRP. Anda juga dapat menggunakan rutinitas pembuatan dan inisialisasi IRP tujuan umum, seperti IoAllocateIrp, IoReuseIrp, atau IoInitializeIrp. Untuk informasi selengkapnya tentang alokasi IRP, lihat Membuat IRP untuk Driver Lower-Level.

Driver kemudian harus mengatur anggota struktur IRP seperti yang dijelaskan dalam tabel berikut.

Anggota IRP	Nilai
UserBuffer	NULL
UserEvent	Alamat objek peristiwa yang diinisialisasi dalam panggilan ke rutinitas KeInitializeEvent . Catatan Jika penyelesaian asinkron permintaan IOCTL tidak diperlukan, anggota ini harus diatur ke NULL. Untuk informasi selengkapnya, lihat Membuat Permintaan IOCTL di Driver.
UserIosb	Alamat struktur IO_STATUS_BLOCK yang dialokasikan pemanggil. Struktur ini diperbarui oleh driver yang lebih rendah untuk menunjukkan status akhir permintaan I/O.

Menyiapkan Struktur Lokasi Tumpukan I/O

Driver memanggil rutinitas IoGetNextIrpStackLocation untuk mengakses lokasi tumpukan I/O driver yang lebih rendah. Fungsi ini mengembalikan penunjuk ke struktur IO_STACK_LOCATION yang berisi parameter untuk lokasi tumpukan I/O.

Driver kemudian harus mengatur anggota dalam struktur IO_STACK_LOCATION seperti yang dijelaskan dalam tabel berikut:

anggota IO_STACK_LOCATION	Nilai
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Penunjuk ke struktur VPCI_WRITE_BLOCK_INPUT . Driver memformat struktur ini dengan parameter untuk permintaan I/O IOCTL_VPCI_WRITE_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	Ukuran, dalam byte, dari struktur VPCI_WRITE_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Nol

Mengeluarkan Permintaan IOCTL

Untuk mengeluarkan permintaan IOCTL ini, driver memanggil rutinitas IoCallDriver untuk meneruskan permintaan ke driver yang lebih rendah berikutnya di tumpukan driver. Driver mengatur parameter IoCallDriver seperti yang dijelaskan dalam tabel berikut ini.

Parameter IoCallDriver	Nilai
DeviceObject	Objek perangkat driver yang lebih rendah.
Irp	Alamat IRP yang sebelumnya dialokasikan dan diinisialisasi. Untuk informasi selengkapnya, lihat Menyiapkan Struktur Paket Permintaan (IRP) I/O.

Hasil Penyelesaian Permintaan IOCTL

Saat permintaan IOCTL IOCTL_VPCI_WRITE_BLOCK selesai, anggota Status struktur IO_STATUS_BLOCK yang dialokasikan pemanggil diatur ke salah satu nilai dalam tabel berikut.:

Nilai status	Deskripsi
STATUS_SUCCESS	IOCTL berhasil diselesaikan.
STATUS_PENDING	IOCTL belum selesai. Driver harus memanggil rutinitas KeWaitForSingleObject untuk menempatkan utas saat ini ke dalam status tunggu. Driver mengatur parameter Objek ke alamat objek peristiwa yang diinisialisasi dalam panggilan ke rutinitas KeInitializeEvent . Peristiwa ini disinyalir ketika permintaan IOCTL selesai. Setelah peristiwa disinyalkan, utas melanjutkan eksekusi.
STATUS_BUFFER_TOO_SMALL	Anggota Parameters.DeviceIoControl.InputBufferLength diatur ke nilai yang kurang dari ukuran, dalam byte, dari struktur VPCI_WRITE_BLOCK_INPUT .

Jika permintaan berhasil diselesaikan, anggota Informasi dari struktur IO_STATUS_BLOCK diatur ke jumlah byte yang ditulis. Jika tidak, anggota Informasi diatur ke nol.

Ketika IOCTL_VPCI_WRITE_BLOCK IOCTL dikeluarkan, driver fungsi fisik PCIe (PF) diberi tahu untuk menulis data ke blok konfigurasi VF yang ditentukan.

Catatan Sistem operasi mencadangkan dan mengelola sumber daya yang diperlukan untuk keberhasilan penyelesaian IOCTL ini.

Blok konfigurasi VF digunakan untuk komunikasi backchannel antara driver PCIe PF dan VF pada perangkat yang mendukung antarmuka SR-IOV. Driver PF mengalokasikan blok konfigurasi untuk setiap VF dalam blok yang tidak digunakan dari ruang konfigurasi PCI perangkat.

Segera setelah blok konfigurasi VF dialokasikan, data konfigurasi VF dapat ditukar dengan cara yang dilindungi antara driver berikut:

Driver VF, yang berjalan di sistem operasi tamu. Sistem operasi ini berjalan dalam partisi anak Hyper-V.
Driver PF, yang berjalan dalam sistem operasi manajemen.
Sistem operasi ini berjalan dalam partisi induk Hyper-V.

Penggunaan blok konfigurasi VF dan format data konfigurasinya ditentukan oleh vendor perangkat keras independen (IHV) perangkat. Data konfigurasi hanya digunakan oleh driver PF dan VF.

CatatanIOCTL IOCTL_VPCI_WRITE_BLOCK menawarkan alternatif asinkron untuk rutinitas WriteVfConfigBlock .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows Server 2012 dan versi Windows yang lebih baru.
Header	vpci.h (termasuk Wdm.h)
IRQL	DISPATCH_LEVEL