lib/librte_eal/include/rte_launch.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_LAUNCH_H_
   6 #define _RTE_LAUNCH_H_
   7
   8 /**
   9  * @file
  10  *
  11  * Launch tasks on other lcores
  12  */
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /**
  19  * State of an lcore.
  20  */
  21 enum rte_lcore_state_t {
  22         WAIT,       /**< waiting a new command */
  23         RUNNING,    /**< executing command */
  24         FINISHED,   /**< command executed */
  25 };
  26
  27 /**
  28  * Definition of a remote launch function.
  29  */
  30 typedef int (lcore_function_t)(void *);
  31
  32 /**
  33  * Launch a function on another lcore.
  34  *
  35  * To be executed on the MAIN lcore only.
  36  *
  37  * Sends a message to a worker lcore (identified by the worker_id) that
  38  * is in the WAIT state (this is true after the first call to
  39  * rte_eal_init()). This can be checked by first calling
  40  * rte_eal_wait_lcore(worker_id).
  41  *
  42  * When the remote lcore receives the message, it switches to
  43  * the RUNNING state, then calls the function f with argument arg. Once the
  44  * execution is done, the remote lcore switches to a FINISHED state and
  45  * the return value of f is stored in a local variable to be read using
  46  * rte_eal_wait_lcore().
  47  *
  48  * The MAIN lcore returns as soon as the message is sent and knows
  49  * nothing about the completion of f.
  50  *
  51  * Note: This function is not designed to offer optimum
  52  * performance. It is just a practical way to launch a function on
  53  * another lcore at initialization time.
  54  *
  55  * @param f
  56  *   The function to be called.
  57  * @param arg
  58  *   The argument for the function.
  59  * @param worker_id
  60  *   The identifier of the lcore on which the function should be executed.
  61  * @return
  62  *   - 0: Success. Execution of function f started on the remote lcore.
  63  *   - (-EBUSY): The remote lcore is not in a WAIT state.
  64  */
  65 int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned worker_id);
  66
  67 /**
  68  * This enum indicates whether the main core must execute the handler
  69  * launched on all logical cores.
  70  */
  71 enum rte_rmt_call_main_t {
  72         SKIP_MAIN = 0, /**< lcore handler not executed by main core. */
  73         CALL_MAIN,     /**< lcore handler executed by main core. */
  74 };
  75
  76 /* These legacy definitions will be removed in future release */
  77 #define SKIP_MASTER     RTE_DEPRECATED(SKIP_MASTER) SKIP_MAIN
  78 #define CALL_MASTER     RTE_DEPRECATED(CALL_MASTER) CALL_MAIN
  79
  80 /**
  81  * Launch a function on all lcores.
  82  *
  83  * Check that each WORKER lcore is in a WAIT state, then call
  84  * rte_eal_remote_launch() for each lcore.
  85  *
  86  * @param f
  87  *   The function to be called.
  88  * @param arg
  89  *   The argument for the function.
  90  * @param call_main
  91  *   If call_main set to SKIP_MAIN, the MAIN lcore does not call
  92  *   the function. If call_main is set to CALL_MAIN, the function
  93  *   is also called on main before returning. In any case, the main
  94  *   lcore returns as soon as it finished its job and knows nothing
  95  *   about the completion of f on the other lcores.
  96  * @return
  97  *   - 0: Success. Execution of function f started on all remote lcores.
  98  *   - (-EBUSY): At least one remote lcore is not in a WAIT state. In this
  99  *     case, no message is sent to any of the lcores.
 100  */
 101 int rte_eal_mp_remote_launch(lcore_function_t *f, void *arg,
 102                              enum rte_rmt_call_main_t call_main);
 103
 104 /**
 105  * Get the state of the lcore identified by worker_id.
 106  *
 107  * To be executed on the MAIN lcore only.
 108  *
 109  * @param worker_id
 110  *   The identifier of the lcore.
 111  * @return
 112  *   The state of the lcore.
 113  */
 114 enum rte_lcore_state_t rte_eal_get_lcore_state(unsigned int worker_id);
 115
 116 /**
 117  * Wait until an lcore finishes its job.
 118  *
 119  * To be executed on the MAIN lcore only.
 120  *
 121  * If the worker lcore identified by the worker_id is in a FINISHED state,
 122  * switch to the WAIT state. If the lcore is in RUNNING state, wait until
 123  * the lcore finishes its job and moves to the FINISHED state.
 124  *
 125  * @param worker_id
 126  *   The identifier of the lcore.
 127  * @return
 128  *   - 0: If the lcore identified by the worker_id is in a WAIT state.
 129  *   - The value that was returned by the previous remote launch
 130  *     function call if the lcore identified by the worker_id was in a
 131  *     FINISHED or RUNNING state. In this case, it changes the state
 132  *     of the lcore to WAIT.
 133  */
 134 int rte_eal_wait_lcore(unsigned worker_id);
 135
 136 /**
 137  * Wait until all lcores finish their jobs.
 138  *
 139  * To be executed on the MAIN lcore only. Issue an
 140  * rte_eal_wait_lcore() for every lcore. The return values are
 141  * ignored.
 142  *
 143  * After a call to rte_eal_mp_wait_lcore(), the caller can assume
 144  * that all worker lcores are in a WAIT state.
 145  */
 146 void rte_eal_mp_wait_lcore(void);
 147
 148 #ifdef __cplusplus
 149 }
 150 #endif
 151
 152 #endif /* _RTE_LAUNCH_H_ */