1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Thread Safety 5============= 6 7The DPDK is comprised of several libraries. 8Some of the functions in these libraries can be safely called from multiple threads simultaneously, while others cannot. 9This section allows the developer to take these issues into account when building their own application. 10 11The run-time environment of the DPDK is typically a single thread per logical core. 12In some cases, it is not only multi-threaded, but multi-process. 13Typically, it is best to avoid sharing data structures between threads and/or processes where possible. 14Where this is not possible, then the execution blocks must access the data in a thread- safe manner. 15Mechanisms such as atomics or locking can be used that will allow execution blocks to operate serially. 16However, this can have an effect on the performance of the application. 17 18Fast-Path APIs 19-------------- 20 21Applications operating in the data plane are performance sensitive but 22certain functions within those libraries may not be safe to call from multiple threads simultaneously. 23The hash, LPM and mempool libraries and RX/TX in the PMD are examples of this. 24 25The hash and LPM libraries are, by design, thread unsafe in order to maintain performance. 26However, if required the developer can add layers on top of these libraries to provide thread safety. 27Locking is not needed in all situations, and in both the hash and LPM libraries, 28lookups of values can be performed in parallel in multiple threads. 29Adding, removing or modifying values, however, 30cannot be done in multiple threads without using locking when a single hash or LPM table is accessed. 31Another alternative to locking would be to create multiple instances of these tables allowing each thread its own copy. 32 33The RX and TX of the PMD are the most critical aspects of a DPDK application 34and it is recommended that no locking be used as it will impact performance. 35Note, however, that these functions can safely be used from multiple threads 36when each thread is performing I/O on a different NIC queue. 37If multiple threads are to use the same hardware queue on the same NIC port, 38then locking, or some other form of mutual exclusion, is necessary. 39 40The ring library is based on a lockless ring-buffer algorithm that maintains its original design for thread safety. 41Moreover, it provides high performance for either multi- or single-consumer/producer enqueue/dequeue operations. 42The mempool library is based on the DPDK lockless ring library and therefore is also multi-thread safe. 43 44Performance Insensitive API 45--------------------------- 46 47Outside of the performance sensitive areas described in Section 25.1, 48the DPDK provides a thread-safe API for most other libraries. 49For example, malloc and memzone functions are safe for use in multi-threaded and multi-process environments. 50 51The setup and configuration of the PMD is not performance sensitive, but is not thread safe either. 52It is possible that the multiple read/writes during PMD setup and configuration could be corrupted in a multi-thread environment. 53Since this is not performance sensitive, the developer can choose to add their own layer to provide thread-safe setup and configuration. 54It is expected that, in most applications, the initial configuration of the network ports would be done by a single thread at startup. 55 56Library Initialization 57---------------------- 58 59It is recommended that DPDK libraries are initialized in the main thread at application startup 60rather than subsequently in the forwarding threads. 61However, the DPDK performs checks to ensure that libraries are only initialized once. 62If initialization is attempted more than once, an error is returned. 63 64In the multi-process case, the configuration information of shared memory will only be initialized by the primary process. 65Thereafter, both primary and secondary processes can allocate/release any objects of memory that finally rely on rte_malloc or memzones. 66 67Interrupt Thread 68---------------- 69 70The DPDK works almost entirely in Linux user space in polling mode. 71For certain infrequent operations, such as receiving a PMD link status change notification, 72callbacks may be called in an additional thread outside the main DPDK processing threads. 73These function callbacks should avoid manipulating DPDK objects that are also managed by the normal DPDK threads, 74and if they need to do so, 75it is up to the application to provide the appropriate locking or mutual exclusion restrictions around those objects. 76