include/linux/wimax/debug.h

   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/device.h>
 158
 159
 160 /* Backend stuff */
 161
 162 /*
 163  * Debug backend: generate a message header from a 'struct device'
 164  *
 165  * @head: buffer where to place the header
 166  * @head_size: length of @head
 167  * @dev: pointer to device used to generate a header from. If NULL,
 168  *     an empty ("") header is generated.
 169  */
 170 static inline
 171 void __d_head(char *head, size_t head_size,
 172               struct device *dev)
 173 {
 174         if (dev == NULL)
 175                 head[0] = 0;
 176         else if ((unsigned long)dev < 4096) {
 177                 printk(KERN_ERR "E: Corrupt dev %p\n", dev);
 178                 WARN_ON(1);
 179         } else
 180                 snprintf(head, head_size, "%s %s: ",
 181                          dev_driver_string(dev), dev_name(dev));
 182 }
 183
 184
 185 /*
 186  * Debug backend: log some message if debugging is enabled
 187  *
 188  * @l: intended debug level
 189  * @tag: tag to prefix the message with
 190  * @dev: 'struct device' associated to this message
 191  * @f: printf-like format and arguments
 192  *
 193  * Note this is optimized out if it doesn't pass the compile-time
 194  * check; however, it is *always* compiled. This is useful to make
 195  * sure the printf-like formats and variables are always checked and
 196  * they don't get bit rot if you have all the debugging disabled.
 197  */
 198 #define _d_printf(l, tag, dev, f, a...)                                 \
 199 do {                                                                    \
 200         char head[64];                                                  \
 201         if (!d_test(l))                                                 \
 202                 break;                                                  \
 203         __d_head(head, sizeof(head), dev);                              \
 204         printk(KERN_ERR "%s%s%s: " f, head, __func__, tag, ##a);        \
 205 } while (0)
 206
 207
 208 /*
 209  * CPP sintatic sugar to generate A_B like symbol names when one of
 210  * the arguments is a a preprocessor #define.
 211  */
 212 #define __D_PASTE__(varname, modulename) varname##_##modulename
 213 #define __D_PASTE(varname, modulename) (__D_PASTE__(varname, modulename))
 214 #define _D_SUBMODULE_INDEX(_name) (D_SUBMODULE_DECLARE(_name))
 215
 216
 217 /*
 218  * Store a submodule's runtime debug level and name
 219  */
 220 struct d_level {
 221         u8 level;
 222         const char *name;
 223 };
 224
 225
 226 /*
 227  * List of available submodules and their debug levels
 228  *
 229  * We call them d_level_MODULENAME and d_level_size_MODULENAME; the
 230  * macros D_LEVEL and D_LEVEL_SIZE contain the name already for
 231  * convenience.
 232  *
 233  * This array and the size are defined on some .c file that is part of
 234  * the current module.
 235  */
 236 #define D_LEVEL __D_PASTE(d_level, D_MODULENAME)
 237 #define D_LEVEL_SIZE __D_PASTE(d_level_size, D_MODULENAME)
 238
 239 extern struct d_level D_LEVEL[];
 240 extern size_t D_LEVEL_SIZE;
 241
 242
 243 /*
 244  * Frontend stuff
 245  *
 246  *
 247  * Stuff you need to declare prior to using the actual "debug" actions
 248  * (defined below).
 249  */
 250
 251 #ifndef D_MODULENAME
 252 #error D_MODULENAME is not defined in your debug-levels.h file
 253 /**
 254  * D_MODULE - Name of the current module
 255  *
 256  * #define in your module's debug-levels.h, making sure it is
 257  * unique. This has to be a legal C identifier.
 258  */
 259 #define D_MODULENAME undefined_modulename
 260 #endif
 261
 262
 263 #ifndef D_MASTER
 264 #warning D_MASTER not defined, but debug.h included! [see docs]
 265 /**
 266  * D_MASTER - Compile time maximum debug level
 267  *
 268  * #define in your debug-levels.h file to the maximum debug level the
 269  * runtime code will be allowed to have. This allows you to provide a
 270  * main knob.
 271  *
 272  * Anything above that level will be optimized out of the compile.
 273  *
 274  * Defaults to zero (no debug code compiled in).
 275  *
 276  * Maximum one definition per module (at the debug-levels.h file).
 277  */
 278 #define D_MASTER 0
 279 #endif
 280
 281 #ifndef D_SUBMODULE
 282 #error D_SUBMODULE not defined, but debug.h included! [see docs]
 283 /**
 284  * D_SUBMODULE - Name of the current submodule
 285  *
 286  * #define in your submodule .c file before #including debug-levels.h
 287  * to the name of the current submodule as previously declared and
 288  * defined with D_SUBMODULE_DECLARE() (in your module's
 289  * debug-levels.h) and D_SUBMODULE_DEFINE().
 290  *
 291  * This is used to provide runtime-control over the debug levels.
 292  *
 293  * Maximum one per .c file! Can be shared among different .c files
 294  * (meaning they belong to the same submodule categorization).
 295  */
 296 #define D_SUBMODULE undefined_module
 297 #endif
 298
 299
 300 /**
 301  * D_SUBMODULE_DECLARE - Declare a submodule for runtime debug level control
 302  *
 303  * @_name: name of the submodule, restricted to the chars that make up a
 304  *     valid C identifier ([a-zA-Z0-9_]).
 305  *
 306  * Declare in the module's debug-levels.h header file as:
 307  *
 308  * enum d_module {
 309  *         D_SUBMODULE_DECLARE(submodule_1),
 310  *         D_SUBMODULE_DECLARE(submodule_2),
 311  *         D_SUBMODULE_DECLARE(submodule_3),
 312  * };
 313  *
 314  * Some corresponding .c file needs to have a matching
 315  * D_SUBMODULE_DEFINE().
 316  */
 317 #define D_SUBMODULE_DECLARE(_name) __D_SUBMODULE_##_name
 318
 319
 320 /**
 321  * D_SUBMODULE_DEFINE - Define a submodule for runtime debug level control
 322  *
 323  * @_name: name of the submodule, restricted to the chars that make up a
 324  *     valid C identifier ([a-zA-Z0-9_]).
 325  *
 326  * Use once per module (in some .c file) as:
 327  *
 328  * static
 329  * struct d_level d_level_SUBMODULENAME[] = {
 330  *         D_SUBMODULE_DEFINE(submodule_1),
 331  *         D_SUBMODULE_DEFINE(submodule_2),
 332  *         D_SUBMODULE_DEFINE(submodule_3),
 333  * };
 334  * size_t d_level_size_SUBDMODULENAME = ARRAY_SIZE(d_level_SUBDMODULENAME);
 335  *
 336  * Matching D_SUBMODULE_DECLARE()s have to be present in a
 337  * debug-levels.h header file.
 338  */
 339 #define D_SUBMODULE_DEFINE(_name)               \
 340 [__D_SUBMODULE_##_name] = {                     \
 341         .level = 0,                             \
 342         .name = #_name                          \
 343 }
 344
 345
 346
 347 /* The actual "debug" operations */
 348
 349
 350 /**
 351  * d_test - Returns true if debugging should be enabled
 352  *
 353  * @l: intended debug level (unsigned)
 354  *
 355  * If the master debug switch is enabled and the current settings are
 356  * higher or equal to the requested level, then debugging
 357  * output/actions should be enabled.
 358  *
 359  * NOTE:
 360  *
 361  * This needs to be coded so that it can be evaluated in compile
 362  * time; this is why the ugly BUG_ON() is placed in there, so the
 363  * D_MASTER evaluation compiles all out if it is compile-time false.
 364  */
 365 #define d_test(l)                                                       \
 366 ({                                                                      \
 367         unsigned __l = l;       /* type enforcer */                     \
 368         (D_MASTER) >= __l                                               \
 369         && ({                                                           \
 370                 BUG_ON(_D_SUBMODULE_INDEX(D_SUBMODULE) >= D_LEVEL_SIZE);\
 371                 D_LEVEL[_D_SUBMODULE_INDEX(D_SUBMODULE)].level >= __l;  \
 372         });                                                             \
 373 })
 374
 375
 376 /**
 377  * d_fnstart - log message at function start if debugging enabled
 378  *
 379  * @l: intended debug level
 380  * @_dev: 'struct device' pointer, NULL if none (for context)
 381  * @f: printf-like format and arguments
 382  */
 383 #define d_fnstart(l, _dev, f, a...) _d_printf(l, " FNSTART", _dev, f, ## a)
 384
 385
 386 /**
 387  * d_fnend - log message at function end if debugging enabled
 388  *
 389  * @l: intended debug level
 390  * @_dev: 'struct device' pointer, NULL if none (for context)
 391  * @f: printf-like format and arguments
 392  */
 393 #define d_fnend(l, _dev, f, a...) _d_printf(l, " FNEND", _dev, f, ## a)
 394
 395
 396 /**
 397  * d_printf - log message if debugging enabled
 398  *
 399  * @l: intended debug level
 400  * @_dev: 'struct device' pointer, NULL if none (for context)
 401  * @f: printf-like format and arguments
 402  */
 403 #define d_printf(l, _dev, f, a...) _d_printf(l, "", _dev, f, ## a)
 404
 405
 406 /**
 407  * d_dump - log buffer hex dump if debugging enabled
 408  *
 409  * @l: intended debug level
 410  * @_dev: 'struct device' pointer, NULL if none (for context)
 411  * @f: printf-like format and arguments
 412  */
 413 #define d_dump(l, dev, ptr, size)                       \
 414 do {                                                    \
 415         char head[64];                                  \
 416         if (!d_test(l))                                 \
 417                 break;                                  \
 418         __d_head(head, sizeof(head), dev);              \
 419         print_hex_dump(KERN_ERR, head, 0, 16, 1,        \
 420                        ((void *) ptr), (size), 0);      \
 421 } while (0)
 422
 423
 424 /**
 425  * Export a submodule's debug level over debugfs as PREFIXSUBMODULE
 426  *
 427  * @prefix: string to prefix the name with
 428  * @submodule: name of submodule (not a string, just the name)
 429  * @dentry: debugfs parent dentry
 430  *
 431  * Returns: 0 if ok, < 0 errno on error.
 432  *
 433  * For removing, just use debugfs_remove_recursive() on the parent.
 434  */
 435 #define d_level_register_debugfs(prefix, name, parent)                  \
 436 ({                                                                      \
 437         int rc;                                                         \
 438         struct dentry *fd;                                              \
 439         struct dentry *verify_parent_type = parent;                     \
 440         fd = debugfs_create_u8(                                         \
 441                 prefix #name, 0600, verify_parent_type,                 \
 442                 &(D_LEVEL[__D_SUBMODULE_ ## name].level));              \
 443         rc = PTR_ERR(fd);                                               \
 444         if (IS_ERR(fd) && rc != -ENODEV)                                \
 445                 printk(KERN_ERR "%s: Can't create debugfs entry %s: "   \
 446                        "%d\n", __func__, prefix #name, rc);             \
 447         else                                                            \
 448                 rc = 0;                                                 \
 449         rc;                                                             \
 450 })
 451
 452
 453 #endif /* #ifndef __debug__h__ */