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

Статья
08/07/2023

Подпрограмма 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. Указывает драйверу мини-порта очистить все кэшированные данные.
- Выполняется драйвером мини-порта только в том случае, если он задает CachesData == TRUE в структуре PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> и Srb-Lun> являются допустимыми.
SRB_FUNCTION_SHUTDOWN: предписывает драйверу мини-порта очистить все кэшированные данные, подготовительные к завершению работы.
- Выполняется драйвером мини-порта только в том случае, если он задает CachesData == TRUE в структуре PORT_CONFIGURATION_INFORMATION .
- 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. Если идентификатор функции в поле ФункцияSrb имеет SRB_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 (см. раздел "Примечания"))