lib/librte_eal/common/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 MASTER lcore only.
  36  *
  37  * Sends a message to a slave lcore (identified by the slave_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(slave_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 MASTER 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 slave_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 slave_id);
  66
  67 /**
  68  * This enum indicates whether the master core must execute the handler
  69  * launched on all logical cores.
  70  */
  71 enum rte_rmt_call_master_t {
  72         SKIP_MASTER = 0, /**< lcore handler not executed by master core. */
  73         CALL_MASTER,     /**< lcore handler executed by master core. */
  74 };
  75
  76 /**
  77  * Launch a function on all lcores.
  78  *
  79  * Check that each SLAVE lcore is in a WAIT state, then call
  80  * rte_eal_remote_launch() for each lcore.
  81  *
  82  * @param f
  83  *   The function to be called.
  84  * @param arg
  85  *   The argument for the function.
  86  * @param call_master
  87  *   If call_master set to SKIP_MASTER, the MASTER lcore does not call
  88  *   the function. If call_master is set to CALL_MASTER, the function
  89  *   is also called on master before returning. In any case, the master
  90  *   lcore returns as soon as it finished its job and knows nothing
  91  *   about the completion of f on the other lcores.
  92  * @return
  93  *   - 0: Success. Execution of function f started on all remote lcores.
  94  *   - (-EBUSY): At least one remote lcore is not in a WAIT state. In this
  95  *     case, no message is sent to any of the lcores.
  96  */
  97 int rte_eal_mp_remote_launch(lcore_function_t *f, void *arg,
  98                              enum rte_rmt_call_master_t call_master);
  99
 100 /**
 101  * Get the state of the lcore identified by slave_id.
 102  *
 103  * To be executed on the MASTER lcore only.
 104  *
 105  * @param slave_id
 106  *   The identifier of the lcore.
 107  * @return
 108  *   The state of the lcore.
 109  */
 110 enum rte_lcore_state_t rte_eal_get_lcore_state(unsigned slave_id);
 111
 112 /**
 113  * Wait until an lcore finishes its job.
 114  *
 115  * To be executed on the MASTER lcore only.
 116  *
 117  * If the slave lcore identified by the slave_id is in a FINISHED state,
 118  * switch to the WAIT state. If the lcore is in RUNNING state, wait until
 119  * the lcore finishes its job and moves to the FINISHED state.
 120  *
 121  * @param slave_id
 122  *   The identifier of the lcore.
 123  * @return
 124  *   - 0: If the lcore identified by the slave_id is in a WAIT state.
 125  *   - The value that was returned by the previous remote launch
 126  *     function call if the lcore identified by the slave_id was in a
 127  *     FINISHED or RUNNING state. In this case, it changes the state
 128  *     of the lcore to WAIT.
 129  */
 130 int rte_eal_wait_lcore(unsigned slave_id);
 131
 132 /**
 133  * Wait until all lcores finish their jobs.
 134  *
 135  * To be executed on the MASTER lcore only. Issue an
 136  * rte_eal_wait_lcore() for every lcore. The return values are
 137  * ignored.
 138  *
 139  * After a call to rte_eal_mp_wait_lcore(), the caller can assume
 140  * that all slave lcores are in a WAIT state.
 141  */
 142 void rte_eal_mp_wait_lcore(void);
 143
 144 #ifdef __cplusplus
 145 }
 146 #endif
 147
 148 #endif /* _RTE_LAUNCH_H_ */