projects / linux.git / blame
| Commit | Line | Data |
|---|---|---|
| 1da177e4 LT |
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 | ||
| d6bc8ac9 | 43 | The netif_msg recommendation adds these features with only a minor |
| 1da177e4 LT |
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 |