On Sat, Apr 3, 2021 at 3:39 AM Narcisa Ana Maria Vasile
<navas...@linux.microsoft.com> wrote:
>
> From: Narcisa Vasile <navas...@microsoft.com>
>
> EAL thread API
>
> **Problem Statement**
> DPDK currently uses the pthread interface to create and manage threads.
> Windows does not support the POSIX thread programming model, so it currently
> relies on a header file that hides the Windows calls under
> pthread matched interfaces. Given that EAL should isolate the environment
> specifics from the applications and libraries and mediate
> all the communication with the operating systems, a new EAL interface
> is needed for thread management.
>
> **Goals**
> * Introduce a generic EAL API for threading support that will remove
> the current Windows pthread.h shim.
> * Replace references to pthread_* across the DPDK codebase with the new
> RTE_THREAD_* API.
> * Allow users to choose between using the RTE_THREAD_* API or a
> 3rd party thread library through a configuration option.
>
> **Design plan**
> New API main files:
> * rte_thread.h (librte_eal/include)
> * rte_thread_types.h (librte_eal/include)
> * rte_thread_windows_types.h (librte_eal/windows/include)
> * rte_thread.c (librte_eal/windows)
> * rte_thread.c (librte_eal/common)
>
> For flexibility, the user is offered the option of either using the
> RTE_THREAD_* API or
> a 3rd party thread library, through a meson flag “use_external_thread_lib”.
> By default, this flag is set to FALSE, which means Windows libraries and
> applications
> will use the RTE_THREAD_* API for managing threads.
>
> If compiling on Windows and the “use_external_thread_lib” is *not* set,
> the following files will be parsed:
> * include/rte_thread.h
> * windows/include/rte_thread_windows_types.h
> * windows/rte_thread.c
> In all other cases, the compilation/parsing includes the following files:
> * include/rte_thread.h
> * include/rte_thread_types.h
> * common/rte_thread.c
>
> **A schematic example of the design**
> --------------------------------------------------
> lib/librte_eal/include/rte_thread.h
> int rte_thread_create();
>
> lib/librte_eal/common/rte_thread.c
> int rte_thread_create()
> {
> return pthread_create();
> }
>
> lib/librte_eal/windows/rte_thread.c
> int rte_thread_create()
> {
> return CreateThread();
> }
>
> lib/librte_eal/windows/meson.build
> if get_option('use_external_thread_lib')
> sources += 'librte_eal/common/rte_thread.c'
> else
> sources += 'librte_eal/windows/rte_thread.c'
> endif
> -----------------------------------------------------
>
> **Thread attributes**
>
> When or after a thread is created, specific characteristics of the thread
> can be adjusted. Given that the thread characteristics that are of interest
> for DPDK applications are affinity and priority, the following structure
> that represents thread attributes has been defined:
>
> typedef struct
> {
> enum rte_thread_priority priority;
> rte_cpuset_t cpuset;
> } rte_thread_attr_t;
>
> The *rte_thread_create()* function can optionally receive an rte_thread_attr_t
> object that will cause the thread to be created with the affinity and priority
> described by the attributes object. If no rte_thread_attr_t is passed
> (parameter is NULL), the default affinity and priority are used.
> An rte_thread_attr_t object can also be set to the default values
> by calling *rte_thread_attr_init()*.
>
> *Priority* is represented through an enum that currently advertises
> two values for priority:
> - RTE_THREAD_PRIORITY_NORMAL
> - RTE_THREAD_PRIORITY_REALTIME_CRITICAL
> The enum can be extended to allow for multiple priority levels.
> rte_thread_set_priority - sets the priority of a thread
> rte_thread_attr_set_priority - updates an rte_thread_attr_t object
> with a new value for priority
>
> The user can choose thread priority through an EAL parameter,
> when starting an application. If EAL parameter is not used,
> the per-platform default value for thread priority is used.
> Otherwise administrator has an option to set one of available options:
> --thread-prio normal
> --thread-prio realtime
>
> Example:
> ./dpdk-l2fwd -l 0-3 -n 4 –thread-prio normal -- -q 8 -p ffff
>
> *Affinity* is described by the already known “rte_cpuset_t” type.
> rte_thread_attr_set/get_affinity - sets/gets the affinity field in a
> rte_thread_attr_t object
> rte_thread_set/get_affinity – sets/gets the affinity of a thread
>
> **Errors**
> A translation function that maps Windows error codes to errno-style
> error codes is provided.
>
> **Future work**
> Note that this patchset was focused on introducing new API that will
> remove the Windows pthread.h shim. In DPDK, there are still a few references
> to pthread_* that were not implemented in the shim.
> The long term plan is for EAL to provide full threading support:
> * Adding support for conditional variables
> * Additional functionality offered by pthread_* (such as pthread_setname_np,
> etc.)
> * Static mutex initializers are not used on Windows. If we must continue
> using them, they need to be platform dependent and an implementation will
> need to be provided for Windows.
Thanks for taking on this huge work.
There is no review on this series and I don't have time for it.
This is a core part of the EAL API.
Seeing how rc1 is at the end of this week, my recommendation is to
postpone to 21.08.
--
David Marchand
