]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright 2017 6WIND S.A. | |
3 | ||
4 | Fail-safe poll mode driver library | |
5 | ================================== | |
6 | ||
f67539c2 TL |
7 | The Fail-safe poll mode driver library (**librte_pmd_failsafe**) implements a |
8 | virtual device that allows using device supporting hotplug, without modifying | |
9 | other components relying on such device (application, other PMDs). | |
10 | In this context, hotplug support is meant as plugging or removing a device | |
11 | from its bus suddenly. | |
11fdf7f2 TL |
12 | |
13 | Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the | |
f67539c2 | 14 | ability to redirect operations to a secondary device when the primary has been |
11fdf7f2 TL |
15 | removed from the system. |
16 | ||
17 | .. note:: | |
18 | ||
19 | The library is enabled by default. You can enable it or disable it manually | |
20 | by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option. | |
21 | ||
22 | Features | |
23 | -------- | |
24 | ||
25 | The Fail-safe PMD only supports a limited set of features. If you plan to use a | |
26 | device underneath the Fail-safe PMD with a specific feature, this feature must | |
f67539c2 | 27 | also be supported by the Fail-safe PMD. |
11fdf7f2 | 28 | |
f67539c2 TL |
29 | A notable exception is the device removal feature. The fail-safe PMD is not |
30 | meant to be removed itself, unlike its sub-devices which should support it. | |
31 | If a sub-device supports hotplugging, the fail-safe PMD will enable its use | |
32 | automatically by detecting capable devices and registering the relevant handler. | |
11fdf7f2 TL |
33 | |
34 | Check the feature matrix for the complete set of supported features. | |
35 | ||
36 | Compilation option | |
37 | ------------------ | |
38 | ||
f67539c2 | 39 | Available options within the ``$RTE_TARGET/build/.config`` file: |
11fdf7f2 TL |
40 | |
41 | - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**) | |
42 | ||
f67539c2 | 43 | This option enables or disables compiling librte_pmd_failsafe. |
11fdf7f2 TL |
44 | |
45 | Using the Fail-safe PMD from the EAL command line | |
46 | ------------------------------------------------- | |
47 | ||
48 | The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a | |
49 | ``--vdev`` parameter to the EAL when starting the application. The device name | |
50 | must start with the *net_failsafe* prefix, followed by numbers or letters. This | |
51 | name must be unique for each device. Each fail-safe instance must have at least one | |
f67539c2 | 52 | sub-device, and at most two. |
11fdf7f2 | 53 | |
f67539c2 | 54 | A sub-device can be any DPDK device, including possibly another fail-safe device. |
11fdf7f2 TL |
55 | |
56 | Fail-safe command line parameters | |
57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
58 | ||
59 | - **dev(<iface>)** parameter | |
60 | ||
61 | This parameter allows the user to define a sub-device. The ``<iface>`` part of | |
f67539c2 TL |
62 | this parameter must be a valid device definition. It follows the same format |
63 | provided to any ``-w`` or ``--vdev`` options. | |
64 | ||
65 | Enclosing the device definition within parentheses here allows using | |
11fdf7f2 TL |
66 | additional sub-device parameters if need be. They will be passed on to the |
67 | sub-device. | |
68 | ||
69 | .. note:: | |
70 | ||
f67539c2 TL |
71 | In case where the sub-device is also used as a whitelist device, using ``-w`` |
72 | on the EAL command line, the fail-safe PMD will use the device with the | |
73 | options provided to the EAL instead of its own parameters. | |
74 | ||
75 | When trying to use a PCI device automatically probed by the blacklist mode, | |
76 | the name for the fail-safe sub-device must be the full PCI id: | |
77 | Domain:Bus:Device.Function, *i.e.* ``00:00:00.0`` instead of ``00:00.0``, | |
78 | as the second form is historically accepted by the DPDK. | |
11fdf7f2 TL |
79 | |
80 | - **exec(<shell command>)** parameter | |
81 | ||
82 | This parameter allows the user to provide a command to the fail-safe PMD to | |
83 | execute and define a sub-device. | |
84 | It is done within a regular shell context. | |
85 | The first line of its output is read by the fail-safe PMD and otherwise | |
f67539c2 | 86 | interpreted as if passed to a **dev** parameter. |
11fdf7f2 | 87 | Any other line is discarded. |
f67539c2 | 88 | If the command fails or output an incorrect string, the sub-device is not |
11fdf7f2 TL |
89 | initialized. |
90 | All commas within the ``shell command`` are replaced by spaces before | |
91 | executing the command. This helps using scripts to specify devices. | |
92 | ||
93 | - **fd(<file descriptor number>)** parameter | |
94 | ||
95 | This parameter reads a device definition from an arbitrary file descriptor | |
96 | number in ``<iface>`` format as described above. | |
97 | ||
98 | The file descriptor is read in non-blocking mode and is never closed in | |
99 | order to take only the last line into account (unlike ``exec()``) at every | |
100 | probe attempt. | |
101 | ||
102 | - **mac** parameter [MAC address] | |
103 | ||
104 | This parameter allows the user to set a default MAC address to the fail-safe | |
105 | and all of its sub-devices. | |
106 | If no default mac address is provided, the fail-safe PMD will read the MAC | |
107 | address of the first of its sub-device to be successfully probed and use it as | |
108 | its default MAC address, trying to set it to all of its other sub-devices. | |
109 | If no sub-device was successfully probed at initialization, then a random MAC | |
f67539c2 | 110 | address is generated, that will be subsequently applied to all sub-devices once |
11fdf7f2 TL |
111 | they are probed. |
112 | ||
113 | - **hotplug_poll** parameter [UINT64] (default **2000**) | |
114 | ||
115 | This parameter allows the user to configure the amount of time in milliseconds | |
f67539c2 | 116 | between two sub-device upkeep round. |
11fdf7f2 TL |
117 | |
118 | Usage example | |
119 | ~~~~~~~~~~~~~ | |
120 | ||
121 | This section shows some example of using **testpmd** with a fail-safe PMD. | |
122 | ||
123 | #. To build a PMD and configure DPDK, refer to the document | |
124 | :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`. | |
125 | ||
f67539c2 TL |
126 | #. Start testpmd. The sub-device ``84:00.0`` should be blacklisted from normal EAL |
127 | operations to avoid probing it twice, as the PCI bus is in blacklist mode. | |
11fdf7f2 TL |
128 | |
129 | .. code-block:: console | |
130 | ||
131 | $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \ | |
132 | --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ | |
133 | -b 84:00.0 -b 00:04.0 -- -i | |
134 | ||
f67539c2 | 135 | If the sub-device ``84:00.0`` is not blacklisted, it will be probed by the |
11fdf7f2 TL |
136 | EAL first. When the fail-safe then tries to initialize it the probe operation |
137 | fails. | |
138 | ||
139 | Note that PCI blacklist mode is the default PCI operating mode. | |
140 | ||
141 | #. Alternatively, it can be used alongside any other device in whitelist mode. | |
142 | ||
143 | .. code-block:: console | |
144 | ||
145 | $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \ | |
146 | --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \ | |
147 | -w 81:00.0 -- -i | |
148 | ||
149 | #. Start testpmd using a flexible device definition | |
150 | ||
151 | .. code-block:: console | |
152 | ||
f67539c2 | 153 | $RTE_TARGET/build/app/testpmd -c 0xff -n 4 -w ff:ff.f \ |
11fdf7f2 TL |
154 | --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i |
155 | ||
156 | #. Start testpmd, automatically probing the device 84:00.0 and using it with | |
157 | the fail-safe. | |
158 | ||
159 | .. code-block:: console | |
160 | ||
161 | $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \ | |
162 | --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i | |
163 | ||
164 | ||
165 | Using the Fail-safe PMD from an application | |
166 | ------------------------------------------- | |
167 | ||
168 | This driver strives to be as seamless as possible to existing applications, in | |
169 | order to propose the hotplug functionality in the easiest way possible. | |
170 | ||
171 | Care must be taken, however, to respect the **ether** API concerning device | |
172 | access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate | |
173 | over ethernet devices, instead of directly accessing them or by writing one's | |
174 | own device iterator. | |
175 | ||
f67539c2 TL |
176 | .. code-block:: C |
177 | ||
178 | unsigned int i; | |
179 | ||
180 | /* VALID iteration over eth-dev. */ | |
181 | RTE_ETH_FOREACH_DEV(i) { | |
182 | [...] | |
183 | } | |
184 | ||
185 | /* INVALID iteration over eth-dev. */ | |
186 | for (i = 0; i < RTE_MAX_ETHPORTS; i++) { | |
187 | [...] | |
188 | } | |
189 | ||
11fdf7f2 TL |
190 | Plug-in feature |
191 | --------------- | |
192 | ||
193 | A sub-device can be defined without existing on the system when the fail-safe | |
194 | PMD is initialized. Upon probing this device, the fail-safe PMD will detect its | |
195 | absence and postpone its use. It will then register for a periodic check on any | |
196 | missing sub-device. | |
197 | ||
198 | During this time, the fail-safe PMD can be used normally, configured and told to | |
f67539c2 TL |
199 | emit and receive packets. It will store any applied configuration but will fail |
200 | to emit anything, returning ``0`` from its TX function. Any unsent packet must | |
201 | be freed. | |
202 | ||
203 | Upon the probing of its missing sub-device, the current stored configuration | |
204 | will be applied. After this configuration pass, the new sub-device will be | |
205 | synchronized with other sub-devices, i.e. be started if the fail-safe PMD has | |
206 | been started by the user before. | |
11fdf7f2 TL |
207 | |
208 | Plug-out feature | |
209 | ---------------- | |
210 | ||
211 | A sub-device supporting the device removal event can be removed from its bus at | |
212 | any time. The fail-safe PMD will register a callback for such event and react | |
213 | accordingly. It will try to safely stop, close and uninit the sub-device having | |
214 | emitted this event, allowing it to free its eventual resources. | |
215 | ||
216 | Fail-safe glossary | |
217 | ------------------ | |
218 | ||
f67539c2 TL |
219 | Fallback device |
220 | Also called **Secondary device**. | |
221 | ||
11fdf7f2 TL |
222 | The fail-safe will fail-over onto this device when the preferred device is |
223 | absent. | |
224 | ||
f67539c2 TL |
225 | Preferred device |
226 | Also called **Primary device**. | |
227 | ||
11fdf7f2 TL |
228 | The first declared sub-device in the fail-safe parameters. |
229 | When this device is plugged, it is always used as emitting device. | |
230 | It is the main sub-device and is used as target for configuration | |
231 | operations if there is any ambiguity. | |
232 | ||
233 | Upkeep round | |
f67539c2 TL |
234 | Periodical event during which sub-devices are serviced. Each devices having a state |
235 | different to that of the fail-safe device itself, is synchronized with it | |
236 | (brought down or up accordingly). Additionally, any sub-device marked for | |
237 | removal is cleaned-up. | |
11fdf7f2 TL |
238 | |
239 | Slave | |
240 | In the context of the fail-safe PMD, synonymous to sub-device. | |
241 | ||
242 | Sub-device | |
243 | A device being utilized by the fail-safe PMD. | |
244 | This is another PMD running underneath the fail-safe PMD. | |
245 | Any sub-device can disappear at any time. The fail-safe will ensure | |
246 | that the device removal happens gracefully. |