Функция ScsiPortNotification (srb.h)

Статья
03/08/2023

Подпрограмма ScsiPortNotification сообщает драйверу порта операционной системы об определенных событиях, например, когда драйвер мини-порта завершает запрос или готов к запуску другого SRB, а также когда адаптер шины узла (HBA) указывает на определенные ошибки SCSI, возникшие во время операции.

Примечание

В будущем модели драйвера портов SCSI и драйвера для минипорта SCSI могут быть изменены или недоступны. Вместо этого рекомендуется использовать модели драйверов Storport и драйверов для мини-портов Storport .

Синтаксис

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

Параметры

NotificationType

Указывает тип уведомления. См. заметки.

HwDeviceExtension

Указатель на расширение аппаратного устройства. Это область хранения для каждого адаптера, которую драйвер порта выделяет и инициализирует от имени драйвера мини-порта. Драйверы минипорта обычно хранят сведения, относящиеся к HBA, в этом расширении, например состояние адаптера шины и сопоставленные диапазоны доступа. Эта область доступна драйверу мини-порта в элементе DeviceExtension-HwDeviceExtension> объекта устройства HBA сразу после того, как драйвер минипорта вызывает ScsiPortInitialize. Драйвер порта освобождает эту память при удалении устройства.

...

Вариадические аргументы для этой подпрограммы. Количество и тип аргументов зависят от NotificationType. См. заметки.

Возвращаемое значение

None

Remarks

Подпрограмма 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

Указывает, что адаптер шины готов к другому запросу для указанной логической единицы. Если это значение задано, 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 требуется опрос или приостановка в ISR. Во время выполнения обратного вызова системные прерывания остаются включенными, но подпрограмма HwScsiInterrupt драйвера мини-порта не будет вызываться. HwScsiEnableInterruptsCallback отвечает за завершение отложенной обработки ввода-вывода и за повторный вызов ScsiPortNotification с помощью CallDisableInterrupts и точки входа HwScsiDisableInterruptsCallback драйвера мини-порта.

Синтаксис:
```
VOID ScsiPortNotification(
  _In_     SCSI_NOTIFICATION_TYPE NotificationType,           // CallEnableInterrupts
  _In_     PVOID                  HwDeviceExtension,
  _In_opt_ PHW_INTERRUPT          HwScsiXxxInterruptsCallback
);
```
NotificationType = CallDisableInterrupts

Указывает, что драйверу мини-порта требуется, чтобы драйвер порта для конкретной операционной системы вызывал подпрограмму HwScsiDisableInterruptsCallback драйвера мини-порта. Если это значение задано, для ScsiPortNotification требуется дополнительный параметр: точка входа для HwScsiDisableInterruptsCallback. Хотя этот обратный вызов выполняется, он не может быть вытеснен прерыванием, за исключением устройства с более высоким приоритетом прерывания, чем 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 требуется дополнительный параметр: идентификатор пути шины, в которой было обнаружено изменение. После этого уведомления драйвер порта повторно заменяется шиной, выдавая команды ЗАПРОСА. Перечисление шины занимает много времени и связывает автобус, поэтому водитель минипорта не должен отправлять это уведомление без необходимости.

Синтаксис:
```
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
);
```

Каждый драйвер мини-порта должен дважды вызывать ScsiPortNotification для каждого вызова подпрограммы HwScsiStartIo драйвера мини-порта с SRB, что драйвер минипорта успешно завершает. Во-первых, драйвер мини-порта вызывает ScsiPortNotification с типом уведомленияNextRequest или NextLuRequest , если драйвер мини-порта поддерживает очередь с тегами или несколько запросов на lu. Затем драйвер мини-порта вызывает ScsiPortNotification с типом уведомленияRequestComplete и запросом, который он только что выполнил.

Подпрограмма HwScsiInterrupt драйвера мини-порта, скорее всего, вызовет ScsiPortNotification с типом уведомленияResetDetected.

Если для HBA требуется, чтобы драйвер мини-порта использовал более миллисекунд обработки операций ввода-вывода, управляемых прерываниями, его подпрограмма HwScsiInterrupt должна отключать прерывания на адаптере безопасности и вызывать ScsiPortNotification с CallEnableInterrupts и предоставляемой драйвером подпрограммой HwScsiEnableInterruptsCallback . Эта подпрограмма, в свою очередь, вызывает ScsiPortNotification с CallDisableInterrupts и соответствующим предоставленным драйвером HwScsiDisableInterruptsCallback.

Драйвер мини-порта, зарегистрированный как поставщик данных WMI, может вызывать ScsiPortNotification с WMIEvent для публикации события, для которого он ранее получил запрос на включение. Драйвер порта помещает событие в очередь в области данных прерывания расширения устройства драйвера мини-порта для последующей обработки на более низком IRQL. Так как одновременно можно поместить в очередь только ограниченное количество событий, драйвер мини-порта должен использовать WMIEvent для сигналов об исключительных, а не обычных условиях, и он должен дать драйверу порта время, чтобы вернуться к DISPATCH_LEVEL между публикациями, чтобы предотвратить потерю событий.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	srb.h (включая Miniport.h, Scsi.h)
Библиотека	Scsiport.lib; Storport.lib
IRQL	(См. раздел "Примечания")