-.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
+
+.. _multi_process_app:
Multi-process Sample Application
================================
-This chapter describes the example applications for multi-processing that are included in the Intel® DPDK.
+This chapter describes the example applications for multi-processing that are included in the DPDK.
Example Applications
--------------------
Building the Sample Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
The multi-process example applications are built in the same way as other sample applications,
-and as documented in the *Intel® DPDK Getting Started Guide*.
-To build all the example applications:
-
-#. Set RTE_SDK and go to the example directory:
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/multi_process
-
-#. Set the target (a default target will be used if not specified). For example:
-
- .. code-block:: console
+and as documented in the *DPDK Getting Started Guide*.
- export RTE_TARGET=x86_64-native-linuxapp-gcc
- See the *Intel® DPDK Getting Started Guide* for possible RTE_TARGET values.
+To compile the sample application see :doc:`compiling`.
-#. Build the applications:
-
- .. code-block:: console
-
- make
+The applications are located in the ``multi_process`` sub-directory.
.. note::
Basic Multi-process Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The examples/simple_mp folder in the Intel® DPDK release contains a basic example application to demonstrate how
-two Intel® DPDK processes can work together using queues and memory pools to share information.
+The examples/simple_mp folder in the DPDK release contains a basic example application to demonstrate how
+two DPDK processes can work together using queues and memory pools to share information.
Running the Application
^^^^^^^^^^^^^^^^^^^^^^^
To run the application, start one copy of the simple_mp binary in one terminal,
-passing at least two cores in the coremask, as follows:
+passing at least two cores in the coremask/corelist, as follows:
.. code-block:: console
- ./build/simple_mp -c 3 -n 4 --proc-type=primary
+ ./build/simple_mp -l 0-1 -n 4 --proc-type=primary
-For the first Intel® DPDK process run, the proc-type flag can be omitted or set to auto,
-since all Intel® DPDK processes will default to being a primary instance,
+For the first DPDK process run, the proc-type flag can be omitted or set to auto,
+since all DPDK processes will default to being a primary instance,
meaning they have control over the hugepage shared memory regions.
The process should start successfully and display a command prompt as follows:
.. code-block:: console
- $ ./build/simple_mp -c 3 -n 4 --proc-type=primary
+ $ ./build/simple_mp -l 0-1 -n 4 --proc-type=primary
EAL: coremask set to 3
EAL: Detected lcore 0 on socket 0
EAL: Detected lcore 1 on socket 0
simple_mp >
To run the secondary process to communicate with the primary process,
-again run the same binary setting at least two cores in the coremask:
+again run the same binary setting at least two cores in the coremask/corelist:
.. code-block:: console
- ./build/simple_mp -c C -n 4 --proc-type=secondary
+ ./build/simple_mp -l 2-3 -n 4 --proc-type=secondary
When running a secondary process such as that shown above, the proc-type parameter can again be specified as auto.
However, omitting the parameter altogether will cause the process to try and start as a primary rather than secondary process.
Symmetric Multi-process Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The second example of Intel® DPDK multi-process support demonstrates how a set of processes can run in parallel,
+The second example of DPDK multi-process support demonstrates how a set of processes can run in parallel,
with each process performing the same set of packet- processing operations.
(Since each process is identical in functionality to the others,
we refer to this as symmetric multi-processing, to differentiate it from asymmetric multi- processing -
where different processes perform different tasks, yet co-operate to form a packet-processing system.)
The following diagram shows the data-flow through the application, using two processes.
-.. _figure_6:
+.. _figure_sym_multi_proc_app:
-**Figure 6. Example Data Flow in a Symmetric Multi-process Application**
+.. figure:: img/sym_multi_proc_app.*
-.. image9_png has been renamed
+ Example Data Flow in a Symmetric Multi-process Application
-|sym_multi_proc_app|
As the diagram shows, each process reads packets from each of the network ports in use.
RSS is used to distribute incoming packets on each port to different hardware RX queues.
.. code-block:: console
- # ./build/symmetric_mp -c 2 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=0
- # ./build/symmetric_mp -c 4 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=1
- # ./build/symmetric_mp -c 8 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=2
- # ./build/symmetric_mp -c 10 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=3
+ # ./build/symmetric_mp -l 1 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=0
+ # ./build/symmetric_mp -l 2 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=1
+ # ./build/symmetric_mp -l 3 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=2
+ # ./build/symmetric_mp -l 4 -n 4 --proc-type=auto -- -p 3 --num-procs=4 --proc-id=3
.. note::
^^^^^^^^^^^^^^^^^^^^^^^^^
The initialization calls in both the primary and secondary instances are the same for the most part,
-calling the rte_eal_init(), 1 G and 10 G driver initialization and then rte_eal_pci_probe() functions.
+calling the rte_eal_init(), 1 G and 10 G driver initialization and then rte_pci_probe() functions.
Thereafter, the initialization done depends on whether the process is configured as a primary or secondary instance.
In the primary instance, a memory pool is created for the packet mbufs and the network ports to be used are initialized -
for(i = 0; i < num_ports; i++){
if(proc_type == RTE_PROC_PRIMARY)
if (smp_port_init(ports[i], mp, (uint16_t)num_procs) < 0)
- rte_exit(EXIT_FAILURE, "Error initialising ports\n");
+ rte_exit(EXIT_FAILURE, "Error initializing ports\n");
}
In the secondary instance, rather than initializing the network ports, the port information exported by the primary process is used,
Client-Server Multi-process Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The third example multi-process application included with the Intel® DPDK shows how one can
+The third example multi-process application included with the DPDK shows how one can
use a client-server type multi-process design to do packet processing.
In this example, a single server process performs the packet reception from the ports being used and
distributes these packets using round-robin ordering among a set of client processes,
The following diagram shows the data-flow through the application, using two client processes.
-.. _figure_7:
+.. _figure_client_svr_sym_multi_proc_app:
-**Figure 7. Example Data Flow in a Client-Server Symmetric Multi-process Application**
+.. figure:: img/client_svr_sym_multi_proc_app.*
-.. image10_png has been renamed
+ Example Data Flow in a Client-Server Symmetric Multi-process Application
-|client_svr_sym_multi_proc_app|
Running the Application
^^^^^^^^^^^^^^^^^^^^^^^
.. note::
- In the server process, a single thread, the master thread, that is, the lowest numbered lcore in the coremask, performs all packet I/O.
- If a coremask is specified with more than a single lcore bit set in it,
+ 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.
+ If a coremask/corelist is specified with more than a single lcore bit set in it,
an additional lcore will be used for a thread to periodically print packet count statistics.
Since the server application stores configuration data in shared memory, including the network ports to be used,
.. code-block:: console
- # ./mp_server/build/mp_server -c 6 -n 4 -- -p 3 -n 2
- # ./mp_client/build/mp_client -c 8 -n 4 --proc-type=auto -- -n 0
- # ./mp_client/build/mp_client -c 10 -n 4 --proc-type=auto -- -n 1
+ # ./mp_server/build/mp_server -l 1-2 -n 4 -- -p 3 -n 2
+ # ./mp_client/build/mp_client -l 3 -n 4 --proc-type=auto -- -n 0
+ # ./mp_client/build/mp_client -l 4 -n 4 --proc-type=auto -- -n 1
.. note::
Master-slave Multi-process Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The fourth example of Intel® DPDK multi-process support demonstrates a master-slave model that
+The fourth example of DPDK multi-process support demonstrates a master-slave model that
provide the capability of application recovery if a slave process crashes or meets unexpected conditions.
In addition, it also demonstrates the floating process,
which can run among different cores in contrast to the traditional way of binding a process/thread to a specific CPU core,
This application performs the same functionality as the L2 Forwarding sample application,
therefore this chapter does not cover that part but describes functionality that is introduced in this multi-process example only.
-Please refer to Chapter 9, "L2 Forwarding Sample Application (in Real and Virtualized Environments)" for more information.
+Please refer to :doc:`l2_forward_real_virtual` for more information.
Unlike previous examples where all processes are started from the command line with input arguments, in this example,
only one process is spawned from the command line and that process creates other processes.
memory, CPU cores, driver, ports, and so on, as the other examples do.
Thereafter, it creates slave processes, as shown in the following figure.
-.. _figure_8:
+.. _figure_master_slave_proc:
-**Figure 8. Master-slave Process Workflow**
+.. figure:: img/master_slave_proc.*
-.. image11_png has been renamed
+ Master-slave Process Workflow
-|master_slave_proc|
The master process calls the rte_eal_mp_remote_launch() EAL function to launch an application function for each pinned thread through the pipe.
Then, it waits to check if any slave processes have exited.
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.
When a slave process exits, the system returns all the resources allocated for this process automatically.
-However, this does not include the resources that were allocated by the Intel® DPDK. All the hardware resources are shared among the processes,
+However, this does not include the resources that were allocated by the DPDK. All the hardware resources are shared among the processes,
which include memzone, mempool, ring, a heap buffer allocated by the rte_malloc library, and so on.
If the new instance runs and the allocated resource is not returned, either resource allocation failed or the hardware resource is lost forever.
#. Set up a notification mechanism for slave process exit cases. After the specific slave leaves,
the master should be notified and then help to create a new instance.
- This mechanism is provided in Section 15.1.5.1, "Master-slave Process Models".
+ This mechanism is provided in Section `Master-slave Process Models`_.
#. Use a synchronization mechanism among dependent processes.
The master should have the capability to stop or kill slave processes that have a dependency on the one that has exited.
The following diagram describes slave process recovery.
-.. _figure_9:
+.. _figure_slave_proc_recov:
-**Figure 9. Slave Process Recovery Process Flow**
+.. figure:: img/slave_proc_recov.*
-.. image12_png has been renamed
+ Slave Process Recovery Process Flow
-|slave_proc_recov|
Floating Process Support
^^^^^^^^^^^^^^^^^^^^^^^^
-When the Intel® DPDK application runs, there is always a -c option passed in to indicate the cores that are enabled.
-Then, the Intel® DPDK creates a thread for each enabled core.
+When the DPDK application runs, there is always a -c option passed in to indicate the cores that are enabled.
+Then, the DPDK creates a thread for each enabled core.
By doing so, it creates a 1:1 mapping between the enabled core and each thread.
-The enabled core always has an ID, therefore, each thread has a unique core ID in the Intel® DPDK execution environment.
+The enabled core always has an ID, therefore, each thread has a unique core ID in the DPDK execution environment.
With the ID, each thread can easily access the structures or resources exclusively belonging to it without using function parameter passing.
It can easily use the rte_lcore_id() function to get the value in every function that is called.
For threads/processes not created in that way, either pinned to a core or not, they will not own a unique ID and the
rte_lcore_id() function will not work in the correct way.
However, sometimes these threads/processes still need the unique ID mechanism to do easy access on structures or resources.
-For example, the Intel® DPDK mempool library provides a local cache mechanism
-(refer to *Intel® DPDK Programmer's Guide* , Section 6.4, "Local Cache")
+For example, the DPDK mempool library provides a local cache mechanism
+(refer to :ref:`mempool_local_cache`)
for fast element allocation and freeing.
If using a non-unique ID or a fake one,
a race condition occurs if two or more threads/ processes with the same core ID try to use the local cache.
To avoid producing redundant code, the Master-Slave process model is still used to spawn floating processes,
then cancel the affinity to specific cores.
-Besides that, clear the core ID assigned to the Intel® DPDK spawning a thread that has a 1:1 mapping with the core mask.
+Besides that, clear the core ID assigned to the DPDK spawning a thread that has a 1:1 mapping with the core mask.
Thereafter, get a new core ID from the unused core ID allocation array.
Run the Application
.. code-block:: console
- #./build/l2fwd_fork -c 1c -n 4 -- -p 3 -f
+ #./build/l2fwd_fork -l 2-4 -n 4 -- -p 3 -f
This example provides another -f option to specify the use of floating process.
If not specified, the example will use a pinned process to perform the L2 forwarding task.
So, it needs to allocate a heap buffer using rte_zmalloc.
In addition, if the -f option is specified,
an array is needed to store the allocated core ID for the floating process so that the master can return it
-after a slave has exited accidently.
+after a slave has exited accidentally.
.. code-block:: c
}
return 0;
}
-
-.. |sym_multi_proc_app| image:: img/sym_multi_proc_app.png
-
-.. |client_svr_sym_multi_proc_app| image:: img/client_svr_sym_multi_proc_app.png
-
-.. |master_slave_proc| image:: img/master_slave_proc.png
-
-.. |slave_proc_recov| image:: img/slave_proc_recov.png
git.droids-corp.org / dpdk.git / blobdiff