172 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. include:: <isonum.txt>3 4====================================5PCI Express I/O Virtualization Howto6====================================7 8:Copyright: |copy| 2009 Intel Corporation9:Authors: - Yu Zhao <yu.zhao@intel.com>10 - Donald Dutile <ddutile@redhat.com>11 12Overview13========14 15What is SR-IOV16--------------17 18Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended19capability which makes one physical device appear as multiple virtual20devices. The physical device is referred to as Physical Function (PF)21while the virtual devices are referred to as Virtual Functions (VF).22Allocation of the VF can be dynamically controlled by the PF via23registers encapsulated in the capability. By default, this feature is24not enabled and the PF behaves as traditional PCIe device. Once it's25turned on, each VF's PCI configuration space can be accessed by its own26Bus, Device and Function Number (Routing ID). And each VF also has PCI27Memory Space, which is used to map its register set. VF device driver28operates on the register set so it can be functional and appear as a29real existing PCI device.30 31User Guide32==========33 34How can I enable SR-IOV capability35----------------------------------36 37Multiple methods are available for SR-IOV enablement.38In the first method, the device driver (PF driver) will control the39enabling and disabling of the capability via API provided by SR-IOV core.40If the hardware has SR-IOV capability, loading its PF driver would41enable it and all VFs associated with the PF. Some PF drivers require42a module parameter to be set to determine the number of VFs to enable.43In the second method, a write to the sysfs file sriov_numvfs will44enable and disable the VFs associated with a PCIe PF. This method45enables per-PF, VF enable/disable values versus the first method,46which applies to all PFs of the same device. Additionally, the47PCI SRIOV core support ensures that enable/disable operations are48valid to reduce duplication in multiple drivers for the same49checks, e.g., check numvfs == 0 if enabling VFs, ensure50numvfs <= totalvfs.51The second method is the recommended method for new/future VF devices.52 53How can I use the Virtual Functions54-----------------------------------55 56The VF is treated as hot-plugged PCI devices in the kernel, so they57should be able to work in the same way as real PCI devices. The VF58requires device driver that is same as a normal PCI device's.59 60Developer Guide61===============62 63SR-IOV API64----------65 66To enable SR-IOV capability:67 68(a) For the first method, in the driver::69 70 int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);71 72'nr_virtfn' is number of VFs to be enabled.73 74(b) For the second method, from sysfs::75 76 echo 'nr_virtfn' > \77 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs78 79To disable SR-IOV capability:80 81(a) For the first method, in the driver::82 83 void pci_disable_sriov(struct pci_dev *dev);84 85(b) For the second method, from sysfs::86 87 echo 0 > \88 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs89 90To enable auto probing VFs by a compatible driver on the host, run91command below before enabling SR-IOV capabilities. This is the92default behavior.93::94 95 echo 1 > \96 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe97 98To disable auto probing VFs by a compatible driver on the host, run99command below before enabling SR-IOV capabilities. Updating this100entry will not affect VFs which are already probed.101::102 103 echo 0 > \104 /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe105 106Usage example107-------------108 109Following piece of code illustrates the usage of the SR-IOV API.110::111 112 static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)113 {114 pci_enable_sriov(dev, NR_VIRTFN);115 116 ...117 118 return 0;119 }120 121 static void dev_remove(struct pci_dev *dev)122 {123 pci_disable_sriov(dev);124 125 ...126 }127 128 static int dev_suspend(struct device *dev)129 {130 ...131 132 return 0;133 }134 135 static int dev_resume(struct device *dev)136 {137 ...138 139 return 0;140 }141 142 static void dev_shutdown(struct pci_dev *dev)143 {144 ...145 }146 147 static int dev_sriov_configure(struct pci_dev *dev, int numvfs)148 {149 if (numvfs > 0) {150 ...151 pci_enable_sriov(dev, numvfs);152 ...153 return numvfs;154 }155 if (numvfs == 0) {156 ....157 pci_disable_sriov(dev);158 ...159 return 0;160 }161 }162 163 static struct pci_driver dev_driver = {164 .name = "SR-IOV Physical Function driver",165 .id_table = dev_id_table,166 .probe = dev_probe,167 .remove = dev_remove,168 .driver.pm = &dev_pm_ops,169 .shutdown = dev_shutdown,170 .sriov_configure = dev_sriov_configure,171 };172