1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun=============== 4*4882a593SmuzhiyunNETIF Msg Level 5*4882a593Smuzhiyun=============== 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunThe design of the network interface message level setting. 8*4882a593Smuzhiyun 9*4882a593SmuzhiyunHistory 10*4882a593Smuzhiyun------- 11*4882a593Smuzhiyun 12*4882a593Smuzhiyun The design of the debugging message interface was guided and 13*4882a593Smuzhiyun constrained by backwards compatibility previous practice. It is useful 14*4882a593Smuzhiyun to understand the history and evolution in order to understand current 15*4882a593Smuzhiyun practice and relate it to older driver source code. 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun From the beginning of Linux, each network device driver has had a local 18*4882a593Smuzhiyun integer variable that controls the debug message level. The message 19*4882a593Smuzhiyun level ranged from 0 to 7, and monotonically increased in verbosity. 20*4882a593Smuzhiyun 21*4882a593Smuzhiyun The message level was not precisely defined past level 3, but were 22*4882a593Smuzhiyun always implemented within +-1 of the specified level. Drivers tended 23*4882a593Smuzhiyun to shed the more verbose level messages as they matured. 24*4882a593Smuzhiyun 25*4882a593Smuzhiyun - 0 Minimal messages, only essential information on fatal errors. 26*4882a593Smuzhiyun - 1 Standard messages, initialization status. No run-time messages 27*4882a593Smuzhiyun - 2 Special media selection messages, generally timer-driver. 28*4882a593Smuzhiyun - 3 Interface starts and stops, including normal status messages 29*4882a593Smuzhiyun - 4 Tx and Rx frame error messages, and abnormal driver operation 30*4882a593Smuzhiyun - 5 Tx packet queue information, interrupt events. 31*4882a593Smuzhiyun - 6 Status on each completed Tx packet and received Rx packets 32*4882a593Smuzhiyun - 7 Initial contents of Tx and Rx packets 33*4882a593Smuzhiyun 34*4882a593Smuzhiyun Initially this message level variable was uniquely named in each driver 35*4882a593Smuzhiyun e.g. "lance_debug", so that a kernel symbolic debugger could locate and 36*4882a593Smuzhiyun modify the setting. When kernel modules became common, the variables 37*4882a593Smuzhiyun were consistently renamed to "debug" and allowed to be set as a module 38*4882a593Smuzhiyun parameter. 39*4882a593Smuzhiyun 40*4882a593Smuzhiyun This approach worked well. However there is always a demand for 41*4882a593Smuzhiyun additional features. Over the years the following emerged as 42*4882a593Smuzhiyun reasonable and easily implemented enhancements 43*4882a593Smuzhiyun 44*4882a593Smuzhiyun - Using an ioctl() call to modify the level. 45*4882a593Smuzhiyun - Per-interface rather than per-driver message level setting. 46*4882a593Smuzhiyun - More selective control over the type of messages emitted. 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun The netif_msg recommendation adds these features with only a minor 49*4882a593Smuzhiyun complexity and code size increase. 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun The recommendation is the following points 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun - Retaining the per-driver integer variable "debug" as a module 54*4882a593Smuzhiyun parameter with a default level of '1'. 55*4882a593Smuzhiyun 56*4882a593Smuzhiyun - Adding a per-interface private variable named "msg_enable". The 57*4882a593Smuzhiyun variable is a bit map rather than a level, and is initialized as:: 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun 1 << debug 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun Or more precisely:: 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun debug < 0 ? 0 : 1 << min(sizeof(int)-1, debug) 64*4882a593Smuzhiyun 65*4882a593Smuzhiyun Messages should changes from:: 66*4882a593Smuzhiyun 67*4882a593Smuzhiyun if (debug > 1) 68*4882a593Smuzhiyun printk(MSG_DEBUG "%s: ... 69*4882a593Smuzhiyun 70*4882a593Smuzhiyun to:: 71*4882a593Smuzhiyun 72*4882a593Smuzhiyun if (np->msg_enable & NETIF_MSG_LINK) 73*4882a593Smuzhiyun printk(MSG_DEBUG "%s: ... 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun 76*4882a593SmuzhiyunThe set of message levels is named 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun 79*4882a593Smuzhiyun ========= =================== ============ 80*4882a593Smuzhiyun Old level Name Bit position 81*4882a593Smuzhiyun ========= =================== ============ 82*4882a593Smuzhiyun 0 NETIF_MSG_DRV 0x0001 83*4882a593Smuzhiyun 1 NETIF_MSG_PROBE 0x0002 84*4882a593Smuzhiyun 2 NETIF_MSG_LINK 0x0004 85*4882a593Smuzhiyun 2 NETIF_MSG_TIMER 0x0004 86*4882a593Smuzhiyun 3 NETIF_MSG_IFDOWN 0x0008 87*4882a593Smuzhiyun 3 NETIF_MSG_IFUP 0x0008 88*4882a593Smuzhiyun 4 NETIF_MSG_RX_ERR 0x0010 89*4882a593Smuzhiyun 4 NETIF_MSG_TX_ERR 0x0010 90*4882a593Smuzhiyun 5 NETIF_MSG_TX_QUEUED 0x0020 91*4882a593Smuzhiyun 5 NETIF_MSG_INTR 0x0020 92*4882a593Smuzhiyun 6 NETIF_MSG_TX_DONE 0x0040 93*4882a593Smuzhiyun 6 NETIF_MSG_RX_STATUS 0x0040 94*4882a593Smuzhiyun 7 NETIF_MSG_PKTDATA 0x0080 95*4882a593Smuzhiyun ========= =================== ============ 96