doc/guides/prog_guide/packet_distrib_lib.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 Packet Distributor Library
  32 ==========================
  33
  34 The DPDK Packet Distributor library is a library designed to be used for dynamic load balancing of traffic
  35 while supporting single packet at a time operation.
  36 When using this library, the logical cores in use are to be considered in two roles: firstly a distributor lcore,
  37 which is responsible for load balancing or distributing packets,
  38 and a set of worker lcores which are responsible for receiving the packets from the distributor and operating on them.
  39 The model of operation is shown in the diagram below.
  40
  41 .. figure:: img/packet_distributor1.*
  42
  43    Packet Distributor mode of operation
  44
  45
  46 Distributor Core Operation
  47 --------------------------
  48
  49 The distributor core does the majority of the processing for ensuring that packets are fairly shared among workers.
  50 The operation of the distributor is as follows:
  51
  52 #.  Packets are passed to the distributor component by having the distributor lcore thread call the "rte_distributor_process()" API
  53
  54 #.  The worker lcores all share a single cache line with the distributor core in order to pass messages and packets to and from the worker.
  55     The process API call will poll all the worker cache lines to see what workers are requesting packets.
  56
  57 #.  As workers request packets, the distributor takes packets from the set of packets passed in and distributes them to the workers.
  58     As it does so, it examines the "tag" -- stored in the RSS hash field in the mbuf -- for each packet
  59     and records what tags are being processed by each  worker.
  60
  61 #.  If the next packet in the input set has a tag which is already being processed by a worker,
  62     then that packet will be queued up for processing by that worker
  63     and given to it in preference to other packets when that work next makes a request for work.
  64     This ensures that no two packets with the same tag are processed in parallel,
  65     and that all packets with the same tag are processed in input order.
  66
  67 #.  Once all input packets passed to the process API have either been distributed to workers
  68     or been queued up for a worker which is processing a given tag,
  69     then the process API returns to the caller.
  70
  71 Other functions which are available to the distributor lcore are:
  72
  73 *   rte_distributor_returned_pkts()
  74
  75 *   rte_distributor_flush()
  76
  77 *   rte_distributor_clear_returns()
  78
  79 Of these the most important API call is "rte_distributor_returned_pkts()"
  80 which should only be called on the lcore which also calls the process API.
  81 It returns to the caller all packets which have finished processing by all worker cores.
  82 Within this set of returned packets, all packets sharing the same tag will be returned in their original order.
  83
  84 **NOTE:**
  85 If worker lcores buffer up packets internally for transmission in bulk afterwards,
  86 the packets sharing a tag will likely get out of order.
  87 Once a worker lcore requests a new packet, the distributor assumes that it has completely finished with the previous packet and
  88 therefore that additional packets with the same tag can safely be distributed to other workers --
  89 who may then flush their buffered packets sooner and cause packets to get out of order.
  90
  91 **NOTE:**
  92 No packet ordering guarantees are made about packets which do not share a common packet tag.
  93
  94 Using the process and returned_pkts API, the following application workflow can be used,
  95 while allowing packet order within a packet flow -- identified by a tag -- to be maintained.
  96
  97
  98 .. figure:: img/packet_distributor2.*
  99
 100    Application workflow
 101
 102
 103 The flush and clear_returns API calls, mentioned previously,
 104 are likely of less use that the process and returned_pkts APIS, and are principally provided to aid in unit testing of the library.
 105 Descriptions of these functions and their use can be found in the DPDK API Reference document.
 106
 107 Worker Operation
 108 ----------------
 109
 110 Worker cores are the cores which do the actual manipulation of the packets distributed by the packet distributor.
 111 Each worker calls "rte_distributor_get_pkt()" API to request a new packet when it has finished processing the previous one.
 112 [The previous packet should be returned to the distributor component by passing it as the final parameter to this API call.]
 113
 114 Since it may be desirable to vary the number of worker cores, depending on the traffic load
 115 i.e. to save power at times of lighter load,
 116 it is possible to have a worker stop processing packets by calling "rte_distributor_return_pkt()" to indicate that
 117 it has finished the current packet and does not want a new one.