diff options
Diffstat (limited to 'helper/include/odp/helper/threads.h')
| -rw-r--r-- | helper/include/odp/helper/threads.h | 368 |
1 files changed, 260 insertions, 108 deletions
diff --git a/helper/include/odp/helper/threads.h b/helper/include/odp/helper/threads.h index 526f0d489..ca420e80a 100644 --- a/helper/include/odp/helper/threads.h +++ b/helper/include/odp/helper/threads.h @@ -1,7 +1,6 @@ -/* Copyright (c) 2013, Linaro Limited - * All rights reserved. - * - * SPDX-License-Identifier: BSD-3-Clause +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2013-2018 Linaro Limited + * Copyright (c) 2019-2024 Nokia */ @@ -10,9 +9,9 @@ * * ODP Linux helper API * - * This file is an optional helper to odp.h APIs. These functions are provided + * This file is an optional helper to ODP APIs. These functions are provided * to ease common setups in a Linux system. User is free to implement the same - * setups in otherways (not via this API). + * setups in other ways (not via this API). */ #ifndef ODPH_LINUX_H_ @@ -22,12 +21,17 @@ extern "C" { #endif +#include <odp_api.h> + #include <pthread.h> #include <getopt.h> #include <sys/types.h> -/** @addtogroup odph_linux ODPH LINUX - * @{ +/** + * @defgroup odph_thread ODPH THREAD + * Setup threads/processes + * + * @{ */ /** Thread parameter for Linux pthreads and processes */ @@ -54,32 +58,53 @@ typedef struct { int status; /**< Process state change status */ } odph_linux_process_t; -/** odpthread linux type: whether an ODP thread is a linux thread or process */ -typedef enum odph_odpthread_linuxtype_e { - ODPTHREAD_NOT_STARTED = 0, - ODPTHREAD_PROCESS, - ODPTHREAD_PTHREAD -} odph_odpthread_linuxtype_t; - -/** odpthread parameters for odp threads (pthreads and processes) */ +/** Thread parameters (pthreads and processes) */ typedef struct { - int (*start)(void *); /**< Thread entry point function */ - void *arg; /**< Argument for the function */ - odp_thread_type_t thr_type; /**< ODP thread type */ - odp_instance_t instance; /**< ODP instance handle */ -} odph_odpthread_params_t; + /** Thread entry point function */ + int (*start)(void *arg); + + /** Argument for the function */ + void *arg; -/** The odpthread starting arguments, used both in process or thread mode */ + /** ODP thread type */ + odp_thread_type_t thr_type; + + /** Minimum stack size in bytes. 0 = use default. */ + uint64_t stack_size; + +} odph_thread_param_t; + +/** Helper internal thread start arguments. Used both in process and thread + * mode */ typedef struct { - odph_odpthread_linuxtype_t linuxtype; /**< process or pthread */ - odph_odpthread_params_t thr_params; /**< odpthread start parameters */ -} odph_odpthread_start_args_t; + /** Thread status */ + uint32_t status; + + /** Thread initialization status */ + odp_atomic_u32_t *init_status; + + /** Process or thread */ + odp_mem_model_t mem_model; -/** Linux odpthread state information, used both in process or thread mode */ + /** ODP instance handle */ + odp_instance_t instance; + + /** Thread parameters */ + odph_thread_param_t thr_params; + +} odph_thread_start_args_t; + +/** Thread state information. Used both in process and thread mode */ typedef struct { - odph_odpthread_start_args_t start_args; /**< start arguments */ - int cpu; /**< CPU ID */ - int last; /**< true if last table entry */ + /** Start arguments */ + odph_thread_start_args_t start_args; + + /** CPU ID */ + int cpu; + + /** 1: last table entry */ + uint8_t last; + /** Variant field mappings for thread/process modes */ union { /** For thread implementation */ @@ -87,41 +112,203 @@ typedef struct { pthread_t thread_id; /**< Pthread ID */ pthread_attr_t attr; /**< Pthread attributes */ } thread; + /** For process implementation */ struct { pid_t pid; /**< Process ID */ int status; /**< Process state chge status*/ } proc; }; -} odph_odpthread_t; + +} odph_thread_t; + +/** Linux helper options */ +typedef struct { + odp_mem_model_t mem_model; /**< Process or thread */ +} odph_helper_options_t; + +/** Common parameters for odph_thread_create() call */ +typedef struct { + /** + * ODP instance handle + * + * This is used for all threads, instead of 'instance' field of per + * thread parameters (odph_thread_param_t). + */ + odp_instance_t instance; + + /** + * CPU mask for thread pinning + */ + const odp_cpumask_t *cpumask; + + /** + * Select between Linux pthreads and processes + * + * 0: Use pthreads + * 1: Use processes + * + * Default value is 0. + */ + int thread_model; + + /** + * Synchronized thread creation + * + * 0: Don't synchronize thread creation + * 1: Create threads in series so that the next thread is created + * only after the previous thread have signaled that it has passed + * ODP local initialization. + * + * Default value is 0. + */ + int sync; + + /** + * Synchronized thread creation timeout in nanoseconds + * + * When synchronized thread creation has been requested, waiting for the + * synchronization signal times out once the time indicated by this + * parameter has passed. + * + * If this parameter is 0, the default value is used. + * + * Default value is ODP_TIME_SEC_IN_NS. + */ + uint64_t sync_timeout; + + /** + * Thread parameter sharing + * + * 0: Thread parameters are not shared. The thread parameter table + * contains 'num' elements. + * 1: The thread parameter table contains a single element, which is + * used for creating all 'num' threads. + * + * Default value is 0. + */ + int share_param; + +} odph_thread_common_param_t; + +/** Thread join result */ +typedef struct { + /** Exit caused by signal */ + odp_bool_t is_sig; + + /** + * Exit status of the joined thread/process + * + * If 'is_sig' is true, then this is the signal number that caused + * process exit. Otherwise status of the exited thread/process. + */ + int ret; +} odph_thread_join_result_t; /** - * Creates and launches odpthreads (as linux threads or processes) + * Initialize thread params * - * Creates, pins and launches threads to separate CPU's based on the cpumask. + * Initialize an odph_thread_param_t to its default values for all fields. * - * @param thread_tbl Thread table - * @param mask CPU mask - * @param thr_params ODP thread parameters + * @param[out] param Pointer to parameter structure + */ +void odph_thread_param_init(odph_thread_param_t *param); + +/** + * Initialize thread common params + * + * Initialize an odph_thread_common_param_t to its default values for all + * fields. + * + * @param[out] param Pointer to parameter structure + */ +void odph_thread_common_param_init(odph_thread_common_param_t *param); + +/** + * Create and pin threads (as Linux pthreads or processes) + * + * Function may be called multiple times to create threads in steps. Each call + * launches 'num' threads and pins those to separate CPUs based on the cpumask. + * Use 'thread_model' parameter to select if Linux pthreads or processes are + * used. This selection may be overridden with ODP helper options. See e.g. + * --odph_proc under odph_options() documentation. + * + * Thread creation may be synchronized by setting 'sync' parameter. It + * serializes thread start up (odp_init_local() calls), which helps to + * stabilize application start up sequence. + * + * By default, the thread parameter table contains 'num' elements, one for + * each thread to be created. However, all threads may be created + * with a single thread parameter table element by setting 'share_param' + * parameter. + * + * Use odph_thread_common_param_init() and odph_thread_param_init() to + * initialize parameters with default values. + * + * Thread table must be large enough to hold 'num' elements. Also the cpumask + * must contain 'num' CPUs. Threads are pinned to CPUs in order - the first + * thread goes to the smallest CPU number of the mask, etc. + * + * Launched threads may be waited for exit with odph_thread_join(), or with + * direct Linux system calls. If odph_thread_join() is used, the output thread + * table elements must not be modified during the life time of the threads. + * + * @param[out] thread Thread table for output + * @param param Common parameters for all threads to be created + * @param thr_param Table of thread parameters + * @param num Number of threads to create * * @return Number of threads created + * @retval -1 On failure + * + * @see odph_thread_join() */ -int odph_odpthreads_create(odph_odpthread_t *thread_tbl, - const odp_cpumask_t *mask, - const odph_odpthread_params_t *thr_params); +int odph_thread_create(odph_thread_t thread[], + const odph_thread_common_param_t *param, + const odph_thread_param_t thr_param[], + int num); /** - * Waits odpthreads (as linux threads or processes) to exit. + * Wait previously launched threads to exit + * + * Function waits for threads launched with odph_thread_create() to exit. + * Threads may be waited to exit in a different order than those were created. + * A function call may be used to wait any number of launched threads to exit. + * A particular thread may be waited only once. + * + * Threads are joined in the order they are in 'thread' table. Returns on the + * first non-zero exit status or other failure. * - * Returns when all odpthreads have terminated. + * @param thread Table of threads to exit + * @param num Number of threads to exit * - * @param thread_tbl Thread table - * @return The number of joined threads or -1 on error. - * (error occurs if any of the start_routine return non-zero or if - * the thread join/process wait itself failed -e.g. as the result of a kill) + * @return Number of threads successfully joined with zero exit status + * (0 ... num) + * @retval -1 On failure * + * @see odph_thread_create() */ -int odph_odpthreads_join(odph_odpthread_t *thread_tbl); +int odph_thread_join(odph_thread_t thread[], int num); + +/** + * Wait previously launched threads to exit + * + * Similar to odph_thread_join() but outputs results of joined threads and + * stops only if the actual join operation fails for some thread. Threads are + * joined in the order they are in 'thread' table. Returns number of threads + * successfully joined and writes respective exit statuses into the 'res' + * table. + * + * @param thread Table of threads to exit + * @param[out] res Table for result output + * @param num Number of threads to exit and results to output + * + * @return Number of threads successfully joined (0 ... num) + * @retval -1 On failure + * + * @see odph_thread_create() + */ +int odph_thread_join_result(odph_thread_t thread[], odph_thread_join_result_t res[], int num); /** * Set CPU affinity of the current odp thread @@ -146,74 +333,39 @@ int odph_odpthread_setaffinity(const int cpu); int odph_odpthread_getaffinity(void); /** - * Merge getopt options - * - * Given two sets of getopt options (each containing possibly both short - * options -a string- and long options -a option array-) this function - * return a single set (i.e. a string for short and an array for long) - * being the concatenation of the two given sets. - * Due to the fact that the size of these arrays is unknown at compilation - * time, this function actually mallocs the the resulting arrays. - * The fourth and fith parameters are actually pointers where these malloc'ed - * areas are returned. - * This means that the caller of this function has to free the two returned - * areas! - * - * @param shortopts1 first set of short options (a string) - * @param shortopts2 second set of short options (a string) - * @param longopts1 first set of long options (a getopt option array) - * @param longopts2 second set of long options (a getopt option array) - * @param shortopts a pointer where the address of the short options list - * (a string) is returned. It contains the concatenation of - * the two given short option strings. - * @param longopts a pointer where the address of the long options list - * (a getopt option array) is returned. - * It contains the concatenation of the two given long - * option arrays. - * if any of shortopts1, shortopts2, longopts1, longopts2 is NULL, the - * corresponding list as assumed to be empty. - * if any of shortopts, longopts is NULL, the corresponding malloc is not - * performed. - * - * @return On success: 0 : both shortopts and longopts are returned (assuming - * the given pointer where not null), possibly - * pointing to an empty string or an empty option array. - * On success, the caller is due to free these areas. - * On failure: -1: Nothing is malloc'ed. + * Parse linux helper options + * + * Parse the command line options. Pick up (--odph_ prefixed) options meant for + * the helper itself. When helper options are found, those are removed from + * argv[] and remaining options are packed to the beginning of the array. + * + * <table> <caption> Currently supported options </caption> + * + * <tr><th>Command line <th>Environment variable <th>Description + * <tr><td>--odph_proc <td>ODPH_PROC_MODE <td>When defined, threads are + * Linux processes. Otherwise, + * pthreads are used instead. + * </table> + * + * @param argc Argument count + * @param argv Argument vector + * + * @return New argument count. Original argument count decremented by + * the number of removed helper options. */ -int odph_merge_getopt_options(const char *shortopts1, - const char *shortopts2, - const struct option *longopts1, - const struct option *longopts2, - char **shortopts, - struct option **longopts); +int odph_parse_options(int argc, char *argv[]); /** - * Parse linux helper options + * Get linux helper options + * + * Return used ODP helper options. odph_parse_options() must be called before + * using this function. * - * Parse the command line options. Pick up options meant for the helper itself. - * If the caller is also having a set of option to parse, it should include - * their description here (shortopts desribes the short options and longopts - * describes the long options, as for getopt_long()). - * This function will issue errors on unknown arguments, so callers failing - * to pass their own command line options description here will see their - * options rejected. - * (the caller wants to set opterr to zero when parsing its own stuff - * with getopts to avoid reacting on helper's options). - * - * @param argc argument count - * @param argv argument values - * @param caller_shortopts caller's set of short options (string). or NULL. - * @param caller_longopts caller's set of long options (getopt option array). - * or NULL. - * - * @return On success: 0 - * On failure: -1 failure occurs if a value passed for a helper - * option is invalid, or on meeting unknown options. + * @param[out] options ODP helper options + * + * @return 0 on success, -1 on failure */ -int odph_parse_options(int argc, char *argv[], - const char *caller_shortopts, - const struct option *caller_longopts); +int odph_options(odph_helper_options_t *options); /** * @} |