функция обратного вызова HW_ADAPTER_CONTROL (storport.h)

Статья
02/26/2024

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

Синтаксис

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

Параметры

[in] DeviceExtension

Указатель на место хранения драйвера минипорта на единицу HBA.

[in] ControlType

Значение SCSI_ADAPTER_CONTROL_TYPE , указывающее операцию управления адаптером, где каждый тип элемента управления инициирует действие драйвером мини-порта. Дополнительные сведения см. в разделе SCSI_ADAPTER_CONTROL_TYPE .

[in] Parameters

Указатель на структуру или значение, содержащее сведения, связанные с ControlType, или значение NULL, если тип элемента управления не использует структуру. Все структуры выделяются вызывающим объектом. Дополнительные сведения см. в разделе SCSI_ADAPTER_CONTROL_TYPE .

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

В зависимости от типа элемента управления HwStorAdapterControl возвращает одно из следующих SCSI_ADAPTER_CONTROL_STATUS значений:

Код возврата	Описание
ScsiAdapterControlSuccess	Драйвер мини-порта успешно выполнил запрошенную операцию. В настоящее время HwStorAdapterControl должен возвращать это значение для всех типов элементов управления.
ScsiAdapterControlUnsuccessful	Не удалось выполнить операцию управления адаптером.

Storport вызывает HwStorAdapterControl мини-порта с типом элемента управления ScsiQuerySupportedControlTypes после инициализации адаптера шины, но до первого ввода-вывода. Драйвер мини-порта заполняет структуру SCSI_SUPPORTED_CONTROL_TYPE_LIST в разделе Параметры операциями, которые он поддерживает. После возврата HwStorAdapterControl из этого вызова драйвер Storport вызывает обратный вызов HwStorAdapterControl драйвера мини-порта только для операций, поддерживаемых мини-портом.

Так как драйверы минипорта, работающие с драйвером Storport, должны поддерживать Plug and Play (PnP), минипорты должны поддерживать типы элементов управления ScsiStopAdapter и ScsiRestartAdapter.

В следующей таблице перечислены текущие irQL и спин-блокировки, полученные при выдаче типа элемента управления.

Тип элемента управления	IRQL	Спин-блокировка
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	None
ScsiStopAdapter	DIRQL	Прерывание блокировки
ScsiRestartAdapter	DIRQL	Прерывание блокировки
ScsiSetBootConfig	PASSIVE_LEVEL	None
ScsiSetRunningConfig	PASSIVE_LEVEL	None
ScsiPowerSettingNotification	PASSIVE_LEVEL	None
ScsiAdapterPower	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	None
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	None
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	None
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	None
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	None
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	None
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	None
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	None
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	None
ScsiAdapterQueryFruId	PASSIVE_LEVEL	None
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	None

Имя HwStorAdapterControl — это просто заполнитель. Фактический прототип этой подпрограммы определен в storport.h следующим образом:

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Примеры

Чтобы определить функцию обратного вызова HwStorAdapterControl , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму обратного вызова HwStorAdapterControl с именем MyHwAdapterControl, используйте тип HW_ADAPTER_CONTROL , как показано в следующем примере кода:

HW_ADAPTER_CONTROL MyHwAdapterControl;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

Тип функции HW_ADAPTER_CONTROL определен в файле заголовка Storport.h . Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции HW_ADAPTER_CONTROL в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов Storport. Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Целевая платформа	Универсальное
Верхняя часть	storport.h (включая Storport.h)
IRQL	См. заметки.