include/linux/wimax/debug.h

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