mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2024-12-29 09:13:38 +00:00
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>
This commit is contained in:
Mauro Carvalho Chehab
David S. Miller
parent
0191533087
commit
c4d5dff60f
@ -84,6 +84,7 @@ Contents:
|
||||
netdev-features
|
||||
netdevices
|
||||
netfilter-sysctl
|
||||
netif-msg
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
||||
95
Documentation/networking/netif-msg.rst
Normal file
95
Documentation/networking/netif-msg.rst
Normal file
@ -0,0 +1,95 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
===============
|
||||
NETIF Msg Level
|
||||
===============
|
||||
|
||||
The design of the network interface message level setting.
|
||||
|
||||
History
|
||||
-------
|
||||
|
||||
The design of the debugging message interface was guided and
|
||||
constrained by backwards compatibility previous practice. It is useful
|
||||
to understand the history and evolution in order to understand current
|
||||
practice and relate it to older driver source code.
|
||||
|
||||
From the beginning of Linux, each network device driver has had a local
|
||||
integer variable that controls the debug message level. The message
|
||||
level ranged from 0 to 7, and monotonically increased in verbosity.
|
||||
|
||||
The message level was not precisely defined past level 3, but were
|
||||
always implemented within +-1 of the specified level. Drivers tended
|
||||
to shed the more verbose level messages as they matured.
|
||||
|
||||
- 0 Minimal messages, only essential information on fatal errors.
|
||||
- 1 Standard messages, initialization status. No run-time messages
|
||||
- 2 Special media selection messages, generally timer-driver.
|
||||
- 3 Interface starts and stops, including normal status messages
|
||||
- 4 Tx and Rx frame error messages, and abnormal driver operation
|
||||
- 5 Tx packet queue information, interrupt events.
|
||||
- 6 Status on each completed Tx packet and received Rx packets
|
||||
- 7 Initial contents of Tx and Rx packets
|
||||
|
||||
Initially this message level variable was uniquely named in each driver
|
||||
e.g. "lance_debug", so that a kernel symbolic debugger could locate and
|
||||
modify the setting. When kernel modules became common, the variables
|
||||
were consistently renamed to "debug" and allowed to be set as a module
|
||||
parameter.
|
||||
|
||||
This approach worked well. However there is always a demand for
|
||||
additional features. Over the years the following emerged as
|
||||
reasonable and easily implemented enhancements
|
||||
|
||||
- Using an ioctl() call to modify the level.
|
||||
- Per-interface rather than per-driver message level setting.
|
||||
- More selective control over the type of messages emitted.
|
||||
|
||||
The netif_msg recommendation adds these features with only a minor
|
||||
complexity and code size increase.
|
||||
|
||||
The recommendation is the following points
|
||||
|
||||
- Retaining the per-driver integer variable "debug" as a module
|
||||
parameter with a default level of '1'.
|
||||
|
||||
- Adding a per-interface private variable named "msg_enable". The
|
||||
variable is a bit map rather than a level, and is initialized as::
|
||||
|
||||
1 << debug
|
||||
|
||||
Or more precisely::
|
||||
|
||||
debug < 0 ? 0 : 1 << min(sizeof(int)-1, debug)
|
||||
|
||||
Messages should changes from::
|
||||
|
||||
if (debug > 1)
|
||||
printk(MSG_DEBUG "%s: ...
|
||||
|
||||
to::
|
||||
|
||||
if (np->msg_enable & NETIF_MSG_LINK)
|
||||
printk(MSG_DEBUG "%s: ...
|
||||
|
||||
|
||||
The set of message levels is named
|
||||
|
||||
|
||||
========= =================== ============
|
||||
Old level Name Bit position
|
||||
========= =================== ============
|
||||
0 NETIF_MSG_DRV 0x0001
|
||||
1 NETIF_MSG_PROBE 0x0002
|
||||
2 NETIF_MSG_LINK 0x0004
|
||||
2 NETIF_MSG_TIMER 0x0004
|
||||
3 NETIF_MSG_IFDOWN 0x0008
|
||||
3 NETIF_MSG_IFUP 0x0008
|
||||
4 NETIF_MSG_RX_ERR 0x0010
|
||||
4 NETIF_MSG_TX_ERR 0x0010
|
||||
5 NETIF_MSG_TX_QUEUED 0x0020
|
||||
5 NETIF_MSG_INTR 0x0020
|
||||
6 NETIF_MSG_TX_DONE 0x0040
|
||||
6 NETIF_MSG_RX_STATUS 0x0040
|
||||
7 NETIF_MSG_PKTDATA 0x0080
|
||||
========= =================== ============
|
||||
@ -1,79 +0,0 @@
|
||||
|
||||
________________
|
||||
NETIF Msg Level
|
||||
|
||||
The design of the network interface message level setting.
|
||||
|
||||
History
|
||||
|
||||
The design of the debugging message interface was guided and
|
||||
constrained by backwards compatibility previous practice. It is useful
|
||||
to understand the history and evolution in order to understand current
|
||||
practice and relate it to older driver source code.
|
||||
|
||||
From the beginning of Linux, each network device driver has had a local
|
||||
integer variable that controls the debug message level. The message
|
||||
level ranged from 0 to 7, and monotonically increased in verbosity.
|
||||
|
||||
The message level was not precisely defined past level 3, but were
|
||||
always implemented within +-1 of the specified level. Drivers tended
|
||||
to shed the more verbose level messages as they matured.
|
||||
0 Minimal messages, only essential information on fatal errors.
|
||||
1 Standard messages, initialization status. No run-time messages
|
||||
2 Special media selection messages, generally timer-driver.
|
||||
3 Interface starts and stops, including normal status messages
|
||||
4 Tx and Rx frame error messages, and abnormal driver operation
|
||||
5 Tx packet queue information, interrupt events.
|
||||
6 Status on each completed Tx packet and received Rx packets
|
||||
7 Initial contents of Tx and Rx packets
|
||||
|
||||
Initially this message level variable was uniquely named in each driver
|
||||
e.g. "lance_debug", so that a kernel symbolic debugger could locate and
|
||||
modify the setting. When kernel modules became common, the variables
|
||||
were consistently renamed to "debug" and allowed to be set as a module
|
||||
parameter.
|
||||
|
||||
This approach worked well. However there is always a demand for
|
||||
additional features. Over the years the following emerged as
|
||||
reasonable and easily implemented enhancements
|
||||
Using an ioctl() call to modify the level.
|
||||
Per-interface rather than per-driver message level setting.
|
||||
More selective control over the type of messages emitted.
|
||||
|
||||
The netif_msg recommendation adds these features with only a minor
|
||||
complexity and code size increase.
|
||||
|
||||
The recommendation is the following points
|
||||
Retaining the per-driver integer variable "debug" as a module
|
||||
parameter with a default level of '1'.
|
||||
|
||||
Adding a per-interface private variable named "msg_enable". The
|
||||
variable is a bit map rather than a level, and is initialized as
|
||||
1 << debug
|
||||
Or more precisely
|
||||
debug < 0 ? 0 : 1 << min(sizeof(int)-1, debug)
|
||||
|
||||
Messages should changes from
|
||||
if (debug > 1)
|
||||
printk(MSG_DEBUG "%s: ...
|
||||
to
|
||||
if (np->msg_enable & NETIF_MSG_LINK)
|
||||
printk(MSG_DEBUG "%s: ...
|
||||
|
||||
|
||||
The set of message levels is named
|
||||
Old level Name Bit position
|
||||
0 NETIF_MSG_DRV 0x0001
|
||||
1 NETIF_MSG_PROBE 0x0002
|
||||
2 NETIF_MSG_LINK 0x0004
|
||||
2 NETIF_MSG_TIMER 0x0004
|
||||
3 NETIF_MSG_IFDOWN 0x0008
|
||||
3 NETIF_MSG_IFUP 0x0008
|
||||
4 NETIF_MSG_RX_ERR 0x0010
|
||||
4 NETIF_MSG_TX_ERR 0x0010
|
||||
5 NETIF_MSG_TX_QUEUED 0x0020
|
||||
5 NETIF_MSG_INTR 0x0020
|
||||
6 NETIF_MSG_TX_DONE 0x0040
|
||||
6 NETIF_MSG_RX_STATUS 0x0040
|
||||
7 NETIF_MSG_PKTDATA 0x0080
|
||||
|
||||
Loading…
Reference in New Issue
Block a user