IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Статья
08/08/2023

Драйвер виртуальной функции PCI Express (PCIe) выдает IOCTL_VPCI_READ_BLOCK

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

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

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

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

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

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

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

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

Основной код

IRP_MJ_DEVICE_CONTROL

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

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

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

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

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

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

Элемент IRP	Значение
UserBuffer	Адрес буфера, выделенного вызывающим объектом, который будет содержать считываемые данные конфигурации.
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_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Указатель на структуру VPCI_READ_BLOCK_INPUT . Драйвер форматирует эту структуру параметрами для запроса ввода-вывода IOCTL_VPCI_READ_BLOCK .
IParameters.DeviceIoControl.InputBufferLength	Размер структуры VPCI_READ_BLOCK_INPUT в байтах.
Parameters.DeviceIoControl.OutputBufferLength	Размер буфера, выделенного вызывающим объектом, в байтах, который будет содержать считываемые данные конфигурации. Примечание Это значение должно совпадать со значением элемента BytesRequestedструктуры VPCI_READ_BLOCK_INPUT .

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

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

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

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

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

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

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

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

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

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

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

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

ПримечаниеIOCTL IOCTL_VPCI_READ_BLOCK предлагает асинхронную альтернативу функции ReadVfConfigBlock .

Требования

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