Documentation/networking/netif-msg.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/netif-msg.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/netif-msg.rst
Extension
.rst
Size
3389 bytes
Lines
96
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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::

Annotation

Implementation Notes