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   =========   ===================       ============