lib/librte_eal/common/include/rte_keepalive.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2015-2016 Intel Corporation.
   3  */
   4
   5 /**
   6  * @file rte_keepalive.h
   7  * DPDK RTE LCore Keepalive Monitor.
   8  *
   9  **/
  10
  11 #ifndef _KEEPALIVE_H_
  12 #define _KEEPALIVE_H_
  13
  14 #include <rte_config.h>
  15 #include <rte_memory.h>
  16
  17 #ifndef RTE_KEEPALIVE_MAXCORES
  18 /**
  19  * Number of cores to track.
  20  * @note Must be larger than the highest core id. */
  21 #define RTE_KEEPALIVE_MAXCORES RTE_MAX_LCORE
  22 #endif
  23
  24 enum rte_keepalive_state {
  25         RTE_KA_STATE_UNUSED = 0,
  26         RTE_KA_STATE_ALIVE = 1,
  27         RTE_KA_STATE_MISSING = 4,
  28         RTE_KA_STATE_DEAD = 2,
  29         RTE_KA_STATE_GONE = 3,
  30         RTE_KA_STATE_DOZING = 5,
  31         RTE_KA_STATE_SLEEP = 6
  32 };
  33
  34 /**
  35  * Keepalive failure callback.
  36  *
  37  *  Receives a data pointer passed to rte_keepalive_create() and the id of the
  38  *  failed core.
  39  *  @param data Data pointer passed to rte_keepalive_create()
  40  *  @param id_core ID of the core that has failed
  41  */
  42 typedef void (*rte_keepalive_failure_callback_t)(
  43         void *data,
  44         const int id_core);
  45
  46 /**
  47  * Keepalive relay callback.
  48  *
  49  *  Receives a data pointer passed to rte_keepalive_register_relay_callback(),
  50  *  the id of the core for which state is to be forwarded, and details of the
  51  *  current core state.
  52  *  @param data Data pointer passed to rte_keepalive_register_relay_callback()
  53  *  @param id_core ID of the core for which state is being reported
  54  *  @param core_state The current state of the core
  55  *  @param Timestamp of when core was last seen alive
  56  */
  57 typedef void (*rte_keepalive_relay_callback_t)(
  58         void *data,
  59         const int id_core,
  60         enum rte_keepalive_state core_state,
  61         uint64_t last_seen
  62         );
  63
  64 /**
  65  * Keepalive state structure.
  66  * @internal
  67  */
  68 struct rte_keepalive;
  69
  70 /**
  71  * Initialise keepalive sub-system.
  72  * @param callback
  73  *   Function called upon detection of a dead core.
  74  * @param data
  75  *   Data pointer to be passed to function callback.
  76  * @return
  77  *   Keepalive structure success, NULL on failure.
  78  */
  79 struct rte_keepalive *rte_keepalive_create(
  80         rte_keepalive_failure_callback_t callback,
  81         void *data);
  82
  83 /**
  84  * Checks & handles keepalive state of monitored cores.
  85  * @param *ptr_timer Triggering timer (unused)
  86  * @param *ptr_data  Data pointer (keepalive structure)
  87  */
  88 void rte_keepalive_dispatch_pings(void *ptr_timer, void *ptr_data);
  89
  90 /**
  91  * Registers a core for keepalive checks.
  92  * @param *keepcfg
  93  *   Keepalive structure pointer
  94  * @param id_core
  95  *   ID number of core to register.
  96  */
  97 void rte_keepalive_register_core(struct rte_keepalive *keepcfg,
  98         const int id_core);
  99
 100 /**
 101  * Per-core keepalive check.
 102  * @param *keepcfg
 103  *   Keepalive structure pointer
 104  *
 105  * This function needs to be called from within the main process loop of
 106  * the LCore to be checked.
 107  */
 108 void
 109 rte_keepalive_mark_alive(struct rte_keepalive *keepcfg);
 110
 111 /**
 112  * Per-core sleep-time indication.
 113  * @param *keepcfg
 114  *   Keepalive structure pointer
 115  *
 116  * If CPU idling is enabled, this function needs to be called from within
 117  * the main process loop of the LCore going to sleep, in order to avoid
 118  * the LCore being mis-detected as dead.
 119  */
 120 void
 121 rte_keepalive_mark_sleep(struct rte_keepalive *keepcfg);
 122
 123 /**
 124  * Registers a 'live core' callback.
 125  *
 126  * The complement of the 'dead core' callback. This is called when a
 127  * core is known to be alive, and is intended for cases when an app
 128  * needs to know 'liveness' beyond just knowing when a core has died.
 129  *
 130  * @param *keepcfg
 131  *   Keepalive structure pointer
 132  * @param callback
 133  *   Function called upon detection of a dead core.
 134  * @param data
 135  *   Data pointer to be passed to function callback.
 136  */
 137 void
 138 rte_keepalive_register_relay_callback(struct rte_keepalive *keepcfg,
 139         rte_keepalive_relay_callback_t callback,
 140         void *data);
 141
 142 #endif /* _KEEPALIVE_H_ */