dc287af27577956f9271e3e32812facf26fbb902
[dpdk.git] / doc / guides / sample_app_ug / multi_process.rst
1 ..  BSD LICENSE
2     Copyright(c) 2010-2014 Intel Corporation. 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 Intel Corporation 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 Multi-process Sample Application
32 ================================
33
34 This chapter describes the example applications for multi-processing that are included in the DPDK.
35
36 Example Applications
37 --------------------
38
39 Building the Sample Applications
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41
42 The multi-process example applications are built in the same way as other sample applications,
43 and as documented in the *DPDK Getting Started Guide*.
44 To build all the example applications:
45
46 #.  Set RTE_SDK and go to the example directory:
47
48     .. code-block:: console
49
50         export RTE_SDK=/path/to/rte_sdk
51         cd ${RTE_SDK}/examples/multi_process
52
53 #.  Set the target (a default target will be used if not specified). For example:
54
55     .. code-block:: console
56
57         export RTE_TARGET=x86_64-native-linuxapp-gcc
58
59     See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
60
61 #.  Build the applications:
62
63     .. code-block:: console
64
65         make
66
67 .. note::
68
69     If just a specific multi-process application needs to be built,
70     the final make command can be run just in that application's directory,
71     rather than at the top-level multi-process directory.
72
73 Basic Multi-process Example
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 The examples/simple_mp folder in the DPDK release contains a basic example application to demonstrate how
77 two DPDK processes can work together using queues and memory pools to share information.
78
79 Running the Application
80 ^^^^^^^^^^^^^^^^^^^^^^^
81
82 To run the application, start one copy of the simple_mp binary in one terminal,
83 passing at least two cores in the coremask, as follows:
84
85 .. code-block:: console
86
87     ./build/simple_mp -c 3 -n 4 --proc-type=primary
88
89 For the first DPDK process run, the proc-type flag can be omitted or set to auto,
90 since all DPDK processes will default to being a primary instance,
91 meaning they have control over the hugepage shared memory regions.
92 The process should start successfully and display a command prompt as follows:
93
94 .. code-block:: console
95
96     $ ./build/simple_mp -c 3 -n 4 --proc-type=primary
97     EAL: coremask set to 3
98     EAL: Detected lcore 0 on socket 0
99     EAL: Detected lcore 1 on socket 0
100     EAL: Detected lcore 2 on socket 0
101     EAL: Detected lcore 3 on socket 0
102     ...
103
104     EAL: Requesting 2 pages of size 1073741824
105     EAL: Requesting 768 pages of size 2097152
106     EAL: Ask a virtual area of 0x40000000 bytes
107     EAL: Virtual area found at 0x7ff200000000 (size = 0x40000000)
108     ...
109
110     EAL: check igb_uio module
111     EAL: check module finished
112     EAL: Master core 0 is ready (tid=54e41820)
113     EAL: Core 1 is ready (tid=53b32700)
114
115     Starting core 1
116
117     simple_mp >
118
119 To run the secondary process to communicate with the primary process,
120 again run the same binary setting at least two cores in the coremask:
121
122 .. code-block:: console
123
124     ./build/simple_mp -c C -n 4 --proc-type=secondary
125
126 When running a secondary process such as that shown above, the proc-type parameter can again be specified as auto.
127 However, omitting the parameter altogether will cause the process to try and start as a primary rather than secondary process.
128
129 Once the process type is specified correctly,
130 the process starts up, displaying largely similar status messages to the primary instance as it initializes.
131 Once again, you will be presented with a command prompt.
132
133 Once both processes are running, messages can be sent between them using the send command.
134 At any stage, either process can be terminated using the quit command.
135
136 .. code-block:: console
137
138    EAL: Master core 10 is ready (tid=b5f89820)           EAL: Master core 8 is ready (tid=864a3820)
139    EAL: Core 11 is ready (tid=84ffe700)                  EAL: Core 9 is ready (tid=85995700)
140    Starting core 11                                      Starting core 9
141    simple_mp > send hello_secondary                      simple_mp > core 9: Received 'hello_secondary'
142    simple_mp > core 11: Received 'hello_primary'         simple_mp > send hello_primary
143    simple_mp > quit                                      simple_mp > quit
144
145 .. note::
146
147     If the primary instance is terminated, the secondary instance must also be shut-down and restarted after the primary.
148     This is necessary because the primary instance will clear and reset the shared memory regions on startup,
149     invalidating the secondary process's pointers.
150     The secondary process can be stopped and restarted without affecting the primary process.
151
152 How the Application Works
153 ^^^^^^^^^^^^^^^^^^^^^^^^^
154
155 The core of this example application is based on using two queues and a single memory pool in shared memory.
156 These three objects are created at startup by the primary process,
157 since the secondary process cannot create objects in memory as it cannot reserve memory zones,
158 and the secondary process then uses lookup functions to attach to these objects as it starts up.
159
160 .. code-block:: c
161
162     if (rte_eal_process_type() == RTE_PROC_PRIMARY){
163         send_ring = rte_ring_create(_PRI_2_SEC, ring_size, SOCKET0, flags);
164         recv_ring = rte_ring_create(_SEC_2_PRI, ring_size, SOCKET0, flags);
165         message_pool = rte_mempool_create(_MSG_POOL, pool_size, string_size, pool_cache, priv_data_sz, NULL, NULL, NULL, NULL, SOCKET0, flags);
166     } else {
167         recv_ring = rte_ring_lookup(_PRI_2_SEC);
168         send_ring = rte_ring_lookup(_SEC_2_PRI);
169         message_pool = rte_mempool_lookup(_MSG_POOL);
170     }
171
172 Note, however, that the named ring structure used as send_ring in the primary process is the recv_ring in the secondary process.
173
174 Once the rings and memory pools are all available in both the primary and secondary processes,
175 the application simply dedicates two threads to sending and receiving messages respectively.
176 The receive thread simply dequeues any messages on the receive ring, prints them,
177 and frees the buffer space used by the messages back to the memory pool.
178 The send thread makes use of the command-prompt library to interactively request user input for messages to send.
179 Once a send command is issued by the user, a buffer is allocated from the memory pool, filled in with the message contents,
180 then enqueued on the appropriate rte_ring.
181
182 Symmetric Multi-process Example
183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
184
185 The second example of DPDK multi-process support demonstrates how a set of processes can run in parallel,
186 with each process performing the same set of packet- processing operations.
187 (Since each process is identical in functionality to the others,
188 we refer to this as symmetric multi-processing, to differentiate it from asymmetric multi- processing -
189 such as a client-server mode of operation seen in the next example,
190 where different processes perform different tasks, yet co-operate to form a packet-processing system.)
191 The following diagram shows the data-flow through the application, using two processes.
192
193 .. _figure_sym_multi_proc_app:
194
195 .. figure:: img/sym_multi_proc_app.*
196
197    Example Data Flow in a Symmetric Multi-process Application
198
199
200 As the diagram shows, each process reads packets from each of the network ports in use.
201 RSS is used to distribute incoming packets on each port to different hardware RX queues.
202 Each process reads a different RX queue on each port and so does not contend with any other process for that queue access.
203 Similarly, each process writes outgoing packets to a different TX queue on each port.
204
205 Running the Application
206 ^^^^^^^^^^^^^^^^^^^^^^^
207
208 As with the simple_mp example, the first instance of the symmetric_mp process must be run as the primary instance,
209 though with a number of other application- specific parameters also provided after the EAL arguments.
210 These additional parameters are:
211
212 *   -p <portmask>, where portmask is a hexadecimal bitmask of what ports on the system are to be used.
213     For example: -p 3 to use ports 0 and 1 only.
214
215 *   --num-procs <N>, where N is the total number of symmetric_mp instances that will be run side-by-side to perform packet processing.
216     This parameter is used to configure the appropriate number of receive queues on each network port.
217
218 *   --proc-id <n>, where n is a numeric value in the range 0 <= n < N (number of processes, specified above).
219     This identifies which symmetric_mp instance is being run, so that each process can read a unique receive queue on each network port.
220
221 The secondary symmetric_mp instances must also have these parameters specified,
222 and the first two must be the same as those passed to the primary instance, or errors result.
223
224 For example, to run a set of four symmetric_mp instances, running on lcores 1-4,
225 all performing level-2 forwarding of packets between ports 0 and 1,
226 the following commands can be used (assuming run as root):
227
228 .. code-block:: console
229
230     # ./build/symmetric_mp -c 2 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=0
231     # ./build/symmetric_mp -c 4 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=1
232     # ./build/symmetric_mp -c 8 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=2
233     # ./build/symmetric_mp -c 10 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=3
234
235 .. note::
236
237     In the above example, the process type can be explicitly specified as primary or secondary, rather than auto.
238     When using auto, the first process run creates all the memory structures needed for all processes -
239     irrespective of whether it has a proc-id of 0, 1, 2 or 3.
240
241 .. note::
242
243     For the symmetric multi-process example, since all processes work in the same manner,
244     once the hugepage shared memory and the network ports are initialized,
245     it is not necessary to restart all processes if the primary instance dies.
246     Instead, that process can be restarted as a secondary,
247     by explicitly setting the proc-type to secondary on the command line.
248     (All subsequent instances launched will also need this explicitly specified,
249     as auto-detection will detect no primary processes running and therefore attempt to re-initialize shared memory.)
250
251 How the Application Works
252 ^^^^^^^^^^^^^^^^^^^^^^^^^
253
254 The initialization calls in both the primary and secondary instances are the same for the most part,
255 calling the rte_eal_init(), 1 G and 10 G driver initialization and then rte_eal_pci_probe() functions.
256 Thereafter, the initialization done depends on whether the process is configured as a primary or secondary instance.
257
258 In the primary instance, a memory pool is created for the packet mbufs and the network ports to be used are initialized -
259 the number of RX and TX queues per port being determined by the num-procs parameter passed on the command-line.
260 The structures for the initialized network ports are stored in shared memory and
261 therefore will be accessible by the secondary process as it initializes.
262
263 .. code-block:: c
264
265     if (num_ports & 1)
266        rte_exit(EXIT_FAILURE, "Application must use an even number of ports\n");
267
268     for(i = 0; i < num_ports; i++){
269         if(proc_type == RTE_PROC_PRIMARY)
270             if (smp_port_init(ports[i], mp, (uint16_t)num_procs) < 0)
271                 rte_exit(EXIT_FAILURE, "Error initializing ports\n");
272     }
273
274 In the secondary instance, rather than initializing the network ports, the port information exported by the primary process is used,
275 giving the secondary process access to the hardware and software rings for each network port.
276 Similarly, the memory pool of mbufs is accessed by doing a lookup for it by name:
277
278 .. code-block:: c
279
280     mp = (proc_type == RTE_PROC_SECONDARY) ? rte_mempool_lookup(_SMP_MBUF_POOL) : rte_mempool_create(_SMP_MBUF_POOL, NB_MBUFS, MBUF_SIZE, ... )
281
282 Once this initialization is complete, the main loop of each process, both primary and secondary,
283 is exactly the same - each process reads from each port using the queue corresponding to its proc-id parameter,
284 and writes to the corresponding transmit queue on the output port.
285
286 Client-Server Multi-process Example
287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
288
289 The third example multi-process application included with the DPDK shows how one can
290 use a client-server type multi-process design to do packet processing.
291 In this example, a single server process performs the packet reception from the ports being used and
292 distributes these packets using round-robin ordering among a set of client  processes,
293 which perform the actual packet processing.
294 In this case, the client applications just perform level-2 forwarding of packets by sending each packet out on a different network port.
295
296 The following diagram shows the data-flow through the application, using two client processes.
297
298 .. _figure_client_svr_sym_multi_proc_app:
299
300 .. figure:: img/client_svr_sym_multi_proc_app.*
301
302    Example Data Flow in a Client-Server Symmetric Multi-process Application
303
304
305 Running the Application
306 ^^^^^^^^^^^^^^^^^^^^^^^
307
308 The server process must be run initially as the primary process to set up all memory structures for use by the clients.
309 In addition to the EAL parameters, the application- specific parameters are:
310
311 *   -p <portmask >, where portmask is a hexadecimal bitmask of what ports on the system are to be used.
312     For example: -p 3 to use ports 0 and 1 only.
313
314 *   -n <num-clients>, where the num-clients parameter is the number of client processes that will process the packets received
315     by the server application.
316
317 .. note::
318
319     In the server process, a single thread, the master thread, that is, the lowest numbered lcore in the coremask, performs all packet I/O.
320     If a coremask is specified with more than a single lcore bit set in it,
321     an additional lcore will be used for a thread to periodically print packet count statistics.
322
323 Since the server application stores configuration data in shared memory, including the network ports to be used,
324 the only application parameter needed by a client process is its client instance ID.
325 Therefore, to run a server application on lcore 1 (with lcore 2 printing statistics) along with two client processes running on lcores 3 and 4,
326 the following commands could be used:
327
328 .. code-block:: console
329
330     # ./mp_server/build/mp_server -c 6 -n 4 -- -p 3 -n 2
331     # ./mp_client/build/mp_client -c 8 -n 4 --proc-type=auto -- -n 0
332     # ./mp_client/build/mp_client -c 10 -n 4 --proc-type=auto -- -n 1
333
334 .. note::
335
336     If the server application dies and needs to be restarted, all client applications also need to be restarted,
337     as there is no support in the server application for it to run as a secondary process.
338     Any client processes that need restarting can be restarted without affecting the server process.
339
340 How the Application Works
341 ^^^^^^^^^^^^^^^^^^^^^^^^^
342
343 The server process performs the network port and data structure initialization much as the symmetric multi-process application does when run as primary.
344 One additional enhancement in this sample application is that the server process stores its port configuration data in a memory zone in hugepage shared memory.
345 This eliminates the need for the client processes to have the portmask parameter passed into them on the command line,
346 as is done for the symmetric multi-process application, and therefore eliminates mismatched parameters as a potential source of errors.
347
348 In the same way that the server process is designed to be run as a primary process instance only,
349 the client processes are designed to be run as secondary instances only.
350 They have no code to attempt to create shared memory objects.
351 Instead, handles to all needed rings and memory pools are obtained via calls to rte_ring_lookup() and rte_mempool_lookup().
352 The network ports for use by the processes are obtained by loading the network port drivers and probing the PCI bus,
353 which will, as in the symmetric multi-process example,
354 automatically get access to the network ports using the settings already configured by the primary/server process.
355
356 Once all applications are initialized, the server operates by reading packets from each network port in turn and
357 distributing those packets to the client queues (software rings, one for each client process) in round-robin order.
358 On the client side, the packets are read from the rings in as big of bursts as possible, then routed out to a different network port.
359 The routing used is very simple. All packets received on the first NIC port are transmitted back out on the second port and vice versa.
360 Similarly, packets are routed between the 3rd and 4th network ports and so on.
361 The sending of packets is done by writing the packets directly to the network ports; they are not transferred back via the server process.
362
363 In both the server and the client processes, outgoing packets are buffered before being sent,
364 so as to allow the sending of multiple packets in a single burst to improve efficiency.
365 For example, the client process will buffer packets to send,
366 until either the buffer is full or until we receive no further packets from the server.
367
368 Master-slave Multi-process Example
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
370
371 The fourth example of DPDK multi-process support demonstrates a master-slave model that
372 provide the capability of application recovery if a slave process crashes or  meets unexpected conditions.
373 In addition, it also demonstrates the floating process,
374 which can run among different cores in contrast to the traditional way of binding a process/thread to a specific CPU core,
375 using the local cache mechanism of mempool structures.
376
377 This application performs the same functionality as the L2 Forwarding sample application,
378 therefore this chapter does not cover that part but describes functionality that is introduced in this multi-process example only.
379 Please refer to Chapter 9, "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information.
380
381 Unlike previous examples where all processes are started from the command line with input arguments, in this example,
382 only one process is spawned from the command line and that process creates other processes.
383 The following section describes this in more detail.
384
385 Master-slave Process Models
386 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
387
388 The process spawned from the command line is called the *master process* in this document.
389 A process created by the master is called a *slave process*.
390 The application has only one master process, but could have multiple slave processes.
391
392 Once the master process begins to run, it tries to initialize all the resources such as
393 memory, CPU cores, driver, ports, and so on, as the other examples do.
394 Thereafter, it creates slave processes, as shown in the following figure.
395
396 .. _figure_master_slave_proc:
397
398 .. figure:: img/master_slave_proc.*
399
400    Master-slave Process Workflow
401
402
403 The master process calls the rte_eal_mp_remote_launch() EAL function to launch an application function for each pinned thread through the pipe.
404 Then, it waits to check if any slave processes have exited.
405 If so, the process tries to re-initialize the resources that belong to that slave and launch them in the pinned thread entry again.
406 The following section describes the recovery procedures in more detail.
407
408 For each pinned thread in EAL, after reading any data from the pipe, it tries to call the function that the application specified.
409 In this master specified function, a fork() call creates a slave process that performs the L2 forwarding task.
410 Then, the function waits until the slave exits, is killed or crashes. Thereafter, it notifies the master of this event and returns.
411 Finally, the EAL pinned thread waits until the new function is launched.
412
413 After discussing the master-slave model, it is necessary to mention another issue, global and static variables.
414
415 For multiple-thread cases, all global and static variables have only one copy and they can be accessed by any thread if applicable.
416 So, they can be used to sync or share data among threads.
417
418 In the previous examples, each process has separate global and static variables in memory and are independent of each other.
419 If it is necessary to share the knowledge, some communication mechanism should be deployed, such as, memzone, ring, shared memory, and so on.
420 The global or static variables are not a valid approach to share data among processes.
421 For variables in this example, on the one hand, the slave process inherits all the knowledge of these variables after being created by the master.
422 On the other hand, other processes cannot know if one or more processes modifies them after slave creation since that
423 is the nature of a multiple process address space.
424 But this does not mean that these variables cannot be used to share or sync data; it depends on the use case.
425 The following are the possible use cases:
426
427 #.  The master process starts and initializes a variable and it will never be changed after slave processes created. This case is OK.
428
429 #.  After the slave processes are created, the master or slave cores need to change a variable, but other processes do not need to know the change.
430     This case is also OK.
431
432 #.  After the slave processes are created, the master or a slave needs to change a variable.
433     In the meantime, one or more other process needs to be aware of the change.
434     In this case, global and static variables cannot be used to share knowledge. Another communication mechanism is needed.
435     A simple approach without lock protection can be a heap buffer allocated by rte_malloc or mem zone.
436
437 Slave Process Recovery Mechanism
438 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
439
440 Before talking about the recovery mechanism, it is necessary to know what is needed before a new slave instance can run if a previous one exited.
441
442 When a slave process exits, the system returns all the resources allocated for this process automatically.
443 However, this does not include the resources that were allocated by the DPDK. All the hardware resources are shared among the processes,
444 which include memzone, mempool, ring, a heap buffer allocated by the rte_malloc library, and so on.
445 If the new instance runs and the allocated resource is not returned, either resource allocation failed or the hardware resource is lost forever.
446
447 When a slave process runs, it may have dependencies on other processes.
448 They could have execution sequence orders; they could share the ring to communicate; they could share the same port for reception and forwarding;
449 they could use lock structures to do exclusive access in some critical path.
450 What happens to the dependent process(es) if the peer leaves?
451 The consequence are varied since the dependency cases are complex.
452 It depends on what the processed had shared.
453 However, it is necessary to notify the peer(s) if one slave exited.
454 Then, the peer(s) will be aware of that and wait until the new instance begins to run.
455
456 Therefore, to provide the capability to resume the new slave instance if the previous one exited, it is necessary to provide several mechanisms:
457
458 #.  Keep a resource list for each slave process.
459     Before a slave process run, the master should prepare a resource list.
460     After it exits, the master could either delete the allocated resources and create new ones,
461     or re-initialize those for use by the new instance.
462
463 #.  Set up a notification mechanism for slave process exit cases. After the specific slave leaves,
464     the master should be notified and then help to create a new instance.
465     This mechanism is provided in Section 15.1.5.1, "Master-slave Process Models".
466
467 #.  Use a synchronization mechanism among dependent processes.
468     The master should have the capability to stop or kill slave processes that have a dependency on the one that has exited.
469     Then, after the new instance of exited slave process begins to run, the dependency ones could resume or run from the start.
470     The example sends a STOP command to slave processes dependent on the exited one, then they will exit.
471     Thereafter, the master creates new instances for the exited slave processes.
472
473 The following diagram describes slave process recovery.
474
475 .. _figure_slave_proc_recov:
476
477 .. figure:: img/slave_proc_recov.*
478
479    Slave Process Recovery Process Flow
480
481
482 Floating Process Support
483 ^^^^^^^^^^^^^^^^^^^^^^^^
484
485 When the DPDK application runs, there is always a -c option passed in to indicate the cores that are enabled.
486 Then, the DPDK creates a thread for each enabled core.
487 By doing so, it creates a 1:1 mapping between the enabled core and each thread.
488 The enabled core always has an ID, therefore, each thread has a unique core ID in the DPDK execution environment.
489 With the ID, each thread can easily access the structures or resources exclusively belonging to it without using function parameter passing.
490 It can easily use the rte_lcore_id() function to get the value in every function that is called.
491
492 For threads/processes not created in that way, either pinned to a core or not, they will not own a unique ID and the
493 rte_lcore_id() function will not work in the correct way.
494 However, sometimes these threads/processes still need the unique ID mechanism to do easy access on structures or resources.
495 For example, the DPDK mempool library provides a local cache mechanism
496 (refer to *DPDK Programmer's Guide* , Section 6.4, "Local Cache")
497 for fast element allocation and freeing.
498 If using a non-unique ID or a fake one,
499 a race condition occurs if two or more threads/ processes with the same core ID try to use the local cache.
500
501 Therefore, unused core IDs from the passing of parameters with the -c option are used to organize the core ID allocation array.
502 Once the floating process is spawned, it tries to allocate a unique core ID from the array and release it on exit.
503
504 A natural way to spawn a floating process is to use the fork() function and allocate a unique core ID from the unused core ID array.
505 However, it is necessary to write new code to provide a notification mechanism for slave exit
506 and make sure the process recovery mechanism can work with it.
507
508 To avoid producing redundant code, the Master-Slave process model is still used to spawn floating processes,
509 then cancel the affinity to specific cores.
510 Besides that, clear the core ID assigned to the DPDK spawning a thread that has a 1:1 mapping with the core mask.
511 Thereafter, get a new core ID from the unused core ID allocation array.
512
513 Run the Application
514 ^^^^^^^^^^^^^^^^^^^
515
516 This example has a command line similar to the L2 Forwarding sample application with a few differences.
517
518 To run the application, start one copy of the l2fwd_fork binary in one terminal.
519 Unlike the L2 Forwarding example,
520 this example requires at least three cores since the master process will wait and be accountable for slave process recovery.
521 The command is as follows:
522
523 .. code-block:: console
524
525     #./build/l2fwd_fork -c 1c -n 4 -- -p 3 -f
526
527 This example provides another -f option to specify the use of floating process.
528 If not specified, the example will use a pinned process to perform the L2 forwarding task.
529
530 To verify the recovery mechanism, proceed as follows: First, check the PID of the slave processes:
531
532 .. code-block:: console
533
534     #ps -fe | grep l2fwd_fork
535     root 5136 4843 29 11:11 pts/1 00:00:05 ./build/l2fwd_fork
536     root 5145 5136 98 11:11 pts/1 00:00:11 ./build/l2fwd_fork
537     root 5146 5136 98 11:11 pts/1 00:00:11 ./build/l2fwd_fork
538
539 Then, kill one of the slaves:
540
541 .. code-block:: console
542
543     #kill -9 5145
544
545 After 1 or 2 seconds, check whether the slave has resumed:
546
547 .. code-block:: console
548
549     #ps -fe | grep l2fwd_fork
550     root 5136 4843 3 11:11 pts/1 00:00:06 ./build/l2fwd_fork
551     root 5247 5136 99 11:14 pts/1 00:00:01 ./build/l2fwd_fork
552     root 5248 5136 99 11:14 pts/1 00:00:01 ./build/l2fwd_fork
553
554 It can also monitor the traffic generator statics to see whether slave processes have resumed.
555
556 Explanation
557 ^^^^^^^^^^^
558
559 As described in previous sections,
560 not all global and static variables need to change to be accessible in multiple processes;
561 it depends on how they are used.
562 In this example,
563 the statics info on packets dropped/forwarded/received count needs to be updated by the slave process,
564 and the master needs to see the update and print them out.
565 So, it needs to allocate a heap buffer using rte_zmalloc.
566 In addition, if the -f option is specified,
567 an array is needed to store the allocated core ID for the floating process so that the master can return it
568 after a slave has exited accidentally.
569
570 .. code-block:: c
571
572     static int
573     l2fwd_malloc_shared_struct(void)
574     {
575         port_statistics = rte_zmalloc("port_stat", sizeof(struct l2fwd_port_statistics) * RTE_MAX_ETHPORTS, 0);
576
577         if (port_statistics == NULL)
578             return -1;
579
580         /* allocate mapping_id array */
581
582         if (float_proc) {
583             int i;
584
585             mapping_id = rte_malloc("mapping_id", sizeof(unsigned) * RTE_MAX_LCORE, 0);
586             if (mapping_id == NULL)
587                 return -1;
588
589             for (i = 0 ;i < RTE_MAX_LCORE; i++)
590                 mapping_id[i] = INVALID_MAPPING_ID;
591
592         }
593         return 0;
594     }
595
596 For each slave process, packets are received from one port and forwarded to another port that another slave is operating on.
597 If the other slave exits accidentally, the port it is operating on may not work normally,
598 so the first slave cannot forward packets to that port.
599 There is a dependency on the port in this case. So, the master should recognize the dependency.
600 The following is the code to detect this dependency:
601
602 .. code-block:: c
603
604     for (portid = 0; portid < nb_ports; portid++) {
605         /* skip ports that are not enabled */
606
607         if ((l2fwd_enabled_port_mask & (1 << portid)) == 0)
608             continue;
609
610         /* Find pair ports' lcores */
611
612         find_lcore = find_pair_lcore = 0;
613         pair_port = l2fwd_dst_ports[portid];
614
615         for (i = 0; i < RTE_MAX_LCORE; i++) {
616             if (!rte_lcore_is_enabled(i))
617                 continue;
618
619             for (j = 0; j < lcore_queue_conf[i].n_rx_port;j++) {
620                 if (lcore_queue_conf[i].rx_port_list[j] == portid) {
621                     lcore = i;
622                     find_lcore = 1;
623                     break;
624                 }
625
626                 if (lcore_queue_conf[i].rx_port_list[j] == pair_port) {
627                     pair_lcore = i;
628                     find_pair_lcore = 1;
629                     break;
630                 }
631             }
632
633             if (find_lcore && find_pair_lcore)
634                 break;
635         }
636
637         if (!find_lcore || !find_pair_lcore)
638             rte_exit(EXIT_FAILURE, "Not find port=%d pair\\n", portid);
639
640         printf("lcore %u and %u paired\\n", lcore, pair_lcore);
641
642         lcore_resource[lcore].pair_id = pair_lcore;
643         lcore_resource[pair_lcore].pair_id = lcore;
644     }
645
646 Before launching the slave process,
647 it is necessary to set up the communication channel between the master and slave so that
648 the master can notify the slave if its peer process with the dependency exited.
649 In addition, the master needs to register a callback function in the case where a specific slave exited.
650
651 .. code-block:: c
652
653     for (i = 0; i < RTE_MAX_LCORE; i++) {
654         if (lcore_resource[i].enabled) {
655             /* Create ring for master and slave communication */
656
657             ret = create_ms_ring(i);
658             if (ret != 0)
659                 rte_exit(EXIT_FAILURE, "Create ring for lcore=%u failed",i);
660
661             if (flib_register_slave_exit_notify(i,slave_exit_cb) != 0)
662                 rte_exit(EXIT_FAILURE, "Register master_trace_slave_exit failed");
663         }
664     }
665
666 After launching the slave process, the master waits and prints out the port statics periodically.
667 If an event indicating that a slave process exited is detected,
668 it sends the STOP command to the peer and waits until it has also exited.
669 Then, it tries to clean up the execution environment and prepare new resources.
670 Finally, the new slave instance is launched.
671
672 .. code-block:: c
673
674     while (1) {
675         sleep(1);
676         cur_tsc = rte_rdtsc();
677         diff_tsc = cur_tsc - prev_tsc;
678
679         /* if timer is enabled */
680
681         if (timer_period > 0) {
682             /* advance the timer */
683             timer_tsc += diff_tsc;
684
685             /* if timer has reached its timeout */
686             if (unlikely(timer_tsc >= (uint64_t) timer_period)) {
687                 print_stats();
688
689                 /* reset the timer */
690                 timer_tsc = 0;
691             }
692         }
693
694         prev_tsc = cur_tsc;
695
696         /* Check any slave need restart or recreate */
697
698         rte_spinlock_lock(&res_lock);
699
700         for (i = 0; i < RTE_MAX_LCORE; i++) {
701             struct lcore_resource_struct *res = &lcore_resource[i];
702             struct lcore_resource_struct *pair = &lcore_resource[res->pair_id];
703
704             /* If find slave exited, try to reset pair */
705
706             if (res->enabled && res->flags && pair->enabled) {
707                 if (!pair->flags) {
708                     master_sendcmd_with_ack(pair->lcore_id, CMD_STOP);
709                     rte_spinlock_unlock(&res_lock);
710                     sleep(1);
711                     rte_spinlock_lock(&res_lock);
712                     if (pair->flags)
713                         continue;
714                 }
715
716                 if (reset_pair(res->lcore_id, pair->lcore_id) != 0)
717                     rte_exit(EXIT_FAILURE, "failed to reset slave");
718
719                 res->flags = 0;
720                 pair->flags = 0;
721             }
722         }
723         rte_spinlock_unlock(&res_lock);
724     }
725
726 When the slave process is spawned and starts to run, it checks whether the floating process option is applied.
727 If so, it clears the affinity to a specific core and also sets the unique core ID to 0.
728 Then, it tries to allocate a new core ID.
729 Since the core ID has changed, the resource allocated by the master cannot work,
730 so it remaps the resource to the new core ID slot.
731
732 .. code-block:: c
733
734     static int
735     l2fwd_launch_one_lcore( attribute ((unused)) void *dummy)
736     {
737         unsigned lcore_id = rte_lcore_id();
738
739         if (float_proc) {
740             unsigned flcore_id;
741
742             /* Change it to floating process, also change it's lcore_id */
743
744             clear_cpu_affinity();
745
746             RTE_PER_LCORE(_lcore_id) = 0;
747
748             /* Get a lcore_id */
749
750             if (flib_assign_lcore_id() < 0 ) {
751                 printf("flib_assign_lcore_id failed\n");
752                 return -1;
753             }
754
755             flcore_id = rte_lcore_id();
756
757             /* Set mapping id, so master can return it after slave exited */
758
759             mapping_id[lcore_id] = flcore_id;
760             printf("Org lcore_id = %u, cur lcore_id = %u\n",lcore_id, flcore_id);
761             remapping_slave_resource(lcore_id, flcore_id);
762         }
763
764         l2fwd_main_loop();
765
766         /* return lcore_id before return */
767         if (float_proc) {
768             flib_free_lcore_id(rte_lcore_id());
769             mapping_id[lcore_id] = INVALID_MAPPING_ID;
770         }
771         return 0;
772     }