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 #include <stdint.h>
37 #include <inttypes.h>
38 
39 /*
40  * Enable diagnostics
41  * 0 = conditionally compiled out
42  * 1 = compiled in and maskable at run time, see below for details
43  */
44 #define LTHREAD_DIAG 0
45 
46 /**
47  *
48  * @file lthread_diag_api.h
49  *
50  * @warning
51  * @b EXPERIMENTAL: this API may change without prior notice
52  *
53  * lthread diagnostic interface
54  *
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
58  * listed below occur.
59  *
60  * Reporting of events can be selectively masked, the bit position in the
61  * mask is determined by the corresponding event identifier listed below.
62  *
63  * Diagnostics are enabled by registering the callback function and mask
64  * using the API lthread_diagnostic_enable().
65  *
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
70  * the specific event.
71  *
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
75  * respectively.
76  *
77  * These create events may also be included in the mask discreetly if it is
78  * desired to monitor only create events.
79  *
80  * @param  time
81  *  The time in cpu clks at which the event occurred
82  *
83  * @param  lthread
84  *  The current lthread
85  *
86  * @param diag_event
87  *  The diagnostic event id (bit position in the mask)
88  *
89  * @param  diag_ref
90  *
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.
95  *
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()
98  * respectively.
99  *
100  * @param p1
101  *  see below
102  *
103  * @param p1
104  *  see below
105  *
106  * @returns
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
109  * or cond var.
110  *
111  * For all other events return value is ignored.
112  *
113  *	LT_DIAG_SCHED_CREATE - Invoked when a scheduler is created
114  *		p1 = the scheduler that was created
115  *		p2 = not used
116  *		return value will be ignored
117  *
118  *	LT_DIAG_SCHED_SHUTDOWN - Invoked when a shutdown request is received
119  *		p1 = the scheduler to be shutdown
120  *		p2 = not used
121  *		return value will be ignored
122  *
123  *	LT_DIAG_LTHREAD_CREATE - Invoked when a thread is created
124  *		p1 = the lthread that was created
125  *		p2 = not used
126  *		return value will be stored in the lthread
127  *
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
131  *		return val ignored
132  *
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
137  *		return val ignored
138  *
139  *	LT_DIAG_LTHREAD_CANCELLED - Invoked when an lthread is cancelled
140  *		p1 = not used
141  *		p2 = not used
142  *		return val ignored
143  *
144  *	LT_DIAG_LTHREAD_DETACH - Invoked when an lthread is detached
145  *		p1 = not used
146  *		p2 = not used
147  *		return val ignored
148  *
149  *	LT_DIAG_LTHREAD_FREE - Invoked when an lthread is freed
150  *		p1 = not used
151  *		p2 = not used
152  *		return val ignored
153  *
154  *	LT_DIAG_LTHREAD_SUSPENDED - Invoked when an lthread is suspended
155  *		p1 = not used
156  *		p2 = not used
157  *		return val ignored
158  *
159  *	LT_DIAG_LTHREAD_YIELD - Invoked when an lthread explicitly yields
160  *		p1 = not used
161  *		p2 = not used
162  *		return val ignored
163  *
164  *	LT_DIAG_LTHREAD_RESCHEDULED - Invoked when an lthread is rescheduled
165  *		p1 = not used
166  *		p2 = not used
167  *		return val ignored
168  *
169  *	LT_DIAG_LTHREAD_RESUMED - Invoked when an lthread is resumed
170  *		p1 = not used
171  *		p2 = not used
172  *		return val ignored
173  *
174  *	LT_DIAG_LTHREAD_AFFINITY - Invoked when an lthread is affinitised
175  *		p1 = the destination lcore_id
176  *		p2 = not used
177  *		return val ignored
178  *
179  *	LT_DIAG_LTHREAD_TMR_START - Invoked when an lthread starts a timer
180  *		p1 = address of timer node
181  *		p2 = the timeout value
182  *		return val ignored
183  *
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
187  *		p2 = not usee
188  *		return val ignored
189  *
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
193  *		return val ignored
194  *
195  *	LT_DIAG_COND_CREATE - Invoked when a condition variable is created
196  *		p1 = address of cond var that was created
197  *		p2 = not used
198  *		return diag ref value will be stored in the condition variable
199  *
200  *	LT_DIAG_COND_DESTROY - Invoked when a condition variable is destroyed
201  *		p1 = not used
202  *		p2 = not used
203  *		return val ignored
204  *
205  *	LT_DIAG_COND_WAIT - Invoked when an lthread waits on a cond var
206  *		p1 = the address of the condition variable
207  *		p2 = not used
208  *		return val ignored
209  *
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
213  *		return val ignored
214  *
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
218  *
219  *	LT_DIAG_MUTEX_CREATE - Invoked when a mutex is created
220  *		p1 = address of muex
221  *		p2 = not used
222  *		return diag ref value will be stored in the mutex variable
223  *
224  *	LT_DIAG_MUTEX_DESTROY - Invoked when a mutex is destroyed
225  *		p1 = address of mutex
226  *		p2 = not used
227  *		return val ignored
228  *
229  *	LT_DIAG_MUTEX_LOCK - Invoked when a mutex lock is obtained
230  *		p1 = address of mutex
231  *		p2 = function return value
232  *		return val ignored
233  *
234  *	LT_DIAG_MUTEX_BLOCKED  - Invoked when an lthread blocks on a mutex
235  *		p1 = address of mutex
236  *		p2 = function return value
237  *		return val ignored
238  *
239  *	LT_DIAG_MUTEX_TRYLOCK - Invoked when a mutex try lock is attempted
240  *		p1 = address of mutex
241  *		p2 = the function return value
242  *		return val ignored
243  *
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
247  *		return val ignored
248  */
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);
252 
253 /*
254  * Set user diagnostic callback and mask
255  * If the callback function pointer is NULL the default
256  * callback handler will be restored.
257  */
258 void lthread_diagnostic_enable(diag_callback cb, uint64_t diag_mask);
259 
260 /*
261  * Set diagnostic mask
262  */
263 void lthread_diagnostic_set_mask(uint64_t mask);
264 
265 /*
266  * lthread diagnostic callback
267  */
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 */
301 	LT_DIAG_EVENT_MAX
302 };
303 
304 #define LT_DIAG_ALL 0xffffffffffffffff
305 
306 
307 /*
308  * Display scheduler stats
309  */
310 void
311 lthread_sched_stats_display(void);
312 
313 /*
314  * return the diagnostic ref val stored in a condition var
315  */
316 uint64_t
317 lthread_cond_diag_ref(struct lthread_cond *c);
318 
319 /*
320  * return the diagnostic ref val stored in a mutex
321  */
322 uint64_t
323 lthread_mutex_diag_ref(struct lthread_mutex *m);
324 
325 #endif				/* LTHREAD_DIAG_API_H_ */
326