doc/guides/prog_guide/index.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 Programmer's Guide
  32 ==================
  33
  34 June 2014
  35
  36
  37 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE,
  38 TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS,
  39 INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY
  40 OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
  41
  42 A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or indirectly, in personal injury or death.
  43 SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES, SUBCONTRACTORS AND AFFILIATES,
  44 AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY,
  45 ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION,
  46 WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS PARTS.
  47
  48 Intel may make changes to specifications and product descriptions at any time, without notice.
  49 Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined".
  50 Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.
  51 The information here is subject to change without notice. Do not finalize a design with this information.
  52
  53 The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications.
  54 Current characterized errata are available on request.
  55
  56 Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
  57
  58 Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548- 4725,
  59 or go to: http://www.intel.com/design/literature.htm.
  60
  61 Any software source code reprinted in this document is furnished for informational purposes only and may only be used or copied and no license, express or implied,
  62 by estoppel or otherwise, to any of the reprinted source code is granted by this document.
  63
  64 Code Names are only for use by Intel to identify products, platforms, programs, services, etc.
  65 ("products") in development by Intel that have not been made commercially available to the public, i.e., announced, launched or shipped.
  66 They are never to be used as "commercial" names for products. Also, they are not intended to function as trademarks.
  67
  68 Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.
  69
  70 \*Other names and brands may be claimed as the property of others.
  71
  72 Copyright © 2012-2014, Intel Corporation. All rights reserved.
  73
  74 **Contents**
  75
  76 .. toctree::
  77     :maxdepth: 3
  78     :numbered:
  79
  80     intro
  81     overview
  82     env_abstraction_layer
  83     malloc_lib
  84     ring_lib
  85     mempool_lib
  86     mbuf_lib
  87     poll_mode_drv
  88     i40e_ixgbe_igb_virt_func_drv
  89     driver_vm_emul_dev
  90     ivshmem_lib
  91     poll_mode_drv_emulated_virtio_nic
  92     poll_mode_drv_paravirtual_vmxnets_nic
  93     intel_dpdk_xen_based_packet_switch_sol
  94     libpcap_ring_based_poll_mode_drv
  95     link_bonding_poll_mode_drv_lib
  96     timer_lib
  97     hash_lib
  98     lpm_lib
  99     lpm6_lib
 100     packet_distrib_lib
 101     ip_fragment_reassembly_lib
 102     multi_proc_support
 103     kernel_nic_interface
 104     thread_safety_intel_dpdk_functions
 105     qos_framework
 106     power_man
 107     packet_classif_access_ctrl
 108     packet_framework
 109     source_org
 110     dev_kit_build_system
 111     dev_kit_root_make_help
 112     extend_intel_dpdk
 113     build_app
 114     ext_app_lib_make_help
 115     perf_opt_guidelines
 116     writing_efficient_code
 117     profile_app
 118     glossary
 119
 120
 121 **Figures**
 122
 123 :ref:`Figure 1. Core Components Architecture <pg_figure_1>`
 124
 125 :ref:`Figure 2. EAL Initialization in a Linux Application Environment <pg_figure_2>`
 126
 127 :ref:`Figure 3. Example of a malloc heap and malloc elements within the malloc library <pg_figure_3>`
 128
 129 :ref:`Figure 4. Ring Structure <pg_figure_4>`
 130
 131 :ref:`Figure 5. Two Channels and Quad-ranked DIMM Example <pg_figure_5>`
 132
 133 :ref:`Figure 6. Three Channels and Two Dual-ranked DIMM Example <pg_figure_6>`
 134
 135 :ref:`Figure 7. A mempool in Memory with its Associated Ring <pg_figure_7>`
 136
 137 :ref:`Figure 8. An mbuf with One Segment <pg_figure_8>`
 138
 139 :ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
 140
 141 :ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode <pg_figure_10>`
 142
 143 :ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
 144
 145 :ref:`Figure 12. Fast Host-based Packet Processing <pg_figure_12>`
 146
 147 :ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
 148
 149 :ref:`Figure 14. Host2VM Communication Example Using kni vhost Back End <pg_figure_14>`
 150
 151 :ref:`Figure 15. Host2VM Communication Example Using qemu vhost Back End <pg_figure_15>`
 152
 153 :ref:`Figure 16. Memory Sharing inthe Intel® DPDK Multi-process Sample Application <pg_figure_16>`
 154
 155 :ref:`Figure 17. Components of an Intel® DPDK KNI Application <pg_figure_17>`
 156
 157 :ref:`Figure 18. Packet Flow via mbufs in the Intel DPDK® KNI <pg_figure_18>`
 158
 159 :ref:`Figure 19. vHost-net Architecture Overview <pg_figure_19>`
 160
 161 :ref:`Figure 20. KNI Traffic Flow <pg_figure_20>`
 162
 163 :ref:`Figure 21. Complex Packet Processing Pipeline with QoS Support <pg_figure_21>`
 164
 165 :ref:`Figure 22. Hierarchical Scheduler Block Internal Diagram <pg_figure_22>`
 166
 167 :ref:`Figure 23. Scheduling Hierarchy per Port <pg_figure_23>`
 168
 169 :ref:`Figure 24. Internal Data Structures per Port <pg_figure_24>`
 170
 171 :ref:`Figure 25. Prefetch Pipeline for the Hierarchical Scheduler Enqueue Operation <pg_figure_25>`
 172
 173 :ref:`Figure 26. Pipe Prefetch State Machine for the Hierarchical Scheduler Dequeue Operation <pg_figure_26>`
 174
 175 :ref:`Figure 27. High-level Block Diagram of the Intel® DPDK Dropper <pg_figure_27>`
 176
 177 :ref:`Figure 28. Flow Through the Dropper <pg_figure_28>`
 178
 179 :ref:`Figure 29. Example Data Flow Through Dropper <pg_figure_29>`
 180
 181 :ref:`Figure 30. Packet Drop Probability for a Given RED Configuration <pg_figure_30>`
 182
 183 :ref:`Figure 31. Initial Drop Probability (pb), Actual Drop probability (pa) Computed Using a Factor 1 (Blue Curve) and a Factor 2 (Red Curve) <pg_figure_31>`
 184
 185 :ref:`Figure 32. Example of packet processing pipeline. The input ports 0 and 1 are connected with the output ports 0, 1 and 2 through tables 0 and 1. <pg_figure_32>`
 186
 187 :ref:`Figure 33. Sequence of steps for hash table operations in packet processing context <pg_figure_33>`
 188
 189 :ref:`Figure 34. Data structures for configurable key size hash tables <pg_figure_34>`
 190
 191 :ref:`Figure 35. Bucket search pipeline for key lookup operation (configurable key size hash tables) <pg_figure_35>`
 192
 193 :ref:`Figure 36. Pseudo-code for match, match_many and match_pos <pg_figure_36>`
 194
 195 :ref:`Figure 37. Data structures for 8-byte key hash tables <pg_figure_37>`
 196
 197 :ref:`Figure 38. Data structures for 16-byte key hash tables <pg_figure_38>`
 198
 199 :ref:`Figure 39. Bucket search pipeline for key lookup operation (single key size hash tables) <pg_figure_39>`
 200
 201 **Tables**
 202
 203 :ref:`Table 1. Packet Processing Pipeline Implementing QoS <pg_table_1>`
 204
 205 :ref:`Table 2. Infrastructure Blocks Used by the Packet Processing Pipeline <pg_table_2>`
 206
 207 :ref:`Table 3. Port Scheduling Hierarchy <pg_table_3>`
 208
 209 :ref:`Table 4. Scheduler Internal Data Structures per Port <pg_table_4>`
 210
 211 :ref:`Table 5. Ethernet Frame Overhead Fields <pg_table_5>`
 212
 213 :ref:`Table 6. Token Bucket Generic Operations <pg_table_6>`
 214
 215 :ref:`Table 7. Token Bucket Generic Parameters <pg_table_7>`
 216
 217 :ref:`Table 8. Token Bucket Persistent Data Structure <pg_table_8>`
 218
 219 :ref:`Table 9. Token Bucket Operations <pg_table_9>`
 220
 221 :ref:`Table 10. Subport/Pipe Traffic Class Upper Limit Enforcement Persistent Data Structure <pg_table_10>`
 222
 223 :ref:`Table 11. Subport/Pipe Traffic Class Upper Limit Enforcement Operations <pg_table_11>`
 224
 225 :ref:`Table 12. Weighted Round Robin (WRR) <pg_table_12>`
 226
 227 :ref:`Table 13. Subport Traffic Class Oversubscription <pg_table_13>`
 228
 229 :ref:`Table 14. Watermark Propagation from Subport Level to Member Pipes at the Beginning of Each Traffic Class Upper Limit Enforcement Period <pg_table_14>`
 230
 231 :ref:`Table 15. Watermark Calculation <pg_table_15>`
 232
 233 :ref:`Table 16. RED Configuration Parameters <pg_table_16>`
 234
 235 :ref:`Table 17. Relative Performance of Alternative Approaches <pg_table_17>`
 236
 237 :ref:`Table 18. RED Configuration Corresponding to RED Configuration File <pg_table_18>`
 238
 239 :ref:`Table 19. Port types <pg_table_19>`
 240
 241 :ref:`Table 20. Port abstract interface <pg_table_20>`
 242
 243 :ref:`Table 21. Table types <pg_table_21>`
 244
 245 :ref:`Table 29. Table Abstract Interface <pg_table_29_1>`
 246
 247 :ref:`Table 22. Configuration parameters common for all hash table types <pg_table_22>`
 248
 249 :ref:`Table 23. Configuration parameters specific to extendible bucket hash table <pg_table_23>`
 250
 251 :ref:`Table 24. Configuration parameters specific to pre-computed key signature hash table <pg_table_24>`
 252
 253 :ref:`Table 25. The main large data structures (arrays) used for configurable key size hash tables <pg_table_25>`
 254
 255 :ref:`Table 26. Field description for bucket array entry (configurable key size hash tables) <pg_table_26>`
 256
 257 :ref:`Table 27. Description of the bucket search pipeline stages (configurable key size hash tables) <pg_table_27>`
 258
 259 :ref:`Table 28. Lookup tables for match, match_many, match_pos <pg_table_28>`
 260
 261 :ref:`Table 29. Collapsed lookup tables for match, match_many and match_pos <pg_table_29>`
 262
 263 :ref:`Table 30. The main large data structures (arrays) used for 8-byte and 16-byte key size hash tables <pg_table_30>`
 264
 265 :ref:`Table 31. Field description for bucket array entry (8-byte and 16-byte key hash tables) <pg_table_31>`
 266
 267 :ref:`Table 32. Description of the bucket search pipeline stages (8-byte and 16-byte key hash tables) <pg_table_32>`
 268
 269 :ref:`Table 33. Next hop actions (reserved) <pg_table_33>`
 270
 271 :ref:`Table 34. User action examples <pg_table_34>`