4 * Copyright(c) 2015 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
33 #ifndef LTHREAD_DIAG_API_H_
34 #define LTHREAD_DIAG_API_H_
41 * 0 = conditionally compiled out
42 * 1 = compiled in and maskable at run time, see below for details
44 #define LTHREAD_DIAG 0
48 * @file lthread_diag_api.h
51 * @b EXPERIMENTAL: this API may change without prior notice
53 * lthread diagnostic interface
55 * If enabled via configuration file option ( tbd ) the lthread subsystem
56 * can generate selected trace information, either RTE_LOG (INFO) messages,
57 * or else invoke a user supplied callback function when any of the events
60 * Reporting of events can be selectively masked, the bit position in the
61 * mask is determined by the corresponding event identifier listed below.
63 * Diagnostics are enabled by registering the callback function and mask
64 * using the API lthread_diagnostic_enable().
66 * Various interesting parameters are passed to the callback, including the
67 * time in cpu clks, the lthread id, the diagnostic event id, a user ref value,
68 * event text string, object being traced, and two context dependent parameters
69 * (p1 and p2). The meaning of the two parameters p1 and p2 depends on
72 * The events LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE and
73 * LT_DIAG_COND_CREATE are implicitly enabled if the event mask includes any of
74 * the LT_DIAG_LTHREAD_XXX, LT_DIAG_MUTEX_XXX or LT_DIAG_COND_XXX events
77 * These create events may also be included in the mask discreetly if it is
78 * desired to monitor only create events.
81 * The time in cpu clks at which the event occurred
87 * The diagnostic event id (bit position in the mask)
91 * For LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE or LT_DIAG_COND_CREATE
92 * this parameter is not used and set to 0.
93 * All other events diag_ref contains the user ref value returned by the
94 * callback function when lthread is created.
96 * The diag_ref values assigned to mutex and cond var can be retrieved
97 * using the APIs lthread_mutex_diag_ref(), and lthread_cond_diag_ref()
107 * For LT_DIAG_LTHREAD_CREATE, LT_DIAG_MUTEX_CREATE or LT_DIAG_COND_CREATE
108 * expects a user diagnostic ref value that will be saved in the lthread, mutex
111 * For all other events return value is ignored.
113 * LT_DIAG_SCHED_CREATE - Invoked when a scheduler is created
114 * p1 = the scheduler that was created
116 * return value will be ignored
118 * LT_DIAG_SCHED_SHUTDOWN - Invoked when a shutdown request is received
119 * p1 = the scheduler to be shutdown
121 * return value will be ignored
123 * LT_DIAG_LTHREAD_CREATE - Invoked when a thread is created
124 * p1 = the lthread that was created
126 * return value will be stored in the lthread
128 * LT_DIAG_LTHREAD_EXIT - Invoked when a lthread exits
129 * p2 = 0 if the thread was already joined
130 * p2 = 1 if the thread was not already joined
133 * LT_DIAG_LTHREAD_JOIN - Invoked when a lthread exits
134 * p1 = the lthread that is being joined
135 * p2 = 0 if the thread was already exited
136 * p2 = 1 if the thread was not already exited
139 * LT_DIAG_LTHREAD_CANCELLED - Invoked when an lthread is cancelled
144 * LT_DIAG_LTHREAD_DETACH - Invoked when an lthread is detached
149 * LT_DIAG_LTHREAD_FREE - Invoked when an lthread is freed
154 * LT_DIAG_LTHREAD_SUSPENDED - Invoked when an lthread is suspended
159 * LT_DIAG_LTHREAD_YIELD - Invoked when an lthread explicitly yields
164 * LT_DIAG_LTHREAD_RESCHEDULED - Invoked when an lthread is rescheduled
169 * LT_DIAG_LTHREAD_RESUMED - Invoked when an lthread is resumed
174 * LT_DIAG_LTHREAD_AFFINITY - Invoked when an lthread is affinitised
175 * p1 = the destination lcore_id
179 * LT_DIAG_LTHREAD_TMR_START - Invoked when an lthread starts a timer
180 * p1 = address of timer node
181 * p2 = the timeout value
184 * LT_DIAG_LTHREAD_TMR_DELETE - Invoked when an lthread deletes a timer
185 * p1 = address of the timer node
186 * p2 = 0 the timer and the was successfully deleted
190 * LT_DIAG_LTHREAD_TMR_EXPIRED - Invoked when an lthread timer expires
191 * p1 = address of scheduler the timer expired on
192 * p2 = the thread associated with the timer
195 * LT_DIAG_COND_CREATE - Invoked when a condition variable is created
196 * p1 = address of cond var that was created
198 * return diag ref value will be stored in the condition variable
200 * LT_DIAG_COND_DESTROY - Invoked when a condition variable is destroyed
205 * LT_DIAG_COND_WAIT - Invoked when an lthread waits on a cond var
206 * p1 = the address of the condition variable
210 * LT_DIAG_COND_SIGNAL - Invoked when an lthread signals a cond var
211 * p1 = the address of the cond var
212 * p2 = the lthread that was signalled, or error code
215 * LT_DIAG_COND_BROADCAST - Invoked when an lthread broadcasts a cond var
216 * p1 = the address of the condition variable
217 * p2 = the lthread(s) that are signalled, or error code
219 * LT_DIAG_MUTEX_CREATE - Invoked when a mutex is created
220 * p1 = address of muex
222 * return diag ref value will be stored in the mutex variable
224 * LT_DIAG_MUTEX_DESTROY - Invoked when a mutex is destroyed
225 * p1 = address of mutex
229 * LT_DIAG_MUTEX_LOCK - Invoked when a mutex lock is obtained
230 * p1 = address of mutex
231 * p2 = function return value
234 * LT_DIAG_MUTEX_BLOCKED - Invoked when an lthread blocks on a mutex
235 * p1 = address of mutex
236 * p2 = function return value
239 * LT_DIAG_MUTEX_TRYLOCK - Invoked when a mutex try lock is attempted
240 * p1 = address of mutex
241 * p2 = the function return value
244 * LT_DIAG_MUTEX_UNLOCKED - Invoked when a mutex is unlocked
245 * p1 = address of mutex
246 * p2 = the thread that was unlocked, or error code
249 typedef uint64_t (*diag_callback) (uint64_t time, struct lthread *lt,
250 int diag_event, uint64_t diag_ref,
251 const char *text, uint64_t p1, uint64_t p2);
254 * Set user diagnostic callback and mask
255 * If the callback function pointer is NULL the default
256 * callback handler will be restored.
258 void lthread_diagnostic_enable(diag_callback cb, uint64_t diag_mask);
261 * Set diagnostic mask
263 void lthread_diagnostic_set_mask(uint64_t mask);
266 * lthread diagnostic callback
268 enum lthread_diag_ev {
269 /* bits 0 - 14 lthread flag group */
270 LT_DIAG_LTHREAD_CREATE, /* 00 mask 0x00000001 */
271 LT_DIAG_LTHREAD_EXIT, /* 01 mask 0x00000002 */
272 LT_DIAG_LTHREAD_JOIN, /* 02 mask 0x00000004 */
273 LT_DIAG_LTHREAD_CANCEL, /* 03 mask 0x00000008 */
274 LT_DIAG_LTHREAD_DETACH, /* 04 mask 0x00000010 */
275 LT_DIAG_LTHREAD_FREE, /* 05 mask 0x00000020 */
276 LT_DIAG_LTHREAD_SUSPENDED, /* 06 mask 0x00000040 */
277 LT_DIAG_LTHREAD_YIELD, /* 07 mask 0x00000080 */
278 LT_DIAG_LTHREAD_RESCHEDULED, /* 08 mask 0x00000100 */
279 LT_DIAG_LTHREAD_SLEEP, /* 09 mask 0x00000200 */
280 LT_DIAG_LTHREAD_RESUMED, /* 10 mask 0x00000400 */
281 LT_DIAG_LTHREAD_AFFINITY, /* 11 mask 0x00000800 */
282 LT_DIAG_LTHREAD_TMR_START, /* 12 mask 0x00001000 */
283 LT_DIAG_LTHREAD_TMR_DELETE, /* 13 mask 0x00002000 */
284 LT_DIAG_LTHREAD_TMR_EXPIRED, /* 14 mask 0x00004000 */
285 /* bits 15 - 19 conditional variable flag group */
286 LT_DIAG_COND_CREATE, /* 15 mask 0x00008000 */
287 LT_DIAG_COND_DESTROY, /* 16 mask 0x00010000 */
288 LT_DIAG_COND_WAIT, /* 17 mask 0x00020000 */
289 LT_DIAG_COND_SIGNAL, /* 18 mask 0x00040000 */
290 LT_DIAG_COND_BROADCAST, /* 19 mask 0x00080000 */
291 /* bits 20 - 25 mutex flag group */
292 LT_DIAG_MUTEX_CREATE, /* 20 mask 0x00100000 */
293 LT_DIAG_MUTEX_DESTROY, /* 21 mask 0x00200000 */
294 LT_DIAG_MUTEX_LOCK, /* 22 mask 0x00400000 */
295 LT_DIAG_MUTEX_TRYLOCK, /* 23 mask 0x00800000 */
296 LT_DIAG_MUTEX_BLOCKED, /* 24 mask 0x01000000 */
297 LT_DIAG_MUTEX_UNLOCKED, /* 25 mask 0x02000000 */
298 /* bits 26 - 27 scheduler flag group - 8 bits */
299 LT_DIAG_SCHED_CREATE, /* 26 mask 0x04000000 */
300 LT_DIAG_SCHED_SHUTDOWN, /* 27 mask 0x08000000 */
304 #define LT_DIAG_ALL 0xffffffffffffffff
308 * Display scheduler stats
311 lthread_sched_stats_display(void);
314 * return the diagnostic ref val stored in a condition var
317 lthread_cond_diag_ref(struct lthread_cond *c);
320 * return the diagnostic ref val stored in a mutex
323 lthread_mutex_diag_ref(struct lthread_mutex *m);
325 #endif /* LTHREAD_DIAG_API_H_ */