tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: PCI: convert pci-iov-howto.txt to reST
Convert plain text documentation to reStructuredText format and add it to
Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
authored by
Changbin Du
and committed by
Bjorn Helgaas
4d2c729c
2e642244
+101
-75
+100
-75
Documentation/PCI/pci-iov-howto.txt
Documentation/PCI/pci-iov-howto.rst
+100
-75
Documentation/PCI/pci-iov-howto.txt
Documentation/PCI/pci-iov-howto.rst
···
1
-
PCI Express I/O Virtualization Howto
2
-
Copyright (C) 2009 Intel Corporation
3
-
Yu Zhao <yu.zhao@intel.com>
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: <isonum.txt>
4
3
5
-
Update: November 2012
6
-
-- sysfs-based SRIOV enable-/disable-ment
7
-
Donald Dutile <ddutile@redhat.com>
4
+
====================================
5
+
PCI Express I/O Virtualization Howto
6
+
====================================
8
7
9
-
1. Overview
8
+
:Copyright: |copy| 2009 Intel Corporation
9
+
:Authors: - Yu Zhao <yu.zhao@intel.com>
10
+
- Donald Dutile <ddutile@redhat.com>
10
11
11
-
1.1 What is SR-IOV
12
+
Overview
13
+
========
14
+
15
+
What is SR-IOV
16
+
--------------
12
17
13
18
Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
14
19
capability which makes one physical device appear as multiple virtual
···
28
23
operates on the register set so it can be functional and appear as a
29
24
real existing PCI device.
30
25
31
-
2. User Guide
26
+
User Guide
27
+
==========
32
28
33
-
2.1 How can I enable SR-IOV capability
29
+
How can I enable SR-IOV capability
30
+
----------------------------------
34
31
35
32
Multiple methods are available for SR-IOV enablement.
36
33
In the first method, the device driver (PF driver) will control the
···
50
43
numvfs <= totalvfs.
51
44
The second method is the recommended method for new/future VF devices.
52
45
53
-
2.2 How can I use the Virtual Functions
46
+
How can I use the Virtual Functions
47
+
-----------------------------------
54
48
55
49
The VF is treated as hot-plugged PCI devices in the kernel, so they
56
50
should be able to work in the same way as real PCI devices. The VF
57
51
requires device driver that is same as a normal PCI device's.
58
52
59
-
3. Developer Guide
53
+
Developer Guide
54
+
===============
60
55
61
-
3.1 SR-IOV API
56
+
SR-IOV API
57
+
----------
62
58
63
59
To enable SR-IOV capability:
64
-
(a) For the first method, in the driver:
60
+
61
+
(a) For the first method, in the driver::
62
+
65
63
int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
66
-
'nr_virtfn' is number of VFs to be enabled.
67
-
(b) For the second method, from sysfs:
64
+
65
+
'nr_virtfn' is number of VFs to be enabled.
66
+
67
+
(b) For the second method, from sysfs::
68
+
68
69
echo 'nr_virtfn' > \
69
70
/sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
70
71
71
72
To disable SR-IOV capability:
72
-
(a) For the first method, in the driver:
73
+
74
+
(a) For the first method, in the driver::
75
+
73
76
void pci_disable_sriov(struct pci_dev *dev);
74
-
(b) For the second method, from sysfs:
77
+
78
+
(b) For the second method, from sysfs::
79
+
75
80
echo 0 > \
76
81
/sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
77
82
78
83
To enable auto probing VFs by a compatible driver on the host, run
79
84
command below before enabling SR-IOV capabilities. This is the
80
85
default behavior.
86
+
::
87
+
81
88
echo 1 > \
82
89
/sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
83
90
84
91
To disable auto probing VFs by a compatible driver on the host, run
85
92
command below before enabling SR-IOV capabilities. Updating this
86
93
entry will not affect VFs which are already probed.
94
+
::
95
+
87
96
echo 0 > \
88
97
/sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
89
98
90
-
3.2 Usage example
99
+
Usage example
100
+
-------------
91
101
92
102
Following piece of code illustrates the usage of the SR-IOV API.
103
+
::
93
104
94
-
static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
95
-
{
96
-
pci_enable_sriov(dev, NR_VIRTFN);
105
+
static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
106
+
{
107
+
pci_enable_sriov(dev, NR_VIRTFN);
97
108
98
-
...
99
-
100
-
return 0;
101
-
}
102
-
103
-
static void dev_remove(struct pci_dev *dev)
104
-
{
105
-
pci_disable_sriov(dev);
106
-
107
-
...
108
-
}
109
-
110
-
static int dev_suspend(struct pci_dev *dev, pm_message_t state)
111
-
{
112
-
...
113
-
114
-
return 0;
115
-
}
116
-
117
-
static int dev_resume(struct pci_dev *dev)
118
-
{
119
-
...
120
-
121
-
return 0;
122
-
}
123
-
124
-
static void dev_shutdown(struct pci_dev *dev)
125
-
{
126
-
...
127
-
}
128
-
129
-
static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
130
-
{
131
-
if (numvfs > 0) {
132
109
...
133
-
pci_enable_sriov(dev, numvfs);
134
-
...
135
-
return numvfs;
136
-
}
137
-
if (numvfs == 0) {
138
-
....
139
-
pci_disable_sriov(dev);
140
-
...
110
+
141
111
return 0;
142
112
}
143
-
}
144
113
145
-
static struct pci_driver dev_driver = {
146
-
.name = "SR-IOV Physical Function driver",
147
-
.id_table = dev_id_table,
148
-
.probe = dev_probe,
149
-
.remove = dev_remove,
150
-
.suspend = dev_suspend,
151
-
.resume = dev_resume,
152
-
.shutdown = dev_shutdown,
153
-
.sriov_configure = dev_sriov_configure,
154
-
};
114
+
static void dev_remove(struct pci_dev *dev)
115
+
{
116
+
pci_disable_sriov(dev);
117
+
118
+
...
119
+
}
120
+
121
+
static int dev_suspend(struct pci_dev *dev, pm_message_t state)
122
+
{
123
+
...
124
+
125
+
return 0;
126
+
}
127
+
128
+
static int dev_resume(struct pci_dev *dev)
129
+
{
130
+
...
131
+
132
+
return 0;
133
+
}
134
+
135
+
static void dev_shutdown(struct pci_dev *dev)
136
+
{
137
+
...
138
+
}
139
+
140
+
static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
141
+
{
142
+
if (numvfs > 0) {
143
+
...
144
+
pci_enable_sriov(dev, numvfs);
145
+
...
146
+
return numvfs;
147
+
}
148
+
if (numvfs == 0) {
149
+
....
150
+
pci_disable_sriov(dev);
151
+
...
152
+
return 0;
153
+
}
154
+
}
155
+
156
+
static struct pci_driver dev_driver = {
157
+
.name = "SR-IOV Physical Function driver",
158
+
.id_table = dev_id_table,
159
+
.probe = dev_probe,
160
+
.remove = dev_remove,
161
+
.suspend = dev_suspend,
162
+
.resume = dev_resume,
163
+
.shutdown = dev_shutdown,
164
+
.sriov_configure = dev_sriov_configure,
165
+
};