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 */ 170static inline 171void __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...) \ 199do { \ 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 */ 220struct 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 239extern struct d_level D_LEVEL[]; 240extern 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) \ 414do { \ 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__ */ 454