Documentation/PCI/pci-iov-howto.txt

Chinese translated version of Documentation/PCI/pci-iov-howto.txt

If you have any comment or update to the content, please contact the

original document maintainer directly.  However, if you have a problem

communicating in English you can also ask the Chinese maintainer for

help.  Contact the Chinese maintainer if this translation is outdated

or if there is a problem with the translation.

Chinese maintainer: 徐红 1534342777@qq.com

---------------------------------------------------------------------

Documentation/PCI/pci-iov-howto.txt的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文

交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

译存在问题，请联系中文版维护者。

中文版维护者： 徐红 1534342777@qq.com

中文版翻译者： 徐红 1534342777@qq.com

以下为正文

---------------------------------------------------------------------

 pci-iov-howto

 串行总线的I/O虚拟化

  --------------------


PCI Express I/O Virtualization Howto


Copyright (C) 2009 Intel Corporation


   Yu Zhao <yu.zhao@intel.com>

Update: November 2012


-- sysfs-based SRIOV enable-/disable-ment


Donald Dutile <ddutile@redhat.com>


串行总线的I/O虚拟化

    版权(C)  2009英特尔公司

    于赵     < yu.zhao@intel.com >

更新:   2012年11月

         ——基于系统文件的SRIOV启用/禁用行为

    唐纳德  Dutile < ddutile@redhat.com >

1. Overview

1.1 What is SR-IOV

Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended

capability which makes one physical device appear as multiple virtual

devices. The physical device is referred to as Physical Function (PF)

while the virtual devices are referred to as Virtual Functions (VF).

Allocation of the VF can be dynamically controlled by the PF via

registers encapsulated in the capability. By default, this feature is

not enabled and the PF behaves as traditional PCIe device. Once it's

turned on, each VF's PCI configuration space can be accessed by its own

Bus, Device and Function Number (Routing ID). And each VF also has PCI

Memory Space, which is used to map its register set. VF device driver

operates on the register set so it can be functional and appear as a

real existing PCI device.

1.概述

1.1什么是单根I/O虚拟化

单根虚拟化（SR-IOV）是串行总线使物理设备呈现为多个虚拟设备的扩展能力。

物理设备被成为物理函数（PF），虚拟设备被称为虚函数（VF）。虚函数的分

配可以被物理函数通过寄存器封装能力动态控制。默认情况下，这个特性是

不启用的，物理函数表现的和传统的PCIe设备一样。一旦它被开启，每个虚函

数的PCI配置空间就能被它的总线、设备及功能号（路由ID）访问。每个虚函数也

有PCI内存空间，用来映射它的寄存器组。虚函数驱动在寄存器组上操作，这样

它就能像真实存在的PCI设备一样发挥功能了。

2. User Guide

2.1 How can I enable SR-IOV capability

Multiple methods are available for SR-IOV enablement.

In the first method, the device driver (PF driver) will control the

enabling and disabling of the capability via API provided by SR-IOV core.

If the hardware has SR-IOV capability, loading its PF driver would

enable it and all VFs associated with the PF.  Some PF drivers require

a module parameter to be set to determine the number of VFs to enable.

In the second method, a write to the sysfs file sriov_numvfs will

enable and disable the VFs associated with a PCIe PF.  This method

enables per-PF, VF enable/disable values versus the first method,

which applies to all PFs of the same device.  Additionally, the

PCI SRIOV core support ensures that enable/disable operations are

valid to reduce duplication in multiple drivers for the same

checks, e.g., check numvfs == 0 if enabling VFs, ensure

numvfs <= totalvfs.

The second method is the recommended method for new/future VF devices.

2.用户指南

2.1如何启用SR-IOV能力

很多方法都可以启用单根I/O虚拟行为。第一种方法，设备驱动（PF驱动）可

以通过SR-IOV核心提供的API控制这种能力的启用和禁用。如果硬件拥有

SR-IOV能力，下载它的PF驱动就能启用，所有的VF都与PF相关。有些PF驱动

需要设置模块参数来确定VF被启用的数量。第二种方法，对系统文件

sriov_numvfs的写入将会启用或禁用与PCIe PF相关的虚拟设备。这种方法启

用每一个PF，VF启用/禁用值与第一种方法相比，这种适用于相同设备的所

有PF。此外，PCI单根虚拟化核心支持确保启用/禁用操作有效减少相同检查

的多个驱动程序的重复。例如：check numvfs == 0 if enabling VFs, ensure

numvfs <= totalvfs.

第二种方法是为未来新型虚拟设备推荐的方法。

2.2 How can I use the Virtual Functions

The VF is treated as hot-plugged PCI devices in the kernel, so they

should be able to work in the same way as real PCI devices. The VF

requires device driver that is same as a normal PCI device's.

2.2如何使用虚函数

VF在内核中被视为热插入PCI设备，因此，它们应该能像真正的PCI设备一样

工作。VF需要和正常PCI设备一样的设备驱动。

3. Developer Guide

3.1 SR-IOV API

To enable SR-IOV capability:

(a) For the first method, in the driver:


int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);


'nr_virtfn' is number of VFs to be enabled.

(b) For the second method, from sysfs:


echo 'nr_virtfn' > \

        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs

To disable SR-IOV capability:

(a) For the first method, in the driver:


void pci_disable_sriov(struct pci_dev *dev);

(b) For the second method, from sysfs:


echo  0 > \

        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs

To notify SR-IOV core of Virtual Function Migration:

(a) In the driver:


irqreturn_t pci_sriov_migration(struct pci_dev *dev);

3.开发者指南

3.1单根I/O虚拟化应用程序编程接口

启用SR-IOV能力

（a）对于第一种方法，在驱动器中:

int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);


'nr_virtfn' 表示被启用的VF的数量.

（b）对于第二种方法，来源于系统文件：

echo  0 > \

        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs

禁用SR-IOV能力

（a）对于第一种方法，在驱动器中：void pci_disable_sriov(struct pci_dev *dev);

（b）对于第二种方法，来源于系统文件：

echo  0 > \

        /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs

通知SR-IOV核心虚函数迁移：

（a）在驱动器中：

irqreturn_t pci_sriov_migration(struct pci_dev *dev);

3.2 Usage example

Following piece of code illustrates the usage of the SR-IOV API.

3.2用例

下面的代码片段说明了SR-IOV API的使用。

static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)

{


pci_enable_sriov(dev, NR_VIRTFN);

...

return 0;

}

static void dev_remove(struct pci_dev *dev)

{


pci_disable_sriov(dev);

...

}

static int dev_suspend(struct pci_dev *dev, pm_message_t state)

{


...

return 0;

}

static int dev_resume(struct pci_dev *dev)

{


...

return 0;

}

static void dev_shutdown(struct pci_dev *dev)

{


...

}

static int dev_sriov_configure(struct pci_dev *dev, int numvfs)

{


if (numvfs > 0) {


...


pci_enable_sriov(dev, numvfs);


...


return numvfs;


}


if (numvfs == 0) {


....


pci_disable_sriov(dev);


...


return 0;


}

}

static struct pci_driver dev_driver = {


.name =
"SR-IOV Physical Function driver",


.id_table =
dev_id_table,


.probe =
dev_probe,


.remove =
dev_remove,


.suspend =
dev_suspend,


.resume =
dev_resume,


.shutdown =
dev_shutdown,


.sriov_configure = dev_sriov_configure,

};