HW_STARTIO fungsi panggilan balik (storport.h)

Artikel
02/26/2024

Driver Storport memanggil rutinitas HwStorStartIo satu kali untuk setiap permintaan I/O yang masuk.

Sintaks

HW_STARTIO HwStartio;

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

Parameter

DeviceExtension

Pointer ke area penyimpanan driver miniport per HBA.

Srb

Penunjuk ke blok permintaan SCSI yang akan dimulai.

Mengembalikan nilai

HwStorStartIo mengembalikan TRUE jika permintaan berhasil dimulai. Jika tidak, ia mengembalikan FALSE.

Keterangan

HwStorStartIo memulai operasi I/O. StorPort dirancang untuk menggunakan data pribadi miniport yang disiapkan di HwStorBuildIo dan disimpan di DeviceExtension atau Srb-SrbExtension>. Karena HwStorBuildIo dipanggil tanpa kunci putaran, performa driver terbaik dicapai dengan menyiapkan data sebanyak mungkin di HwStorBuildIo.

Storport memanggil HwStorStartIo dengan cara berikut:

Untuk driver miniport non-virtual penyimpanan, tergantung pada nilai SynchronizationModel yang diatur dalam PORT_CONFIGURATION_INFORMATION, Storport selalu memanggil HwStorStartIo pada IRQL yang sama dan menggunakan kunci putar internal untuk memastikan bahwa permintaan I/O dimulai secara berurutan. IRQL adalah DISPATCH_LEVEL (mode dupleks penuh) atau DIRQL (mode setengah dupleks).

Saat menangani I/O dalam mode setengah dupleks, rutinitas HwStorStartIo tidak harus memperoleh kunci putarnya sendiri. Selain itu, alokasi memori menggunakan StorPortAllocatePool dan pengecualian timbal balik melalui StorPortAcquireSpinLock tidak diizinkan dalam rutinitas HwStorStartIo . Dalam mode dupleks penuh, StorPortAllocatePool dan StorPortAcquireSpinLock dapat digunakan dalam rutinitas HwStorStartIo .

Jika miniport non-virtual mendukung pengoptimalan saluran bersamaan (STOR_PERF_CONCURRENT_CHANNELS diatur oleh StorPortInitializePerfOpts), beberapa panggilan ke HwStorStartIo secara bersamaan dimungkinkan. Dalam hal ini, miniport perlu memastikan bahwa sumber daya bersama dilindungi oleh kunci. Dengan pengoptimalan performa ini, Storport tidak akan memperoleh kunci StartIo sebelum memanggil HwStorStartIo dan miniport harus menyediakan kuncinya sendiri jika diperlukan.
Untuk driver miniport virtual penyimpanan, Storport memanggil HwStorStartIo di IRQL <= DISPATCH_LEVEL dan tidak menggunakan kunci putar internal. Rutinitas HwStorStartIo dapat memperoleh kunci putarnya sendiri dengan memanggil StorPortAcquireSpinLock. Selain itu, panggilan ke StorPortAllocatePool diizinkan dalam rutinitas HwStorStartIo dari driver miniport virtual penyimpanan.

SRB diharapkan selesai ketika status SCSI diterima. Ketika driver Storport menyelesaikan SRB dengan memanggil StorPortNotification dengan NotificationType dari RequestComplete, SRB diharapkan mengembalikan salah satu nilai berikut di bidang SrbStatus dari Srb:

SRB_STATUS_SUCCESS
- Menunjukkan bahwa Srb dikirim dan status SCSI (mungkin dengan data) dikembalikan.
- Storport mengembalikan data dan status ke pemanggil.
- Tindakan miniport tidak ada, kecuali untuk menyelesaikan permintaan dengan menggunakan StorPortNotification untuk RequestComplete, mungkin dari HwStorDpcRoutine.
SRB_STATUS_BUSY
- Menunjukkan bahwa ada masalah sementara dengan pengiriman Srb (misalnya, register adapter atau buffer sibuk).
- Storport membuang ekstensi Srb asli yang dibidik Srb-SrbExtension> dan mengeluarkan yang baru. Storport mengirimkan Srb asli dengan ekstensi Srb yang baru diterbitkan dalam panggilan berikutnya ke HwStorBuildIo dan HwStorStartIo. Semua data dalam ekstensi Srb asli akan hilang.
- Miniport tidak boleh memperbarui DataTransferLength Srb.
- Karena ekstensi Srb baru dikeluarkan, miniport harus memastikan bahwa ekstensi tersebut tidak pernah mengeluarkan SRB_STATUS_BUSY di tengah transaksi SCSI. Setelah transaksi dimulai, transaksi harus diselesaikan atau dibatalkan. Status sibuk perangkat keras selama transaksi harus ditangani oleh driver miniport.

Nama HwStorStartIo adalah tempat penampung untuk menggambarkan rutinitas miniport yang diatur dalam anggota HwStartIo dari struktur HW_INITIALIZATION_DATA . Struktur ini diteruskan dalam parameter HwInitializationData dari StorPortInitialize. Prototipe aktual dari rutinitas ini didefinisikan dalam Storport.h sebagai berikut:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

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 .

Contoh

Untuk menentukan rutinitas panggilan balik HwStorStartIo , Anda harus terlebih dahulu memberikan deklarasi fungsi yang diperlukan Static Driver Verifier (SDV) dan alat verifikasi lainnya, seperti yang ditunjukkan dalam contoh kode berikut:

Untuk menentukan fungsi panggilan balik HwStorStartIo , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. 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 HwStorStartIo yang diberi nama MyHwStartIo, gunakan jenis HW_STARTIO dan terapkan rutinitas panggilan balik Anda sebagai berikut:

HW_STARTIO MyHwStartIo

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

Jenis fungsi HW_STARTIO ditentukan dalam file header Storport.h . Untuk mengidentifikasi kesalahan dengan lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan ke _Use_decl_annotations_ annotation definisi fungsi Anda. _Use_decl_annotations_ annotation memastikan bahwa anotasi yang diterapkan ke jenis fungsi HW_STARTIO 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.