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 |today|
  35
  36
  37 **Contents**
  38
  39 .. toctree::
  40     :maxdepth: 3
  41     :numbered:
  42
  43     intro
  44     overview
  45     env_abstraction_layer
  46     malloc_lib
  47     ring_lib
  48     mempool_lib
  49     mbuf_lib
  50     poll_mode_drv
  51     i40e_ixgbe_igb_virt_func_drv
  52     driver_vm_emul_dev
  53     ivshmem_lib
  54     poll_mode_drv_emulated_virtio_nic
  55     poll_mode_drv_paravirtual_vmxnets_nic
  56     intel_dpdk_xen_based_packet_switch_sol
  57     libpcap_ring_based_poll_mode_drv
  58     link_bonding_poll_mode_drv_lib
  59     mlx4_poll_mode_drv
  60     timer_lib
  61     hash_lib
  62     lpm_lib
  63     lpm6_lib
  64     packet_distrib_lib
  65     reorder_lib
  66     ip_fragment_reassembly_lib
  67     multi_proc_support
  68     kernel_nic_interface
  69     thread_safety_intel_dpdk_functions
  70     qos_framework
  71     power_man
  72     packet_classif_access_ctrl
  73     packet_framework
  74     vhost_lib
  75     port_hotplug_framework
  76     source_org
  77     dev_kit_build_system
  78     dev_kit_root_make_help
  79     extend_intel_dpdk
  80     build_app
  81     ext_app_lib_make_help
  82     perf_opt_guidelines
  83     writing_efficient_code
  84     profile_app
  85     glossary
  86
  87
  88 **Figures**
  89
  90 :ref:`Figure 1. Core Components Architecture <pg_figure_1>`
  91
  92 :ref:`Figure 2. EAL Initialization in a Linux Application Environment <pg_figure_2>`
  93
  94 :ref:`Figure 3. Example of a malloc heap and malloc elements within the malloc library <pg_figure_3>`
  95
  96 :ref:`Figure 4. Ring Structure <pg_figure_4>`
  97
  98 :ref:`Figure 5. Two Channels and Quad-ranked DIMM Example <pg_figure_5>`
  99
 100 :ref:`Figure 6. Three Channels and Two Dual-ranked DIMM Example <pg_figure_6>`
 101
 102 :ref:`Figure 7. A mempool in Memory with its Associated Ring <pg_figure_7>`
 103
 104 :ref:`Figure 8. An mbuf with One Segment <pg_figure_8>`
 105
 106 :ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
 107
 108 :ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode <pg_figure_10>`
 109
 110 :ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
 111
 112 :ref:`Figure 12. Fast Host-based Packet Processing <pg_figure_12>`
 113
 114 :ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
 115
 116 :ref:`Figure 14. Host2VM Communication Example Using kni vhost Back End <pg_figure_14>`
 117
 118 :ref:`Figure 15. Host2VM Communication Example Using qemu vhost Back End <pg_figure_15>`
 119
 120 :ref:`Figure 16. Memory Sharing inthe Intel® DPDK Multi-process Sample Application <pg_figure_16>`
 121
 122 :ref:`Figure 17. Components of an Intel® DPDK KNI Application <pg_figure_17>`
 123
 124 :ref:`Figure 18. Packet Flow via mbufs in the Intel DPDK® KNI <pg_figure_18>`
 125
 126 :ref:`Figure 19. vHost-net Architecture Overview <pg_figure_19>`
 127
 128 :ref:`Figure 20. KNI Traffic Flow <pg_figure_20>`
 129
 130 :ref:`Figure 21. Complex Packet Processing Pipeline with QoS Support <pg_figure_21>`
 131
 132 :ref:`Figure 22. Hierarchical Scheduler Block Internal Diagram <pg_figure_22>`
 133
 134 :ref:`Figure 23. Scheduling Hierarchy per Port <pg_figure_23>`
 135
 136 :ref:`Figure 24. Internal Data Structures per Port <pg_figure_24>`
 137
 138 :ref:`Figure 25. Prefetch Pipeline for the Hierarchical Scheduler Enqueue Operation <pg_figure_25>`
 139
 140 :ref:`Figure 26. Pipe Prefetch State Machine for the Hierarchical Scheduler Dequeue Operation <pg_figure_26>`
 141
 142 :ref:`Figure 27. High-level Block Diagram of the Intel® DPDK Dropper <pg_figure_27>`
 143
 144 :ref:`Figure 28. Flow Through the Dropper <pg_figure_28>`
 145
 146 :ref:`Figure 29. Example Data Flow Through Dropper <pg_figure_29>`
 147
 148 :ref:`Figure 30. Packet Drop Probability for a Given RED Configuration <pg_figure_30>`
 149
 150 :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>`
 151
 152 :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>`
 153
 154 :ref:`Figure 33. Sequence of steps for hash table operations in packet processing context <pg_figure_33>`
 155
 156 :ref:`Figure 34. Data structures for configurable key size hash tables <pg_figure_34>`
 157
 158 :ref:`Figure 35. Bucket search pipeline for key lookup operation (configurable key size hash tables) <pg_figure_35>`
 159
 160 :ref:`Figure 36. Pseudo-code for match, match_many and match_pos <pg_figure_36>`
 161
 162 :ref:`Figure 37. Data structures for 8-byte key hash tables <pg_figure_37>`
 163
 164 :ref:`Figure 38. Data structures for 16-byte key hash tables <pg_figure_38>`
 165
 166 :ref:`Figure 39. Bucket search pipeline for key lookup operation (single key size hash tables) <pg_figure_39>`
 167
 168 **Tables**
 169
 170 :ref:`Table 1. Packet Processing Pipeline Implementing QoS <pg_table_1>`
 171
 172 :ref:`Table 2. Infrastructure Blocks Used by the Packet Processing Pipeline <pg_table_2>`
 173
 174 :ref:`Table 3. Port Scheduling Hierarchy <pg_table_3>`
 175
 176 :ref:`Table 4. Scheduler Internal Data Structures per Port <pg_table_4>`
 177
 178 :ref:`Table 5. Ethernet Frame Overhead Fields <pg_table_5>`
 179
 180 :ref:`Table 6. Token Bucket Generic Operations <pg_table_6>`
 181
 182 :ref:`Table 7. Token Bucket Generic Parameters <pg_table_7>`
 183
 184 :ref:`Table 8. Token Bucket Persistent Data Structure <pg_table_8>`
 185
 186 :ref:`Table 9. Token Bucket Operations <pg_table_9>`
 187
 188 :ref:`Table 10. Subport/Pipe Traffic Class Upper Limit Enforcement Persistent Data Structure <pg_table_10>`
 189
 190 :ref:`Table 11. Subport/Pipe Traffic Class Upper Limit Enforcement Operations <pg_table_11>`
 191
 192 :ref:`Table 12. Weighted Round Robin (WRR) <pg_table_12>`
 193
 194 :ref:`Table 13. Subport Traffic Class Oversubscription <pg_table_13>`
 195
 196 :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>`
 197
 198 :ref:`Table 15. Watermark Calculation <pg_table_15>`
 199
 200 :ref:`Table 16. RED Configuration Parameters <pg_table_16>`
 201
 202 :ref:`Table 17. Relative Performance of Alternative Approaches <pg_table_17>`
 203
 204 :ref:`Table 18. RED Configuration Corresponding to RED Configuration File <pg_table_18>`
 205
 206 :ref:`Table 19. Port types <pg_table_19>`
 207
 208 :ref:`Table 20. Port abstract interface <pg_table_20>`
 209
 210 :ref:`Table 21. Table types <pg_table_21>`
 211
 212 :ref:`Table 29. Table Abstract Interface <pg_table_29_1>`
 213
 214 :ref:`Table 22. Configuration parameters common for all hash table types <pg_table_22>`
 215
 216 :ref:`Table 23. Configuration parameters specific to extendible bucket hash table <pg_table_23>`
 217
 218 :ref:`Table 24. Configuration parameters specific to pre-computed key signature hash table <pg_table_24>`
 219
 220 :ref:`Table 25. The main large data structures (arrays) used for configurable key size hash tables <pg_table_25>`
 221
 222 :ref:`Table 26. Field description for bucket array entry (configurable key size hash tables) <pg_table_26>`
 223
 224 :ref:`Table 27. Description of the bucket search pipeline stages (configurable key size hash tables) <pg_table_27>`
 225
 226 :ref:`Table 28. Lookup tables for match, match_many, match_pos <pg_table_28>`
 227
 228 :ref:`Table 29. Collapsed lookup tables for match, match_many and match_pos <pg_table_29>`
 229
 230 :ref:`Table 30. The main large data structures (arrays) used for 8-byte and 16-byte key size hash tables <pg_table_30>`
 231
 232 :ref:`Table 31. Field description for bucket array entry (8-byte and 16-byte key hash tables) <pg_table_31>`
 233
 234 :ref:`Table 32. Description of the bucket search pipeline stages (8-byte and 16-byte key hash tables) <pg_table_32>`
 235
 236 :ref:`Table 33. Next hop actions (reserved) <pg_table_33>`
 237
 238 :ref:`Table 34. User action examples <pg_table_34>`