]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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_ */ |