~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/wimax/debug.h

Version: ~ [ linux-5.9.1 ] ~ [ linux-5.8.16 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.72 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.152 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.202 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.240 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.240 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.85 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  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
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
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
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(&params, " ");
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 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp