LXR dpdk/lib/eal/include/rte

   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
  15extern "C" {
  16#endif
  17
  18/**
  19 * State of an lcore.
  20 */
  21enum 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 */
  30typedef 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 */
  65int 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 */
  71enum 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 */
 101int 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 */
 114enum 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 */
 134int 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 */
 146void rte_eal_mp_wait_lcore(void);
 147
 148#ifdef __cplusplus
 149}
 150#endif
 151
 152#endif /* _RTE_LAUNCH_H_ */
 153