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