Navigation
index
next
|
previous
|
Data Plane Development Kit 19.11.3 documentation
»
Programmer’s Guide
1. Introduction
1.1. Documentation Roadmap
1.2. Related Publications
2. Overview
2.1. Development Environment
2.2. Environment Abstraction Layer
2.3. Core Components
2.3.1. Ring Manager (librte_ring)
2.3.2. Memory Pool Manager (librte_mempool)
2.3.3. Network Packet Buffer Management (librte_mbuf)
2.3.4. Timer Manager (librte_timer)
2.4. Ethernet* Poll Mode Driver Architecture
2.5. Packet Forwarding Algorithm Support
2.6. librte_net
3. Environment Abstraction Layer
3.1. EAL in a Linux-userland Execution Environment
3.1.1. Initialization and Core Launching
3.1.2. Shutdown and Cleanup
3.1.3. Multi-process Support
3.1.4. Memory Mapping Discovery and Memory Reservation
3.1.5. Support for Externally Allocated Memory
3.1.6. Per-lcore and Shared Variables
3.1.7. Logs
3.1.8. CPU Feature Identification
3.1.9. User Space Interrupt Event
3.1.10. Blacklisting
3.1.11. Misc Functions
3.1.12. IOVA Mode Detection
3.1.13. IOVA Mode Configuration
3.2. Memory Segments and Memory Zones (memzone)
3.3. Multiple pthread
3.3.1. EAL pthread and lcore Affinity
3.3.2. non-EAL pthread support
3.3.3. Public Thread API
3.3.4. Control Thread API
3.3.5. Known Issues
3.3.6. cgroup control
3.4. Malloc
3.4.1. Cookies
3.4.2. Alignment and NUMA Constraints
3.4.3. Use Cases
3.4.4. Internal Implementation
4. Service Cores
4.1. Service Core Initialization
4.2. Enabling Services on Cores
4.3. Service Core Statistics
5. RCU Library
5.1. What is Quiescent State
5.2. Factors affecting the RCU mechanism
5.3. RCU in DPDK
5.4. How to use this library
6. Ring Library
6.1. References for Ring Implementation in FreeBSD*
6.2. Lockless Ring Buffer in Linux*
6.3. Additional Features
6.3.1. Name
6.4. Use Cases
6.5. Anatomy of a Ring Buffer
6.5.1. Single Producer Enqueue
6.5.2. Single Consumer Dequeue
6.5.3. Multiple Producers Enqueue
6.5.4. Modulo 32-bit Indexes
6.6. References
7. Stack Library
7.1. Implementation
7.1.1. Lock-based Stack
7.1.2. Lock-free Stack
8. Mempool Library
8.1. Cookies
8.2. Stats
8.3. Memory Alignment Constraints
8.4. Local Cache
8.5. Mempool Handlers
8.6. Use Cases
9. Mbuf Library
9.1. Design of Packet Buffers
9.2. Buffers Stored in Memory Pools
9.3. Constructors
9.4. Allocating and Freeing mbufs
9.5. Manipulating mbufs
9.6. Meta Information
9.7. Direct and Indirect Buffers
9.8. Debug
9.9. Use Cases
10. Poll Mode Driver
10.1. Requirements and Assumptions
10.2. Design Principles
10.3. Logical Cores, Memory and NIC Queues Relationships
10.4. Device Identification, Ownership and Configuration
10.4.1. Device Identification
10.4.2. Port Ownership
10.4.3. Device Configuration
10.4.4. On-the-Fly Configuration
10.4.5. Configuration of Transmit Queues
10.4.6. Free Tx mbuf on Demand
10.4.7. Hardware Offload
10.5. Poll Mode Driver API
10.5.1. Generalities
10.5.2. Generic Packet Representation
10.5.3. Ethernet Device API
10.5.4. Ethernet Device Standard Device Arguments
10.5.5. Extended Statistics API
10.5.6. NIC Reset API
11. Generic flow API (rte_flow)
11.1. Overview
11.2. Flow rule
11.2.1. Description
11.2.2. Attributes
11.2.3. Pattern item
11.2.4. Matching pattern
11.2.5. Meta item types
11.2.6. Data matching item types
11.2.7. Actions
11.2.8. Action types
11.2.9. Negative types
11.2.10. Planned types
11.3. Rules management
11.3.1. Validation
11.3.2. Creation
11.3.3. Destruction
11.3.4. Flush
11.3.5. Query
11.4. Flow isolated mode
11.5. Verbose error reporting
11.6. Helpers
11.6.1. Error initializer
11.6.2. Object conversion
11.7. Caveats
11.8. PMD interface
11.9. Device compatibility
11.9.1. Global bit-masks
11.9.2. Unsupported layer types
11.9.3.
ANY
pattern item
11.9.4. Unsupported actions
11.9.5. Flow rules priority
11.10. Future evolutions
12. Switch Representation within DPDK Applications
12.1. Introduction
12.2. Port Representors
12.3. Basic SR-IOV
12.4. Controlled SR-IOV
12.4.1. Initialization
12.4.2. VF Representors
12.4.3. Traffic Steering
12.5. Flow API (rte_flow)
12.5.1. Extensions
12.5.2. Traffic Direction
12.5.3. Transferring Traffic
12.5.4. Pattern Items And Actions
12.5.5. Actions Order and Repetition
12.6. Switching Examples
12.6.1. Associating VF 1 with Physical Port 0
12.6.2. Sharing Broadcasts
12.6.3. Encapsulating VF 2 Traffic in VXLAN
13. Traffic Metering and Policing API
13.1. Overview
13.2. Configuration steps
13.3. Run-time processing
14. Traffic Management API
14.1. Overview
14.2. Capability API
14.3. Scheduling Algorithms
14.4. Traffic Shaping
14.5. Congestion Management
14.6. Packet Marking
14.7. Steps to Setup the Hierarchy
14.7.1. Initial Hierarchy Specification
14.7.2. Hierarchy Commit
14.7.3. Run-Time Hierarchy Updates
15. Wireless Baseband Device Library
15.1. Design Principles
15.2. Device Management
15.2.1. Device Creation
15.2.2. Device Identification
15.2.3. Device Configuration
15.2.4. Queues Configuration
15.2.5. Device & Queues Management
15.2.6. Logical Cores, Memory and Queues Relationships
15.3. Device Operation Capabilities
15.3.1. Capabilities Discovery
15.4. Operation Processing
15.4.1. Enqueue / Dequeue Burst APIs
15.4.2. Operation Representation
15.4.3. Operation Management and Allocation
15.4.4. BBDEV Inbound/Outbound Memory
15.4.5. BBDEV Turbo Encode Operation
15.4.6. BBDEV Turbo Decode Operation
15.4.7. BBDEV LDPC Encode Operation
15.4.8. BBDEV LDPC Decode Operation
15.5. Sample code
15.5.1. BBDEV Device API
16. Cryptography Device Library
16.1. Design Principles
16.2. Device Management
16.2.1. Device Creation
16.2.2. Device Identification
16.2.3. Device Configuration
16.2.4. Configuration of Queue Pairs
16.2.5. Logical Cores, Memory and Queues Pair Relationships
16.3. Device Features and Capabilities
16.3.1. Device Features
16.3.2. Device Operation Capabilities
16.3.3. Capabilities Discovery
16.4. Operation Processing
16.4.1. Private data
16.4.2. Enqueue / Dequeue Burst APIs
16.4.3. Operation Representation
16.4.4. Operation Management and Allocation
16.5. Symmetric Cryptography Support
16.5.1. Session and Session Management
16.5.2. Transforms and Transform Chaining
16.5.3. Symmetric Operations
16.6. Sample code
16.7. Asymmetric Cryptography
16.7.1. Session and Session Management
16.7.2. Asymmetric Sessionless Support
16.7.3. Transforms and Transform Chaining
16.7.4. Asymmetric Operations
16.8. Asymmetric crypto Sample code
16.8.1. Asymmetric Crypto Device API
17. Compression Device Library
17.1. Device Management
17.1.1. Device Creation
17.1.2. Device Identification
17.1.3. Device Configuration
17.1.4. Configuration of Queue Pairs
17.1.5. Logical Cores, Memory and Queues Pair Relationships
17.2. Device Features and Capabilities
17.2.1. Capabilities
17.2.2. Capabilities Discovery
17.3. Compression Operation
17.3.1. Operation Representation
17.3.2. Operation Management and Allocation
17.3.3. Passing source data as mbuf-chain
17.3.4. Operation Status
17.3.5. Operation status after enqueue / dequeue
17.3.6. Produced, Consumed And Operation Status
17.4. Transforms
17.5. Compression API Hash support
17.6. Compression API Stateless operation
17.6.1. priv_xform in Stateless operation
17.6.2. Stateless and OUT_OF_SPACE
17.6.3. Hash in Stateless
17.6.4. Checksum in Stateless
17.7. Compression API Stateful operation
17.7.1. Stream in Stateful operation
17.7.2. Stateful and OUT_OF_SPACE
17.7.3. Hash in Stateful
17.7.4. Checksum in Stateful
17.8. Burst in compression API
17.8.1. Enqueue / Dequeue Burst APIs
17.9. Sample code
17.9.1. Compression Device API
18. Security Library
18.1. Design Principles
18.1.1. Inline Crypto
18.1.2. Inline protocol offload
18.1.3. Lookaside protocol offload
18.1.4. PDCP Flow Diagram
18.2. Device Features and Capabilities
18.2.1. Device Capabilities For Security Operations
18.2.2. Capabilities Discovery
18.2.3. Security Session Create/Free
18.2.4. Security session configuration
18.2.5. Security API
18.2.6. Flow based Security Session
19. Rawdevice Library
19.1. Introduction
19.2. Design
19.2.1. Device Identification
20. Link Bonding Poll Mode Driver Library
20.1. Link Bonding Modes Overview
20.2. Implementation Details
20.2.1. Link Status Change Interrupts / Polling
20.2.2. Requirements / Limitations
20.2.3. Configuration
20.3. Using Link Bonding Devices
20.3.1. Using the Poll Mode Driver from an Application
20.3.2. Using Link Bonding Devices from the EAL Command Line
21. Timer Library
21.1. Implementation Details
21.2. Use Cases
21.3. References
22. Hash Library
22.1. Hash API Overview
22.2. Multi-process support
22.3. Multi-thread support
22.4. Extendable Bucket Functionality support
22.5. Implementation Details (non Extendable Bucket Case)
22.6. Implementation Details (with Extendable Bucket)
22.7. Entry distribution in hash table
22.8. Use Case: Flow Classification
22.9. References
23. Elastic Flow Distributor Library
23.1. Introduction
23.2. Flow Based Distribution
23.2.1. Computation Based Schemes
23.2.2. Flow-Table Based Schemes
23.2.3. EFD Based Scheme
23.3. Example of EFD Library Usage
23.4. Library API Overview
23.4.1. EFD Table Create
23.4.2. EFD Insert and Update
23.4.3. EFD Lookup
23.4.4. EFD Delete
23.5. Library Internals
23.5.1. Insert Function Internals
23.5.2. Lookup Function Internals
23.5.3. Group Rebalancing Function Internals
23.6. References
24. Membership Library
24.1. Introduction
24.2. Vector of Bloom Filters
24.3. Hash-Table based Set-Summaries
24.3.1. Set-Summaries with False Negative Probability
24.4. Library API Overview
24.4.1. Set-summary Create
24.4.2. Set-summary Element Insertion
24.4.3. Set-summary Element Lookup
24.4.4. Set-summary Element Delete
24.5. References
25. LPM Library
25.1. LPM API Overview
25.2. Implementation Details
25.2.1. Addition
25.2.2. Lookup
25.2.3. Limitations in the Number of Rules
25.2.4. Use Case: IPv4 Forwarding
25.2.5. References
26. LPM6 Library
26.1. LPM6 API Overview
26.1.1. Implementation Details
26.1.2. Addition
26.1.3. Lookup
26.1.4. Limitations in the Number of Rules
26.2. Use Case: IPv6 Forwarding
27. Flow Classification Library
27.1. Overview
27.1.1. Classifier creation
27.1.2. Adding a table to the Classifier
27.1.3. Flow Parsing
27.1.4. Adding Flow Rules
27.1.5. Deleting Flow Rules
27.1.6. Packet Matching
28. Packet Distributor Library
28.1. Distributor Core Operation
28.2. Worker Operation
29. Reorder Library
29.1. Operation
29.2. Implementation Details
29.3. Use Case: Packet Distributor
30. IP Fragmentation and Reassembly Library
30.1. Packet fragmentation
30.2. Packet reassembly
30.2.1. IP Fragment Table
30.2.2. Packet Reassembly
30.2.3. Debug logging and Statistics Collection
31. Generic Receive Offload Library
31.1. Overview
31.2. Two Sets of API
31.2.1. Lightweight Mode API
31.2.2. Heavyweight Mode API
31.3. Reassembly Algorithm
31.3.1. Challenges
31.3.2. Key-based Reassembly Algorithm
31.4. TCP/IPv4 GRO
31.5. VxLAN GRO
31.6. GRO Library Limitations
32. Generic Segmentation Offload Library
32.1. Overview
32.2. Limitations
32.3. Packet Segmentation
32.3.1. GSO Output Segment Format
32.4. Supported GSO Packet Types
32.4.1. TCP/IPv4 GSO
32.4.2. UDP/IPv4 GSO
32.4.3. VxLAN GSO
32.4.4. GRE GSO
32.5. How to Segment a Packet
33. The librte_pdump Library
33.1. Operation
33.2. Implementation Details
33.3. Use Case: Packet Capturing
34. Multi-process Support
34.1. Memory Sharing
34.2. Deployment Models
34.2.1. Symmetric/Peer Processes
34.2.2. Asymmetric/Non-Peer Processes
34.2.3. Running Multiple Independent DPDK Applications
34.2.4. Running Multiple Independent Groups of DPDK Applications
34.3. Multi-process Limitations
34.4. Communication between multiple processes
34.4.1. Registering for incoming messages
34.4.2. Sending messages
34.4.3. Sending requests
34.4.4. Receiving and responding to messages
34.4.5. Misc considerations
35. Kernel NIC Interface
35.1. The DPDK KNI Kernel Module
35.1.1. Loopback Mode
35.1.2. Kernel Thread Mode
35.1.3. Default Carrier State
35.2. KNI Creation and Deletion
35.3. DPDK mbuf Flow
35.4. Use Case: Ingress
35.5. Use Case: Egress
35.6. IOVA = VA: Support
35.7. Ethtool
36. Thread Safety of DPDK Functions
36.1. Fast-Path APIs
36.2. Performance Insensitive API
36.3. Library Initialization
36.4. Interrupt Thread
37. Event Device Library
37.1. Event struct
37.1.1. Event Metadata
37.1.2. Event Payload
37.1.3. Queues
37.1.4. Ports
37.2. API Walk-through
37.2.1. Init and Config
37.2.2. Setting up Queues
37.2.3. Setting up Ports
37.2.4. Linking Queues and Ports
37.2.5. Starting the EventDev
37.2.6. Ingress of New Events
37.2.7. Forwarding of Events
37.2.8. Egress of Events
37.3. Summary
38. Event Ethernet Rx Adapter Library
38.1. API Walk-through
38.1.1. Creating an Adapter Instance
38.1.2. Adding Rx Queues to the Adapter Instance
38.1.3. Querying Adapter Capabilities
38.1.4. Configuring the Service Function
38.1.5. Starting the Adapter Instance
38.1.6. Getting Adapter Statistics
38.1.7. Interrupt Based Rx Queues
38.1.8. Rx Callback for SW Rx Adapter
39. Event Ethernet Tx Adapter Library
39.1. API Walk-through
39.1.1. Creating an Adapter Instance
39.1.2. Adding Tx Queues to the Adapter Instance
39.1.3. Querying Adapter Capabilities
39.1.4. Linking a Queue to the Adapter’s Event Port
39.1.5. Configuring the Service Function
39.1.6. Starting the Adapter Instance
39.1.7. Enqueuing Packets to the Adapter
39.1.8. Getting Adapter Statistics
40. Event Timer Adapter Library
40.1. Event Timer struct
40.1.1. Timer Expiry Event
40.1.2. Timeout Ticks
40.1.3. State
40.1.4. User Metadata
40.2. API Overview
40.2.1. Create and Configure an Adapter Instance
40.2.2. Retrieve Event Timer Adapter Contextual Information
40.2.3. Configuring the Service Component
40.2.4. Starting the Adapter Instance
40.2.5. Arming Event Timers
40.2.6. Canceling Event Timers
40.3. Processing Timer Expiry Events
40.4. Summary
41. Event Crypto Adapter Library
41.1. Adapter Mode
41.1.1. RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode
41.1.2. RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode
41.2. API Overview
41.2.1. Create an adapter instance
41.2.2. Querying adapter capabilities
41.2.3. Adding queue pair to the adapter instance
41.2.4. Configure the service function
41.2.5. Set event request/response information
41.2.6. Start the adapter instance
41.2.7. Get adapter statistics
42. Quality of Service (QoS) Framework
42.1. Packet Pipeline with QoS Support
42.2. Hierarchical Scheduler
42.2.1. Overview
42.2.2. Scheduling Hierarchy
42.2.3. Application Programming Interface (API)
42.2.4. Implementation
42.2.5. Worst Case Scenarios for Performance
42.3. Dropper
42.3.1. Configuration
42.3.2. Enqueue Operation
42.3.3. Queue Empty Operation
42.3.4. Source Files Location
42.3.5. Integration with the DPDK QoS Scheduler
42.3.6. Integration with the DPDK QoS Scheduler Sample Application
42.3.7. Application Programming Interface (API)
42.4. Traffic Metering
42.4.1. Functional Overview
42.4.2. Implementation Overview
43. Power Management
43.1. CPU Frequency Scaling
43.2. Core-load Throttling through C-States
43.3. Per-core Turbo Boost
43.4. Use of Power Library in a Hyper-Threaded Environment
43.5. API Overview of the Power Library
43.6. User Cases
43.7. Empty Poll API
43.7.1. Abstract
43.7.2. Proposed Solution
43.7.3. API Overview for Empty Poll Power Management
43.8. User Cases
43.9. References
44. Packet Classification and Access Control
44.1. Overview
44.1.1. Rule definition
44.1.2. RT memory size limit
44.1.3. Classification methods
44.2. Application Programming Interface (API) Usage
44.2.1. Classify with Multiple Categories
45. Packet Framework
45.1. Design Objectives
45.2. Overview
45.3. Port Library Design
45.3.1. Port Types
45.3.2. Port Interface
45.4. Table Library Design
45.4.1. Table Types
45.4.2. Table Interface
45.4.3. Hash Table Design
45.5. Pipeline Library Design
45.5.1. Connectivity of Ports and Tables
45.5.2. Port Actions
45.5.3. Table Actions
45.6. Multicore Scaling
45.6.1. Shared Data Structures
45.7. Interfacing with Accelerators
46. Vhost Library
46.1. Vhost API Overview
46.2. Vhost-user Implementations
46.3. Guest memory requirement
46.4. Vhost supported vSwitch reference
46.5. Vhost data path acceleration (vDPA)
47. Metrics Library
47.1. Initializing the library
47.2. Registering metrics
47.3. Updating metric values
47.4. Querying metrics
47.5. Deinitialising the library
47.6. Bit-rate statistics library
47.6.1. Initialization
47.6.2. Controlling the sampling rate
47.7. Latency statistics library
47.7.1. Initialization
47.7.2. Triggering statistic updates
47.7.3. Library shutdown
47.7.4. Timestamp and latency calculation
48. Berkeley Packet Filter Library
48.1. Not currently supported eBPF features
49. IPsec Packet Processing Library
49.1. SA level API
49.1.1. RTE_SECURITY_ACTION_TYPE_NONE
49.1.2. RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO
49.1.3. RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL
49.1.4. RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
49.2. SA database API
49.2.1. Create/destroy
49.2.2. Add/delete rules
49.2.3. Lookup
49.3. Supported features
49.4. Limitations
50. Source Organization
50.1. Makefiles and Config
50.2. Libraries
50.3. Drivers
50.4. Applications
51. Development Kit Build System
51.1. Building the Development Kit Binary
51.1.1. Build Directory Concept
51.2. Building External Applications
51.3. Makefile Description
51.3.1. General Rules For DPDK Makefiles
51.3.2. Makefile Types
51.3.3. Internally Generated Build Tools
51.3.4. Useful Variables Provided by the Build System
51.3.5. Variables that Can be Set/Overridden in a Makefile Only
51.3.6. Variables that can be Set/Overridden by the User on the Command Line Only
51.3.7. Variables that Can be Set/Overridden by the User in a Makefile or Command Line
52. Development Kit Root Makefile Help
52.1. Configuration Targets
52.2. Build Targets
52.3. Install Targets
52.4. Test Targets
52.5. Documentation Targets
52.6. Misc Targets
52.7. Other Useful Command-line Variables
52.8. Make in a Build Directory
52.9. Compiling for Debug
53. Extending the DPDK
53.1. Example: Adding a New Library libfoo
53.1.1. Example: Using libfoo in the Test Application
54. Building Your Own Application
54.1. Compiling a Sample Application in the Development Kit Directory
54.2. Build Your Own Application Outside the Development Kit
54.3. Customizing Makefiles
54.3.1. Application Makefile
54.3.2. Library Makefile
54.3.3. Customize Makefile Actions
55. External Application/Library Makefile help
55.1. Prerequisites
55.2. Build Targets
55.3. Help Targets
55.4. Other Useful Command-line Variables
55.5. Make from Another Directory
56. Performance Optimization Guidelines
56.1. Introduction
57. Writing Efficient Code
57.1. Memory
57.1.1. Memory Copy: Do not Use libc in the Data Plane
57.1.2. Memory Allocation
57.1.3. Concurrent Access to the Same Memory Area
57.1.4. NUMA
57.1.5. Distribution Across Memory Channels
57.1.6. Locking memory pages
57.2. Communication Between lcores
57.3. PMD Driver
57.3.1. Lower Packet Latency
57.4. Locks and Atomic Operations
57.5. Coding Considerations
57.5.1. Inline Functions
57.5.2. Branch Prediction
57.6. Setting the Target CPU Type
58. Link Time Optimization
59. Profile Your Application
59.1. Profiling on x86
59.1.1. Profiling with VTune
59.2. Profiling on ARM64
59.2.1. Using Linux perf
59.2.2. High-resolution cycle counter
60. Glossary
Previous topic
48. NTB Sample Application
Next topic
1. Introduction
This Page
Show Source
Quick search
Enter search terms or a module, class or function name.
Navigation
index
next
|
previous
|
Data Plane Development Kit 19.11.3 documentation
»