IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

The driver for a PCI Express (PCIe) virtual function (VF) issues an IOCTL_VPCI_READ_BLOCK

I/O control code (IOCTL) in order to read data from a VF configuration block. The driver issues this IOCTL to the next-lower driver in the driver stack.

When the driver issues the IOCTL_VPCI_READ_BLOCK IOCTL, the driver must follow these steps:

Preparing an I/O Request Packet Structure

Preparing an I/O Stack Location Structure

Issuing the IOCTL Request

IOCTL Request Completion Results

For more information about issuing IOCTLs between kernel-mode drivers, see Creating IOCTL Requests in Drivers.

Major code

IRP_MJ_DEVICE_CONTROL

Status block

Irp->IoStatus.Status is set to STATUS_SUCCESS if the request is successful.

Otherwise, Status to the appropriate error condition as a NTSTATUS code.

For more information, see [XREF-LINK:NTSTATUS Values].

Remarks

Preparing an I/O Request Packet Structure

The driver must first allocate or reuse an I/O request packet (IRP). You can use the IoBuildDeviceIoControlRequest function to specifically allocate an IOCTL IRP. You can also use general-purpose IRP creation and initialization functions, such as IoAllocateIrp, IoReuseIrp, or IoInitializeIrp. For more information about IRP allocation, see Creating IRPs for Lower-Level Drivers.

The driver must then set the members of the IRP structure as described in the following table.

IRP member	Value
UserBuffer	The address of the caller-allocated buffer that will contain the configuration data to be read.
UserEvent	The address of the event object that was initialized in the call to the KeInitializeEvent function. Note  If asynchronous completion of the IOCTL request is not required, this member should be set to NULL. For more information, see Creating IOCTL Requests in Drivers.
UserIosb	The address of a caller-allocated IO_STATUS_BLOCK structure. This structure is updated by the lower driver to indicate the final status of the I/O request.

 

Preparing an I/O Stack Location Structure

The driver calls the IoGetNextIrpStackLocation function to access the lower driver's I/O stack location. This function returns a pointer to an IO_STACK_LOCATION structure that contains the parameters for the I/O stack location.

The driver must then set the members in the IO_STACK_LOCATION structure as described in the following table.

IO_STACK_LOCATION member	Value
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	A pointer to a VPCI_READ_BLOCK_INPUT structure. The driver formats this structure with the parameters for the IOCTL_VPCI_READ_BLOCK I/O request.
IParameters.DeviceIoControl.InputBufferLength	The size, in bytes, of the VPCI_READ_BLOCK_INPUT structure.
Parameters.DeviceIoControl.OutputBufferLength	The size, in bytes, of the caller-allocated buffer that will contain the configuration data to be read. Note  This value must be the same as the value of the BytesRequested member of the VPCI_READ_BLOCK_INPUT structure.

 

Issuing the IOCTL Request

To issue this IOCTL request, the driver calls the IoCallDriver function to pass the request on to the next-lower driver in the driver stack. The driver sets the parameters of IoCallDriver as described in the following table.

IoCallDriver parameter	Value
DeviceObject	The device object of the lower driver.
Irp	The address of the IRP that was previously allocated and initialized. For more information, see Preparing an I/O Request Packet (IRP) Structure.

 

IOCTL Request Completion Results

When the IOCTL_VPCI_READ_BLOCK IOCTL request is completed, the Status member of the caller-allocated IO_STATUS_BLOCK structure is set to one of the values in the following table.

Status value	Description
STATUS_SUCCESS	The IOCTL completed successfully.
STATUS_PENDING	The IOCTL has not completed. The driver must call the KeWaitForSingleObject function in order to put the current thread into a wait state. The driver sets the Object parameter to the address of an event object that was initialized in the call to the KeInitializeEvent function. The event is signaled when the IOCTL request is completed. Once the event is signaled, the thread resumes execution.
STATUS_BUFFER_TOO_SMALL	Either the Parameters.DeviceIoControl.InputBufferLength member or the Parameters.DeviceIoControl.OutputBufferLength member was set to a value that is less than the required buffer size.

 

If the request completed successfully, the Information member of the IO_STATUS_BLOCK structure is set to the number of bytes that were read. Otherwise, the Information member is set to zero.

When the IOCTL_VPCI_READ_BLOCK IOCTL is issued, the driver of the PCIe physical function (PF) is notified to return the data from the specified VF configuration block.

A VF configuration block is used for backchannel communication between the drivers of the PCIe PF and a VF on a device that supports the SR-IOV interface. Data from a VF configuration block can be exchanged between the following drivers:

• The VF driver, which runs in the guest operating system. This operating system runs within a Hyper-V child partition.
• The PF driver, which runs in the management operating system.

  This operating system runs within the Hyper-V parent partition.

The usage of the VF configuration block and the format of its configuration data are defined by the independent hardware vendor (IHV) of the device. The configuration data is used only by the drivers of the PF and VF.

Requirements

Requirement	Value
Minimum supported client	Supported in Windows Server 2012 and later versions of Windows.
Header	vpci.h (include Wdm.h)
IRQL	DISPATCH_LEVEL

See also

IO_STATUS_BLOCK

IRP_MJ_INTERNAL_DEVICE_CONTROL

ReadVfConfigBlock

Creating IOCTL Requests in Drivers

VPCI_READ_BLOCK_INPUT

IRP

IO_STACK_LOCATION

IoCallDriver