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