net/ixgbe: add tuned Rx/Tx parameters
[dpdk.git] / doc / guides / sample_app_ug / exception_path.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2010-2014 Intel Corporation.
3
4 Exception Path Sample Application
5 =================================
6
7 The Exception Path sample application is a simple example that demonstrates the use of the DPDK
8 to set up an exception path for packets to go through the Linux* kernel.
9 This is done by using virtual TAP network interfaces.
10 These can be read from and written to by the DPDK application and
11 appear to the kernel as a standard network interface.
12
13 Overview
14 --------
15
16 The application creates two threads for each NIC port being used.
17 One thread reads from the port and writes the data unmodified to a thread-specific TAP interface.
18 The second thread reads from a TAP interface and writes the data unmodified to the NIC port.
19
20 The packet flow through the exception path application is as shown in the following figure.
21
22 .. _figure_exception_path_example:
23
24 .. figure:: img/exception_path_example.*
25
26    Packet Flow
27
28
29 To make throughput measurements, kernel bridges must be setup to forward data between the bridges appropriately.
30
31 Compiling the Application
32 -------------------------
33
34 To compile the sample application see :doc:`compiling`.
35
36 The application is located in the ``exception_path`` sub-directory.
37
38 Running the Application
39 -----------------------
40
41 The application requires a number of command line options:
42
43 .. code-block:: console
44
45     .build/exception_path [EAL options] -- -p PORTMASK -i IN_CORES -o OUT_CORES
46
47 where:
48
49 *   -p PORTMASK: A hex bitmask of ports to use
50
51 *   -i IN_CORES: A hex bitmask of cores which read from NIC
52
53 *   -o OUT_CORES: A hex bitmask of cores which write to NIC
54
55 Refer to the *DPDK Getting Started Guide* for general information on running applications
56 and the Environment Abstraction Layer (EAL) options.
57
58 The number of bits set in each bitmask must be the same.
59 The coremask -c or the corelist -l parameter of the EAL options should include IN_CORES and OUT_CORES.
60 The same bit must not be set in IN_CORES and OUT_CORES.
61 The affinities between ports and cores are set beginning with the least significant bit of each mask, that is,
62 the port represented by the lowest bit in PORTMASK is read from by the core represented by the lowest bit in IN_CORES,
63 and written to by the core represented by the lowest bit in OUT_CORES.
64
65 For example to run the application with two ports and four cores:
66
67 .. code-block:: console
68
69     ./build/exception_path -l 0-3 -n 4 -- -p 3 -i 3 -o c
70
71 Getting Statistics
72 ~~~~~~~~~~~~~~~~~~
73
74 While the application is running, statistics on packets sent and
75 received can be displayed by sending the SIGUSR1 signal to the application from another terminal:
76
77 .. code-block:: console
78
79     killall -USR1 exception_path
80
81 The statistics can be reset by sending a SIGUSR2 signal in a similar way.
82
83 Explanation
84 -----------
85
86 The following sections provide some explanation of the code.
87
88 Initialization
89 ~~~~~~~~~~~~~~
90
91 Setup of the mbuf pool, driver and queues is similar to the setup done in the :ref:`l2_fwd_app_real_and_virtual`.
92 In addition, the TAP interfaces must also be created.
93 A TAP interface is created for each lcore that is being used.
94 The code for creating the TAP interface is as follows:
95
96 .. code-block:: c
97
98     /*
99      *   Create a tap network interface, or use existing one with same name.
100      *   If name[0]='\0' then a name is automatically assigned and returned in name.
101      */
102
103     static int tap_create(char *name)
104     {
105         struct ifreq ifr;
106         int fd, ret;
107
108         fd = open("/dev/net/tun", O_RDWR);
109         if (fd < 0)
110             return fd;
111
112         memset(&ifr, 0, sizeof(ifr));
113
114         /* TAP device without packet information */
115
116         ifr.ifr_flags = IFF_TAP | IFF_NO_PI;
117         if (name && *name)
118             rte_snprinf(ifr.ifr_name, IFNAMSIZ, name);
119
120         ret = ioctl(fd, TUNSETIFF, (void *) &ifr);
121
122         if (ret < 0) {
123             close(fd);
124             return ret;
125
126         }
127
128         if (name)
129             snprintf(name, IFNAMSIZ, ifr.ifr_name);
130
131         return fd;
132     }
133
134 The other step in the initialization process that is unique to this sample application
135 is the association of each port with two cores:
136
137 *   One core to read from the port and write to a TAP interface
138
139 *   A second core to read from a TAP interface and write to the port
140
141 This is done using an array called port_ids[], which is indexed by the lcore IDs.
142 The population of this array is shown below:
143
144 .. code-block:: c
145
146     tx_port = 0;
147     rx_port = 0;
148
149     RTE_LCORE_FOREACH(i) {
150         if (input_cores_mask & (1ULL << i)) {
151             /* Skip ports that are not enabled */
152             while ((ports_mask & (1 << rx_port)) == 0) {
153                 rx_port++;
154                 if (rx_port > (sizeof(ports_mask) * 8))
155                     goto fail; /* not enough ports */
156             }
157             port_ids[i] = rx_port++;
158         } else if (output_cores_mask & (1ULL << i)) {
159             /* Skip ports that are not enabled */
160             while ((ports_mask & (1 << tx_port)) == 0) {
161                 tx_port++;
162                 if (tx_port > (sizeof(ports_mask) * 8))
163                    goto fail; /* not enough ports */
164             }
165             port_ids[i] = tx_port++;
166         }
167    }
168
169 Packet Forwarding
170 ~~~~~~~~~~~~~~~~~
171
172 After the initialization steps are complete, the main_loop() function is run on each lcore.
173 This function first checks the lcore_id against the user provided input_cores_mask and output_cores_mask to see
174 if this core is reading from or writing to a TAP interface.
175
176 For the case that reads from a NIC port, the packet reception is the same as in the L2 Forwarding sample application
177 (see :ref:`l2_fwd_app_rx_tx_packets`).
178 The packet transmission is done by calling write() with the file descriptor of the appropriate TAP interface
179 and then explicitly freeing the mbuf back to the pool.
180
181 ..  code-block:: c
182
183     /* Loop forever reading from NIC and writing to tap */
184
185     for (;;) {
186         struct rte_mbuf *pkts_burst[PKT_BURST_SZ];
187         unsigned i;
188
189         const unsigned nb_rx = rte_eth_rx_burst(port_ids[lcore_id], 0, pkts_burst, PKT_BURST_SZ);
190
191         lcore_stats[lcore_id].rx += nb_rx;
192
193         for (i = 0; likely(i < nb_rx); i++) {
194             struct rte_mbuf *m = pkts_burst[i];
195             int ret = write(tap_fd, rte_pktmbuf_mtod(m, void*),
196
197             rte_pktmbuf_data_len(m));
198             rte_pktmbuf_free(m);
199             if (unlikely(ret<0))
200                 lcore_stats[lcore_id].dropped++;
201             else
202                 lcore_stats[lcore_id].tx++;
203         }
204     }
205
206 For the other case that reads from a TAP interface and writes to a NIC port,
207 packets are retrieved by doing a read() from the file descriptor of the appropriate TAP interface.
208 This fills in the data into the mbuf, then other fields are set manually.
209 The packet can then be transmitted as normal.
210
211 .. code-block:: c
212
213     /* Loop forever reading from tap and writing to NIC */
214
215     for (;;) {
216         int ret;
217         struct rte_mbuf *m = rte_pktmbuf_alloc(pktmbuf_pool);
218
219         if (m == NULL)
220             continue;
221
222         ret = read(tap_fd, m->pkt.data, MAX_PACKET_SZ); lcore_stats[lcore_id].rx++;
223         if (unlikely(ret < 0)) {
224             FATAL_ERROR("Reading from %s interface failed", tap_name);
225         }
226
227         m->pkt.nb_segs = 1;
228         m->pkt.next = NULL;
229         m->pkt.data_len = (uint16_t)ret;
230
231         ret = rte_eth_tx_burst(port_ids[lcore_id], 0, &m, 1);
232         if (unlikely(ret < 1)) {
233             rte_pktmuf_free(m);
234             lcore_stats[lcore_id].dropped++;
235         }
236         else {
237             lcore_stats[lcore_id].tx++;
238         }
239     }
240
241 To set up loops for measuring throughput, TAP interfaces can be connected using bridging.
242 The steps to do this are described in the section that follows.
243
244 Managing TAP Interfaces and Bridges
245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246
247 The Exception Path sample application creates TAP interfaces with names of the format tap_dpdk_nn,
248 where nn is the lcore ID. These TAP interfaces need to be configured for use:
249
250 .. code-block:: console
251
252     ifconfig tap_dpdk_00 up
253
254 To set up a bridge between two interfaces so that packets sent to one interface can be read from another,
255 use the brctl tool:
256
257 .. code-block:: console
258
259     brctl addbr "br0"
260     brctl addif br0 tap_dpdk_00
261     brctl addif br0 tap_dpdk_03
262     ifconfig br0 up
263
264 The TAP interfaces created by this application exist only when the application is running,
265 so the steps above need to be repeated each time the application is run.
266 To avoid this, persistent TAP interfaces can be created using openvpn:
267
268 .. code-block:: console
269
270     openvpn --mktun --dev tap_dpdk_00
271
272 If this method is used, then the steps above have to be done only once and
273 the same TAP interfaces can be reused each time the application is run.
274 To remove bridges and persistent TAP interfaces, the following commands are used:
275
276 .. code-block:: console
277
278     ifconfig br0 down
279     brctl delbr br0
280     openvpn --rmtun --dev tap_dpdk_00
281