NETIF Msg Level

역사와 비트맵 기반 권장 방식

네트워크 인터페이스 메시지 수준 설계는 이전 드라이버와의 호환성에 제약을 받았습니다. 현재 방식을 이해하고 오래된 드라이버 소스와 연결하려면 이 디버그 인터페이스의 변천을 알아야 합니다.

초기 Linux 네트워크 드라이버는 0부터 7까지의 로컬 정수로 디버그 출력량을 제어했습니다. 값이 커질수록 메시지가 많아졌지만 수준 3 이후의 의미는 정확히 통일되지 않았고 드라이버별 구현은 지정 수준에서 대략 한 단계 안쪽으로 달랐습니다. 드라이버가 성숙하면서 상세 메시지를 제거하는 경향도 있었습니다.

수준 0은 치명적 오류의 필수 정보만, 1은 초기화 상태 같은 표준 메시지만 출력합니다. 2는 주로 timer driver의 특수 media 선택, 3은 정상 상태를 포함한 인터페이스 시작·중지를 뜻합니다. 4는 TX/RX 프레임 오류와 비정상 동작, 5는 TX queue와 interrupt, 6은 완료된 각 TX와 수신 RX 상태, 7은 TX/RX 패킷의 초기 내용을 출력합니다.

처음에는 `lance_debug`처럼 드라이버마다 고유한 변수명을 써서 커널 symbolic debugger가 찾아 수정하게 했습니다. 모듈이 일반화된 뒤에는 이름을 `debug`로 통일하고 module parameter로 설정할 수 있게 했습니다.

기존 방식은 단순하고 잘 동작했지만 ioctl을 통한 변경, 드라이버 전체가 아닌 인터페이스별 수준, 메시지 종류별 선택 제어가 필요해졌습니다. `netif_msg` 권장안은 코드 크기와 복잡성을 조금만 늘리면서 이를 제공합니다.

드라이버별 정수 module parameter `debug`는 기본 수준 1로 유지합니다. 각 인터페이스 private data에는 수준이 아닌 비트맵 `msg_enable`을 추가합니다. 초기값은 개념상 `1 << debug`이고, 정확히는 음수면 0, 그렇지 않으면 정수 크기에 맞게 제한한 비트를 켭니다. 이후 `debug > 1` 같은 수치 비교를 `msg_enable & NETIF_MSG_LINK` 같은 종류별 비트 검사로 바꿉니다.

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