]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. BSD LICENSE |
2 | Copyright(c) 2015 IGEL Co.,Ltd. All rights reserved. | |
3 | All rights reserved. | |
4 | ||
5 | Redistribution and use in source and binary forms, with or without | |
6 | modification, are permitted provided that the following conditions | |
7 | are met: | |
8 | ||
9 | * Redistributions of source code must retain the above copyright | |
10 | notice, this list of conditions and the following disclaimer. | |
11 | * Redistributions in binary form must reproduce the above copyright | |
12 | notice, this list of conditions and the following disclaimer in | |
13 | the documentation and/or other materials provided with the | |
14 | distribution. | |
15 | * Neither the name of IGEL Co.,Ltd. nor the names of its | |
16 | contributors may be used to endorse or promote products derived | |
17 | from this software without specific prior written permission. | |
18 | ||
19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
20 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
21 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
22 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
23 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
24 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
25 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
26 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
27 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
28 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
30 | ||
31 | Port Hotplug Framework | |
32 | ====================== | |
33 | ||
34 | The Port Hotplug Framework provides DPDK applications with the ability to | |
35 | attach and detach ports at runtime. Because the framework depends on PMD | |
36 | implementation, the ports that PMDs cannot handle are out of scope of this | |
37 | framework. Furthermore, after detaching a port from a DPDK application, the | |
38 | framework doesn't provide a way for removing the devices from the system. | |
39 | For the ports backed by a physical NIC, the kernel will need to support PCI | |
40 | Hotplug feature. | |
41 | ||
42 | Overview | |
43 | -------- | |
44 | ||
45 | The basic requirements of the Port Hotplug Framework are: | |
46 | ||
47 | * DPDK applications that use the Port Hotplug Framework must manage their | |
48 | own ports. | |
49 | ||
50 | The Port Hotplug Framework is implemented to allow DPDK applications to | |
51 | manage ports. For example, when DPDK applications call the port attach | |
52 | function, the attached port number is returned. DPDK applications can | |
53 | also detach the port by port number. | |
54 | ||
55 | * Kernel support is needed for attaching or detaching physical device | |
56 | ports. | |
57 | ||
58 | To attach new physical device ports, the device will be recognized by | |
59 | userspace driver I/O framework in kernel at first. Then DPDK | |
60 | applications can call the Port Hotplug functions to attach the ports. | |
61 | For detaching, steps are vice versa. | |
62 | ||
63 | * Before detaching, they must be stopped and closed. | |
64 | ||
65 | DPDK applications must call "rte_eth_dev_stop()" and | |
66 | "rte_eth_dev_close()" APIs before detaching ports. These functions will | |
67 | start finalization sequence of the PMDs. | |
68 | ||
69 | * The framework doesn't affect legacy DPDK applications behavior. | |
70 | ||
71 | If the Port Hotplug functions aren't called, all legacy DPDK apps can | |
72 | still work without modifications. | |
73 | ||
74 | Port Hotplug API overview | |
75 | ------------------------- | |
76 | ||
77 | * Attaching a port | |
78 | ||
79 | "rte_eth_dev_attach()" API attaches a port to DPDK application, and | |
80 | returns the attached port number. Before calling the API, the device | |
81 | should be recognized by an userspace driver I/O framework. The API | |
82 | receives a pci address like "0000:01:00.0" or a virtual device name | |
83 | like "net_pcap0,iface=eth0". In the case of virtual device name, the | |
84 | format is the same as the general "--vdev" option of DPDK. | |
85 | ||
86 | * Detaching a port | |
87 | ||
88 | "rte_eth_dev_detach()" API detaches a port from DPDK application, and | |
89 | returns a pci address of the detached device or a virtual device name | |
90 | of the device. | |
91 | ||
92 | Reference | |
93 | --------- | |
94 | ||
95 | "testpmd" supports the Port Hotplug Framework. | |
96 | ||
97 | Limitations | |
98 | ----------- | |
99 | ||
100 | * The Port Hotplug APIs are not thread safe. | |
101 | ||
102 | * The framework can only be enabled with Linux. BSD is not supported. | |
103 | ||
104 | * To detach a port, the port should be backed by a device that igb_uio | |
105 | manages. VFIO is not supported. | |
106 | ||
107 | * Not all PMDs support detaching feature. | |
108 | To know whether a PMD can support detaching, search for the | |
109 | "RTE_PCI_DRV_DETACHABLE" flag in PMD implementation. If the flag is | |
110 | defined in the PMD, detaching is supported. |