tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: networking: convert netif-msg.txt to ReST
- add SPDX header;
- adjust title and chapter markups;
- mark lists as such;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
authored by
Mauro Carvalho Chehab
and committed by
David S. Miller
c4d5dff6
01915330
+96
-79
+1
Documentation/networking/index.rst
+1
Documentation/networking/index.rst
+95
Documentation/networking/netif-msg.rst
+95
Documentation/networking/netif-msg.rst
···
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
+
========= =================== ============
-79
Documentation/networking/netif-msg.txt
-79
Documentation/networking/netif-msg.txt
···
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 recommendation 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
-