docs: networking: convert netif-msg.txt to ReST

   netdev-features

   netdevices

   netfilter-sysctl

   netif-msg

.. only::  subproject and html

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

 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

   - 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

 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.

   - 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

  - 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

  - 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

    Or more precisely::

	debug < 0 ? 0 : 1 << min(sizeof(int)-1, debug)

    Messages should changes from

    Messages should changes from::

      if (debug > 1)

	   printk(MSG_DEBUG "%s: ...

    to

    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

    6         NETIF_MSG_TX_DONE		0x0040

    6         NETIF_MSG_RX_STATUS	0x0040

    7         NETIF_MSG_PKTDATA		0x0080

  =========   ===================	============