Commit | Line | Data |
---|---|---|
c4d5dff6 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
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 | ========= =================== ============ |