eal: rename IPC request as synchronous one
[dpdk.git] / doc / guides / nics / fail_safe.rst
1 ..  BSD LICENSE
2     Copyright 2017 6WIND S.A.
3
4     Redistribution and use in source and binary forms, with or without
5     modification, are permitted provided that the following conditions
6     are met:
7
8     * Redistributions of source code must retain the above copyright
9     notice, this list of conditions and the following disclaimer.
10     * Redistributions in binary form must reproduce the above copyright
11     notice, this list of conditions and the following disclaimer in
12     the documentation and/or other materials provided with the
13     distribution.
14     * Neither the name of 6WIND S.A. nor the names of its
15     contributors may be used to endorse or promote products derived
16     from this software without specific prior written permission.
17
18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30 Fail-safe poll mode driver library
31 ==================================
32
33 The Fail-safe poll mode driver library (**librte_pmd_failsafe**) is a virtual
34 device that allows using any device supporting hotplug (sudden device removal
35 and plugging on its bus), without modifying other components relying on such
36 device (application, other PMDs).
37
38 Additionally to the Seamless Hotplug feature, the Fail-safe PMD offers the
39 ability to redirect operations to secondary devices when the primary has been
40 removed from the system.
41
42 .. note::
43
44    The library is enabled by default. You can enable it or disable it manually
45    by setting the ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` configuration option.
46
47 Features
48 --------
49
50 The Fail-safe PMD only supports a limited set of features. If you plan to use a
51 device underneath the Fail-safe PMD with a specific feature, this feature must
52 be supported by the Fail-safe PMD to avoid throwing any error.
53
54 A notable exception is the device removal feature. The fail-safe PMD being a
55 virtual device, it cannot currently be removed in the sense of a specific bus
56 hotplug, like for PCI for example. It will however enable this feature for its
57 sub-device automatically, detecting those that are capable and register the
58 relevant callback for such event.
59
60 Check the feature matrix for the complete set of supported features.
61
62 Compilation option
63 ------------------
64
65 This option can be modified in the ``$RTE_TARGET/build/.config`` file.
66
67 - ``CONFIG_RTE_LIBRTE_PMD_FAILSAFE`` (default **y**)
68
69   Toggle compiling librte_pmd_failsafe.
70
71 Using the Fail-safe PMD from the EAL command line
72 -------------------------------------------------
73
74 The Fail-safe PMD can be used like most other DPDK virtual devices, by passing a
75 ``--vdev`` parameter to the EAL when starting the application. The device name
76 must start with the *net_failsafe* prefix, followed by numbers or letters. This
77 name must be unique for each device. Each fail-safe instance must have at least one
78 sub-device, up to ``RTE_MAX_ETHPORTS-1``.
79
80 A sub-device can be any legal DPDK device, including possibly another fail-safe
81 instance.
82
83 Fail-safe command line parameters
84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85
86 - **dev(<iface>)** parameter
87
88   This parameter allows the user to define a sub-device. The ``<iface>`` part of
89   this parameter must be a valid device definition. It could be the argument
90   provided to any ``-w`` device specification or the argument that would be
91   given to a ``--vdev`` parameter (including a fail-safe).
92   Enclosing the device definition within parenthesis here allows using
93   additional sub-device parameters if need be. They will be passed on to the
94   sub-device.
95
96 .. note::
97
98    In case of whitelist sub-device probed by EAL, fail-safe PMD will take the device
99    as is, which means that EAL device options are taken in this case.
100    When trying to use a PCI device automatically probed in blacklist mode,
101    the syntax for the fail-safe must be with the full PCI id:
102    Domain:Bus:Device.Function. See the usage example section.
103
104 - **exec(<shell command>)** parameter
105
106   This parameter allows the user to provide a command to the fail-safe PMD to
107   execute and define a sub-device.
108   It is done within a regular shell context.
109   The first line of its output is read by the fail-safe PMD and otherwise
110   interpreted as if passed by the regular **dev** parameter.
111   Any other line is discarded.
112   If the command fail or output an incorrect string, the sub-device is not
113   initialized.
114   All commas within the ``shell command`` are replaced by spaces before
115   executing the command. This helps using scripts to specify devices.
116
117 - **fd(<file descriptor number>)** parameter
118
119   This parameter reads a device definition from an arbitrary file descriptor
120   number in ``<iface>`` format as described above.
121
122   The file descriptor is read in non-blocking mode and is never closed in
123   order to take only the last line into account (unlike ``exec()``) at every
124   probe attempt.
125
126 - **mac** parameter [MAC address]
127
128   This parameter allows the user to set a default MAC address to the fail-safe
129   and all of its sub-devices.
130   If no default mac address is provided, the fail-safe PMD will read the MAC
131   address of the first of its sub-device to be successfully probed and use it as
132   its default MAC address, trying to set it to all of its other sub-devices.
133   If no sub-device was successfully probed at initialization, then a random MAC
134   address is generated, that will be subsequently applied to all sub-device once
135   they are probed.
136
137 - **hotplug_poll** parameter [UINT64] (default **2000**)
138
139   This parameter allows the user to configure the amount of time in milliseconds
140   between two slave upkeep round.
141
142 Usage example
143 ~~~~~~~~~~~~~
144
145 This section shows some example of using **testpmd** with a fail-safe PMD.
146
147 #. To build a PMD and configure DPDK, refer to the document
148    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`.
149
150 #. Start testpmd. The slave device should be blacklisted from normal EAL
151    operations to avoid probing it twice when in PCI blacklist mode.
152
153    .. code-block:: console
154
155       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
156          --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
157          -b 84:00.0 -b 00:04.0 -- -i
158
159    If the slave device being used is not blacklisted, it will be probed by the
160    EAL first. When the fail-safe then tries to initialize it the probe operation
161    fails.
162
163    Note that PCI blacklist mode is the default PCI operating mode.
164
165 #. Alternatively, it can be used alongside any other device in whitelist mode.
166
167    .. code-block:: console
168
169       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
170          --vdev 'net_failsafe0,mac=de:ad:be:ef:01:02,dev(84:00.0),dev(net_ring0)' \
171          -w 81:00.0 -- -i
172
173 #. Start testpmd using a flexible device definition
174
175    .. code-block:: console
176
177       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 --no-pci \
178          --vdev='net_failsafe0,exec(echo 84:00.0)' -- -i
179
180 #. Start testpmd, automatically probing the device 84:00.0 and using it with
181    the fail-safe.
182  
183    .. code-block:: console
184  
185       $RTE_TARGET/build/app/testpmd -c 0xff -n 4 \
186          --vdev 'net_failsafe0,dev(0000:84:00.0),dev(net_ring0)' -- -i
187
188
189 Using the Fail-safe PMD from an application
190 -------------------------------------------
191
192 This driver strives to be as seamless as possible to existing applications, in
193 order to propose the hotplug functionality in the easiest way possible.
194
195 Care must be taken, however, to respect the **ether** API concerning device
196 access, and in particular, using the ``RTE_ETH_FOREACH_DEV`` macro to iterate
197 over ethernet devices, instead of directly accessing them or by writing one's
198 own device iterator.
199
200 Plug-in feature
201 ---------------
202
203 A sub-device can be defined without existing on the system when the fail-safe
204 PMD is initialized. Upon probing this device, the fail-safe PMD will detect its
205 absence and postpone its use. It will then register for a periodic check on any
206 missing sub-device.
207
208 During this time, the fail-safe PMD can be used normally, configured and told to
209 emit and receive packets. It will store any applied configuration, and try to
210 apply it upon the probing of its missing sub-device. After this configuration
211 pass, the new sub-device will be synchronized with other sub-devices, i.e. be
212 started if the fail-safe PMD has been started by the user before.
213
214 Plug-out feature
215 ----------------
216
217 A sub-device supporting the device removal event can be removed from its bus at
218 any time. The fail-safe PMD will register a callback for such event and react
219 accordingly. It will try to safely stop, close and uninit the sub-device having
220 emitted this event, allowing it to free its eventual resources.
221
222 Fail-safe glossary
223 ------------------
224
225 Fallback device : Secondary device
226     The fail-safe will fail-over onto this device when the preferred device is
227     absent.
228
229 Preferred device : Primary device
230     The first declared sub-device in the fail-safe parameters.
231     When this device is plugged, it is always used as emitting device.
232     It is the main sub-device and is used as target for configuration
233     operations if there is any ambiguity.
234
235 Upkeep round
236     Periodical process when slaves are serviced. Each devices having a state
237     different to that of the fail-safe device itself, is synchronized with it.
238     Additionally, each slave having the remove flag set are cleaned-up.
239
240 Slave
241     In the context of the fail-safe PMD, synonymous to sub-device.
242
243 Sub-device
244     A device being utilized by the fail-safe PMD.
245     This is another PMD running underneath the fail-safe PMD.
246     Any sub-device can disappear at any time. The fail-safe will ensure
247     that the device removal happens gracefully.