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