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 <stdbool.h>
  45 #include <stdint.h>
  46 #include <stdio.h>
  47 #include <string.h>
  48
  49 #include "spdk/queue.h"
  50
  51 typedef void (*spdk_event_fn)(void *arg1, void *arg2);
  52
  53 /**
  54  * \brief An event is a function that is passed to and called on an lcore.
  55  */
  56 struct spdk_event;
  57
  58 typedef void (*spdk_poller_fn)(void *arg);
  59
  60 /**
  61  * \brief A poller is a function that is repeatedly called on an lcore.
  62  */
  63 struct spdk_poller;
  64
  65 typedef void (*spdk_app_shutdown_cb)(void);
  66 typedef void (*spdk_sighandler_t)(int);
  67
  68 /**
  69  * \brief Event framework initialization options
  70  */
  71 struct spdk_app_opts {
  72         const char *name;
  73         const char *config_file;
  74         const char *reactor_mask;
  75         const char *log_facility;
  76         const char *tpoint_group_mask;
  77
  78         int shm_id;
  79
  80         spdk_app_shutdown_cb    shutdown_cb;
  81         spdk_sighandler_t       usr1_handler;
  82
  83         bool                    enable_coredump;
  84         int                     dpdk_mem_channel;
  85         int                     dpdk_master_core;
  86         int                     dpdk_mem_size;
  87
  88         /* The maximum latency allowed when passing an event
  89          * from one core to another. A value of 0
  90          * means all cores continually poll. This is
  91          * specified in microseconds.
  92          */
  93         uint64_t                max_delay_us;
  94 };
  95
  96 /**
  97  * \brief Initialize the default value of opts
  98 */
  99 void spdk_app_opts_init(struct spdk_app_opts *opts);
 100
 101 /**
 102  * \brief Initialize an application to use the event framework. This must be called prior to using
 103  * any other functions in this library.
 104 */
 105 void spdk_app_init(struct spdk_app_opts *opts);
 106
 107 /**
 108  * \brief Perform final shutdown operations on an application using the event framework.
 109 */
 110 int spdk_app_fini(void);
 111
 112 /**
 113  * \brief Start the framework. Once started, the framework will call start_fn on the master
 114  * core with the arguments provided. This call will block until \ref spdk_app_stop is called.
 115 */
 116 int spdk_app_start(spdk_event_fn start_fn, void *arg1, void *arg2);
 117
 118 /**
 119  * \brief Start shutting down the framework.  Typically this function is not called directly, and
 120  * the shutdown process is started implicitly by a process signal.  But in applications that are
 121  * using SPDK for a subset of its process threads, this function can be called in lieu of a signal.
 122  */
 123 void spdk_app_start_shutdown(void);
 124
 125 /**
 126  * \brief Stop the framework. This does not wait for all threads to exit. Instead, it kicks off
 127  * the shutdown process and returns. Once the shutdown process is complete, \ref spdk_app_start will return.
 128 */
 129 void spdk_app_stop(int rc);
 130
 131 /**
 132  * \brief Generate a configuration file that corresponds to the current running state.
 133 */
 134 int spdk_app_get_running_config(char **config_str, char *name);
 135
 136 /**
 137  * \brief Return the shared memory id for this application.
 138 */
 139 int spdk_app_get_shm_id(void);
 140
 141 /**
 142  * \brief Convert a string containing a CPU core mask into a bitmask
 143  */
 144 int spdk_app_parse_core_mask(const char *mask, uint64_t *cpumask);
 145
 146 /**
 147  * \brief Return a mask of the CPU cores active for this application
 148  */
 149 uint64_t spdk_app_get_core_mask(void);
 150
 151 /**
 152  * \brief Return the number of CPU cores utilized by this application
 153  */
 154 int spdk_app_get_core_count(void) __attribute__((deprecated));
 155
 156 /**
 157  * \brief Return the lcore of the current thread.
 158  */
 159 uint32_t spdk_app_get_current_core(void) __attribute__((deprecated));
 160
 161 /**
 162  * \brief Allocate an event to be passed to \ref spdk_event_call
 163  */
 164 struct spdk_event *spdk_event_allocate(uint32_t lcore, spdk_event_fn fn,
 165                                        void *arg1, void *arg2);
 166
 167 /**
 168  * \brief Pass the given event to the associated lcore and call the function.
 169  */
 170 void spdk_event_call(struct spdk_event *event);
 171
 172 /**
 173  * \brief Register a poller on the given lcore.
 174  */
 175 void spdk_poller_register(struct spdk_poller **ppoller,
 176                           spdk_poller_fn fn,
 177                           void *arg,
 178                           uint32_t lcore,
 179                           uint64_t period_microseconds);
 180
 181 /**
 182  * \brief Unregister a poller on the given lcore.
 183  */
 184 void spdk_poller_unregister(struct spdk_poller **ppoller,
 185                             struct spdk_event *complete);
 186
 187 #endif