helper: thread: new thread create and join calls

Defined new versions of thread create and join calls. New calls
explicitly support thread create and join in multiple steps.
Also per thread and common parameters are improved.

Signed-off-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Matias Elo <matias.elo@nokia.com>
Reviewed-by: Stanislaw Kardach <skardach@marvell.com>

1 files changed, 144 insertions, 8 deletions

diff --git a/helper/include/odp/helper/threads.h b/helper/include/odp/helper/threads.h
index 6cee2522d..5a2a21157 100644
--- a/helper/include/odp/helper/threads.h
+++ b/helper/include/odp/helper/threads.h
@@ -54,18 +54,26 @@ typedef struct {
 	int   status;   /**< Process state change status */
 } odph_linux_process_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;
+
+	/** ODP thread type */
+	odp_thread_type_t thr_type;
+
+	/** @deprecated ODP instance handle for odph_odpthreads_create(). */
+	odp_instance_t instance;
+
+} odph_thread_param_t;
 
 /** The odpthread starting arguments, used both in process or thread mode */
 typedef struct {
 	odp_mem_model_t mem_model;          /**< process or thread */
-	odph_odpthread_params_t thr_params; /**< odpthread start parameters */
+	odph_thread_param_t thr_params; /**< odpthread start parameters */
 } odph_odpthread_start_args_t;
 
 /** Linux odpthread state information, used both in process or thread mode */
@@ -86,13 +94,130 @@ typedef struct {
 			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;
 
+/** Legacy thread table entry */
+typedef odph_thread_t odph_odpthread_t;
+
+/** Legacy thread parameters */
+typedef odph_thread_param_t odph_odpthread_params_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;
+
+	/**
+	 * 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;
+
+/**
+ * Create and pin threads (as Linux pthreads or processes)
+ *
+ * This is an updated version of odph_odpthreads_create() call. It 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.
+ *
+ * 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.
+ *
+ * @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_thread_create(odph_thread_t thread[],
+		       const odph_thread_common_param_t *param,
+		       const odph_thread_param_t thr_param[],
+		       int num);
+
+/**
+ * Wait previously launched threads to exit
+ *
+ * This is an updated version of odph_odpthreads_join() call. It 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.
+ *
+ * @param thread        Table of threads to exit
+ * @param num           Number of threads to exit
+ *
+ * @return Number of threads exited
+ * @retval -1  On failure
+ *
+ * @see odph_thread_create()
+ */
+int odph_thread_join(odph_thread_t thread[], int num);
+
 /**
  * Creates and launches odpthreads (as linux threads or processes)
  *
@@ -103,6 +228,8 @@ typedef struct {
  * @param thr_params    ODP thread parameters
  *
  * @return Number of threads created
+ *
+ * @deprecated Use odph_thread_create() instead.
  */
 int odph_odpthreads_create(odph_odpthread_t *thread_tbl,
 			   const odp_cpumask_t *mask,
@@ -118,6 +245,7 @@ int odph_odpthreads_create(odph_odpthread_t *thread_tbl,
  * (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)
  *
+ * @deprecated Use odph_thread_join() instead.
  */
 int odph_odpthreads_join(odph_odpthread_t *thread_tbl);
 
@@ -150,6 +278,14 @@ int odph_odpthread_getaffinity(void);
  * 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
  *