xref: /dpdk/doc/guides/sample_app_ug/server_node_efd.rst (revision 8750576fb2a9a067ffbcce4bab6481f3bfa47097)
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2016-2017 Intel Corporation.
3
4Server-Node EFD Sample Application
5==================================
6
7This sample application demonstrates the use of EFD library as a flow-level
8load balancer. For more information about the EFD Library, please refer to the
9DPDK programmer's guide.
10
11This sample application is a variant of the :doc:`multi_process`
12where a specific target node is specified for every and each flow
13(not in a round-robin fashion as the original load balancing sample application).
14
15Overview
16--------
17
18The architecture of the EFD flow-based load balancer sample application is
19presented in the following figure.
20
21.. _figure_efd_sample_app_overview:
22
23.. figure:: img/server_node_efd.*
24
25   Using EFD as a Flow-Level Load Balancer
26
27As shown in :numref:`figure_efd_sample_app_overview`,
28the sample application consists of a front-end node (server)
29using the EFD library to create a load-balancing table for flows,
30for each flow a target backend worker node is specified. The EFD table does not
31store the flow key (unlike a regular hash table), and hence, it can
32individually load-balance millions of flows (number of targets * maximum number
33of flows fit in a flow table per target) while still fitting in CPU cache.
34
35It should be noted that although they are referred to as nodes, the frontend
36server and worker nodes are processes running on the same platform.
37
38Front-end Server
39~~~~~~~~~~~~~~~~
40
41Upon initializing, the frontend server node (process) creates a flow
42distributor table (based on the EFD library) which is populated with flow
43information and its intended target node.
44
45The sample application assigns a specific target node_id (process) for each of
46the IP destination addresses as follows:
47
48.. code-block:: c
49
50    node_id = i % num_nodes; /* Target node id is generated */
51    ip_dst = rte_cpu_to_be_32(i); /* Specific ip destination address is
52                                     assigned to this target node */
53
54then the pair of <key,target> is inserted into the flow distribution table.
55
56The main loop of the server process receives a burst of packets, then for
57each packet, a flow key (IP destination address) is extracted. The flow
58distributor table is looked up and the target node id is returned. Packets are
59then enqueued to the specified target node id.
60
61It should be noted that flow distributor table is not a membership test table,
62i.e. if the key has already been inserted the target node id will be correct.
63But for new keys, the flow distributor table will return a value (which can be
64valid).
65
66Backend Worker Nodes
67~~~~~~~~~~~~~~~~~~~~
68
69Upon initializing, the worker node (process) creates a flow table (a regular
70hash table that stores the key default size 1M flows) which is populated with
71only the flow information that is serviced at this node. This flow key is
72essential to point out new keys that have not been inserted before.
73
74The worker node's main loop is simply receiving packets then doing a hash table
75lookup. If a match occurs then statistics are updated for flows serviced by
76this node. If no match is found in the local hash table then this indicates
77that this is a new flow, which is dropped.
78
79
80Compiling the Application
81-------------------------
82
83To compile the sample application, see :doc:`compiling`.
84
85The application is located in the ``server_node_efd`` sub-directory.
86
87Running the Application
88-----------------------
89
90The application has two binaries to be run: the front-end server
91and the back-end node.
92
93The frontend server (server) has the following command line options::
94
95    ./<build_dir>/examples/dpdk-server [EAL options] -- -p PORTMASK -n NUM_NODES -f NUM_FLOWS
96
97Where,
98
99* ``-p PORTMASK:`` Hexadecimal bitmask of ports to configure
100* ``-n NUM_NODES:`` Number of back-end nodes that will be used
101* ``-f NUM_FLOWS:`` Number of flows to be added in the EFD table (1 million, by default)
102
103The back-end node (node) has the following command line options::
104
105    ./node [EAL options] -- -n NODE_ID
106
107Where,
108
109* ``-n NODE_ID:`` Node ID, which cannot be equal or higher than NUM_MODES
110
111
112First, the server app must be launched, with the number of nodes that will be run.
113Once it has been started, the node instances can be run, with different NODE_ID.
114These instances have to be run as secondary processes, with ``--proc-type=secondary``
115in the EAL options, which will attach to the primary process memory, and therefore,
116they can access the queues created by the primary process to distribute packets.
117
118To successfully run the application, the command line used to start the
119application has to be in sync with the traffic flows configured on the traffic
120generator side.
121
122For examples of application command lines and traffic generator flows, please
123refer to the DPDK Test Report. For more details on how to set up and run the
124sample applications provided with DPDK package, please refer to the
125:ref:`DPDK Getting Started Guide for Linux <linux_gsg>` and
126:ref:`DPDK Getting Started Guide for FreeBSD <freebsd_gsg>`.
127
128
129Explanation
130-----------
131
132As described in previous sections, there are two processes in this example.
133
134The first process, the front-end server, creates and populates the EFD table,
135which is used to distribute packets to nodes, which the number of flows
136specified in the command line (1 million, by default).
137
138
139.. literalinclude:: ../../../examples/server_node_efd/efd_server/init.c
140    :language: c
141    :start-after: Create EFD table. 8<
142    :end-before: >8 End of creation EFD table.
143
144After initialization, packets are received from the enabled ports, and the IPv4
145address from the packets is used as a key to look up in the EFD table,
146which tells the node where the packet has to be distributed.
147
148.. literalinclude:: ../../../examples/server_node_efd/efd_server/main.c
149    :language: c
150    :start-after: Processing packets. 8<
151    :end-before: >8 End of process_packets.
152
153The burst of packets received is enqueued in temporary buffers (per node),
154and enqueued in the shared ring between the server and the node.
155After this, a new burst of packets is received and this process is
156repeated infinitely.
157
158.. literalinclude:: ../../../examples/server_node_efd/efd_server/main.c
159    :language: c
160    :start-after: Flush rx queue. 8<
161    :end-before: >8 End of sending a burst of traffic to a node.
162
163The second process, the back-end node, receives the packets from the shared
164ring with the server and send them out, if they belong to the node.
165
166At initialization, it attaches to the server process memory, to have
167access to the shared ring, parameters and statistics.
168
169.. literalinclude:: ../../../examples/server_node_efd/efd_node/node.c
170    :language: c
171    :start-after: Attaching to the server process memory. 8<
172    :end-before: >8 End of attaching to the server process memory.
173    :dedent: 1
174
175Then, the hash table that contains the flows that will be handled
176by the node is created and populated.
177
178.. literalinclude:: ../../../examples/server_node_efd/efd_node/node.c
179    :language: c
180    :start-after: Creation of hash table. 8<
181    :end-before: >8 End of creation of hash table.
182
183After initialization, packets are dequeued from the shared ring
184(from the server) and, like in the server process,
185the IPv4 address from the packets is used as a key to look up in the hash table.
186If there is a hit, packet is stored in a buffer, to be eventually transmitted
187in one of the enabled ports. If key is not there, packet is dropped, since the
188flow is not handled by the node.
189
190.. literalinclude:: ../../../examples/server_node_efd/efd_node/node.c
191    :language: c
192    :start-after: Packets dequeued from the shared ring. 8<
193    :end-before: >8 End of packets dequeuing.
194
195Finally, note that both processes updates statistics, such as transmitted, received
196and dropped packets, which are shown and refreshed by the server app.
197
198.. literalinclude:: ../../../examples/server_node_efd/efd_server/main.c
199    :language: c
200    :start-after: Display recorded statistics. 8<
201    :end-before: >8 End of displaying the recorded statistics.
202