Programmer's Guide
Total Page：16
File Type：pdf, Size：1020Kb
Programmer’s Guide Release 18.11.11 Jan 20, 2021 CONTENTS 1 Introduction 1 1.1 Documentation Roadmap...............................1 1.2 Related Publications..................................2 2 Overview 3 2.1 Development Environment..............................3 2.2 Environment Abstraction Layer............................4 2.3 Core Components...................................4 2.3.1 Ring Manager (librte_ring)..........................4 2.3.2 Memory Pool Manager (librte_mempool)..................4 2.3.3 Network Packet Buffer Management (librte_mbuf).............6 2.3.4 Timer Manager (librte_timer)........................6 2.4 Ethernet* Poll Mode Driver Architecture.......................6 2.5 Packet Forwarding Algorithm Support........................6 2.6 librte_net........................................6 3 Environment Abstraction Layer7 3.1 EAL in a Linux-userland Execution Environment..................7 3.1.1 Initialization and Core Launching......................8 3.1.2 Shutdown and Cleanup...........................8 3.1.3 Multi-process Support............................8 3.1.4 Memory Mapping Discovery and Memory Reservation..........8 3.1.5 Support for Externally Allocated Memory.................. 11 3.1.6 Per-lcore and Shared Variables....................... 12 3.1.7 Logs...................................... 12 3.1.8 CPU Feature Identification.......................... 12 3.1.9 User Space Interrupt Event......................... 13 3.1.10 Blacklisting.................................. 14 3.1.11 Misc Functions................................ 14 3.1.12 IOVA Mode Configuration.......................... 14 3.2 Memory Segments and Memory Zones (memzone)................ 14 3.3 Multiple pthread.................................... 14 3.3.1 EAL pthread and lcore Affinity........................ 15 3.3.2 non-EAL pthread support.......................... 15 3.3.3 Public Thread API.............................. 15 3.3.4 Control Thread API.............................. 16 3.3.5 Known Issues................................. 16 3.3.6 cgroup control................................. 17 3.4 Malloc.......................................... 18 i 3.4.1 Cookies.................................... 18 3.4.2 Alignment and NUMA Constraints...................... 18 3.4.3 Use Cases.................................. 18 3.4.4 Internal Implementation........................... 18 4 Service Cores 23 4.1 Service Core Initialization............................... 23 4.2 Enabling Services on Cores............................. 23 4.3 Service Core Statistics................................ 24 5 Ring Library 25 5.1 References for Ring Implementation in FreeBSD*................. 26 5.2 Lockless Ring Buffer in Linux*............................ 26 5.3 Additional Features.................................. 26 5.3.1 Name..................................... 26 5.4 Use Cases....................................... 26 5.5 Anatomy of a Ring Buffer............................... 26 5.5.1 Single Producer Enqueue.......................... 27 5.5.2 Single Consumer Dequeue......................... 28 5.5.3 Multiple Producers Enqueue......................... 29 5.5.4 Modulo 32-bit Indexes............................ 33 5.6 References....................................... 35 6 Mempool Library 37 6.1 Cookies......................................... 37 6.2 Stats.......................................... 37 6.3 Memory Alignment Constraints............................ 37 6.4 Local Cache...................................... 38 6.5 Mempool Handlers.................................. 39 6.6 Use Cases....................................... 40 7 Mbuf Library 41 7.1 Design of Packet Buffers............................... 41 7.2 Buffers Stored in Memory Pools........................... 43 7.3 Constructors...................................... 43 7.4 Allocating and Freeing mbufs............................. 43 7.5 Manipulating mbufs.................................. 43 7.6 Meta Information.................................... 43 7.7 Direct and Indirect Buffers.............................. 45 7.8 Debug......................................... 46 7.9 Use Cases....................................... 46 8 Poll Mode Driver 47 8.1 Requirements and Assumptions........................... 47 8.2 Design Principles................................... 48 8.3 Logical Cores, Memory and NIC Queues Relationships.............. 49 8.4 Device Identification, Ownership and Configuration................ 49 8.4.1 Device Identification............................. 49 8.4.2 Port Ownership................................ 50 8.4.3 Device Configuration............................. 50 8.4.4 On-the-Fly Configuration........................... 50 8.4.5 Configuration of Transmit Queues...................... 51 ii 8.4.6 Free Tx mbuf on Demand.......................... 52 8.4.7 Hardware Offload............................... 52 8.5 Poll Mode Driver API................................. 53 8.5.1 Generalities.................................. 53 8.5.2 Generic Packet Representation....................... 54 8.5.3 Ethernet Device API............................. 54 8.5.4 Ethernet Device Standard Device Arguments............... 54 8.5.5 Extended Statistics API........................... 54 8.5.6 NIC Reset API................................ 57 9 Generic flow API (rte_flow) 59 9.1 Overview........................................ 59 9.2 Flow rule........................................ 59 9.2.1 Description.................................. 59 9.2.2 Attributes................................... 60 9.2.3 Pattern item.................................. 62 9.2.4 Matching pattern............................... 63 9.2.5 Meta item types................................ 64 9.2.6 Data matching item types.......................... 68 9.2.7 Actions..................................... 77 9.2.8 Action types.................................. 79 9.2.9 Negative types................................ 93 9.2.10 Planned types................................. 93 9.3 Rules management.................................. 93 9.3.1 Validation................................... 93 9.3.2 Creation.................................... 94 9.3.3 Destruction.................................. 95 9.3.4 Flush...................................... 95 9.3.5 Query..................................... 96 9.4 Isolated mode..................................... 96 9.5 Verbose error reporting................................ 97 9.6 Helpers......................................... 98 9.6.1 Error initializer................................. 98 9.6.2 Object conversion............................... 98 9.7 Caveats......................................... 99 9.8 PMD interface..................................... 99 9.9 Device compatibility.................................. 100 9.9.1 Global bit-masks............................... 100 9.9.2 Unsupported layer types........................... 100 9.9.3 ANY pattern item............................... 100 9.9.4 Unsupported actions............................. 101 9.9.5 Flow rules priority............................... 101 9.10 Future evolutions................................... 102 10 Switch Representation within DPDK Applications 103 10.1 Introduction....................................... 104 10.2 Port Representors................................... 104 10.3 Basic SR-IOV..................................... 105 10.4 Controlled SR-IOV................................... 106 10.4.1 Initialization.................................. 106 10.4.2 VF Representors............................... 107 10.4.3 Traffic Steering................................ 108 iii 10.5 Flow API (rte_flow).................................. 109 10.5.1 Extensions.................................. 109 10.5.2 Traffic Direction................................ 109 10.5.3 Transferring Traffic.............................. 110 10.5.4 Pattern Items And Actions.......................... 112 10.5.5 Actions Order and Repetition........................ 114 10.6 Switching Examples.................................. 114 10.6.1 Associating VF 1 with Physical Port 0.................... 115 10.6.2 Sharing Broadcasts............................. 115 10.6.3 Encapsulating VF 2 Traffic in VXLAN.................... 116 11 Traffic Metering and Policing API 117 11.1 Overview........................................ 117 11.2 Configuration steps.................................. 117 11.3 Run-time processing................................. 117 12 Traffic Management API 119 12.1 Overview........................................ 119 12.2 Capability API..................................... 119 12.3 Scheduling Algorithms................................ 120 12.4 Traffic Shaping..................................... 120 12.5 Congestion Management............................... 120 12.6 Packet Marking.................................... 121 12.7 Steps to Setup the Hierarchy............................. 121 12.7.1 Initial Hierarchy Specification........................ 122 12.7.2 Hierarchy Commit.............................. 122 12.7.3 Run-Time Hierarchy Updates........................ 122 13 Wireless Baseband Device Library 123 13.1 Design Principles................................... 123 13.2 Device Management................................. 123 13.2.1 Device Creation................................ 123 13.2.2 Device Identification............................. 124 13.2.3 Device Configuration............................. 124 13.2.4 Queues Configuration............................ 124 13.2.5 Device & Queues