doc/guides/sample_app_ug/server_node_efd.rst

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