ceph/src/spdk/include/spdk/event.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /**
  35  * \file
  36  * Event framework public API.
  37  *
  38  * See @ref event_components for an overview of the SPDK event framework API.
  39  */
  40
  41 #ifndef SPDK_EVENT_H
  42 #define SPDK_EVENT_H
  43
  44 #include "spdk/stdinc.h"
  45
  46 #include "spdk/cpuset.h"
  47 #include "spdk/queue.h"
  48 #include "spdk/log.h"
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /**
  55  * Event handler function.
  56  *
  57  * \param arg1 Argument 1.
  58  * \param arg2 Argument 2.
  59  */
  60 typedef void (*spdk_event_fn)(void *arg1, void *arg2);
  61
  62 /**
  63  * \brief An event is a function that is passed to and called on an lcore.
  64  */
  65 struct spdk_event;
  66
  67 /**
  68  * \brief A poller is a function that is repeatedly called on an lcore.
  69  */
  70 struct spdk_poller;
  71
  72 /**
  73  * Callback function for customized shutdown handling of application.
  74  */
  75 typedef void (*spdk_app_shutdown_cb)(void);
  76
  77 /**
  78  * Signal handler fucntion.
  79  *
  80  * \param signal Signal number.
  81  */
  82 typedef void (*spdk_sighandler_t)(int signal);
  83
  84 #define SPDK_DEFAULT_RPC_ADDR "/var/tmp/spdk.sock"
  85
  86 /**
  87  * \brief Event framework initialization options
  88  */
  89 struct spdk_app_opts {
  90         const char *name;
  91         const char *config_file;
  92         const char *rpc_addr; /* Can be UNIX domain socket path or IP address + TCP port */
  93         const char *reactor_mask;
  94         const char *tpoint_group_mask;
  95
  96         int shm_id;
  97
  98         spdk_app_shutdown_cb    shutdown_cb;
  99         spdk_sighandler_t       usr1_handler;
 100
 101         bool                    enable_coredump;
 102         int                     mem_channel;
 103         int                     master_core;
 104         int                     mem_size;
 105         bool                    no_pci;
 106         bool                    hugepage_single_segments;
 107         bool                    unlink_hugepage;
 108         enum spdk_log_level     print_level;
 109         size_t                  num_pci_addr;
 110         struct spdk_pci_addr    *pci_blacklist;
 111         struct spdk_pci_addr    *pci_whitelist;
 112
 113         /* The maximum latency allowed when passing an event
 114          * from one core to another. A value of 0
 115          * means all cores continually poll. This is
 116          * specified in microseconds.
 117          */
 118         uint64_t                max_delay_us;
 119
 120         /* Wait for the associated RPC before initializing subsystems
 121          * when this flag is enabled.
 122          */
 123         bool                    delay_subsystem_init;
 124 };
 125
 126 struct spdk_reactor_tsc_stats {
 127         uint64_t busy_tsc;
 128         uint64_t idle_tsc;
 129         uint64_t unknown_tsc;
 130 };
 131
 132 /**
 133  * Initialize the default value of opts
 134  *
 135  * \param opts Data structure where SPDK will initialize the default options.
 136  */
 137 void spdk_app_opts_init(struct spdk_app_opts *opts);
 138
 139 /**
 140  * Start the framework.
 141  *
 142  * Before calling this function, the fields of opts must be initialized by
 143  * spdk_app_opts_init(). Once started, the framework will call start_fn on the
 144  * master core with the arguments provided. This call will block until spdk_app_stop()
 145  * is called, or if an error condition occurs during the intialization
 146  * code within spdk_app_start(), itself, before invoking the caller's
 147  * supplied function.
 148  *
 149  * \param opts Initialization options used for this application.
 150  * \param start_fn Event function that is called when the framework starts.
 151  * \param arg1 Argument passed to function start_fn.
 152  * \param arg2 Argument passed to function start_fn.
 153  *
 154  * \return 0 on success or non-zero on failure.
 155  */
 156 int spdk_app_start(struct spdk_app_opts *opts, spdk_event_fn start_fn,
 157                    void *arg1, void *arg2);
 158
 159 /**
 160  * Perform final shutdown operations on an application using the event framework.
 161  */
 162 void spdk_app_fini(void);
 163
 164 /**
 165  * Start shutting down the framework.
 166  *
 167  * Typically this function is not called directly, and the shutdown process is
 168  * started implicitly by a process signal. But in applications that are using
 169  * SPDK for a subset of its process threads, this function can be called in lieu
 170  * of a signal.
 171  */
 172 void spdk_app_start_shutdown(void);
 173
 174 /**
 175  * Stop the framework.
 176  *
 177  * This does not wait for all threads to exit. Instead, it kicks off the shutdown
 178  * process and returns. Once the shutdown process is complete, spdk_app_start()
 179  * will return.
 180  *
 181  * \param rc The rc value specified here will be returned to caller of spdk_app_start().
 182  */
 183 void spdk_app_stop(int rc);
 184
 185 /**
 186  * Generate a configuration file that corresponds to the current running state.
 187  *
 188  * \param config_str Values obtained from the generated configuration file.
 189  * \param name Prefix for name of temporary configuration file to save the current config.
 190  *
 191  * \return 0 on success, -1 on failure.
 192  */
 193 int spdk_app_get_running_config(char **config_str, char *name);
 194
 195 /**
 196  * Return the shared memory id for this application.
 197  *
 198  * \return shared memory id.
 199  */
 200 int spdk_app_get_shm_id(void);
 201
 202 /**
 203  * Convert a string containing a CPU core mask into a bitmask
 204  *
 205  * \param mask String containing a CPU core mask.
 206  * \param cpumask Bitmask of CPU cores.
 207  *
 208  * \return 0 on success, -1 on failure.
 209  */
 210 int spdk_app_parse_core_mask(const char *mask, struct spdk_cpuset *cpumask);
 211
 212 /**
 213  * Get the mask of the CPU cores active for this application
 214  *
 215  * \return the bitmask of the active CPU cores.
 216  */
 217 struct spdk_cpuset *spdk_app_get_core_mask(void);
 218
 219 #define SPDK_APP_GETOPT_STRING "c:de:ghi:m:n:p:r:s:uB:L:RW:"
 220
 221 enum spdk_app_parse_args_rvals {
 222         SPDK_APP_PARSE_ARGS_HELP = 0,
 223         SPDK_APP_PARSE_ARGS_SUCCESS = 1,
 224         SPDK_APP_PARSE_ARGS_FAIL = 2
 225 };
 226 typedef enum spdk_app_parse_args_rvals spdk_app_parse_args_rvals_t;
 227
 228 /**
 229  * Helper function for parsing arguments and printing usage messages.
 230  *
 231  * \param argc Count of arguments in argv parameter array.
 232  * \param argv Array of command line arguments.
 233  * \param opts Default options for the application.
 234  * \param getopt_str String representing the app-specific command line parameters.
 235  * Characters in this string must not conflict with characters in SPDK_APP_GETOPT_STRING.
 236  * \param app_long_opts Array of full-name parameters. Can be NULL.
 237  * \param parse Function pointer to call if an argument in getopt_str is found.
 238  * \param usage Function pointer to print usage messages for app-specific command
 239  *              line parameters.
 240  *\return SPDK_APP_PARSE_ARGS_FAIL on failure, SPDK_APP_PARSE_ARGS_SUCCESS on
 241  *        success, SPDK_APP_PARSE_ARGS_HELP if '-h' passed as an option.
 242  */
 243 spdk_app_parse_args_rvals_t spdk_app_parse_args(int argc, char **argv,
 244                 struct spdk_app_opts *opts, const char *getopt_str,
 245                 struct option *app_long_opts, void (*parse)(int ch, char *arg),
 246                 void (*usage)(void));
 247
 248 /**
 249  * Print usage strings for common SPDK command line options.
 250  *
 251  * May only be called after spdk_app_parse_args().
 252  */
 253 void spdk_app_usage(void);
 254
 255 /**
 256  * Allocate an event to be passed to spdk_event_call().
 257  *
 258  * \param lcore Lcore to run this event.
 259  * \param fn Function used to execute event.
 260  * \param arg1 Argument passed to function fn.
 261  * \param arg2 Argument passed to function fn.
 262  *
 263  * \return a pointer to the allocated event.
 264  */
 265 struct spdk_event *spdk_event_allocate(uint32_t lcore, spdk_event_fn fn,
 266                                        void *arg1, void *arg2);
 267
 268 /**
 269  * Pass the given event to the associated lcore and call the function.
 270  *
 271  * \param event Event to execute.
 272  */
 273 void spdk_event_call(struct spdk_event *event);
 274
 275 /**
 276  * Enable or disable monitoring of context switches.
 277  *
 278  * \param enabled True to enable, false to disable.
 279  */
 280 void spdk_reactor_enable_context_switch_monitor(bool enabled);
 281
 282 /**
 283  * Return whether context switch monitoring is enabled.
 284  *
 285  * \return true if enabled or false otherwise.
 286  */
 287 bool spdk_reactor_context_switch_monitor_enabled(void);
 288
 289 /**
 290  * Get tsc stats from a given reactor
 291  * Copy cumulative reactor tsc values to user's tsc_stats structure.
 292  *
 293  * \param tsc_stats User's tsc_stats structure.
 294  * \param core_id Get tsc data on this Reactor core id.
 295  */
 296 int spdk_reactor_get_tsc_stats(struct spdk_reactor_tsc_stats *tsc_stats, uint32_t core_id);
 297
 298 #ifdef __cplusplus
 299 }
 300 #endif
 301
 302 #endif