HW_BUILDIO fungsi panggilan balik (storport.h)

Artikel
08/07/2023

HwStorBuildIo rutin memproses SRB dengan akses tidak disinkronkan ke struktur data sistem bersama sebelum meneruskannya ke HwStorStartIo.

Sintaks

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Parameter

DeviceExtension

Penunjuk ke area penyimpanan driver miniport per HBA.

Srb

Pointer ke blok permintaan SCSI (SRB) yang akan diproses.

Nilai kembali

HwStorBuildIo mengembalikan TRUE untuk memberi tahu pemanggil bahwa StorPort harus memanggil rutinitas HwStorStartIo jika StorPort menganggap LUN siap menerima I/O. HwStorBuildIo mengembalikan FALSE untuk memberi tahu pemanggil bahwa SRB tidak boleh diteruskan ke HwStorStartIo. Dalam kasus seperti itu, driver miniport harus menyelesaikan SRB dengan memanggil StorPortNotification dengan jenis pemberitahuan RequestComplete. Ini dapat dilakukan di HwStorBuildIo atau di tempat lain di driver miniport, selama SRB selesai sebelum batas waktu yang ditentukan di bidang TimeOutValue dari struktur SRB.

Keterangan

Nama HwStorBuildIo hanyalah tempat penampung untuk fungsi miniport yang diarahkan oleh anggota HwBuildIo dalam struktur HW_INITIALIZATION_DATA . Prototipe aktual dari rutinitas ini didefinisikan dalam Storport.h sebagai berikut:

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Driver port memanggil rutinitas HwStorBuildIo di DISPATCH IRQL tanpa memegang kunci spin apa pun. Karena itu, alokasi memori menggunakan StorPortAllocatePool dan pengecualian timbal balik melalui StorPortAcquireSpinLock diizinkan di HwStorBuildIo. Dalam lingkungan multiprosesor, lebih dari satu HwStorBuildIo dapat aktif pada satu waktu, sehingga driver miniport diperlukan untuk menyinkronkan akses ke sumber daya sistem, yang mungkin bertentangan jika lebih dari satu instans HwStorBuildIo aktif pada waktu tertentu.

Dengan menyelesaikan aktivitas penyiapan I/O yang memakan waktu di HwStorBuildIo alih-alih di HwStorStartIo, driver miniport memungkinkan konkurensi I/O yang lebih besar dan oleh karena itu meningkatkan throughput I/O. Untuk performa tertinggi, driver miniport diharapkan untuk melakukan praprosem sebanyak mungkin di HwStorBuildIo sehingga dapat mengirim permintaan ke HBA melalui HwStorStartIo dalam waktu sesingkat mungkin. Data dan status yang telah diolah sebelumnya dapat disimpan dalam struktur DeviceExtension atau SrbExtension . Hanya modifikasi pada bagian unik DeviceExtension yang harus terjadi karena tidak ada kunci yang ditahan. HwStorBuildIo dan HwStorStartIo menerima jenis fungsi Srb berikut:

SRB_FUNCTION_EXECUTE_SCSI: Mengirim CDB ke bus/target/lun yang ditentukan.
- Srb-DataTransferLength> berlaku untuk semua Cdbs.
- Srb-DataBuffer> adalah NULL untuk permintaan baca dan tulis. Untuk mengakses data terkait, gunakan StorPortGetScatterGatherList (untuk transfer Dma) atau StorPortGetSystemAddress (untuk I/O yang dikontrol program) untuk mendapatkan daftar Scatter Gather atau alamat virtual buffer. Untuk permintaan lain, Srb-Databuffer> menunjuk ke data yang terkait dengan Srb.
- Srb-PathId> valid dan mewakili pathid yang diberikan kepada Storport di StorPortNotification (BusChange). Penulis driver miniport perlu menggunakan pathid sebagai indeks ke dalam tabel bus dalam miniport.
- Srb-TargetId> dan Srb-Lun> valid.
SRB_FUNCTION_IO_CONTROL: Miniport ditentukan.
- Srb-DataTransferLength> dan Srb-DataBuffer> valid jika diatur oleh pemohon.
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.
SRB_FUNCTION_RESET_LOGICAL_UNIT: Reset unit logis yang ditentukan (jika perangkat mampu).
- Srb-DataTransferLength> dan Srb-DataBuffer> tidak valid.
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.
SRB_FUNCTION_RESET_DEVICE: Reset Target Scsi yang ditentukan.
- Srb-DataTransferLength> dan Srb-DataBuffer>, Srb-Lun> tidak valid.
- Srb-PathId> dan Srb-TargetId> valid.
SRB_FUNCTION_RESET_BUS: Reset semua target pada bus SCSI yang ditentukan.
- Hanya Srb-PathId> yang valid.
SRB_FUNCTION_FLUSH: Menginstruksikan driver miniport untuk membersihkan semua data yang di-cache.
- Hanya dilakukan oleh driver miniport jika mengatur CachesData == TRUE dalam struktur PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.
SRB_FUNCTION_SHUTDOWN: Menginstruksikan driver miniport untuk membersihkan semua persiapan data yang di-cache untuk dimatikan.
- Hanya dilakukan oleh driver miniport jika mengatur CachesData == TRUE dalam struktur PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.
SRB_FUNCTION_DUMP_POINTERS: Menyediakan informasi yang diperlukan bagi pengemudi miniport untuk mendukung crash dump dan hibernasi.
- Permintaan ini dikirim ke driver miniport virtual Storport yang digunakan untuk mengontrol disk yang menyimpan data crash dump. Dimulai dengan Windows 8, driver miniport non-virtual dapat secara opsional menerima permintaan ini.
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.
SRB_FUNCTION_FREE_DUMP_POINTERS: Dimulai dengan Windows 8, permintaan ini dikirim ke miniport ke sumber daya gratis yang dialokasikan selama permintaan SRB_FUNCTION_DUMP_POINTERS.
- Srb-PathId>, Srb-TargetId>, dan Srb-Lun> semuanya valid.

Mulai dari Windows 8, parameter Srb dapat menunjuk ke SCSI_REQUEST_BLOCK atau STORAGE_REQUEST_BLOCK. Jika pengidentifikasi fungsi di bidang FungsiSrbSRB_FUNCTION_STORAGE_REQUEST_BLOCK, SRB adalah struktur permintaan STORAGE_REQUEST_BLOCK .

Untuk informasi selengkapnya tentang apa yang dapat dan tidak dapat Anda lakukan dengan aman dalam rutinitas driver miniport ini, lihat Rutinitas HwStorBuildIo yang Tidak Disinkronkan.

Contoh

Untuk menentukan fungsi panggilan balik HwStorBuildIo , 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 rutinitas panggilan balik HwStorBuildIo yang bernama MyHwBuildIo, gunakan jenis HW_BUILDIO seperti yang ditunjukkan dalam contoh kode ini:

HW_BUILDIO MyHwBuildIo;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

Jenis fungsi HW_BUILDIO didefinisikan dalam file header Storport.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 HW_BUILDIO dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi Menggunakan Jenis Peran Fungsi untuk Driver Storport. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.