Fungsi ScsiPortNotification (srb.h)

Artikel
03/08/2023

Rutinitas ScsiPortNotification menginformasikan driver port khusus sistem operasi dari peristiwa tertentu, seperti ketika driver miniport menyelesaikan permintaan atau siap untuk memulai SRB lain, serta ketika adaptor bus host (HBA) menunjukkan kondisi kesalahan SCSI tertentu yang terjadi selama operasi.

Catatan

Driver port SCSI dan model driver miniport SCSI dapat diubah atau tidak tersedia di masa mendatang. Sebagai gantinya, sebaiknya gunakan driver Storport dan model driver miniport Storport .

Sintaks

SCSIPORT_API VOID ScsiPortNotification(
  SCSI_NOTIFICATION_TYPE NotificationType,
  PVOID                  HwDeviceExtension,
  ...                    
);

Parameter

NotificationType

Menentukan jenis pemberitahuan. Lihat Keterangan.

HwDeviceExtension

Arahkan ke ekstensi perangkat keras. Ini adalah area penyimpanan per HBA yang dialokasikan dan diinisialisasi driver port atas nama driver miniport. Driver Miniport biasanya menyimpan informasi khusus HBA dalam ekstensi ini, seperti status HBA dan rentang akses HBA yang dipetakan. Area ini tersedia untuk driver miniport di deviceExtension-HwDeviceExtension> anggota objek perangkat HBA segera setelah driver miniport memanggil ScsiPortInitialize. Pengandar porta membebaskan memori ini ketika melepas perangkat.

...

Argumen variadik untuk rutinitas ini. Jumlah dan jenis argumen bergantung pada NotificationType. Lihat Keterangan.

Nilai kembali

Tidak ada

Keterangan

Rutinitas ScsiPortNotification memiliki serangkaian parameter opsional yang berbeda yang terkait dengan setiap NotificationType. Daftar nilai yang mungkin untuk NotificationType mengikuti, bersama dengan deskripsi untuk setiap nilai.

NotificationType = RequestComplete

Menunjukkan bahwa Srb yang diberikan telah selesai. Jika nilai ini diatur, ScsiPortNotification memerlukan satu parameter tambahan: alamat SRB. Setelah pemberitahuan ini, driver port khusus sistem operasi memiliki permintaan. Driver miniport tidak boleh mengakses Srb, dan tidak boleh meneruskan Srb ke rutinitas lain (seperti ScsiPortLogError).

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // RequestComplete
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PSCSI_REQUEST_BLOCK    Srb
);
```
NotificationType = NextRequest

Menunjukkan driver miniport siap untuk permintaan lain ke target yang saat ini tidak sibuk. Pemberitahuan ini harus dikirim oleh driver miniport segera setelah driver siap untuk permintaan lain. Biasanya, pemberitahuan ini dikirim dari rutinitas HwScsiStartIo tetapi, kadang-kadang, dari rutinitas HwScsiInterrupt (atau HwScsiEnableInterruptsCallback).
NotificationType = NextLuRequest

Menunjukkan bahwa HBA siap untuk permintaan lain untuk unit logis yang ditentukan. Jika nilai ini ditetapkan, ScsiPortNotification memerlukan tiga parameter tambahan: (1) ID jalur, (2) ID target, dan (3) nomor unit logis. Nilai ini harus digunakan hanya jika HBA dapat mengantrekan beberapa permintaan dan mendukung pengertian permintaan otomatis atau antrean yang diberi tag.

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // NextLuRequest
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_                        PathId,
  _In_opt_                        TargetId,
  _In_opt_                        Lun
);
```
NotificationType = ResetDetected

Menunjukkan bahwa HBA telah mendeteksi reset pada bus SCSI. Setelah pemberitahuan ini, driver miniport masih bertanggung jawab untuk menyelesaikan permintaan aktif apa pun. Driver port SCSI akan mengelola semua penundaan pengaturan ulang bus yang diperlukan.
NotificationType = CallEnableInterrupts

Menunjukkan bahwa driver miniport memerlukan driver port khusus sistem operasi untuk memanggil rutinitas HwScsiEnableInterruptsCallback driver miniport. Jika nilai ini diatur, ScsiPortNotification memerlukan parameter tambahan: titik masuk untuk HwScsiEnableInterruptsCallback. Rutinitas HwScsiInterrupt driver miniport melakukan panggilan ini setelah menonaktifkan gangguan pada HBA, untuk menunda beberapa pemrosesan I/O yang digerakkan oleh interupsi jika HBA memerlukan polling atau mengulur waktu di ISR. Saat panggilan balik berjalan, gangguan sistem tetap diaktifkan tetapi rutinitas HwScsiInterrupt driver miniport tidak akan dipanggil. HwScsiEnableInterruptsCallback bertanggung jawab untuk menyelesaikan pemrosesan I/O yang ditangguhkan dan untuk memanggil ScsiPortNotification lagi dengan CallDisableInterrupts dan titik masuk HwScsiDisableInterruptsCallback driver miniport.

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,           // CallEnableInterrupts
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
);
```
NotificationType = CallDisableInterrupts

Menunjukkan bahwa driver miniport memerlukan driver port khusus sistem operasi untuk memanggil rutinitas HwScsiDisableInterruptsCallback driver miniport. Jika nilai ini diatur, ScsiPortNotification memerlukan parameter tambahan: titik masuk untuk HwScsiDisableInterruptsCallback. Meskipun panggilan balik ini berjalan, panggilan balik ini tidak dapat didahulukan oleh gangguan kecuali dari perangkat dengan gangguan prioritas yang lebih tinggi daripada HBA. Dalam panggilan balik ini, driver miniport dapat mengaktifkan kembali gangguan pada HBA.

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,          // CallDisableInterrupts
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
);
```
NotificationType = RequestTimerCall

Menunjukkan bahwa driver miniport memerlukan driver port khusus sistem operasi untuk memanggil rutinitas HwScsiTimer driver miniport dalam jumlah mikrosekon yang diminta. Jika nilai ini ditetapkan, ScsiPortNotification memerlukan dua parameter tambahan: (1) titik masuk untuk rutinitas HwScsiTimer driver miniport, dan (2) interval MiniportTimerValue , dalam mikrodetik. Perhatikan bahwa resolusi timer sistem adalah sekitar 10 milidetik.

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // RequestTimerCall
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_TIMER              HwScsiTimer,
  _In_opt_ ULONG                  MiniportTimerValue
);
```
NotificationType = BusChangeDetected

Menunjukkan bahwa perangkat target mungkin telah ditambahkan atau dihapus dari bus dinamis. Jika nilai ini diatur, ScsiPortNotification memerlukan parameter tambahan: ID jalur bus tempat perubahan terdeteksi. Setelah pemberitahuan ini, driver port menghitung ulang bus dengan mengeluarkan perintah INQUIRY. Enumerasi bus memakan waktu dan mengikat bus, sehingga pengemudi miniport tidak boleh mengirim pemberitahuan ini tidak perlu.

Sintaks:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // BusChangeDetected
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ UCHAR                  PathId
);
```
NotificationType = WMIEvent

Menunjukkan bahwa driver miniport telah mendeteksi peristiwa di mana satu atau beberapa konsumen data WMI terdaftar. Jika nilai ini diatur, ScsiPortNotification memerlukan setidaknya tiga argumen tambahan: (1) penunjuk ke struktur peristiwa WMI, (2) ukuran struktur peristiwa, dan (3) ID jalur perangkat target jika peristiwa berasal dari perangkat, atau 0xFF jika peristiwa berasal dari adaptor. Jika (3) adalah ID jalur, ScsiPortNotification memerlukan dua argumen tambahan: (4) ID target, dan (5) nomor unit logis (LUN) dari perangkat target.

Sintaks untuk PathId != 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIEvent
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PVOID                  WMIEvent,
  _In_opt_ UCHAR                  PathId,              // != 0xFF
  _In_opt_ UCHAR                  TargetId,
  _In_opt_ UCHAR                  Lun
);
```
Sintaks untuk PathId = 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIEvent
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PVOID                  WMIEvent,
  _In_opt_ UCHAR                  PathId               // 0xFF
);
```
NotificationType = WMIReregister

Menunjukkan bahwa driver miniport telah mengubah item data atau jumlah instans blok data tertentu yang sebelumnya terdaftar dengan memanggil IoWMIRegistrationControl. Jika WMIRegister diatur, ScsiPortNotification memerlukan setidaknya dua argumen tambahan: (1) ID jalur perangkat target untuk mendaftarkan ulang perangkat tersebut, atau 0xFF untuk mendaftarkan ulang adaptor. Jika (1) adalah ID jalur, ScsiPortNotification memerlukan dua argumen tambahan: (2) ID target, dan (3) nomor unit logis (LUN) dari perangkat target.

Sintaks untuk PathId != 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIReregister
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ UCHAR                  PathId,             // != 0xFF
  _In_opt_ UCHAR                  TargetId,
  _In_opt_ UCHAR                  Lun
);
```
Sintaks untuk PathId = 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // WMIReregister
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ UCHAR                  PathId              // 0xFF
);
```

Setiap driver miniport harus memanggil ScsiPortNotification dua kali untuk setiap panggilan ke rutinitas HwScsiStartIo driver miniport dengan SRB yang berhasil diselesaikan driver miniport. Pertama, driver miniport memanggil ScsiPortNotification dengan NotificationType of NextRequest atau dengan NextLuRequest jika driver miniport mendukung antrean bertag atau beberapa permintaan per LU. Kemudian, driver miniport memanggil ScsiPortNotification dengan NotificationType dari RequestComplete dan permintaan yang baru saja dipenuhi.

Rutinitas HwScsiInterrupt driver miniport kemungkinan besar akan memanggil ScsiPortNotification dengan NotificationType of ResetDetected.

Jika HBA mengharuskan driver miniport untuk menggunakan lebih dari operasi I/O berbasis interupsi pemrosesan milidetik, rutinitas HwScsiInterrupt-nya harus menonaktifkan gangguan pada HBA dan memanggil ScsiPortNotification dengan CallEnableInterrupts dan rutin HwScsiEnableInterruptsCallback yang disediakan driver. Rutinitas ini, pada gilirannya, memanggil ScsiPortNotification dengan CallDisableInterrupts dan HwScsiDisableInterruptsCallback yang disediakan driver yang sesuai.

Driver miniport yang terdaftar sebagai penyedia data WMI dapat memanggil ScsiPortNotification dengan WMIEvent untuk memposting peristiwa yang sebelumnya telah menerima permintaan pengaktifan. Driver port mengantre peristiwa di area data interupsi ekstensi perangkat driver miniport untuk diproses nanti pada IRQL yang lebih rendah. Karena hanya sejumlah peristiwa terbatas yang dapat diantrekan pada satu waktu, driver miniport harus menggunakan WMIEvent untuk memberi sinyal yang luar biasa daripada kondisi rutin, dan itu harus memberikan waktu driver port untuk kembali ke DISPATCH_LEVEL antara posting, untuk mencegah peristiwa hilang.