ScsiPortNotification 函式 (srb.h)

發行項
02/26/2024

ScsiPortNotification 例程會通知操作系統特定的埠驅動程式特定事件，例如當迷你埠驅動程式完成要求或準備好啟動另一個 SRB，以及主機總線適配卡 (HBA 時，) 表示作業期間發生的特定 SCSI 錯誤狀況。

注意

未來可能會變更或無法使用 SCSI 埠驅動程式和 SCSI 迷你埠驅動程式模型。相反地，我們建議使用 Storport 驅動程式和 Storport 迷你埠驅動程式模型。

語法

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

參數

NotificationType

指定通知的類型。請參閱＜備註＞。

HwDeviceExtension

硬體裝置擴充功能的指標。這是埠驅動程式代表迷你埠驅動程式配置和初始化的每個 HBA 儲存區域。迷你埠驅動程式通常會在此延伸模組中儲存 HBA 特定資訊，例如 HBA 的狀態和 HBA 的對應存取範圍。此區域可在迷你埠驅動程式呼叫 ScsiPortInitialize 之後，立即提供給 HBA 裝置物件的 DeviceExtension-HwDeviceExtension> 成員。埠驅動程式會在移除裝置時釋放此記憶體。

...

這個例程的 Variadic 自變數。自變數的數目和類型取決於 NotificationType。請參閱＜備註＞。

傳回值

無

備註

ScsiPortNotification 例程有一組與每個 NotificationType 相關聯的不同選擇性參數。 NotificationType 的可能值清單如下，以及每個值的描述。

NotificationType = RequestComplete

表示指定的 Srb 已完成。如果設定此值， ScsiPortNotification 需要一個額外的參數：SRB 的位址。此通知之後，操作系統特定的埠驅動程式會擁有要求。迷你埠驅動程式不得存取 Srb，而且不能將 Srb 傳遞給另一個例程 (，例如 ScsiPortLogError) 。

語法：
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // RequestComplete
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PSCSI_REQUEST_BLOCK    Srb
);
```
NotificationType = NextRequest

表示迷你埠驅動程式已準備好對目前未忙碌的目標提出另一個要求。當驅動程式準備好進行另一個要求時，應該立即由迷你埠驅動程序傳送此通知。通常，此通知會從 HwScsiStartIo 例程傳送，但有時來自 HwScsiInterrupt (或 HwScsiEnableInterruptsCallback) 例程。
NotificationType = NextLuRequest

表示 HBA 已準備好用於指定之邏輯單元的另一個要求。如果設定此值， ScsiPortNotification 需要三個額外的參數： (1) 路徑標識碼、 (2) 目標標識符， (3) 邏輯單元編號。只有在 HBA 可以佇列多個要求並支援自動要求感知或標記的佇列時，才應該使用此值。

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

指出 HBA 已在 SCSI 總線上偵測到重設。此通知之後，迷你埠驅動程式仍負責完成任何作用中的要求。 SCSI 埠驅動程式會管理所有必要的總線重設延遲。
NotificationType = CallEnableInterrupts

指出迷你埠驅動程式需要操作系統特定的埠驅動程式，才能呼叫迷你埠驅動程式的 HwScsiEnableInterruptsCallback 例程。如果設定此值， ScsiPortNotification 需要額外的參數： HwScsiEnableInterruptsCallback 的進入點。迷你埠驅動程式的 HwScsiInterrupt 例程會在停用 HBA 上的中斷之後進行此呼叫，以在 HBA 需要輪詢或停止 ISR 時延遲某些中斷驅動 I/O 處理。當回呼執行時，系統中斷仍會保持啟用，但不會呼叫迷你埠驅動程式的 HwScsiInterrupt 例程。 HwScsiEnableInterruptsCallback 負責完成延遲的 I/O 處理，並使用 CallDisableInterrupts 和 miniport 驅動程式的 HwScsiDisableInterruptsCallback 進入點再次呼叫 ScsiPortNotification。

語法：
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,           // CallEnableInterrupts
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
);
```
NotificationType = CallDisableInterrupts

表示迷你埠驅動程式需要操作系統特定的埠驅動程式來呼叫迷你埠驅動程式的 HwScsiDisableInterruptsCallback 例程。如果設定此值， ScsiPortNotification 需要額外的參數： HwScsiDisableInterruptsCallback 的進入點。雖然此回呼執行，但除了優先順序高於 HBA 的裝置外，無法先占中斷。在此回呼中，迷你埠驅動程式會在 HBA 上重新啟用中斷。

語法：
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,          // CallDisableInterrupts
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
);
```
NotificationType = RequestTimerCall

指出迷你埠驅動程式需要操作系統特定的埠驅動程式，才能在要求的微秒數中呼叫迷你埠驅動程式的 HwScsiTimer 例程。如果設定此值， ScsiPortNotification 需要兩個額外的參數： (1) 迷你埠驅動程式 HwScsiTimer 例程的進入點，並以微秒為單位 (2) MiniportTimerValue 間隔。請注意，系統定時器的解析度大約是 10 毫秒。

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

指出目標裝置可能已從動態總線新增或移除。如果設定這個值， ScsiPortNotification 需要額外的參數：偵測到變更的總線路徑標識符。在此通知之後，埠驅動程式會發出 INQUIRY 命令，以繼續匯流線。總線列舉相當耗時並系結總線，因此迷你埠驅動程式不應該不必要地傳送此通知。

語法：
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // BusChangeDetected
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ UCHAR                  PathId
);
```

NotificationType = WMIEvent

指出迷你埠驅動程式偵測到已註冊一或多個 WMI 數據取用者的事件。如果設定這個值， ScsiPortNotification 至少需要三個額外的自變數： (1) WMI 事件結構的指標、 (2) 事件結構的大小， (3) 目標裝置的路徑標識符，如果事件源自裝置，則0xFF。如果 (3) 是路徑標識符， ScsiPortNotification 需要兩個額外的自變數： (4) 目標標識符， (5) 目標裝置的 LUN) 邏輯單元 (編號。

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
);

PathId 的語法 = 0xFF

VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIEvent
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PVOID                  WMIEvent,
  _In_opt_ UCHAR                  PathId               // 0xFF
);

NotificationType = WMIReregister

表示迷你埠驅動程式已藉由呼叫 IoWMIRegistrationControl 來變更先前註冊之指定數據區塊的數據項或實例數目。如果設定 WMIReregister，ScsiPortNotification 至少需要兩個額外的自變數： (1) 目標裝置的路徑識別碼來重新註冊該裝置，或0xFF重新註冊適配卡。如果 (1) 是路徑標識符， ScsiPortNotification 需要兩個額外的自變數： (2) 目標標識符， (3) 目標裝置的 LUN) 邏輯單元 (編號。

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

每個迷你埠驅動程式都必須針對迷你埠驅動程式的 HwScsiStartIo 例程呼叫 ScsiPortNotification 兩次，且迷你埠驅動程式成功完成的 SRB。首先，如果迷你埠驅動程序支援標記的佇列或每個 LU 的多個要求，則會使用 NextRequest 的 NotificationType 或 NextLuRequest 呼叫 ScsiPortNotification。然後，迷你埠驅動程式會使用 RequestComplete 的 NotificationType 和剛滿足的要求呼叫 ScsiPortNotification。

迷你埠驅動程式的 HwScsiInterrupt 例程最有可能使用 ResetDetected 的 NotificationType 呼叫 ScsiPortNotification。

如果 HBA 要求迷你埠驅動程式使用超過毫秒的處理中斷驅動 I/O 作業，其 HwScsiInterrupt 例程應該停用 HBA 上的中斷，並使用 CallEnableInterrupts 和驅動程式提供的 HwScsiEnableInterruptsCallback 例程來呼叫 ScsiPortNotification。此例程接著會呼叫 ScsiPortNotification 與 CallDisableInterrupts 和對應的驅動程式提供的 HwScsiDisableInterruptsCallback。

註冊為 WMI 數據提供者的迷你埠驅動程式可以使用 WMIEvent 呼叫 ScsiPortNotification，以張貼先前收到啟用要求的事件。埠驅動程式會將事件排入迷你埠驅動程式裝置延伸模組的中斷數據區域中，以供稍後在較低的 IRQL 進行處理。因為一次只能排入有限的事件佇列，所以迷你埠驅動程序應該使用 WMIEvent 來發出例外狀況，而不是例程條件，而且應該讓埠驅動程式時間回到張貼之間的DISPATCH_LEVEL，以防止事件遺失。