1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4NETIF Msg Level
5===============
6
7The design of the network interface message level setting.
8
9History
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
76The 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  =========   ===================	============
96