examples/performance-thread/common/lthread_diag_api.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2015 Intel Corporation. All rights reserved.
   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 #ifndef LTHREAD_DIAG_API_H_
  34 #define LTHREAD_DIAG_API_H_
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #include <stdint.h>
  41 #include <inttypes.h>
  42
  43 /*
  44  * Enable diagnostics
  45  * 0 = conditionally compiled out
  46  * 1 = compiled in and maskable at run time, see below for details
  47  */
  48 #define LTHREAD_DIAG 0
  49
  50 /**
  51  *
  52  * @file lthread_diag_api.h
  53  *
  54  * @warning
  55  * @b EXPERIMENTAL: this API may change without prior notice
  56  *
  57  * lthread diagnostic interface
  58  *
  59  * If enabled via configuration file option ( tbd ) the lthread subsystem
  60  * can generate selected trace information, either RTE_LOG  (INFO) messages,
  61  * or else invoke a user supplied callback function when any of the events
  62  * listed below occur.
  63  *
  64  * Reporting of events can be selectively masked, the bit position in the
  65  * mask is determined by the corresponding event identifier listed below.
  66  *
  67  * Diagnostics are enabled by registering the callback function and mask
  68  * using the API lthread_diagnostic_enable().
  69  *
  70  * Various interesting parameters are passed to the callback, including the
  71  * time in cpu clks, the lthread id, the diagnostic event id, a user ref value,
  72  * event text string, object being traced, and two context dependent parameters
  73  * (p1 and p2). The meaning of the two parameters p1 and p2 depends on
  74  * the specific event.
  75  *
  76  * The events LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE and
  77  * LT_DIAG_COND_CREATE are implicitly enabled if the event mask includes any of
  78  * the LT_DIAG_LTHREAD_XXX, LT_DIAG_MUTEX_XXX or LT_DIAG_COND_XXX events
  79  * respectively.
  80  *
  81  * These create events may also be included in the mask discreetly if it is
  82  * desired to monitor only create events.
  83  *
  84  * @param  time
  85  *  The time in cpu clks at which the event occurred
  86  *
  87  * @param  lthread
  88  *  The current lthread
  89  *
  90  * @param diag_event
  91  *  The diagnostic event id (bit position in the mask)
  92  *
  93  * @param  diag_ref
  94  *
  95  * For LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE or LT_DIAG_COND_CREATE
  96  * this parameter is not used and set to 0.
  97  * All other events diag_ref contains the user ref value returned by the
  98  * callback function when lthread is created.
  99  *
 100  * The diag_ref values assigned to mutex and cond var can be retrieved
 101  * using the APIs lthread_mutex_diag_ref(), and lthread_cond_diag_ref()
 102  * respectively.
 103  *
 104  * @param p1
 105  *  see below
 106  *
 107  * @param p1
 108  *  see below
 109  *
 110  * @returns
 111  * For LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE or LT_DIAG_COND_CREATE
 112  * expects a user diagnostic ref value that will be saved in the lthread, mutex
 113  * or cond var.
 114  *
 115  * For all other events return value is ignored.
 116  *
 117  *      LT_DIAG_SCHED_CREATE - Invoked when a scheduler is created
 118  *              p1 = the scheduler that was created
 119  *              p2 = not used
 120  *              return value will be ignored
 121  *
 122  *      LT_DIAG_SCHED_SHUTDOWN - Invoked when a shutdown request is received
 123  *              p1 = the scheduler to be shutdown
 124  *              p2 = not used
 125  *              return value will be ignored
 126  *
 127  *      LT_DIAG_LTHREAD_CREATE - Invoked when a thread is created
 128  *              p1 = the lthread that was created
 129  *              p2 = not used
 130  *              return value will be stored in the lthread
 131  *
 132  *      LT_DIAG_LTHREAD_EXIT - Invoked when a lthread exits
 133  *              p2 = 0 if the thread was already joined
 134  *              p2 = 1 if the thread was not already joined
 135  *              return val ignored
 136  *
 137  *      LT_DIAG_LTHREAD_JOIN - Invoked when a lthread exits
 138  *              p1 = the lthread that is being joined
 139  *              p2 = 0 if the thread was already exited
 140  *              p2 = 1 if the thread was not already exited
 141  *              return val ignored
 142  *
 143  *      LT_DIAG_LTHREAD_CANCELLED - Invoked when an lthread is cancelled
 144  *              p1 = not used
 145  *              p2 = not used
 146  *              return val ignored
 147  *
 148  *      LT_DIAG_LTHREAD_DETACH - Invoked when an lthread is detached
 149  *              p1 = not used
 150  *              p2 = not used
 151  *              return val ignored
 152  *
 153  *      LT_DIAG_LTHREAD_FREE - Invoked when an lthread is freed
 154  *              p1 = not used
 155  *              p2 = not used
 156  *              return val ignored
 157  *
 158  *      LT_DIAG_LTHREAD_SUSPENDED - Invoked when an lthread is suspended
 159  *              p1 = not used
 160  *              p2 = not used
 161  *              return val ignored
 162  *
 163  *      LT_DIAG_LTHREAD_YIELD - Invoked when an lthread explicitly yields
 164  *              p1 = not used
 165  *              p2 = not used
 166  *              return val ignored
 167  *
 168  *      LT_DIAG_LTHREAD_RESCHEDULED - Invoked when an lthread is rescheduled
 169  *              p1 = not used
 170  *              p2 = not used
 171  *              return val ignored
 172  *
 173  *      LT_DIAG_LTHREAD_RESUMED - Invoked when an lthread is resumed
 174  *              p1 = not used
 175  *              p2 = not used
 176  *              return val ignored
 177  *
 178  *      LT_DIAG_LTHREAD_AFFINITY - Invoked when an lthread is affinitised
 179  *              p1 = the destination lcore_id
 180  *              p2 = not used
 181  *              return val ignored
 182  *
 183  *      LT_DIAG_LTHREAD_TMR_START - Invoked when an lthread starts a timer
 184  *              p1 = address of timer node
 185  *              p2 = the timeout value
 186  *              return val ignored
 187  *
 188  *      LT_DIAG_LTHREAD_TMR_DELETE - Invoked when an lthread deletes a timer
 189  *              p1 = address of the timer node
 190  *              p2 = 0 the timer and the was successfully deleted
 191  *              p2 = not usee
 192  *              return val ignored
 193  *
 194  *      LT_DIAG_LTHREAD_TMR_EXPIRED - Invoked when an lthread timer expires
 195  *              p1 = address of scheduler the timer expired on
 196  *              p2 = the thread associated with the timer
 197  *              return val ignored
 198  *
 199  *      LT_DIAG_COND_CREATE - Invoked when a condition variable is created
 200  *              p1 = address of cond var that was created
 201  *              p2 = not used
 202  *              return diag ref value will be stored in the condition variable
 203  *
 204  *      LT_DIAG_COND_DESTROY - Invoked when a condition variable is destroyed
 205  *              p1 = not used
 206  *              p2 = not used
 207  *              return val ignored
 208  *
 209  *      LT_DIAG_COND_WAIT - Invoked when an lthread waits on a cond var
 210  *              p1 = the address of the condition variable
 211  *              p2 = not used
 212  *              return val ignored
 213  *
 214  *      LT_DIAG_COND_SIGNAL - Invoked when an lthread signals a cond var
 215  *              p1 = the address of the cond var
 216  *              p2 = the lthread that was signalled, or error code
 217  *              return val ignored
 218  *
 219  *      LT_DIAG_COND_BROADCAST - Invoked when an lthread broadcasts a cond var
 220  *              p1 = the address of the condition variable
 221  *              p2 = the lthread(s) that are signalled, or error code
 222  *
 223  *      LT_DIAG_MUTEX_CREATE - Invoked when a mutex is created
 224  *              p1 = address of muex
 225  *              p2 = not used
 226  *              return diag ref value will be stored in the mutex variable
 227  *
 228  *      LT_DIAG_MUTEX_DESTROY - Invoked when a mutex is destroyed
 229  *              p1 = address of mutex
 230  *              p2 = not used
 231  *              return val ignored
 232  *
 233  *      LT_DIAG_MUTEX_LOCK - Invoked when a mutex lock is obtained
 234  *              p1 = address of mutex
 235  *              p2 = function return value
 236  *              return val ignored
 237  *
 238  *      LT_DIAG_MUTEX_BLOCKED  - Invoked when an lthread blocks on a mutex
 239  *              p1 = address of mutex
 240  *              p2 = function return value
 241  *              return val ignored
 242  *
 243  *      LT_DIAG_MUTEX_TRYLOCK - Invoked when a mutex try lock is attempted
 244  *              p1 = address of mutex
 245  *              p2 = the function return value
 246  *              return val ignored
 247  *
 248  *      LT_DIAG_MUTEX_UNLOCKED - Invoked when a mutex is unlocked
 249  *              p1 = address of mutex
 250  *              p2 = the thread that was unlocked, or error code
 251  *              return val ignored
 252  */
 253 typedef uint64_t (*diag_callback) (uint64_t time, struct lthread *lt,
 254                                   int diag_event, uint64_t diag_ref,
 255                                 const char *text, uint64_t p1, uint64_t p2);
 256
 257 /*
 258  * Set user diagnostic callback and mask
 259  * If the callback function pointer is NULL the default
 260  * callback handler will be restored.
 261  */
 262 void lthread_diagnostic_enable(diag_callback cb, uint64_t diag_mask);
 263
 264 /*
 265  * Set diagnostic mask
 266  */
 267 void lthread_diagnostic_set_mask(uint64_t mask);
 268
 269 /*
 270  * lthread diagnostic callback
 271  */
 272 enum lthread_diag_ev {
 273         /* bits 0 - 14 lthread flag group */
 274         LT_DIAG_LTHREAD_CREATE,         /* 00 mask 0x00000001 */
 275         LT_DIAG_LTHREAD_EXIT,           /* 01 mask 0x00000002 */
 276         LT_DIAG_LTHREAD_JOIN,           /* 02 mask 0x00000004 */
 277         LT_DIAG_LTHREAD_CANCEL,         /* 03 mask 0x00000008 */
 278         LT_DIAG_LTHREAD_DETACH,         /* 04 mask 0x00000010 */
 279         LT_DIAG_LTHREAD_FREE,           /* 05 mask 0x00000020 */
 280         LT_DIAG_LTHREAD_SUSPENDED,      /* 06 mask 0x00000040 */
 281         LT_DIAG_LTHREAD_YIELD,          /* 07 mask 0x00000080 */
 282         LT_DIAG_LTHREAD_RESCHEDULED,    /* 08 mask 0x00000100 */
 283         LT_DIAG_LTHREAD_SLEEP,          /* 09 mask 0x00000200 */
 284         LT_DIAG_LTHREAD_RESUMED,        /* 10 mask 0x00000400 */
 285         LT_DIAG_LTHREAD_AFFINITY,       /* 11 mask 0x00000800 */
 286         LT_DIAG_LTHREAD_TMR_START,      /* 12 mask 0x00001000 */
 287         LT_DIAG_LTHREAD_TMR_DELETE,     /* 13 mask 0x00002000 */
 288         LT_DIAG_LTHREAD_TMR_EXPIRED,    /* 14 mask 0x00004000 */
 289         /* bits 15 - 19 conditional variable flag group */
 290         LT_DIAG_COND_CREATE,            /* 15 mask 0x00008000 */
 291         LT_DIAG_COND_DESTROY,           /* 16 mask 0x00010000 */
 292         LT_DIAG_COND_WAIT,              /* 17 mask 0x00020000 */
 293         LT_DIAG_COND_SIGNAL,            /* 18 mask 0x00040000 */
 294         LT_DIAG_COND_BROADCAST,         /* 19 mask 0x00080000 */
 295         /* bits 20 - 25 mutex flag group */
 296         LT_DIAG_MUTEX_CREATE,           /* 20 mask 0x00100000 */
 297         LT_DIAG_MUTEX_DESTROY,          /* 21 mask 0x00200000 */
 298         LT_DIAG_MUTEX_LOCK,             /* 22 mask 0x00400000 */
 299         LT_DIAG_MUTEX_TRYLOCK,          /* 23 mask 0x00800000 */
 300         LT_DIAG_MUTEX_BLOCKED,          /* 24 mask 0x01000000 */
 301         LT_DIAG_MUTEX_UNLOCKED,         /* 25 mask 0x02000000 */
 302         /* bits 26 - 27 scheduler flag group - 8 bits */
 303         LT_DIAG_SCHED_CREATE,           /* 26 mask 0x04000000 */
 304         LT_DIAG_SCHED_SHUTDOWN,         /* 27 mask 0x08000000 */
 305         LT_DIAG_EVENT_MAX
 306 };
 307
 308 #define LT_DIAG_ALL 0xffffffffffffffff
 309
 310
 311 /*
 312  * Display scheduler stats
 313  */
 314 void
 315 lthread_sched_stats_display(void);
 316
 317 /*
 318  * return the diagnostic ref val stored in a condition var
 319  */
 320 uint64_t
 321 lthread_cond_diag_ref(struct lthread_cond *c);
 322
 323 /*
 324  * return the diagnostic ref val stored in a mutex
 325  */
 326 uint64_t
 327 lthread_mutex_diag_ref(struct lthread_mutex *m);
 328
 329 #ifdef __cplusplus
 330 }
 331 #endif
 332
 333 #endif                          /* LTHREAD_DIAG_API_H_ */