Поделиться через

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

  • Статья

Подпрограмма HwStorBuildIo обрабатывает SRB с несинхронизированным доступом к общим структурам системных данных перед передачей в HwStorStartIo.

Синтаксис

HW_BUILDIO HwBuildio;

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

Параметры

DeviceExtension

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

Srb

Указатель на блок запросов SCSI (SRB) для обработки.

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

HwStorBuildIo возвращает значение TRUE , чтобы сообщить вызывающей объекту, что StorPort должен вызвать подпрограмму HwStorStartIo , если StorPort считает, что LUN готов к приему ввода-вывода. HwStorBuildIo возвращает значение FALSE , чтобы сообщить вызывающей о том, что SRB не следует передавать в HwStorStartIo. В таких случаях драйвер мини-порта должен завершить SRB, вызвав StorPortNotification с типом уведомления RequestComplete. Это можно сделать в HwStorBuildIo или в другом месте драйвера мини-порта, если SRB будет завершена до истечения времени ожидания, указанного в поле TimeOutValue структуры SRB.

Комментарии

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

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Драйвер порта вызывает подпрограмму HwStorBuildIo в DISPATCH IRQL, не удерживая при этом блокировки спина. Поэтому в HwStorBuildIo разрешено выделение памяти с помощью StorPortAllocatePool и взаимное исключение с помощью StorPortAcquireSpinLock. В многопроцессорной среде одновременно может быть активно несколько HwStorBuildIo , поэтому драйвер минипорта требуется для синхронизации доступа к системным ресурсам, что может быть в состоянии состязания, если в любой момент времени активен более одного экземпляра HwStorBuildIo .

Выполняя длительные действия по настройке ввода-вывода в HwStorBuildIo , а не в HwStorStartIo, драйвер минипорта обеспечивает больший параллелизм операций ввода-вывода и, следовательно, повышает пропускную способность ввода-вывода. Для достижения максимальной производительности драйверы мини-порта должны выполнять как можно большую предварительную обработку в HwStorBuildIo , чтобы они могли отправлять запросы в HBA через HwStorStartIo в кратчайшие сроки. Предварительно обработанные данные и состояние могут храниться в структурах DeviceExtension или SrbExtension . Только изменения уникальных частей DeviceExtension должны происходить, так как блокировки не удерживаются. HwStorBuildIo и HwStorStartIo получают следующие типы функций Srb:

  • SRB_FUNCTION_EXECUTE_SCSI: отправляет CDB в указанную шину, целевой объект или lun.

    • Srb-DataTransferLength> допустим для всех cdbs.
    • Srb-DataBuffer> имеет значение NULL для запросов на чтение и запись. Чтобы получить доступ к связанным данным, используйте StorPortGetScatterGatherList (для передачи Dma) или StorPortGetSystemAddress (для операций ввода-вывода, контролируемых программой), чтобы получить список точечной сборки или виртуальный адрес буфера. Для других запросов Srb-Databuffer> указывает на данные, связанные с Srb.
    • Srb-PathId> является допустимым и представляет идентификатор пути, заданный storport в StorPortNotification (BusChange). Авторы водителей минипорта должны использовать pathid в качестве индекса в таблице автобусов в пределах минипорта.
    • Допустимы значения Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_IO_CONTROL: определен минипорт.

    • Srb-DataTransferLength> и Srb-DataBuffer> допустимы, если они заданы инициатором запроса.
    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_RESET_LOGICAL_UNIT. Сброс указанной логической единицы (если устройство поддерживается).

    • Недопустимые значения Srb-DataTransferLength> и Srb-DataBuffer>.
    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_RESET_DEVICE. Сброс указанного целевого объекта Scsi.

    • Недопустимы srb-DataTransferLength> и Srb-DataBuffer>, Srb-Lun>.
    • Допустимы значения Srb-PathId> и Srb-TargetId>.

  • SRB_FUNCTION_RESET_BUS. Сброс всех целевых объектов в указанной шине SCSI.

    • Допустимы только Srb-PathId>.

  • SRB_FUNCTION_FLUSH. Указывает драйверу мини-порта очистить все кэшированные данные.

    • Выполняется драйвером мини-порта, только если в структуре PORT_CONFIGURATION_INFORMATION задано значение CachesData == TRUE.
    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_SHUTDOWN: предписывает драйверу мини-порта очистить все кэшированные данные, чтобы завершить работу.

    • Выполняется драйвером мини-порта, только если в структуре PORT_CONFIGURATION_INFORMATION задано значение CachesData == TRUE.
    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_DUMP_POINTERS. Предоставляет сведения, необходимые драйверу мини-порта для поддержки аварийного дампа и гибернации.

    • Этот запрос отправляется в драйвер виртуального минипорта Storport, который используется для управления диском, на котором хранятся данные аварийного дампа. Начиная с Windows 8, не виртуальные драйверы минипорта могут при необходимости получать этот запрос.
    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

  • SRB_FUNCTION_FREE_DUMP_POINTERS. Начиная с Windows 8 этот запрос отправляется в мини-порт для освобождения ресурсов, выделенных во время запроса SRB_FUNCTION_DUMP_POINTERS.

    • Допустимы все значения Srb-PathId>, Srb-TargetId> и Srb-Lun>.

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

Дополнительные сведения о том, что вы можете и не можете безопасно делать в этой подпрограмме драйвера мини-порта, см. в разделе Unsynchronized HwStorBuildIo Routine.

Примеры

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

Например, чтобы определить подпрограмму обратного вызова HwStorBuildIo с именем MyHwBuildIo, используйте тип HW_BUILDIO , как показано в этом примере кода:

HW_BUILDIO MyHwBuildIo;

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

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

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

Требования

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

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

HwStorStartIo

PORT_CONFIGURATION_INFORMATION

SCSI_REQUEST_BLOCK

STORAGE_REQUEST_BLOCK

StorPortAcquireSpinLock

StorPortAllocatePool

StorPortNotification