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