ScsiPortNotification-Funktion (srb.h)

Artikel
02/07/2025

Die ScsiPortNotification Routine informiert den betriebssystemspezifischen Porttreiber über bestimmte Ereignisse, z. B. wenn ein Miniporttreiber eine Anforderung abschließt oder bereit ist, einen anderen SRB zu starten, sowie wenn der Hostbusadapter (HBA) bestimmte SCSI-Fehlerbedingungen angibt, die während eines Vorgangs aufgetreten sind.

Anmerkung

Die SCSI-Porttreiber- und SCSI-Miniporttreibermodelle können in Zukunft geändert oder nicht verfügbar sein. Stattdessen empfehlen wir die Verwendung des Storport-Treibers und Storport Miniport Treibermodelle.

Syntax

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

Parameter

NotificationType

Gibt den Typ der Benachrichtigung an. Siehe Anmerkungen.

HwDeviceExtension

Zeiger auf die Hardwaregeräteerweiterung. Dies ist ein Speicherbereich pro HBA, den der Porttreiber im Namen des Miniporttreibers zuordnet und initialisiert. Miniporttreiber speichern in der Regel HBA-spezifische Informationen in dieser Erweiterung, z. B. den Zustand der HBA und die zugeordneten Zugriffsbereiche der HBA. Dieser Bereich steht dem Miniporttreiber im DeviceExtension->HwDeviceExtension Mitglied des Geräteobjekts der HBA unmittelbar nach dem Aufruf ScsiPortInitializezur Verfügung. Der Porttreiber gibt diesen Speicher frei, wenn es das Gerät entfernt.

...

Variadische Argumente für diese Routine. Die Anzahl und art der Argumente sind von NotificationTypeabhängig. Siehe Anmerkungen.

Rückgabewert

Nichts

Bemerkungen

Die ScsiPortNotification Routine verfügt über einen anderen Satz optionaler Parameter, die den einzelnen NotificationType-zugeordnet sind. Die Liste der möglichen Werte für NotificationType folgt zusammen mit Beschreibungen für jeden Wert.

NotificationType = RequestComplete

Gibt an, dass die angegebene Srb abgeschlossen ist. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification einen zusätzlichen Parameter: die Adresse des SRB. Nach dieser Benachrichtigung besitzt der betriebssystemspezifische Porttreiber die Anforderung. Der Miniporttreiber darf nicht auf die Srbzugreifen, und er darf die Srb- nicht an eine andere Routine übergeben (z. B. ScsiPortLogError).

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

Gibt an, dass der Miniporttreiber für eine andere Anforderung an ein Ziel bereit ist, das derzeit nicht ausgelastet ist. Diese Benachrichtigung sollte vom Miniporttreiber gesendet werden, sobald der Treiber für eine andere Anforderung bereit ist. In der Regel wird diese Benachrichtigung von der HwScsiStartIo Routine gesendet, manchmal aber von der HwScsiInterrupt (oder HwScsiEnableInterruptsCallback).
NotificationType = NextLuRequest

Gibt an, dass die HBA für eine andere Anforderung für die angegebene logische Einheit bereit ist. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification drei zusätzliche Parameter: (1) die Pfad-ID, (2) die Ziel-ID und (3) die logische Einheitennummer. Dieser Wert sollte nur verwendet werden, wenn die HBA mehrere Anforderungen in die Warteschlange stellen kann und die Funktion für die automatische Anforderung oder die kategorisierte Warteschlange unterstützen kann.

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

Gibt an, dass die HBA eine Zurücksetzung auf dem SCSI-Bus erkannt hat. Nach dieser Benachrichtigung ist der Miniporttreiber weiterhin für die Durchführung aktiver Anforderungen verantwortlich. Der SCSI-Porttreiber verwaltet alle erforderlichen Buszurücksetzungsverzögerungen.
NotificationType = CallEnableInterrupts

Gibt an, dass der Miniporttreiber den betriebssystemspezifischen Porttreiber benötigt, um die HwScsiEnableInterruptsCallback Routine des Miniporttreibers aufzurufen. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification einen zusätzlichen Parameter: den Einstiegspunkt für die HwScsiEnableInterruptsCallback-. Die HwScsiInterrupt--Routine des Miniporttreibers führt diesen Aufruf aus, nachdem Deaktivierung von Unterbrechungen auf der HBA deaktiviert wurde, um eine unterbrechungsgesteuerte E/A-Verarbeitung zu verzögern, wenn die HBA abfragen oder in der ISR angehalten werden muss. Während der Rückruf ausgeführt wird, bleiben Systemunterbrechungen aktiviert, aber die HwScsiInterrupt- Routine des Miniporttreibers wird nicht aufgerufen. Die HwScsiEnableInterruptsCallback- ist dafür verantwortlich, die verzögerte E/A-Verarbeitung abzuschließen und ScsiPortNot ification erneut mit CallDisableInterrupts und dem HwScsiDisableInterruptsCallback Einstiegspunkt des Miniporttreibers aufzurufen.

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

Gibt an, dass der Miniporttreiber den betriebssystemspezifischen Porttreiber benötigt, um die HwScsiDisableInterruptsCallback Routine des Miniporttreibers aufzurufen. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification einen zusätzlichen Parameter: den Einstiegspunkt für die HwScsiDisableInterruptsCallback-. Während dieser Rückruf ausgeführt wird, kann er nicht von einem Interrupt außer von einem Gerät mit höherer Priorität als der HBA vorgebeutet werden. In diesem Rückruf wird der Miniporttreiber auf der HBA erneut unterbrochen.

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

Gibt an, dass der Miniporttreiber den betriebssystemspezifischen Porttreiber benötigt, um die HwScsiTimer Routine des Miniporttreibers in der angeforderten Anzahl von Mikrosekunden aufzurufen. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification zwei zusätzliche Parameter: (1) den Einstiegspunkt für die HwScsiTimer Routine des Miniporttreibers und (2) ein MiniportTimerValue Intervall in Mikrosekunden. Beachten Sie, dass die Auflösung des Systemzeitgebers ungefähr 10 Millisekunden beträgt.

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

Gibt an, dass ein Zielgerät möglicherweise zu einem dynamischen Bus hinzugefügt oder daraus entfernt wurde. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification einen zusätzlichen Parameter: die Pfad-ID des Buss, auf dem die Änderung erkannt wurde. Nach dieser Benachrichtigung listet der Porttreiber den Bus durch Ausstellen von UNTERSUCHUNGsbefehlen erneut auf. Die Busenumeration ist zeitaufwändig und bindet den Bus, daher sollte ein Miniporttreiber diese Benachrichtigung nicht unnötig senden.

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

Gibt an, dass der Miniporttreiber ein Ereignis erkannt hat, für das mindestens ein WMI-Datenverbraucher registriert ist. Wenn dieser Wert festgelegt ist, erfordert ScsiPortNotification mindestens drei zusätzliche Argumente: (1) einen Zeiger auf eine WMI-Ereignisstruktur, (2) die Größe der Ereignisstruktur und (3) die Pfad-ID des Zielgeräts, wenn das Ereignis von einem Gerät stammt, oder 0xFF, wenn das Ereignis vom Adapter stammt. Wenn (3) eine Pfad-ID ist, erfordert ScsiPortNotification zwei zusätzliche Argumente: (4) die Ziel-ID und (5) die logische Einheitennummer (LUN) des Zielgeräts.

Syntax für 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
);
```
Syntax für PathId = 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIEvent
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PVOID                  WMIEvent,
  _In_opt_ UCHAR                  PathId               // 0xFF
);
```
NotificationType = WMIReregister-

Gibt an, dass der Miniporttreiber die Datenelemente oder die Anzahl der Instanzen eines bestimmten Datenblocks geändert hat, die zuvor durch Aufrufen von IoWMIRegistrationControlregistriert wurden. Wenn WMIReregister- festgelegt ist, erfordert ScsiPortNotification mindestens zwei zusätzliche Argumente: (1) die Pfad-ID des Zielgeräts, um das Gerät erneut zu registrieren, oder 0xFF, um den Adapter erneut zu registrieren. Wenn (1) eine Pfad-ID ist, erfordert ScsiPortNotification zwei zusätzliche Argumente: (2) die Ziel-ID und (3) die logische Einheitennummer (LUN) des Zielgeräts.

Syntax für 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
);
```
Syntax für PathId = 0xFF
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // WMIReregister
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ UCHAR                  PathId              // 0xFF
);
```

Jeder Miniporttreiber muss ScsiPortNotification zweimal für jeden Aufruf der HwScsiStart Io-Routine des Miniporttreibers mit einem SRB aufrufen, den der Miniporttreiber erfolgreich abgeschlossen hat. Zunächst ruft der Miniporttreiber ScsiPortNotification mit dem NotificationType- von NextRequest oder mit NextLuRequest- auf, wenn der Miniporttreiber markierte Warteschlangen oder mehrere Anforderungen pro LU unterstützt. Anschließend ruft der Miniporttreiber ScsiPortNotification mit dem NotificationType- von RequestComplete- und der Anforderung auf, dass er gerade erfüllt wurde.

Die HwScsiInterrupt Routine eines Miniporttreibers ruft höchstwahrscheinlich ScsiPortNotification- mit dem NotificationType-ResetDetectedauf.

Wenn ein HBA-Miniporttreiber mehr als eine Millisekundenverarbeitung von unterbrechungsgesteuerten E/A-Vorgängen verwenden muss, sollte die HwScsiInterrupt- Routine Unterbrechungen für die HBA deaktivieren und ScsiPortNotification mit CallEnableInterrupts- und einer vom Treiber bereitgestellten HwScsiEnableInterruptsCallback Routine aufrufen. Diese Routine ruft wiederum ScsiPortNotification mit CallDisableInterrupts und den entsprechenden Treiber bereitgestellten HwScsiDisableInterruptsCallbackauf.

Ein Miniporttreiber, der als WMI-Datenanbieter registriert ist, kann ScsiPortNotification- mit WMIEvent- aufrufen, um ein Ereignis zu veröffentlichen, für das er zuvor eine Aktivierungsanforderung empfangen hat. Der Porttreiber stellt das Ereignis im Unterbrechungsdatenbereich der Geräteerweiterung des Miniporttreibers für die spätere Verarbeitung bei einem niedrigeren IRQL in die Warteschlange. Da nur eine begrenzte Anzahl von Ereignissen gleichzeitig in die Warteschlange gestellt werden kann, sollte der Miniporttreiber WMIEvent- verwenden, um außergewöhnliche anstelle von Routinebedingungen zu signalisieren, und es sollte dem Porttreiber Zeit geben, um zwischen Bereitstellungen zurück zu DISPATCH_LEVEL zu gelangen, um zu verhindern, dass Ereignisse verloren gehen.