IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Статья
08/08/2023

Драйвер для виртуальной функции PCI Express (PCIe) выдает код управления IOCTL_VPCI_WRITE_BLOCK ввода-вывода (IOCTL) для записи данных в блок конфигурации VF. Драйвер выдает этот IOCTL следующему драйверу в стеке драйверов.

Примечание Этот запрос IOCTL отправляется драйвером PCIe VF на устройстве, поддерживающем интерфейс SR-IOV.

Когда драйвер выдает IOCTL_VPCI_WRITE_BLOCK IOCTL, драйвер должен выполнить следующие действия:

Подготовка структуры пакета запроса ввода-вывода

Подготовка структуры расположения стека ввода-вывода

Выдача запроса IOCTL

Результаты завершения запроса IOCTL

Дополнительные сведения о выдаче ioCTL между драйверами в режиме ядра см. в разделе Создание запросов IOCTL в драйверах.

Основной код

IRP_MJ_DEVICE_CONTROL

Блок состояния

Irp-IoStatus.Status> имеет значение STATUS_SUCCESS, если запрос выполнен успешно.

В противном случае — состояние соответствующего условия ошибки в виде кода NTSTATUS.

Дополнительные сведения см. в разделе [значения XREF-LINK:NTSTATUS].

Драйвер должен сначала выделить или повторно использовать пакет запросов ввода-вывода (IRP). Для выделения IOCTL IRP можно использовать подпрограмму IoBuildDeviceIoControlRequest . Вы также можете использовать процедуры создания и инициализации IRP общего назначения, такие как IoAllocateIrp, IoReuseIrp или IoInitializeIrp. Дополнительные сведения о выделении IRP см. в разделе Создание irP для драйверов Lower-Level.

Затем драйвер должен задать элементы структуры IRP , как описано в следующей таблице.

Элемент IRP	Значение
UserBuffer	NULL
UserEvent	Адрес объекта события, который был инициализирован в вызове подпрограммы KeInitializeEvent . Примечание Если асинхронное завершение запроса IOCTL не требуется, этот элемент должен иметь значение NULL. Дополнительные сведения см. в разделе Создание запросов IOCTL в драйверах.
UserIosb	Адрес структуры, выделенной вызывающей IO_STATUS_BLOCK . Эта структура обновляется нижним драйвером, чтобы указать окончательное состояние запроса ввода-вывода.

Подготовка структуры расположения стека ввода-вывода

Драйвер вызывает подпрограмму IoGetNextIrpStackLocation для доступа к расположению стека ввода-вывода нижнего драйвера. Эта функция возвращает указатель на структуру IO_STACK_LOCATION , содержащую параметры для расположения стека ввода-вывода.

Затем драйвер должен задать члены в структуре IO_STACK_LOCATION , как описано в следующей таблице:

элемент IO_STACK_LOCATION	Значение
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Указатель на структуру VPCI_WRITE_BLOCK_INPUT . Драйвер форматирует эту структуру с параметрами для запроса ввода-вывода IOCTL_VPCI_WRITE_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	Размер структуры VPCI_WRITE_BLOCK_INPUT в байтах.
Parameters.DeviceIoControl.OutputBufferLength	Ноль

Выдача запроса IOCTL

Чтобы выполнить этот запрос IOCTL, драйвер вызывает подпрограмму IoCallDriver для передачи запроса следующему драйверу в стеке драйверов. Драйвер задает параметры IoCallDriver , как описано в следующей таблице.

Параметр IoCallDriver	Значение
DeviceObject	Объект устройства нижнего драйвера.
Irp	Адрес IRP , который был ранее выделен и инициализирован. Дополнительные сведения см. в статье Подготовка структуры пакета запроса ввода-вывода (IRP).

Результаты завершения запроса IOCTL

После завершения запроса IOCTL IOCTL_VPCI_WRITE_BLOCKэлементу Status структуры IO_STATUS_BLOCK , выделенной вызывающим объектом, присваивается одно из значений, приведенных в следующей таблице.

Значение состояния	Описание
STATUS_SUCCESS	IOCTL успешно завершен.
STATUS_PENDING	IOCTL не завершен. Драйвер должен вызвать подпрограмму KeWaitForSingleObject , чтобы поместить текущий поток в состояние ожидания. Драйвер задает в параметре Object адрес объекта события, который был инициализирован в вызове подпрограммы KeInitializeEvent . Событие получает сигнал о завершении запроса IOCTL. После сигнала о событии поток возобновляет выполнение.
STATUS_BUFFER_TOO_SMALL	Для элемента Parameters.DeviceIoControl.InputBufferLength задано значение меньше размера структуры VPCI_WRITE_BLOCK_INPUT в байтах .

Если запрос выполнен успешно, для элемента Informationструктуры IO_STATUS_BLOCK устанавливается число записанных байтов. В противном случае элементу Information присваивается нулевое значение.

При выдаче IOCTL_VPCI_WRITE_BLOCK IOCTL драйвер физической функции PCIe (PF) получает уведомление о записи данных в указанный блок конфигурации VF.

Примечание Операционная система резервирует и управляет ресурсами, необходимыми для успешного выполнения этого IOCTL.

Блок конфигурации VF используется для обмена данными между драйверами PCIe PF и VF на устройстве, поддерживающем интерфейс SR-IOV. Драйвер PF выделяет блок конфигурации для каждого VF в неиспользуемых блоках пространства конфигурации PCI устройства.

После выделения блока конфигурации VF данные конфигурации VF можно обмениваться защищенным способом между следующими драйверами:

Драйвер VF, который выполняется в гостевой операционной системе. Эта операционная система работает в дочернем разделе Hyper-V.
Драйвер PF, который работает в операционной системе управления.
Эта операционная система работает в родительском разделе Hyper-V.

Использование блока конфигурации VF и формат его данных конфигурации определяются независимым поставщиком оборудования (IHV) устройства. Данные конфигурации используются только драйверами PF и VF.

ПримечаниеIOCTL IOCTL_VPCI_WRITE_BLOCK предлагает асинхронную альтернативу подпрограмме WriteVfConfigBlock .

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Server 2012 и более поздних версиях Windows.
Верхняя часть	vpci.h (включая Wdm.h)
IRQL	DISPATCH_LEVEL