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

  • Статья

Драйвер Storport вызывает подпрограмму HwStorStartIo один раз для каждого входящего запроса ввода-вывода.

Синтаксис

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Параметры

DeviceExtension

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

Srb

Указатель на блок запросов SCSI, который требуется запустить.

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

Если запрос был успешно инициирован, HwStorStartIo возвращает значение TRUE. В противном случае возвращается значение FALSE.

Комментарии

HwStorStartIo инициирует операцию ввода-вывода. StorPort предназначен для использования частных данных мини-порта, которые подготовлены в HwStorBuildIo и хранятся в DeviceExtension или Srb-SrbExtension>. Так как HwStorBuildIo вызывается без спин-блокировок, наилучшая производительность драйвера достигается путем подготовки как можно большего объема данных в HwStorBuildIo.

Storport вызывает HwStorStartIo следующими способами:

  • Для драйверов, не относящихся к виртуальному хранилищу, в зависимости от значения SynchronizationModel , заданного в PORT_CONFIGURATION_INFORMATION, Storport всегда вызывает HwStorStartIo в том же IRQL и использует внутреннюю блокировку спина, чтобы обеспечить последовательное инициирование запросов ввода-вывода. IRQL DISPATCH_LEVEL (полнодуплексный режим) или DIRQL (полудуплексный режим).

    При обработке операций ввода-вывода в полудуплексном режиме подпрограмме HwStorStartIo не нужно получать собственную блокировку спина. Кроме того, выделение памяти с помощью StorPortAllocatePool и взаимное исключение с помощью StorPortAcquireSpinLock не разрешено в подпрограмме HwStorStartIo . В полнодуплексном режиме в подпрограмме HwStorStartIo можно использовать StorPortAllocatePool и StorPortAcquireSpinLock.

    Если не виртуальный минипорт поддерживает оптимизацию параллельных каналов (STOR_PERF_CONCURRENT_CHANNELS задано StorPortInitializePerfOpts), возможно несколько одновременных вызовов HwStorStartIo . В этом случае мини-порт должен обеспечить защиту всех общих ресурсов с помощью блокировки. При такой оптимизации производительности Storport не получит блокировку StartIo до вызова HwStorStartIo , и при необходимости минипорт должен предоставить собственную блокировку.

  • Для драйверов виртуального минипорта хранилища Storport вызывает HwStorStartIo в любом IRQL <= DISPATCH_LEVEL и не использует внутреннюю блокировку спина. Подпрограмма HwStorStartIo может получить собственную блокировку спина, вызвав StorPortAcquireSpinLock. Кроме того, вызовы StorPortAllocatePool разрешены в подпрограмме HwStorStartIo драйвера виртуального мини-порта хранилища.

Ожидается, что SRB будет завершен при получении состояния SCSI. Когда драйвер Storport завершает SRB путем вызова StorPortNotification с Типом уведомленияRequestComplete, SRB должен возвращать одно из следующих значений в поле SrbStatus SrbStatus Srb:

  • SRB_STATUS_SUCCESS

    • Указывает, что Srb был отправлен и возвращено состояние SCSI (возможно, с данными).
    • Storport возвращает данные и состояние вызывающей объекту.
    • Действие мини-порта отсутствует, за исключением выполнения запроса с помощью StorPortNotification для RequestComplete, вероятно, из HwStorDpcRoutine.

  • SRB_STATUS_BUSY

    • Указывает, что существует временная проблема с отправкой Srb (например, регистры адаптеров или буферы заняты).
    • Storport удаляет исходное расширение Srb, на которое указывает Srb-SrbExtension>, и выдает новое. Storport отправляет исходный Srb с новым расширением Srb в последующих вызовах HwStorBuildIo и HwStorStartIo. Все данные в исходном расширении Srb будут потеряны.
    • Мини-порт не должен обновлять DataTransferLength SRB.
    • Так как выдается новое расширение Srb, мини-порт должен убедиться, что он никогда не выдает SRB_STATUS_BUSY в середине транзакции SCSI. После запуска транзакции ее необходимо завершить или отменить. Состояния занятости оборудования во время транзакции должны обрабатываться драйвером мини-порта.

Имя HwStorStartIo — это заполнитель для описания подпрограммы miniport, заданной в элементе HwStartIoHW_INITIALIZATION_DATA структуры. Эта структура передается в параметре HwInitializationDataобъекта StorPortInitialize. Фактический прототип этой подпрограммы определен в Storport.h следующим образом:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Начиная с Windows 8 параметр Srb может указывать на SCSI_REQUEST_BLOCK или STORAGE_REQUEST_BLOCK. Если идентификатор функции в поле ФункцияSrbSRB_FUNCTION_STORAGE_REQUEST_BLOCK, SRB является STORAGE_REQUEST_BLOCK структурой запроса.

Примеры

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

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

Например, чтобы определить подпрограмму обратного вызова HwStorStartIo с именем MyHwStartIo, используйте тип HW_STARTIO и реализуйте процедуру обратного вызова следующим образом:

HW_STARTIO MyHwStartIo

BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

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

Требования

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

См. также раздел

HwStorBuildIo

SCSI_REQUEST_BLOCK

STORAGE_REQUEST_BLOCK

StorPortInitialize