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

Статья
08/07/2023

Подпрограмма HwStorFindAdapter использует предоставленную конфигурацию, чтобы определить, поддерживается ли конкретный адаптер HBA, и, если это так, для возврата сведений о конфигурации этого адаптера.

Синтаксис

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Параметры

DeviceExtension

Предоставляет область хранения для каждого адаптера.

[in] HwContext

задано значение NULL.

[in] BusInformation

задано значение NULL.

[in] ArgumentString

Предоставляет строку, завершаемую значением NULL, с контекстными сведениями о драйвере.

[in/out] ConfigInfo

Предоставляет инициализированную структуру PORT_CONFIGURATION_INFORMATION , которую драйвер мини-порта использует во время инициализации.

[in] Reserved3

Зарезервировано для системного использования.

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

HwStorFindAdapter должен возвращать одно из следующих значений состояния:

Код возврата	Описание
SP_RETURN_FOUND	Указывает, что был найден поддерживаемый HBA и что сведения о конфигурации, относящиеся к HBA, были успешно определены и заданы в структуре PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Указывает, что HBA найден, но произошла ошибка при получении сведений о конфигурации. По возможности такую ошибку следует регистрировать с помощью StorPortLogError.
SP_RETURN_BAD_CONFIG	Указывает, что предоставленные сведения о конфигурации были недопустимыми для адаптера.
SP_RETURN_NOT_FOUND	Указывает, что для предоставленных сведений о конфигурации не найдено поддерживаемого адаптера HBA.

Так как драйвер Storport поддерживает только устройства Plug and Play (PnP), параметры HwContext и BusInformationдля HwStorFindAdapter не предоставляются не виртуальным драйверам мини-портов.

HwStorFindAdapter должен задать поля MaximumTransferLength и NumberOfPhysicalBreaks в структуре ConfigInfo . Помимо этих полей, структура PORT_CONFIGURATION_INFORMATION всегда будет полностью указывать все ресурсы адаптера, необходимые для запуска адаптера.

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

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

В большинстве случаев StorPort вызывает подпрограмму HwStorFindAdapter по адресу IRQL == PASSIVE_LEVEL без получения спиновых блокировок. Исключением является случай, когда мини-порт не поддерживает вызов HwStorAdaptorControl с типом элемента управления ScsiRestartAdapter . В этом случае StorPort повторно инициализирует адаптер, вызывая HwStorFindAdapter и HwStorInitialize. В этом случае HwStorFindAdapter вызывается по адресу IRQL == DISPATCH_LEVEL. Кроме того, в режиме дампа HwStorFindAdapter вызывается по адресу IRQL == HIGH_LEVEL.

Примеры

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

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

HW_FIND_ADAPTER MyHwFindAdapter;

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

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

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

Требования

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