1 /*
2 * Linux WiMAX
3 * Collection of tools to manage debug operations.
4 *
5 *
6 * Copyright (C) 2005-2007 Intel Corporation
7 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8 *
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License version
11 * 2 as published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 * 02110-1301, USA.
22 *
23 *
24 * Don't #include this file directly, read on!
25 *
26 *
27 * EXECUTING DEBUGGING ACTIONS OR NOT
28 *
29 * The main thing this framework provides is decission power to take a
30 * debug action (like printing a message) if the current debug level
31 * allows it.
32 *
33 * The decission power is at two levels: at compile-time (what does
34 * not make it is compiled out) and at run-time. The run-time
35 * selection is done per-submodule (as they are declared by the user
36 * of the framework).
37 *
38 * A call to d_test(L) (L being the target debug level) returns true
39 * if the action should be taken because the current debug levels
40 * allow it (both compile and run time).
41 *
42 * It follows that a call to d_test() that can be determined to be
43 * always false at compile time will get the code depending on it
44 * compiled out by optimization.
45 *
46 *
47 * DEBUG LEVELS
48 *
49 * It is up to the caller to define how much a debugging level is.
50 *
51 * Convention sets 0 as "no debug" (so an action marked as debug level 0
52 * will always be taken). The increasing debug levels are used for
53 * increased verbosity.
54 *
55 *
56 * USAGE
57 *
58 * Group the code in modules and submodules inside each module [which
59 * in most cases maps to Linux modules and .c files that compose
60 * those].
61 *
62 *
63 * For each module, there is:
64 *
65 * - a MODULENAME (single word, legal C identifier)
66 *
67 * - a debug-levels.h header file that declares the list of
68 * submodules and that is included by all .c files that use
69 * the debugging tools. The file name can be anything.
70 *
71 * - some (optional) .c code to manipulate the runtime debug levels
72 * through debugfs.
73 *
74 * The debug-levels.h file would look like:
75 *
76 * #ifndef __debug_levels__h__
77 * #define __debug_levels__h__
78 *
79 * #define D_MODULENAME modulename
80 * #define D_MASTER 10
81 *
82 * #include <linux/wimax/debug.h>
83 *
84 * enum d_module {
85 * D_SUBMODULE_DECLARE(submodule_1),
86 * D_SUBMODULE_DECLARE(submodule_2),
87 * ...
88 * D_SUBMODULE_DECLARE(submodule_N)
89 * };
90 *
91 * #endif
92 *
93 * D_MASTER is the maximum compile-time debug level; any debug actions
94 * above this will be out. D_MODULENAME is the module name (legal C
95 * identifier), which has to be unique for each module (to avoid
96 * namespace collisions during linkage). Note those #defines need to
97 * be done before #including debug.h
98 *
99 * We declare N different submodules whose debug level can be
100 * independently controlled during runtime.
101 *
102 * In a .c file of the module (and only in one of them), define the
103 * following code:
104 *
105 * struct d_level D_LEVEL[] = {
106 * D_SUBMODULE_DEFINE(submodule_1),
107 * D_SUBMODULE_DEFINE(submodule_2),
108 * ...
109 * D_SUBMODULE_DEFINE(submodule_N),
110 * };
111 * size_t D_LEVEL_SIZE = ARRAY_SIZE(D_LEVEL);
112 *
113 * Externs for d_level_MODULENAME and d_level_size_MODULENAME are used
114 * and declared in this file using the D_LEVEL and D_LEVEL_SIZE macros
115 * #defined also in this file.
116 *
117 * To manipulate from user space the levels, create a debugfs dentry
118 * and then register each submodule with:
119 *
120 * result = d_level_register_debugfs("PREFIX_", submodule_X, parent);
121 * if (result < 0)
122 * goto error;
123 *
124 * Where PREFIX_ is a name of your chosing. This will create debugfs
125 * file with a single numeric value that can be use to tweak it. To
126 * remove the entires, just use debugfs_remove_recursive() on 'parent'.
127 *
128 * NOTE: remember that even if this will show attached to some
129 * particular instance of a device, the settings are *global*.
130 *
131 *
132 * On each submodule (for example, .c files), the debug infrastructure
133 * should be included like this:
134 *
135 * #define D_SUBMODULE submodule_x // matches one in debug-levels.h
136 * #include "debug-levels.h"
137 *
138 * after #including all your include files.
139 *
140 *
141 * Now you can use the d_*() macros below [d_test(), d_fnstart(),
142 * d_fnend(), d_printf(), d_dump()].
143 *
144 * If their debug level is greater than D_MASTER, they will be
145 * compiled out.
146 *
147 * If their debug level is lower or equal than D_MASTER but greater
148 * than the current debug level of their submodule, they'll be
149 * ignored.
150 *
151 * Otherwise, the action will be performed.
152 */
153 #ifndef __debug__h__
154 #define __debug__h__
155
156 #include <linux/types.h>
157 #include <linux/slab.h>
158
159 struct device;
160
161 /* Backend stuff */
162
163 /*
164 * Debug backend: generate a message header from a 'struct device'
165 *
166 * @head: buffer where to place the header
167 * @head_size: length of @head
168 * @dev: pointer to device used to generate a header from. If NULL,
169 * an empty ("") header is generated.
170 */
171 static inline
__d_head(char * head,size_t head_size,struct device * dev)172 void __d_head(char *head, size_t head_size,
173 struct device *dev)
174 {
175 if (dev == NULL)
176 head[0] = 0;
177 else if ((unsigned long)dev < 4096) {
178 printk(KERN_ERR "E: Corrupt dev %p\n", dev);
179 WARN_ON(1);
180 } else
181 snprintf(head, head_size, "%s %s: ",
182 dev_driver_string(dev), dev_name(dev));
183 }
184
185
186 /*
187 * Debug backend: log some message if debugging is enabled
188 *
189 * @l: intended debug level
190 * @tag: tag to prefix the message with
191 * @dev: 'struct device' associated to this message
192 * @f: printf-like format and arguments
193 *
194 * Note this is optimized out if it doesn't pass the compile-time
195 * check; however, it is *always* compiled. This is useful to make
196 * sure the printf-like formats and variables are always checked and
197 * they don't get bit rot if you have all the debugging disabled.
198 */
199 #define _d_printf(l, tag, dev, f, a...) \
200 do { \
201 char head[64]; \
202 if (!d_test(l)) \
203 break; \
204 __d_head(head, sizeof(head), dev); \
205 printk(KERN_ERR "%s%s%s: " f, head, __func__, tag, ##a); \
206 } while (0)
207
208
209 /*
210 * CPP sintatic sugar to generate A_B like symbol names when one of
211 * the arguments is a a preprocessor #define.
212 */
213 #define __D_PASTE__(varname, modulename) varname##_##modulename
214 #define __D_PASTE(varname, modulename) (__D_PASTE__(varname, modulename))
215 #define _D_SUBMODULE_INDEX(_name) (D_SUBMODULE_DECLARE(_name))
216
217
218 /*
219 * Store a submodule's runtime debug level and name
220 */
221 struct d_level {
222 u8 level;
223 const char *name;
224 };
225
226
227 /*
228 * List of available submodules and their debug levels
229 *
230 * We call them d_level_MODULENAME and d_level_size_MODULENAME; the
231 * macros D_LEVEL and D_LEVEL_SIZE contain the name already for
232 * convenience.
233 *
234 * This array and the size are defined on some .c file that is part of
235 * the current module.
236 */
237 #define D_LEVEL __D_PASTE(d_level, D_MODULENAME)
238 #define D_LEVEL_SIZE __D_PASTE(d_level_size, D_MODULENAME)
239
240 extern struct d_level D_LEVEL[];
241 extern size_t D_LEVEL_SIZE;
242
243
244 /*
245 * Frontend stuff
246 *
247 *
248 * Stuff you need to declare prior to using the actual "debug" actions
249 * (defined below).
250 */
251
252 #ifndef D_MODULENAME
253 #error D_MODULENAME is not defined in your debug-levels.h file
254 /**
255 * D_MODULE - Name of the current module
256 *
257 * #define in your module's debug-levels.h, making sure it is
258 * unique. This has to be a legal C identifier.
259 */
260 #define D_MODULENAME undefined_modulename
261 #endif
262
263
264 #ifndef D_MASTER
265 #warning D_MASTER not defined, but debug.h included! [see docs]
266 /**
267 * D_MASTER - Compile time maximum debug level
268 *
269 * #define in your debug-levels.h file to the maximum debug level the
270 * runtime code will be allowed to have. This allows you to provide a
271 * main knob.
272 *
273 * Anything above that level will be optimized out of the compile.
274 *
275 * Defaults to zero (no debug code compiled in).
276 *
277 * Maximum one definition per module (at the debug-levels.h file).
278 */
279 #define D_MASTER 0
280 #endif
281
282 #ifndef D_SUBMODULE
283 #error D_SUBMODULE not defined, but debug.h included! [see docs]
284 /**
285 * D_SUBMODULE - Name of the current submodule
286 *
287 * #define in your submodule .c file before #including debug-levels.h
288 * to the name of the current submodule as previously declared and
289 * defined with D_SUBMODULE_DECLARE() (in your module's
290 * debug-levels.h) and D_SUBMODULE_DEFINE().
291 *
292 * This is used to provide runtime-control over the debug levels.
293 *
294 * Maximum one per .c file! Can be shared among different .c files
295 * (meaning they belong to the same submodule categorization).
296 */
297 #define D_SUBMODULE undefined_module
298 #endif
299
300
301 /**
302 * D_SUBMODULE_DECLARE - Declare a submodule for runtime debug level control
303 *
304 * @_name: name of the submodule, restricted to the chars that make up a
305 * valid C identifier ([a-zA-Z0-9_]).
306 *
307 * Declare in the module's debug-levels.h header file as:
308 *
309 * enum d_module {
310 * D_SUBMODULE_DECLARE(submodule_1),
311 * D_SUBMODULE_DECLARE(submodule_2),
312 * D_SUBMODULE_DECLARE(submodule_3),
313 * };
314 *
315 * Some corresponding .c file needs to have a matching
316 * D_SUBMODULE_DEFINE().
317 */
318 #define D_SUBMODULE_DECLARE(_name) __D_SUBMODULE_##_name
319
320
321 /**
322 * D_SUBMODULE_DEFINE - Define a submodule for runtime debug level control
323 *
324 * @_name: name of the submodule, restricted to the chars that make up a
325 * valid C identifier ([a-zA-Z0-9_]).
326 *
327 * Use once per module (in some .c file) as:
328 *
329 * static
330 * struct d_level d_level_SUBMODULENAME[] = {
331 * D_SUBMODULE_DEFINE(submodule_1),
332 * D_SUBMODULE_DEFINE(submodule_2),
333 * D_SUBMODULE_DEFINE(submodule_3),
334 * };
335 * size_t d_level_size_SUBDMODULENAME = ARRAY_SIZE(d_level_SUBDMODULENAME);
336 *
337 * Matching D_SUBMODULE_DECLARE()s have to be present in a
338 * debug-levels.h header file.
339 */
340 #define D_SUBMODULE_DEFINE(_name) \
341 [__D_SUBMODULE_##_name] = { \
342 .level = 0, \
343 .name = #_name \
344 }
345
346
347
348 /* The actual "debug" operations */
349
350
351 /**
352 * d_test - Returns true if debugging should be enabled
353 *
354 * @l: intended debug level (unsigned)
355 *
356 * If the master debug switch is enabled and the current settings are
357 * higher or equal to the requested level, then debugging
358 * output/actions should be enabled.
359 *
360 * NOTE:
361 *
362 * This needs to be coded so that it can be evaluated in compile
363 * time; this is why the ugly BUG_ON() is placed in there, so the
364 * D_MASTER evaluation compiles all out if it is compile-time false.
365 */
366 #define d_test(l) \
367 ({ \
368 unsigned __l = l; /* type enforcer */ \
369 (D_MASTER) >= __l \
370 && ({ \
371 BUG_ON(_D_SUBMODULE_INDEX(D_SUBMODULE) >= D_LEVEL_SIZE);\
372 D_LEVEL[_D_SUBMODULE_INDEX(D_SUBMODULE)].level >= __l; \
373 }); \
374 })
375
376
377 /**
378 * d_fnstart - log message at function start if debugging enabled
379 *
380 * @l: intended debug level
381 * @_dev: 'struct device' pointer, NULL if none (for context)
382 * @f: printf-like format and arguments
383 */
384 #define d_fnstart(l, _dev, f, a...) _d_printf(l, " FNSTART", _dev, f, ## a)
385
386
387 /**
388 * d_fnend - log message at function end if debugging enabled
389 *
390 * @l: intended debug level
391 * @_dev: 'struct device' pointer, NULL if none (for context)
392 * @f: printf-like format and arguments
393 */
394 #define d_fnend(l, _dev, f, a...) _d_printf(l, " FNEND", _dev, f, ## a)
395
396
397 /**
398 * d_printf - log message if debugging enabled
399 *
400 * @l: intended debug level
401 * @_dev: 'struct device' pointer, NULL if none (for context)
402 * @f: printf-like format and arguments
403 */
404 #define d_printf(l, _dev, f, a...) _d_printf(l, "", _dev, f, ## a)
405
406
407 /**
408 * d_dump - log buffer hex dump if debugging enabled
409 *
410 * @l: intended debug level
411 * @_dev: 'struct device' pointer, NULL if none (for context)
412 * @f: printf-like format and arguments
413 */
414 #define d_dump(l, dev, ptr, size) \
415 do { \
416 char head[64]; \
417 if (!d_test(l)) \
418 break; \
419 __d_head(head, sizeof(head), dev); \
420 print_hex_dump(KERN_ERR, head, 0, 16, 1, \
421 ((void *) ptr), (size), 0); \
422 } while (0)
423
424
425 /**
426 * Export a submodule's debug level over debugfs as PREFIXSUBMODULE
427 *
428 * @prefix: string to prefix the name with
429 * @submodule: name of submodule (not a string, just the name)
430 * @dentry: debugfs parent dentry
431 *
432 * Returns: 0 if ok, < 0 errno on error.
433 *
434 * For removing, just use debugfs_remove_recursive() on the parent.
435 */
436 #define d_level_register_debugfs(prefix, name, parent) \
437 ({ \
438 int rc; \
439 struct dentry *fd; \
440 struct dentry *verify_parent_type = parent; \
441 fd = debugfs_create_u8( \
442 prefix #name, 0600, verify_parent_type, \
443 &(D_LEVEL[__D_SUBMODULE_ ## name].level)); \
444 rc = PTR_ERR(fd); \
445 if (IS_ERR(fd) && rc != -ENODEV) \
446 printk(KERN_ERR "%s: Can't create debugfs entry %s: " \
447 "%d\n", __func__, prefix #name, rc); \
448 else \
449 rc = 0; \
450 rc; \
451 })
452
453
454 static inline
d_submodule_set(struct d_level * d_level,size_t d_level_size,const char * submodule,u8 level,const char * tag)455 void d_submodule_set(struct d_level *d_level, size_t d_level_size,
456 const char *submodule, u8 level, const char *tag)
457 {
458 struct d_level *itr, *top;
459 int index = -1;
460
461 for (itr = d_level, top = itr + d_level_size; itr < top; itr++) {
462 index++;
463 if (itr->name == NULL) {
464 printk(KERN_ERR "%s: itr->name NULL?? (%p, #%d)\n",
465 tag, itr, index);
466 continue;
467 }
468 if (!strcmp(itr->name, submodule)) {
469 itr->level = level;
470 return;
471 }
472 }
473 printk(KERN_ERR "%s: unknown submodule %s\n", tag, submodule);
474 }
475
476
477 /**
478 * d_parse_params - Parse a string with debug parameters from the
479 * command line
480 *
481 * @d_level: level structure (D_LEVEL)
482 * @d_level_size: number of items in the level structure
483 * (D_LEVEL_SIZE).
484 * @_params: string with the parameters; this is a space (not tab!)
485 * separated list of NAME:VALUE, where value is the debug level
486 * and NAME is the name of the submodule.
487 * @tag: string for error messages (example: MODULE.ARGNAME).
488 */
489 static inline
d_parse_params(struct d_level * d_level,size_t d_level_size,const char * _params,const char * tag)490 void d_parse_params(struct d_level *d_level, size_t d_level_size,
491 const char *_params, const char *tag)
492 {
493 char submodule[130], *params, *params_orig, *token, *colon;
494 unsigned level, tokens;
495
496 if (_params == NULL)
497 return;
498 params_orig = kstrdup(_params, GFP_KERNEL);
499 params = params_orig;
500 while (1) {
501 token = strsep(¶ms, " ");
502 if (token == NULL)
503 break;
504 if (*token == '\0') /* eat joint spaces */
505 continue;
506 /* kernel's sscanf %s eats until whitespace, so we
507 * replace : by \n so it doesn't get eaten later by
508 * strsep */
509 colon = strchr(token, ':');
510 if (colon != NULL)
511 *colon = '\n';
512 tokens = sscanf(token, "%s\n%u", submodule, &level);
513 if (colon != NULL)
514 *colon = ':'; /* set back, for error messages */
515 if (tokens == 2)
516 d_submodule_set(d_level, d_level_size,
517 submodule, level, tag);
518 else
519 printk(KERN_ERR "%s: can't parse '%s' as a "
520 "SUBMODULE:LEVEL (%d tokens)\n",
521 tag, token, tokens);
522 }
523 kfree(params_orig);
524 }
525
526 #endif /* #ifndef __debug__h__ */
527