| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | |
| 2 | ________________ |
| 3 | NETIF Msg Level |
| 4 | |
| 5 | The design of the network interface message level setting. |
| 6 | |
| 7 | History |
| 8 | |
| 9 | The design of the debugging message interface was guided and |
| 10 | constrained by backwards compatibility previous practice. It is useful |
| 11 | to understand the history and evolution in order to understand current |
| 12 | practice and relate it to older driver source code. |
| 13 | |
| 14 | From the beginning of Linux, each network device driver has had a local |
| 15 | integer variable that controls the debug message level. The message |
| 16 | level ranged from 0 to 7, and monotonically increased in verbosity. |
| 17 | |
| 18 | The message level was not precisely defined past level 3, but were |
| 19 | always implemented within +-1 of the specified level. Drivers tended |
| 20 | to shed the more verbose level messages as they matured. |
| 21 | 0 Minimal messages, only essential information on fatal errors. |
| 22 | 1 Standard messages, initialization status. No run-time messages |
| 23 | 2 Special media selection messages, generally timer-driver. |
| 24 | 3 Interface starts and stops, including normal status messages |
| 25 | 4 Tx and Rx frame error messages, and abnormal driver operation |
| 26 | 5 Tx packet queue information, interrupt events. |
| 27 | 6 Status on each completed Tx packet and received Rx packets |
| 28 | 7 Initial contents of Tx and Rx packets |
| 29 | |
| 30 | Initially this message level variable was uniquely named in each driver |
| 31 | e.g. "lance_debug", so that a kernel symbolic debugger could locate and |
| 32 | modify the setting. When kernel modules became common, the variables |
| 33 | were consistently renamed to "debug" and allowed to be set as a module |
| 34 | parameter. |
| 35 | |
| 36 | This approach worked well. However there is always a demand for |
| 37 | additional features. Over the years the following emerged as |
| 38 | reasonable and easily implemented enhancements |
| 39 | Using an ioctl() call to modify the level. |
| 40 | Per-interface rather than per-driver message level setting. |
| 41 | More selective control over the type of messages emitted. |
| 42 | |
| 43 | The netif_msg recommandation adds these features with only a minor |
| 44 | complexity and code size increase. |
| 45 | |
| 46 | The recommendation is the following points |
| 47 | Retaining the per-driver integer variable "debug" as a module |
| 48 | parameter with a default level of '1'. |
| 49 | |
| 50 | Adding a per-interface private variable named "msg_enable". The |
| 51 | variable is a bit map rather than a level, and is initialized as |
| 52 | 1 << debug |
| 53 | Or more precisely |
| 54 | debug < 0 ? 0 : 1 << min(sizeof(int)-1, debug) |
| 55 | |
| 56 | Messages should changes from |
| 57 | if (debug > 1) |
| 58 | printk(MSG_DEBUG "%s: ... |
| 59 | to |
| 60 | if (np->msg_enable & NETIF_MSG_LINK) |
| 61 | printk(MSG_DEBUG "%s: ... |
| 62 | |
| 63 | |
| 64 | The set of message levels is named |
| 65 | Old level Name Bit position |
| 66 | 0 NETIF_MSG_DRV 0x0001 |
| 67 | 1 NETIF_MSG_PROBE 0x0002 |
| 68 | 2 NETIF_MSG_LINK 0x0004 |
| 69 | 2 NETIF_MSG_TIMER 0x0004 |
| 70 | 3 NETIF_MSG_IFDOWN 0x0008 |
| 71 | 3 NETIF_MSG_IFUP 0x0008 |
| 72 | 4 NETIF_MSG_RX_ERR 0x0010 |
| 73 | 4 NETIF_MSG_TX_ERR 0x0010 |
| 74 | 5 NETIF_MSG_TX_QUEUED 0x0020 |
| 75 | 5 NETIF_MSG_INTR 0x0020 |
| 76 | 6 NETIF_MSG_TX_DONE 0x0040 |
| 77 | 6 NETIF_MSG_RX_STATUS 0x0040 |
| 78 | 7 NETIF_MSG_PKTDATA 0x0080 |
| 79 | |