Documentation/virt/hyperv/vpci.rst

Source file repositories/reference/linux-study-clean/Documentation/virt/hyperv/vpci.rst

File Facts

System
Linux kernel
Corpus path
Documentation/virt/hyperv/vpci.rst
Extension
.rst
Size
15918 bytes
Lines
317
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

PCI pass-thru devices
=========================
In a Hyper-V guest VM, PCI pass-thru devices (also called
virtual PCI devices, or vPCI devices) are physical PCI devices
that are mapped directly into the VM's physical address space.
Guest device drivers can interact directly with the hardware
without intermediation by the host hypervisor.  This approach
provides higher bandwidth access to the device with lower
latency, compared with devices that are virtualized by the
hypervisor.  The device should appear to the guest just as it
would when running on bare metal, so no changes are required
to the Linux device drivers for the device.

Hyper-V terminology for vPCI devices is "Discrete Device
Assignment" (DDA).  Public documentation for Hyper-V DDA is
available here: `DDA`_

.. _DDA: https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/plan/plan-for-deploying-devices-using-discrete-device-assignment

DDA is typically used for storage controllers, such as NVMe,
and for GPUs.  A similar mechanism for NICs is called SR-IOV
and produces the same benefits by allowing a guest device
driver to interact directly with the hardware.  See Hyper-V
public documentation here: `SR-IOV`_

.. _SR-IOV: https://learn.microsoft.com/en-us/windows-hardware/drivers/network/overview-of-single-root-i-o-virtualization--sr-iov-

This discussion of vPCI devices includes DDA and SR-IOV
devices.

Device Presentation
-------------------
Hyper-V provides full PCI functionality for a vPCI device when
it is operating, so the Linux device driver for the device can
be used unchanged, provided it uses the correct Linux kernel
APIs for accessing PCI config space and for other integration
with Linux.  But the initial detection of the PCI device and
its integration with the Linux PCI subsystem must use Hyper-V
specific mechanisms.  Consequently, vPCI devices on Hyper-V
have a dual identity.  They are initially presented to Linux
guests as VMBus devices via the standard VMBus "offer"
mechanism, so they have a VMBus identity and appear under
/sys/bus/vmbus/devices.  The VMBus vPCI driver in Linux at
drivers/pci/controller/pci-hyperv.c handles a newly introduced
vPCI device by fabricating a PCI bus topology and creating all
the normal PCI device data structures in Linux that would
exist if the PCI device were discovered via ACPI on a bare-
metal system.  Once those data structures are set up, the
device also has a normal PCI identity in Linux, and the normal
Linux device driver for the vPCI device can function as if it
were running in Linux on bare-metal.  Because vPCI devices are
presented dynamically through the VMBus offer mechanism, they
do not appear in the Linux guest's ACPI tables.  vPCI devices
may be added to a VM or removed from a VM at any time during
the life of the VM, and not just during initial boot.

With this approach, the vPCI device is a VMBus device and a
PCI device at the same time.  In response to the VMBus offer
message, the hv_pci_probe() function runs and establishes a
VMBus connection to the vPCI VSP on the Hyper-V host.  That
connection has a single VMBus channel.  The channel is used to
exchange messages with the vPCI VSP for the purpose of setting
up and configuring the vPCI device in Linux.  Once the device
is fully configured in Linux as a PCI device, the VMBus
channel is used only if Linux changes the vCPU to be interrupted
in the guest, or if the vPCI device is removed from
the VM while the VM is running.  The ongoing operation of the
device happens directly between the Linux device driver for

Annotation

Implementation Notes