Funzione SCSIPortNotification (srb.h)

Articolo
02/26/2024

La routine SCSIPortNotification informa il driver di porta specifico del sistema operativo di determinati eventi, ad esempio quando un driver miniport completa una richiesta o è pronto per avviare un'altra SRB, nonché quando l'adattatore del bus host (HBA) indica determinate condizioni di errore SCSI che si sono verificate durante un'operazione.

Nota

I modelli di driver di porta SCSI e miniport SCSI possono essere modificati o non disponibili in futuro. È invece consigliabile usare i modelli di driver Storport e Miniport Storport.

Sintassi

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

Parametri

NotificationType

Specifica il tipo di notifica. Vedere la sezione Osservazioni.

HwDeviceExtension

Puntatore all'estensione del dispositivo hardware. Si tratta di un'area di archiviazione per HBA che il driver di porta alloca e inizializza per conto del driver miniport. I driver miniport in genere archiviano informazioni specifiche di HBA in questa estensione, ad esempio lo stato dell'HBA e gli intervalli di accesso mappati di HBA. Questa area è disponibile per il driver miniport nel membro DeviceExtension-HwDeviceExtension> dell'oggetto dispositivo HBA immediatamente dopo che il driver miniport chiama SCSIPortInitialize. Il driver di porta libera questa memoria quando rimuove il dispositivo.

...

Argomenti variadici per questa routine. Il numero e il tipo di argomenti dipendono da NotificationType. Vedere la sezione Osservazioni.

Valore restituito

nessuno

Osservazioni

La routine SCSIPortNotification ha un set diverso di parametri facoltativi associati a ogni tipo di notifica. L'elenco dei valori possibili per NotificationType segue, insieme alle descrizioni per ogni valore.

NotificationType = RequestComplete

Indica che il valore Srb specificato è terminato. Se questo valore è impostato, SCSIPortNotification richiede un parametro aggiuntivo: l'indirizzo della SRB. Dopo questa notifica, il driver di porta specifico del sistema operativo possiede la richiesta. Il driver miniport non deve accedere a Srb e non deve passare la Srb a un'altra routine,ad esempio SCSIPortLogError.

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

Indica che il driver miniport è pronto per un'altra richiesta a una destinazione che non è attualmente occupato. Questa notifica deve essere inviata dal driver miniport non appena il driver è pronto per un'altra richiesta. In genere, questa notifica viene inviata dalla routine HwScsiStartIo ma, a volte, dalla routine HwScsiInterrupt (o HwScsiEnableInterruptsCallback).
NotificationType = NextLuRequest

Indica che l'HBA è pronto per un'altra richiesta per l'unità logica specificata. Se questo valore è impostato, SCSIPortNotification richiede tre parametri aggiuntivi: (1) l'ID percorso, (2) l'ID di destinazione e (3) il numero di unità logica. Questo valore deve essere usato solo se l'HBA può accodare più richieste e supportare l'accodamento automatico o l'accodamento con tag.

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

Indica che l'HBA ha rilevato una reimpostazione del bus SCSI. Dopo questa notifica, il driver miniport è ancora responsabile del completamento di eventuali richieste attive. Il driver della porta SCSI gestirà tutti i ritardi necessari per la reimpostazione del bus.
NotificationType = CallEnableInterrupts

Indica che il driver miniport richiede al driver di porta specifico del sistema operativo di chiamare la routine HwScsiEnableInterruptsCallback del driver miniport. Se questo valore è impostato, SCSIPortNotification richiede un parametro aggiuntivo: il punto di ingresso per HwScsiEnableInterruptsCallback. La routine HwScsiInterrupt del driver miniport effettua questa chiamata dopo la disabilitazione degli interruzioni nell'HBA, per rinviare un'elaborazione di I/O basata su interruzioni se l'HBA richiede il polling o lo stallo nell'ISR. Durante l'esecuzione del callback, gli interruzioni di sistema rimangono abilitati, ma la routine HwSCSIInterrupt del driver miniport non verrà chiamata. HwScsiEnableInterruptsCallback è responsabile del completamento dell'elaborazione di I/O posticipata e della chiamata di nuovo a SCSIPortNotification con CallDisableInterrupts e al punto di ingresso HwScsiDisruptsCallback del driver miniport.

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

Indica che il driver miniport richiede il driver di porta specifico del sistema operativo per chiamare la routine HwScsiDisableInterruptsCallback del driver miniport. Se questo valore è impostato, SCSIPortNotification richiede un parametro aggiuntivo: il punto di ingresso per HwScsiDisableInterruptsCallback. Durante l'esecuzione di questo callback, non può essere preceduto da un interruzione tranne da un dispositivo con una priorità superiore rispetto all'HBA. In questo callback, il driver miniport reenables interrompe l'hbA.

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

Indica che il driver miniport richiede al driver di porta specifico del sistema operativo di chiamare la routine HwScsiTimer del driver miniport nel numero richiesto di microsecondi. Se questo valore è impostato, SCSIPortNotification richiede due parametri aggiuntivi: (1) il punto di ingresso per la routine HwScsiTimer del driver miniport e (2) un intervallo MiniportTimerValue , in microsecondi. Si noti che la risoluzione del timer di sistema è di circa 10 millisecondi.

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

Indica che un dispositivo di destinazione potrebbe essere stato aggiunto o rimosso da un bus dinamico. Se questo valore è impostato, SCSIPortNotification richiede un parametro aggiuntivo: l'ID percorso del bus in cui è stata rilevata la modifica. Dopo questa notifica, il driver della porta rinumera il bus emettendo comandi INQUIRY. L'enumerazione del bus richiede tempo e collega il bus, quindi un conducente miniport non deve inviare questa notifica inutilmente.

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

Indica che il driver miniport ha rilevato un evento per il quale viene registrato uno o più consumer di dati WMI. Se questo valore è impostato, SCSIPortNotification richiede almeno tre argomenti aggiuntivi: (1) un puntatore a una struttura di eventi WMI, (2) le dimensioni della struttura evento e (3) l'ID percorso del dispositivo di destinazione se l'evento ha origine da un dispositivo o 0xFF se l'evento ha origine dall'adattatore. Se (3) è un ID percorso, SCSIPortNotification richiede due argomenti aggiuntivi: (4) l'ID di destinazione e (5) il numero di unità logica (LUN) del dispositivo di destinazione.

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

Indica che il driver miniport ha modificato gli elementi di dati o il numero di istanze di un determinato blocco di dati registrato in precedenza chiamando IoWMIRegistrationControl. Se WMIReregister è impostato, SCSIPortNotification richiede almeno due argomenti aggiuntivi: (1) l'ID percorso del dispositivo di destinazione per registrare nuovamente il dispositivo o 0xFF per registrare nuovamente l'adapter. Se (1) è un ID percorso, SCSIPortNotification richiede due argomenti aggiuntivi: (2) l'ID di destinazione e (3) il numero di unità logica (LUN) del dispositivo di destinazione.

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

Ogni driver miniport deve chiamare due volte SCSIPortNotification per ogni chiamata alla routine HwScsiStartIo del driver miniport con una SRB completata correttamente dal driver miniport. Prima di tutto, il driver miniport chiama SCSIPortNotification con il tipo di notifica di NextRequest o con NextLuRequest se il driver miniport supporta accodamento con tag o più richieste per LU. Il driver miniport chiama quindi SCSIPortNotification con NotificationType of RequestComplete e la richiesta appena soddisfatta.

La routine HwScsiInterrupt di un driver miniport è più probabile chiamare SCSIPortNotification con Il tipo di notifica di ResetDetected.

Se un driver HBA richiede che il driver miniport usi più di un millisecondo di operazioni di I/O basate su interruzioni di elaborazione, la routine HwSCSIInterrupt deve disabilitare gli interruzioni nell'HBA e chiamare SCSIPortNotification con CallEnableInterrupts e una routine HwSCSIEnableInterruptsCallback. Questa routine, a sua volta, chiama SCSIPortNotification con CallDisableInterrupts e il driver fornito corrispondente HwSCSIDisruptsCallback.

Un driver miniport registrato come provider di dati WMI può chiamare SCSIPortNotification con WMIEvent per pubblicare un evento per cui ha ricevuto in precedenza una richiesta di abilitazione. Il driver della porta accoda l'evento nell'area dati di interruzione dell'estensione del dispositivo del driver miniport per l'elaborazione successiva in un irQL inferiore. Poiché solo un numero limitato di eventi può essere accodato alla volta, il driver miniport deve usare WMIEvent per segnalare condizioni eccezionali anziché di routine e deve dare il tempo del driver della porta per tornare a DISPATCH_LEVEL tra le registrazioni, per evitare che gli eventi vengano persi.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	srb.h (include Miniport.h, SCSI.h)
Libreria	Scsiport.lib; Storport.lib
IRQL	(Vedere la sezione Osservazioni)

Vedi anche

HwScsiDisableInterruptsCallback

HwScsiEnableInterruptsCallback

HwScsiTimer

IoWMIRegistrationControl

SCSIPortCompleteRequest