ScsiPortNotification - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// srb.h

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

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-srb-scsiportnotification)

ScsiPortNotification function

Description

The ScsiPortNotification routine informs the operating system-specific port driver of certain events, such as when a miniport driver completes a request or is ready to start another SRB, as well as when the host bus adapter (HBA) indicates certain SCSI error conditions that occurred during an operation.

[!NOTE]

The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Instead, we recommend using the Storport driver and Storport miniport driver models.

Parameters

NotificationType

Specifies the type of notification. See Remarks.

HwDeviceExtension

Pointer to the hardware device extension. This is a per-HBA storage area that the port driver allocates and initializes on behalf of the miniport driver. Miniport drivers usually store HBA-specific information in this extension, such as the state of the HBA and the HBA's mapped access ranges. This area is available to the miniport driver in the DeviceExtension->HwDeviceExtension member of the HBA's device object immediately after the miniport driver calls ScsiPortInitialize. The port driver frees this memory when it removes the device.

...

Variadic arguments for this routine. The number and type of arguments depend on NotificationType. See Remarks.

Return value

None

Remarks

The ScsiPortNotification routine has a different set of optional parameters associated with each NotificationType. The list of possible values for NotificationType follows, along with descriptions for each value.

  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // RequestComplete
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ PSCSI_REQUEST_BLOCK    Srb
  );
 
  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,   // NextLuRequest
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_                        PathId,
    _In_opt_                        TargetId,
    _In_opt_                        Lun
  );
 
  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,           // CallEnableInterrupts
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
  );
 
  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,          // CallDisableInterrupts
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
  );
 
  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // RequestTimerCall
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ PHW_TIMER              HwScsiTimer,
    _In_opt_ ULONG                  MiniportTimerValue
  );
 
  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // BusChangeDetected
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ UCHAR                  PathId
  );
 
  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 for PathId = 0xFF

  VOID ScsiPortNotification(
    _In_     SCSI_NOTIFICATION_TYPE NotificationType,    // WMIEvent
    _In_     PVOID                  HwDeviceExtension,
    _In_opt_ PVOID                  WMIEvent,
    _In_opt_ UCHAR                  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 for PathId = 0xFF

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

Every miniport driver must call ScsiPortNotification twice for each call to the miniport driver's HwScsiStartIo routine with an SRB that the miniport driver completes successfully. First, the miniport driver calls ScsiPortNotification with the NotificationType of NextRequest or with NextLuRequest if the miniport driver supports tagged queuing or multiple requests per LU. Then, the miniport driver calls ScsiPortNotification with the NotificationType of RequestComplete and the request that it has just satisfied.

A miniport driver's HwScsiInterrupt routine is most likely to call ScsiPortNotification with the NotificationType of ResetDetected.

If an HBA requires the miniport driver to use more than a millisecond processing interrupt-driven I/O operations, its HwScsiInterrupt routine should disable interrupts on the HBA and call ScsiPortNotification with CallEnableInterrupts and a driver-supplied HwScsiEnableInterruptsCallback routine. This routine, in turn, calls ScsiPortNotification with CallDisableInterrupts and the corresponding driver-supplied HwScsiDisableInterruptsCallback.

A miniport driver that is registered as a WMI data provider can call ScsiPortNotification with WMIEvent to post an event for which it has previously received an enable request. The port driver queues the event in the interrupt data area of the miniport driver's device extension for later processing at a lower IRQL. Because only a limited number of events can be queued at one time, the miniport driver should use WMIEvent to signal exceptional rather than routine conditions, and it should give the port driver time to get back to DISPATCH_LEVEL between postings, to prevent events from being lost.

See also

HwScsiDisableInterruptsCallback

HwScsiEnableInterruptsCallback

HwScsiTimer

IoWMIRegistrationControl

ScsiPortCompleteRequest