1============================= 2Netlink interface for ethtool 3============================= 4 5 6Basic information 7================= 8 9Netlink interface for ethtool uses generic netlink family ``ethtool`` 10(userspace application should use macros ``ETHTOOL_GENL_NAME`` and 11``ETHTOOL_GENL_VERSION`` defined in ``<linux/ethtool_netlink.h>`` uapi 12header). This family does not use a specific header, all information in 13requests and replies is passed using netlink attributes. 14 15The ethtool netlink interface uses extended ACK for error and warning 16reporting, userspace application developers are encouraged to make these 17messages available to user in a suitable way. 18 19Requests can be divided into three categories: "get" (retrieving information), 20"set" (setting parameters) and "action" (invoking an action). 21 22All "set" and "action" type requests require admin privileges 23(``CAP_NET_ADMIN`` in the namespace). Most "get" type requests are allowed for 24anyone but there are exceptions (where the response contains sensitive 25information). In some cases, the request as such is allowed for anyone but 26unprivileged users have attributes with sensitive information (e.g. 27wake-on-lan password) omitted. 28 29 30Conventions 31=========== 32 33Attributes which represent a boolean value usually use NLA_U8 type so that we 34can distinguish three states: "on", "off" and "not present" (meaning the 35information is not available in "get" requests or value is not to be changed 36in "set" requests). For these attributes, the "true" value should be passed as 37number 1 but any non-zero value should be understood as "true" by recipient. 38In the tables below, "bool" denotes NLA_U8 attributes interpreted in this way. 39 40In the message structure descriptions below, if an attribute name is suffixed 41with "+", parent nest can contain multiple attributes of the same type. This 42implements an array of entries. 43 44Attributes that need to be filled-in by device drivers and that are dumped to 45user space based on whether they are valid or not should not use zero as a 46valid value. This avoids the need to explicitly signal the validity of the 47attribute in the device driver API. 48 49 50Request header 51============== 52 53Each request or reply message contains a nested attribute with common header. 54Structure of this header is 55 56 ============================== ====== ============================= 57 ``ETHTOOL_A_HEADER_DEV_INDEX`` u32 device ifindex 58 ``ETHTOOL_A_HEADER_DEV_NAME`` string device name 59 ``ETHTOOL_A_HEADER_FLAGS`` u32 flags common for all requests 60 ============================== ====== ============================= 61 62``ETHTOOL_A_HEADER_DEV_INDEX`` and ``ETHTOOL_A_HEADER_DEV_NAME`` identify the 63device message relates to. One of them is sufficient in requests, if both are 64used, they must identify the same device. Some requests, e.g. global string 65sets, do not require device identification. Most ``GET`` requests also allow 66dump requests without device identification to query the same information for 67all devices providing it (each device in a separate message). 68 69``ETHTOOL_A_HEADER_FLAGS`` is a bitmap of request flags common for all request 70types. The interpretation of these flags is the same for all request types but 71the flags may not apply to requests. Recognized flags are: 72 73 ================================= =================================== 74 ``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply 75 ``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT) 76 ``ETHTOOL_FLAG_STATS`` include optional device statistics 77 ================================= =================================== 78 79New request flags should follow the general idea that if the flag is not set, 80the behaviour is backward compatible, i.e. requests from old clients not aware 81of the flag should be interpreted the way the client expects. A client must 82not set flags it does not understand. 83 84 85Bit sets 86======== 87 88For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32`` 89type is used. For arbitrary length bitmaps, ethtool netlink uses a nested 90attribute with contents of one of two forms: compact (two binary bitmaps 91representing bit values and mask of affected bits) and bit-by-bit (list of 92bits identified by either index or name). 93 94Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together 95with their values which saves a round trip (when the bitset is passed in a 96request) or at least a second request (when the bitset is in a reply). This is 97useful for one shot applications like traditional ethtool command. On the 98other hand, long running applications like ethtool monitor (displaying 99notifications) or network management daemons may prefer fetching the names 100only once and using compact form to save message size. Notifications from 101ethtool netlink interface always use compact form for bitsets. 102 103A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK`` 104not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests 105modifying a bitmap, the former changes the bit set in mask to values set in 106value and preserves the rest; the latter sets the bits set in the bitmap and 107clears the rest. 108 109Compact form: nested (bitset) atrribute contents: 110 111 ============================ ====== ============================ 112 ``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list 113 ``ETHTOOL_A_BITSET_SIZE`` u32 number of significant bits 114 ``ETHTOOL_A_BITSET_VALUE`` binary bitmap of bit values 115 ``ETHTOOL_A_BITSET_MASK`` binary bitmap of valid bits 116 ============================ ====== ============================ 117 118Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits 119rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte 120order, words ordered from least significant to most significant (i.e. the same 121way as bitmaps are passed with ioctl interface). 122 123For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are 124mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if 125``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair); 126if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not 127allowed (bitset represents a single bitmap. 128 129Kernel bit set length may differ from userspace length if older application is 130used on newer kernel or vice versa. If userspace bitmap is longer, an error is 131issued only if the request actually tries to set values of some bits not 132recognized by kernel. 133 134Bit-by-bit form: nested (bitset) attribute contents: 135 136 +------------------------------------+--------+-----------------------------+ 137 | ``ETHTOOL_A_BITSET_NOMASK`` | flag | no mask, only a list | 138 +------------------------------------+--------+-----------------------------+ 139 | ``ETHTOOL_A_BITSET_SIZE`` | u32 | number of significant bits | 140 +------------------------------------+--------+-----------------------------+ 141 | ``ETHTOOL_A_BITSET_BITS`` | nested | array of bits | 142 +-+----------------------------------+--------+-----------------------------+ 143 | | ``ETHTOOL_A_BITSET_BITS_BIT+`` | nested | one bit | 144 +-+-+--------------------------------+--------+-----------------------------+ 145 | | | ``ETHTOOL_A_BITSET_BIT_INDEX`` | u32 | bit index (0 for LSB) | 146 +-+-+--------------------------------+--------+-----------------------------+ 147 | | | ``ETHTOOL_A_BITSET_BIT_NAME`` | string | bit name | 148 +-+-+--------------------------------+--------+-----------------------------+ 149 | | | ``ETHTOOL_A_BITSET_BIT_VALUE`` | flag | present if bit is set | 150 +-+-+--------------------------------+--------+-----------------------------+ 151 152Bit size is optional for bit-by-bit form. ``ETHTOOL_A_BITSET_BITS`` nest can 153only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an 154arbitrary number of them. A bit may be identified by its index or by its 155name. When used in requests, listed bits are set to 0 or 1 according to 156``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved. A request fails if 157index exceeds kernel bit length or if name is not recognized. 158 159When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as 160a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in 161such case. Such bitset represents a bitmap with listed bits set and the rest 162zero. 163 164In requests, application can use either form. Form used by kernel in reply is 165determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request 166header. Semantics of value and mask depends on the attribute. 167 168 169List of message types 170===================== 171 172All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix 173according to message purpose: 174 175 ============== ====================================== 176 ``_GET`` userspace request to retrieve data 177 ``_SET`` userspace request to set data 178 ``_ACT`` userspace request to perform an action 179 ``_GET_REPLY`` kernel reply to a ``GET`` request 180 ``_SET_REPLY`` kernel reply to a ``SET`` request 181 ``_ACT_REPLY`` kernel reply to an ``ACT`` request 182 ``_NTF`` kernel notification 183 ============== ====================================== 184 185Userspace to kernel: 186 187 ===================================== ================================= 188 ``ETHTOOL_MSG_STRSET_GET`` get string set 189 ``ETHTOOL_MSG_LINKINFO_GET`` get link settings 190 ``ETHTOOL_MSG_LINKINFO_SET`` set link settings 191 ``ETHTOOL_MSG_LINKMODES_GET`` get link modes info 192 ``ETHTOOL_MSG_LINKMODES_SET`` set link modes info 193 ``ETHTOOL_MSG_LINKSTATE_GET`` get link state 194 ``ETHTOOL_MSG_DEBUG_GET`` get debugging settings 195 ``ETHTOOL_MSG_DEBUG_SET`` set debugging settings 196 ``ETHTOOL_MSG_WOL_GET`` get wake-on-lan settings 197 ``ETHTOOL_MSG_WOL_SET`` set wake-on-lan settings 198 ``ETHTOOL_MSG_FEATURES_GET`` get device features 199 ``ETHTOOL_MSG_FEATURES_SET`` set device features 200 ``ETHTOOL_MSG_PRIVFLAGS_GET`` get private flags 201 ``ETHTOOL_MSG_PRIVFLAGS_SET`` set private flags 202 ``ETHTOOL_MSG_RINGS_GET`` get ring sizes 203 ``ETHTOOL_MSG_RINGS_SET`` set ring sizes 204 ``ETHTOOL_MSG_CHANNELS_GET`` get channel counts 205 ``ETHTOOL_MSG_CHANNELS_SET`` set channel counts 206 ``ETHTOOL_MSG_COALESCE_GET`` get coalescing parameters 207 ``ETHTOOL_MSG_COALESCE_SET`` set coalescing parameters 208 ``ETHTOOL_MSG_PAUSE_GET`` get pause parameters 209 ``ETHTOOL_MSG_PAUSE_SET`` set pause parameters 210 ``ETHTOOL_MSG_EEE_GET`` get EEE settings 211 ``ETHTOOL_MSG_EEE_SET`` set EEE settings 212 ``ETHTOOL_MSG_TSINFO_GET`` get timestamping info 213 ``ETHTOOL_MSG_CABLE_TEST_ACT`` action start cable test 214 ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` action start raw TDR cable test 215 ``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info 216 ``ETHTOOL_MSG_FEC_GET`` get FEC settings 217 ``ETHTOOL_MSG_FEC_SET`` set FEC settings 218 ``ETHTOOL_MSG_MODULE_EEPROM_GET`` read SFP module EEPROM 219 ``ETHTOOL_MSG_STATS_GET`` get standard statistics 220 ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` get PHC virtual clocks info 221 ``ETHTOOL_MSG_MODULE_SET`` set transceiver module parameters 222 ``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters 223 ===================================== ================================= 224 225Kernel to userspace: 226 227 ======================================== ================================= 228 ``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents 229 ``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings 230 ``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification 231 ``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info 232 ``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification 233 ``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info 234 ``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings 235 ``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification 236 ``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings 237 ``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification 238 ``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features 239 ``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET 240 ``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification 241 ``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags 242 ``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags 243 ``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes 244 ``ETHTOOL_MSG_RINGS_NTF`` ring sizes 245 ``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts 246 ``ETHTOOL_MSG_CHANNELS_NTF`` channel counts 247 ``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters 248 ``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters 249 ``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters 250 ``ETHTOOL_MSG_PAUSE_NTF`` pause parameters 251 ``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings 252 ``ETHTOOL_MSG_EEE_NTF`` EEE settings 253 ``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info 254 ``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results 255 ``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results 256 ``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info 257 ``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings 258 ``ETHTOOL_MSG_FEC_NTF`` FEC settings 259 ``ETHTOOL_MSG_MODULE_EEPROM_GET_REPLY`` read SFP module EEPROM 260 ``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics 261 ``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info 262 ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters 263 ======================================== ================================= 264 265``GET`` requests are sent by userspace applications to retrieve device 266information. They usually do not contain any message specific attributes. 267Kernel replies with corresponding "GET_REPLY" message. For most types, ``GET`` 268request with ``NLM_F_DUMP`` and no device identification can be used to query 269the information for all devices supporting the request. 270 271If the data can be also modified, corresponding ``SET`` message with the same 272layout as corresponding ``GET_REPLY`` is used to request changes. Only 273attributes where a change is requested are included in such request (also, not 274all attributes may be changed). Replies to most ``SET`` request consist only 275of error code and extack; if kernel provides additional data, it is sent in 276the form of corresponding ``SET_REPLY`` message which can be suppressed by 277setting ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header. 278 279Data modification also triggers sending a ``NTF`` message with a notification. 280These usually bear only a subset of attributes which was affected by the 281change. The same notification is issued if the data is modified using other 282means (mostly ioctl ethtool interface). Unlike notifications from ethtool 283netlink code which are only sent if something actually changed, notifications 284triggered by ioctl interface may be sent even if the request did not actually 285change any data. 286 287``ACT`` messages request kernel (driver) to perform a specific action. If some 288information is reported by kernel (which can be suppressed by setting 289``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header), the reply takes form of 290an ``ACT_REPLY`` message. Performing an action also triggers a notification 291(``NTF`` message). 292 293Later sections describe the format and semantics of these messages. 294 295 296STRSET_GET 297========== 298 299Requests contents of a string set as provided by ioctl commands 300``ETHTOOL_GSSET_INFO`` and ``ETHTOOL_GSTRINGS.`` String sets are not user 301writeable so that the corresponding ``STRSET_SET`` message is only used in 302kernel replies. There are two types of string sets: global (independent of 303a device, e.g. device feature names) and device specific (e.g. device private 304flags). 305 306Request contents: 307 308 +---------------------------------------+--------+------------------------+ 309 | ``ETHTOOL_A_STRSET_HEADER`` | nested | request header | 310 +---------------------------------------+--------+------------------------+ 311 | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | string set to request | 312 +-+-------------------------------------+--------+------------------------+ 313 | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | 314 +-+-+-----------------------------------+--------+------------------------+ 315 | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | 316 +-+-+-----------------------------------+--------+------------------------+ 317 318Kernel response contents: 319 320 +---------------------------------------+--------+-----------------------+ 321 | ``ETHTOOL_A_STRSET_HEADER`` | nested | reply header | 322 +---------------------------------------+--------+-----------------------+ 323 | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | array of string sets | 324 +-+-------------------------------------+--------+-----------------------+ 325 | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | 326 +-+-+-----------------------------------+--------+-----------------------+ 327 | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | 328 +-+-+-----------------------------------+--------+-----------------------+ 329 | | | ``ETHTOOL_A_STRINGSET_COUNT`` | u32 | number of strings | 330 +-+-+-----------------------------------+--------+-----------------------+ 331 | | | ``ETHTOOL_A_STRINGSET_STRINGS`` | nested | array of strings | 332 +-+-+-+---------------------------------+--------+-----------------------+ 333 | | | | ``ETHTOOL_A_STRINGS_STRING+`` | nested | one string | 334 +-+-+-+-+-------------------------------+--------+-----------------------+ 335 | | | | | ``ETHTOOL_A_STRING_INDEX`` | u32 | string index | 336 +-+-+-+-+-------------------------------+--------+-----------------------+ 337 | | | | | ``ETHTOOL_A_STRING_VALUE`` | string | string value | 338 +-+-+-+-+-------------------------------+--------+-----------------------+ 339 | ``ETHTOOL_A_STRSET_COUNTS_ONLY`` | flag | return only counts | 340 +---------------------------------------+--------+-----------------------+ 341 342Device identification in request header is optional. Depending on its presence 343a and ``NLM_F_DUMP`` flag, there are three type of ``STRSET_GET`` requests: 344 345 - no ``NLM_F_DUMP,`` no device: get "global" stringsets 346 - no ``NLM_F_DUMP``, with device: get string sets related to the device 347 - ``NLM_F_DUMP``, no device: get device related string sets for all devices 348 349If there is no ``ETHTOOL_A_STRSET_STRINGSETS`` array, all string sets of 350requested type are returned, otherwise only those specified in the request. 351Flag ``ETHTOOL_A_STRSET_COUNTS_ONLY`` tells kernel to only return string 352counts of the sets, not the actual strings. 353 354 355LINKINFO_GET 356============ 357 358Requests link settings as provided by ``ETHTOOL_GLINKSETTINGS`` except for 359link modes and autonegotiation related information. The request does not use 360any attributes. 361 362Request contents: 363 364 ==================================== ====== ========================== 365 ``ETHTOOL_A_LINKINFO_HEADER`` nested request header 366 ==================================== ====== ========================== 367 368Kernel response contents: 369 370 ==================================== ====== ========================== 371 ``ETHTOOL_A_LINKINFO_HEADER`` nested reply header 372 ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port 373 ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address 374 ``ETHTOOL_A_LINKINFO_TP_MDIX`` u8 MDI(-X) status 375 ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control 376 ``ETHTOOL_A_LINKINFO_TRANSCEIVER`` u8 transceiver 377 ==================================== ====== ========================== 378 379Attributes and their values have the same meaning as matching members of the 380corresponding ioctl structures. 381 382``LINKINFO_GET`` allows dump requests (kernel returns reply message for all 383devices supporting the request). 384 385 386LINKINFO_SET 387============ 388 389``LINKINFO_SET`` request allows setting some of the attributes reported by 390``LINKINFO_GET``. 391 392Request contents: 393 394 ==================================== ====== ========================== 395 ``ETHTOOL_A_LINKINFO_HEADER`` nested request header 396 ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port 397 ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address 398 ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control 399 ==================================== ====== ========================== 400 401MDI(-X) status and transceiver cannot be set, request with the corresponding 402attributes is rejected. 403 404 405LINKMODES_GET 406============= 407 408Requests link modes (supported, advertised and peer advertised) and related 409information (autonegotiation status, link speed and duplex) as provided by 410``ETHTOOL_GLINKSETTINGS``. The request does not use any attributes. 411 412Request contents: 413 414 ==================================== ====== ========================== 415 ``ETHTOOL_A_LINKMODES_HEADER`` nested request header 416 ==================================== ====== ========================== 417 418Kernel response contents: 419 420 ========================================== ====== ========================== 421 ``ETHTOOL_A_LINKMODES_HEADER`` nested reply header 422 ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status 423 ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes 424 ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes 425 ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) 426 ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode 427 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode 428 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_STATE`` u8 Master/slave port state 429 ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching 430 ========================================== ====== ========================== 431 432For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask 433represents supported modes. ``ETHTOOL_A_LINKMODES_PEER`` in the reply is a bit 434list. 435 436``LINKMODES_GET`` allows dump requests (kernel returns reply messages for all 437devices supporting the request). 438 439 440LINKMODES_SET 441============= 442 443Request contents: 444 445 ========================================== ====== ========================== 446 ``ETHTOOL_A_LINKMODES_HEADER`` nested request header 447 ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status 448 ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes 449 ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes 450 ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) 451 ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode 452 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode 453 ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching 454 ``ETHTOOL_A_LINKMODES_LANES`` u32 lanes 455 ========================================== ====== ========================== 456 457``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If 458autonegotiation is on (either set now or kept from before), advertised modes 459are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one 460of speed, duplex and lanes is specified, kernel adjusts advertised modes to all 461supported modes matching speed, duplex, lanes or all (whatever is specified). 462This autoselection is done on ethtool side with ioctl interface, netlink 463interface is supposed to allow requesting changes without knowing what exactly 464kernel supports. 465 466 467LINKSTATE_GET 468============= 469 470Requests link state information. Link up/down flag (as provided by 471``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might 472be provided as well. In general, extended state describes reasons for why a port 473is down, or why it operates in some non-obvious mode. This request does not have 474any attributes. 475 476Request contents: 477 478 ==================================== ====== ========================== 479 ``ETHTOOL_A_LINKSTATE_HEADER`` nested request header 480 ==================================== ====== ========================== 481 482Kernel response contents: 483 484 ==================================== ====== ============================ 485 ``ETHTOOL_A_LINKSTATE_HEADER`` nested reply header 486 ``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down) 487 ``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index 488 ``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value 489 ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state 490 ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate 491 ==================================== ====== ============================ 492 493For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns 494carrier flag provided by ``netif_carrier_ok()`` but there are drivers which 495define their own handler. 496 497``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are 498optional values. ethtool core can provide either both 499``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``, 500or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them. 501 502``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all 503devices supporting the request). 504 505 506Link extended states: 507 508 ================================================ ============================================ 509 ``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or 510 issues therein 511 512 ``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training 513 514 ``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer 515 or forward error correction sublayer 516 517 ``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues 518 519 ``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected 520 521 ``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable, 522 e.g., unsupported cable 523 524 ``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure 525 during reading or parsing the data 526 527 ``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm 528 529 ``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the 530 power required from cable or module 531 532 ``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated 533 534 ``ETHTOOL_LINK_EXT_STATE_MODULE`` Transceiver module issue 535 ================================================ ============================================ 536 537Link extended substates: 538 539 Autoneg substates: 540 541 =============================================================== ================================ 542 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down 543 544 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side 545 546 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed 547 548 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force 549 mode or there is no agreement of 550 speed 551 552 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes 553 in both sides are mismatched 554 555 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator 556 =============================================================== ================================ 557 558 Link training substates: 559 560 =========================================================================== ==================== 561 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not 562 recognized, the 563 lock failed 564 565 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not 566 occur before 567 timeout 568 569 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not 570 send ready signal 571 after training 572 process 573 574 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not 575 ready yet 576 =========================================================================== ==================== 577 578 Link logical mismatch substates: 579 580 ================================================================ =============================== 581 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was 582 not locked in first phase - 583 block lock 584 585 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was 586 not locked in second phase - 587 alignment markers lock 588 589 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did 590 not get align status 591 592 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is 593 not locked 594 595 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is 596 not locked 597 ================================================================ =============================== 598 599 Bad signal integrity substates: 600 601 ================================================================= ============================= 602 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical 603 errors 604 605 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to 606 operate the cable at a rate 607 that is not formally 608 supported, which led to 609 signal integrity issues 610 611 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_REFERENCE_CLOCK_LOST`` The external clock signal for 612 SerDes is too weak or 613 unavailable. 614 615 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_ALOS`` The received signal for 616 SerDes is too weak because 617 analog loss of signal. 618 ================================================================= ============================= 619 620 Cable issue substates: 621 622 =================================================== ============================================ 623 ``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable 624 625 ``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure 626 =================================================== ============================================ 627 628 Transceiver module issue substates: 629 630 =================================================== ============================================ 631 ``ETHTOOL_LINK_EXT_SUBSTATE_MODULE_CMIS_NOT_READY`` The CMIS Module State Machine did not reach 632 the ModuleReady state. For example, if the 633 module is stuck at ModuleFault state 634 =================================================== ============================================ 635 636DEBUG_GET 637========= 638 639Requests debugging settings of a device. At the moment, only message mask is 640provided. 641 642Request contents: 643 644 ==================================== ====== ========================== 645 ``ETHTOOL_A_DEBUG_HEADER`` nested request header 646 ==================================== ====== ========================== 647 648Kernel response contents: 649 650 ==================================== ====== ========================== 651 ``ETHTOOL_A_DEBUG_HEADER`` nested reply header 652 ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask 653 ==================================== ====== ========================== 654 655The message mask (``ETHTOOL_A_DEBUG_MSGMASK``) is equal to message level as 656provided by ``ETHTOOL_GMSGLVL`` and set by ``ETHTOOL_SMSGLVL`` in ioctl 657interface. While it is called message level there for historical reasons, most 658drivers and almost all newer drivers use it as a mask of enabled message 659classes (represented by ``NETIF_MSG_*`` constants); therefore netlink 660interface follows its actual use in practice. 661 662``DEBUG_GET`` allows dump requests (kernel returns reply messages for all 663devices supporting the request). 664 665 666DEBUG_SET 667========= 668 669Set or update debugging settings of a device. At the moment, only message mask 670is supported. 671 672Request contents: 673 674 ==================================== ====== ========================== 675 ``ETHTOOL_A_DEBUG_HEADER`` nested request header 676 ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask 677 ==================================== ====== ========================== 678 679``ETHTOOL_A_DEBUG_MSGMASK`` bit set allows setting or modifying mask of 680enabled debugging message types for the device. 681 682 683WOL_GET 684======= 685 686Query device wake-on-lan settings. Unlike most "GET" type requests, 687``ETHTOOL_MSG_WOL_GET`` requires (netns) ``CAP_NET_ADMIN`` privileges as it 688(potentially) provides SecureOn(tm) password which is confidential. 689 690Request contents: 691 692 ==================================== ====== ========================== 693 ``ETHTOOL_A_WOL_HEADER`` nested request header 694 ==================================== ====== ========================== 695 696Kernel response contents: 697 698 ==================================== ====== ========================== 699 ``ETHTOOL_A_WOL_HEADER`` nested reply header 700 ``ETHTOOL_A_WOL_MODES`` bitset mask of enabled WoL modes 701 ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password 702 ==================================== ====== ========================== 703 704In reply, ``ETHTOOL_A_WOL_MODES`` mask consists of modes supported by the 705device, value of modes which are enabled. ``ETHTOOL_A_WOL_SOPASS`` is only 706included in reply if ``WAKE_MAGICSECURE`` mode is supported. 707 708 709WOL_SET 710======= 711 712Set or update wake-on-lan settings. 713 714Request contents: 715 716 ==================================== ====== ========================== 717 ``ETHTOOL_A_WOL_HEADER`` nested request header 718 ``ETHTOOL_A_WOL_MODES`` bitset enabled WoL modes 719 ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password 720 ==================================== ====== ========================== 721 722``ETHTOOL_A_WOL_SOPASS`` is only allowed for devices supporting 723``WAKE_MAGICSECURE`` mode. 724 725 726FEATURES_GET 727============ 728 729Gets netdev features like ``ETHTOOL_GFEATURES`` ioctl request. 730 731Request contents: 732 733 ==================================== ====== ========================== 734 ``ETHTOOL_A_FEATURES_HEADER`` nested request header 735 ==================================== ====== ========================== 736 737Kernel response contents: 738 739 ==================================== ====== ========================== 740 ``ETHTOOL_A_FEATURES_HEADER`` nested reply header 741 ``ETHTOOL_A_FEATURES_HW`` bitset dev->hw_features 742 ``ETHTOOL_A_FEATURES_WANTED`` bitset dev->wanted_features 743 ``ETHTOOL_A_FEATURES_ACTIVE`` bitset dev->features 744 ``ETHTOOL_A_FEATURES_NOCHANGE`` bitset NETIF_F_NEVER_CHANGE 745 ==================================== ====== ========================== 746 747Bitmaps in kernel response have the same meaning as bitmaps used in ioctl 748interference but attribute names are different (they are based on 749corresponding members of struct net_device). Legacy "flags" are not provided, 750if userspace needs them (most likely only ethtool for backward compatibility), 751it can calculate their values from related feature bits itself. 752ETHA_FEATURES_HW uses mask consisting of all features recognized by kernel (to 753provide all names when using verbose bitmap format), the other three use no 754mask (simple bit lists). 755 756 757FEATURES_SET 758============ 759 760Request to set netdev features like ``ETHTOOL_SFEATURES`` ioctl request. 761 762Request contents: 763 764 ==================================== ====== ========================== 765 ``ETHTOOL_A_FEATURES_HEADER`` nested request header 766 ``ETHTOOL_A_FEATURES_WANTED`` bitset requested features 767 ==================================== ====== ========================== 768 769Kernel response contents: 770 771 ==================================== ====== ========================== 772 ``ETHTOOL_A_FEATURES_HEADER`` nested reply header 773 ``ETHTOOL_A_FEATURES_WANTED`` bitset diff wanted vs. result 774 ``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active 775 ==================================== ====== ========================== 776 777Request constains only one bitset which can be either value/mask pair (request 778to change specific feature bits and leave the rest) or only a value (request 779to set all features to specified set). 780 781As request is subject to netdev_change_features() sanity checks, optional 782kernel reply (can be suppressed by ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request 783header) informs client about the actual result. ``ETHTOOL_A_FEATURES_WANTED`` 784reports the difference between client request and actual result: mask consists 785of bits which differ between requested features and result (dev->features 786after the operation), value consists of values of these bits in the request 787(i.e. negated values from resulting features). ``ETHTOOL_A_FEATURES_ACTIVE`` 788reports the difference between old and new dev->features: mask consists of 789bits which have changed, values are their values in new dev->features (after 790the operation). 791 792``ETHTOOL_MSG_FEATURES_NTF`` notification is sent not only if device features 793are modified using ``ETHTOOL_MSG_FEATURES_SET`` request or on of ethtool ioctl 794request but also each time features are modified with netdev_update_features() 795or netdev_change_features(). 796 797 798PRIVFLAGS_GET 799============= 800 801Gets private flags like ``ETHTOOL_GPFLAGS`` ioctl request. 802 803Request contents: 804 805 ==================================== ====== ========================== 806 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header 807 ==================================== ====== ========================== 808 809Kernel response contents: 810 811 ==================================== ====== ========================== 812 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested reply header 813 ``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags 814 ==================================== ====== ========================== 815 816``ETHTOOL_A_PRIVFLAGS_FLAGS`` is a bitset with values of device private flags. 817These flags are defined by driver, their number and names (and also meaning) 818are device dependent. For compact bitset format, names can be retrieved as 819``ETH_SS_PRIV_FLAGS`` string set. If verbose bitset format is requested, 820response uses all private flags supported by the device as mask so that client 821gets the full information without having to fetch the string set with names. 822 823 824PRIVFLAGS_SET 825============= 826 827Sets or modifies values of device private flags like ``ETHTOOL_SPFLAGS`` 828ioctl request. 829 830Request contents: 831 832 ==================================== ====== ========================== 833 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header 834 ``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags 835 ==================================== ====== ========================== 836 837``ETHTOOL_A_PRIVFLAGS_FLAGS`` can either set the whole set of private flags or 838modify only values of some of them. 839 840 841RINGS_GET 842========= 843 844Gets ring sizes like ``ETHTOOL_GRINGPARAM`` ioctl request. 845 846Request contents: 847 848 ==================================== ====== ========================== 849 ``ETHTOOL_A_RINGS_HEADER`` nested request header 850 ==================================== ====== ========================== 851 852Kernel response contents: 853 854 ==================================== ====== =========================== 855 ``ETHTOOL_A_RINGS_HEADER`` nested reply header 856 ``ETHTOOL_A_RINGS_RX_MAX`` u32 max size of RX ring 857 ``ETHTOOL_A_RINGS_RX_MINI_MAX`` u32 max size of RX mini ring 858 ``ETHTOOL_A_RINGS_RX_JUMBO_MAX`` u32 max size of RX jumbo ring 859 ``ETHTOOL_A_RINGS_TX_MAX`` u32 max size of TX ring 860 ``ETHTOOL_A_RINGS_RX`` u32 size of RX ring 861 ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring 862 ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring 863 ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring 864 ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring 865 ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split 866 ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE 867 ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode 868 ==================================== ====== =========================== 869 870``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with 871page-flipping TCP zero-copy receive (``getsockopt(TCP_ZEROCOPY_RECEIVE)``). 872If enabled the device is configured to place frame headers and data into 873separate buffers. The device configuration must make it possible to receive 874full memory pages of data, for example because MTU is high enough or through 875HW-GRO. 876 877``ETHTOOL_A_RINGS_TX_PUSH`` flag is used to enable descriptor fast 878path to send packets. In ordinary path, driver fills descriptors in DRAM and 879notifies NIC hardware. In fast path, driver pushes descriptors to the device 880through MMIO writes, thus reducing the latency. However, enabling this feature 881may increase the CPU cost. Drivers may enforce additional per-packet 882eligibility checks (e.g. on packet size). 883 884RINGS_SET 885========= 886 887Sets ring sizes like ``ETHTOOL_SRINGPARAM`` ioctl request. 888 889Request contents: 890 891 ==================================== ====== =========================== 892 ``ETHTOOL_A_RINGS_HEADER`` nested reply header 893 ``ETHTOOL_A_RINGS_RX`` u32 size of RX ring 894 ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring 895 ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring 896 ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring 897 ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring 898 ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE 899 ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode 900 ==================================== ====== =========================== 901 902Kernel checks that requested ring sizes do not exceed limits reported by 903driver. Driver may impose additional constraints and may not suspport all 904attributes. 905 906 907``ETHTOOL_A_RINGS_CQE_SIZE`` specifies the completion queue event size. 908Completion queue events(CQE) are the events posted by NIC to indicate the 909completion status of a packet when the packet is sent(like send success or 910error) or received(like pointers to packet fragments). The CQE size parameter 911enables to modify the CQE size other than default size if NIC supports it. 912A bigger CQE can have more receive buffer pointers inturn NIC can transfer 913a bigger frame from wire. Based on the NIC hardware, the overall completion 914queue size can be adjusted in the driver if CQE size is modified. 915 916CHANNELS_GET 917============ 918 919Gets channel counts like ``ETHTOOL_GCHANNELS`` ioctl request. 920 921Request contents: 922 923 ==================================== ====== ========================== 924 ``ETHTOOL_A_CHANNELS_HEADER`` nested request header 925 ==================================== ====== ========================== 926 927Kernel response contents: 928 929 ===================================== ====== ========================== 930 ``ETHTOOL_A_CHANNELS_HEADER`` nested reply header 931 ``ETHTOOL_A_CHANNELS_RX_MAX`` u32 max receive channels 932 ``ETHTOOL_A_CHANNELS_TX_MAX`` u32 max transmit channels 933 ``ETHTOOL_A_CHANNELS_OTHER_MAX`` u32 max other channels 934 ``ETHTOOL_A_CHANNELS_COMBINED_MAX`` u32 max combined channels 935 ``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count 936 ``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count 937 ``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count 938 ``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count 939 ===================================== ====== ========================== 940 941 942CHANNELS_SET 943============ 944 945Sets channel counts like ``ETHTOOL_SCHANNELS`` ioctl request. 946 947Request contents: 948 949 ===================================== ====== ========================== 950 ``ETHTOOL_A_CHANNELS_HEADER`` nested request header 951 ``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count 952 ``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count 953 ``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count 954 ``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count 955 ===================================== ====== ========================== 956 957Kernel checks that requested channel counts do not exceed limits reported by 958driver. Driver may impose additional constraints and may not suspport all 959attributes. 960 961 962COALESCE_GET 963============ 964 965Gets coalescing parameters like ``ETHTOOL_GCOALESCE`` ioctl request. 966 967Request contents: 968 969 ==================================== ====== ========================== 970 ``ETHTOOL_A_COALESCE_HEADER`` nested request header 971 ==================================== ====== ========================== 972 973Kernel response contents: 974 975 =========================================== ====== ======================= 976 ``ETHTOOL_A_COALESCE_HEADER`` nested reply header 977 ``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx 978 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx 979 ``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ 980 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ 981 ``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx 982 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx 983 ``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ 984 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ 985 ``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update 986 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce 987 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce 988 ``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate 989 ``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx 990 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx 991 ``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx 992 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx 993 ``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate 994 ``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx 995 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx 996 ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx 997 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx 998 ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval 999 ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx 1000 ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx 1001 =========================================== ====== ======================= 1002 1003Attributes are only included in reply if their value is not zero or the 1004corresponding bit in ``ethtool_ops::supported_coalesce_params`` is set (i.e. 1005they are declared as supported by driver). 1006 1007Timer reset mode (``ETHTOOL_A_COALESCE_USE_CQE_TX`` and 1008``ETHTOOL_A_COALESCE_USE_CQE_RX``) controls the interaction between packet 1009arrival and the various time based delay parameters. By default timers are 1010expected to limit the max delay between any packet arrival/departure and a 1011corresponding interrupt. In this mode timer should be started by packet 1012arrival (sometimes delivery of previous interrupt) and reset when interrupt 1013is delivered. 1014Setting the appropriate attribute to 1 will enable ``CQE`` mode, where 1015each packet event resets the timer. In this mode timer is used to force 1016the interrupt if queue goes idle, while busy queues depend on the packet 1017limit to trigger interrupts. 1018 1019COALESCE_SET 1020============ 1021 1022Sets coalescing parameters like ``ETHTOOL_SCOALESCE`` ioctl request. 1023 1024Request contents: 1025 1026 =========================================== ====== ======================= 1027 ``ETHTOOL_A_COALESCE_HEADER`` nested request header 1028 ``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx 1029 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx 1030 ``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ 1031 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ 1032 ``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx 1033 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx 1034 ``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ 1035 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ 1036 ``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update 1037 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce 1038 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce 1039 ``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate 1040 ``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx 1041 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx 1042 ``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx 1043 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx 1044 ``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate 1045 ``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx 1046 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx 1047 ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx 1048 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx 1049 ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval 1050 ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx 1051 ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx 1052 =========================================== ====== ======================= 1053 1054Request is rejected if it attributes declared as unsupported by driver (i.e. 1055such that the corresponding bit in ``ethtool_ops::supported_coalesce_params`` 1056is not set), regardless of their values. Driver may impose additional 1057constraints on coalescing parameters and their values. 1058 1059 1060PAUSE_GET 1061========= 1062 1063Gets pause frame settings like ``ETHTOOL_GPAUSEPARAM`` ioctl request. 1064 1065Request contents: 1066 1067 ===================================== ====== ========================== 1068 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1069 ===================================== ====== ========================== 1070 1071Kernel response contents: 1072 1073 ===================================== ====== ========================== 1074 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1075 ``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation 1076 ``ETHTOOL_A_PAUSE_RX`` bool receive pause frames 1077 ``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames 1078 ``ETHTOOL_A_PAUSE_STATS`` nested pause statistics 1079 ===================================== ====== ========================== 1080 1081``ETHTOOL_A_PAUSE_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set 1082in ``ETHTOOL_A_HEADER_FLAGS``. 1083It will be empty if driver did not report any statistics. Drivers fill in 1084the statistics in the following structure: 1085 1086.. kernel-doc:: include/linux/ethtool.h 1087 :identifiers: ethtool_pause_stats 1088 1089Each member has a corresponding attribute defined. 1090 1091PAUSE_SET 1092========= 1093 1094Sets pause parameters like ``ETHTOOL_GPAUSEPARAM`` ioctl request. 1095 1096Request contents: 1097 1098 ===================================== ====== ========================== 1099 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1100 ``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation 1101 ``ETHTOOL_A_PAUSE_RX`` bool receive pause frames 1102 ``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames 1103 ===================================== ====== ========================== 1104 1105 1106EEE_GET 1107======= 1108 1109Gets Energy Efficient Ethernet settings like ``ETHTOOL_GEEE`` ioctl request. 1110 1111Request contents: 1112 1113 ===================================== ====== ========================== 1114 ``ETHTOOL_A_EEE_HEADER`` nested request header 1115 ===================================== ====== ========================== 1116 1117Kernel response contents: 1118 1119 ===================================== ====== ========================== 1120 ``ETHTOOL_A_EEE_HEADER`` nested request header 1121 ``ETHTOOL_A_EEE_MODES_OURS`` bool supported/advertised modes 1122 ``ETHTOOL_A_EEE_MODES_PEER`` bool peer advertised link modes 1123 ``ETHTOOL_A_EEE_ACTIVE`` bool EEE is actively used 1124 ``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled 1125 ``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled 1126 ``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us) 1127 ===================================== ====== ========================== 1128 1129In ``ETHTOOL_A_EEE_MODES_OURS``, mask consists of link modes for which EEE is 1130enabled, value of link modes for which EEE is advertised. Link modes for which 1131peer advertises EEE are listed in ``ETHTOOL_A_EEE_MODES_PEER`` (no mask). The 1132netlink interface allows reporting EEE status for all link modes but only 1133first 32 are provided by the ``ethtool_ops`` callback. 1134 1135 1136EEE_SET 1137======= 1138 1139Sets Energy Efficient Ethernet parameters like ``ETHTOOL_SEEE`` ioctl request. 1140 1141Request contents: 1142 1143 ===================================== ====== ========================== 1144 ``ETHTOOL_A_EEE_HEADER`` nested request header 1145 ``ETHTOOL_A_EEE_MODES_OURS`` bool advertised modes 1146 ``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled 1147 ``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled 1148 ``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us) 1149 ===================================== ====== ========================== 1150 1151``ETHTOOL_A_EEE_MODES_OURS`` is used to either list link modes to advertise 1152EEE for (if there is no mask) or specify changes to the list (if there is 1153a mask). The netlink interface allows reporting EEE status for all link modes 1154but only first 32 can be set at the moment as that is what the ``ethtool_ops`` 1155callback supports. 1156 1157 1158TSINFO_GET 1159========== 1160 1161Gets timestamping information like ``ETHTOOL_GET_TS_INFO`` ioctl request. 1162 1163Request contents: 1164 1165 ===================================== ====== ========================== 1166 ``ETHTOOL_A_TSINFO_HEADER`` nested request header 1167 ===================================== ====== ========================== 1168 1169Kernel response contents: 1170 1171 ===================================== ====== ========================== 1172 ``ETHTOOL_A_TSINFO_HEADER`` nested request header 1173 ``ETHTOOL_A_TSINFO_TIMESTAMPING`` bitset SO_TIMESTAMPING flags 1174 ``ETHTOOL_A_TSINFO_TX_TYPES`` bitset supported Tx types 1175 ``ETHTOOL_A_TSINFO_RX_FILTERS`` bitset supported Rx filters 1176 ``ETHTOOL_A_TSINFO_PHC_INDEX`` u32 PTP hw clock index 1177 ===================================== ====== ========================== 1178 1179``ETHTOOL_A_TSINFO_PHC_INDEX`` is absent if there is no associated PHC (there 1180is no special value for this case). The bitset attributes are omitted if they 1181would be empty (no bit set). 1182 1183CABLE_TEST 1184========== 1185 1186Start a cable test. 1187 1188Request contents: 1189 1190 ==================================== ====== ========================== 1191 ``ETHTOOL_A_CABLE_TEST_HEADER`` nested request header 1192 ==================================== ====== ========================== 1193 1194Notification contents: 1195 1196An Ethernet cable typically contains 1, 2 or 4 pairs. The length of 1197the pair can only be measured when there is a fault in the pair and 1198hence a reflection. Information about the fault may not be available, 1199depending on the specific hardware. Hence the contents of the notify 1200message are mostly optional. The attributes can be repeated an 1201arbitrary number of times, in an arbitrary order, for an arbitrary 1202number of pairs. 1203 1204The example shows the notification sent when the test is completed for 1205a T2 cable, i.e. two pairs. One pair is OK and hence has no length 1206information. The second pair has a fault and does have length 1207information. 1208 1209 +---------------------------------------------+--------+---------------------+ 1210 | ``ETHTOOL_A_CABLE_TEST_HEADER`` | nested | reply header | 1211 +---------------------------------------------+--------+---------------------+ 1212 | ``ETHTOOL_A_CABLE_TEST_STATUS`` | u8 | completed | 1213 +---------------------------------------------+--------+---------------------+ 1214 | ``ETHTOOL_A_CABLE_TEST_NTF_NEST`` | nested | all the results | 1215 +-+-------------------------------------------+--------+---------------------+ 1216 | | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test result | 1217 +-+-+-----------------------------------------+--------+---------------------+ 1218 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1219 +-+-+-----------------------------------------+--------+---------------------+ 1220 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code | 1221 +-+-+-----------------------------------------+--------+---------------------+ 1222 | | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test results | 1223 +-+-+-----------------------------------------+--------+---------------------+ 1224 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1225 +-+-+-----------------------------------------+--------+---------------------+ 1226 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code | 1227 +-+-+-----------------------------------------+--------+---------------------+ 1228 | | ``ETHTOOL_A_CABLE_NEST_FAULT_LENGTH`` | nested | cable length | 1229 +-+-+-----------------------------------------+--------+---------------------+ 1230 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR`` | u8 | pair number | 1231 +-+-+-----------------------------------------+--------+---------------------+ 1232 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_CM`` | u32 | length in cm | 1233 +-+-+-----------------------------------------+--------+---------------------+ 1234 1235CABLE_TEST TDR 1236============== 1237 1238Start a cable test and report raw TDR data 1239 1240Request contents: 1241 1242 +--------------------------------------------+--------+-----------------------+ 1243 | ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header | 1244 +--------------------------------------------+--------+-----------------------+ 1245 | ``ETHTOOL_A_CABLE_TEST_TDR_CFG`` | nested | test configuration | 1246 +-+------------------------------------------+--------+-----------------------+ 1247 | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | first data distance | 1248 +-+-+----------------------------------------+--------+-----------------------+ 1249 | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | last data distance | 1250 +-+-+----------------------------------------+--------+-----------------------+ 1251 | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step | 1252 +-+-+----------------------------------------+--------+-----------------------+ 1253 | | ``ETHTOOL_A_CABLE_TEST_TDR_CFG_PAIR`` | u8 | pair to test | 1254 +-+-+----------------------------------------+--------+-----------------------+ 1255 1256The ETHTOOL_A_CABLE_TEST_TDR_CFG is optional, as well as all members 1257of the nest. All distances are expressed in centimeters. The PHY takes 1258the distances as a guide, and rounds to the nearest distance it 1259actually supports. If a pair is passed, only that one pair will be 1260tested. Otherwise all pairs are tested. 1261 1262Notification contents: 1263 1264Raw TDR data is gathered by sending a pulse down the cable and 1265recording the amplitude of the reflected pulse for a given distance. 1266 1267It can take a number of seconds to collect TDR data, especial if the 1268full 100 meters is probed at 1 meter intervals. When the test is 1269started a notification will be sent containing just 1270ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value 1271ETHTOOL_A_CABLE_TEST_NTF_STATUS_STARTED. 1272 1273When the test has completed a second notification will be sent 1274containing ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value 1275ETHTOOL_A_CABLE_TEST_NTF_STATUS_COMPLETED and the TDR data. 1276 1277The message may optionally contain the amplitude of the pulse send 1278down the cable. This is measured in mV. A reflection should not be 1279bigger than transmitted pulse. 1280 1281Before the raw TDR data should be an ETHTOOL_A_CABLE_TDR_NEST_STEP 1282nest containing information about the distance along the cable for the 1283first reading, the last reading, and the step between each 1284reading. Distances are measured in centimeters. These should be the 1285exact values the PHY used. These may be different to what the user 1286requested, if the native measurement resolution is greater than 1 cm. 1287 1288For each step along the cable, a ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE is 1289used to report the amplitude of the reflection for a given pair. 1290 1291 +---------------------------------------------+--------+----------------------+ 1292 | ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header | 1293 +---------------------------------------------+--------+----------------------+ 1294 | ``ETHTOOL_A_CABLE_TEST_TDR_STATUS`` | u8 | completed | 1295 +---------------------------------------------+--------+----------------------+ 1296 | ``ETHTOOL_A_CABLE_TEST_TDR_NTF_NEST`` | nested | all the results | 1297 +-+-------------------------------------------+--------+----------------------+ 1298 | | ``ETHTOOL_A_CABLE_TDR_NEST_PULSE`` | nested | TX Pulse amplitude | 1299 +-+-+-----------------------------------------+--------+----------------------+ 1300 | | | ``ETHTOOL_A_CABLE_PULSE_mV`` | s16 | Pulse amplitude | 1301 +-+-+-----------------------------------------+--------+----------------------+ 1302 | | ``ETHTOOL_A_CABLE_NEST_STEP`` | nested | TDR step info | 1303 +-+-+-----------------------------------------+--------+----------------------+ 1304 | | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | First data distance | 1305 +-+-+-----------------------------------------+--------+----------------------+ 1306 | | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | Last data distance | 1307 +-+-+-----------------------------------------+--------+----------------------+ 1308 | | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step| 1309 +-+-+-----------------------------------------+--------+----------------------+ 1310 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1311 +-+-+-----------------------------------------+--------+----------------------+ 1312 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1313 +-+-+-----------------------------------------+--------+----------------------+ 1314 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1315 +-+-+-----------------------------------------+--------+----------------------+ 1316 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1317 +-+-+-----------------------------------------+--------+----------------------+ 1318 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1319 +-+-+-----------------------------------------+--------+----------------------+ 1320 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1321 +-+-+-----------------------------------------+--------+----------------------+ 1322 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1323 +-+-+-----------------------------------------+--------+----------------------+ 1324 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1325 +-+-+-----------------------------------------+--------+----------------------+ 1326 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1327 +-+-+-----------------------------------------+--------+----------------------+ 1328 1329TUNNEL_INFO 1330=========== 1331 1332Gets information about the tunnel state NIC is aware of. 1333 1334Request contents: 1335 1336 ===================================== ====== ========================== 1337 ``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header 1338 ===================================== ====== ========================== 1339 1340Kernel response contents: 1341 1342 +---------------------------------------------+--------+---------------------+ 1343 | ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header | 1344 +---------------------------------------------+--------+---------------------+ 1345 | ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables | 1346 +-+-------------------------------------------+--------+---------------------+ 1347 | | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table | 1348 +-+-+-----------------------------------------+--------+---------------------+ 1349 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the | 1350 | | | | | table | 1351 +-+-+-----------------------------------------+--------+---------------------+ 1352 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which | 1353 | | | | | table can hold | 1354 +-+-+-----------------------------------------+--------+---------------------+ 1355 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port | 1356 +-+-+-+---------------------------------------+--------+---------------------+ 1357 | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port | 1358 +-+-+-+---------------------------------------+--------+---------------------+ 1359 | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type | 1360 +-+-+-+---------------------------------------+--------+---------------------+ 1361 1362For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that 1363the table contains static entries, hard-coded by the NIC. 1364 1365FEC_GET 1366======= 1367 1368Gets FEC configuration and state like ``ETHTOOL_GFECPARAM`` ioctl request. 1369 1370Request contents: 1371 1372 ===================================== ====== ========================== 1373 ``ETHTOOL_A_FEC_HEADER`` nested request header 1374 ===================================== ====== ========================== 1375 1376Kernel response contents: 1377 1378 ===================================== ====== ========================== 1379 ``ETHTOOL_A_FEC_HEADER`` nested request header 1380 ``ETHTOOL_A_FEC_MODES`` bitset configured modes 1381 ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection 1382 ``ETHTOOL_A_FEC_ACTIVE`` u32 index of active FEC mode 1383 ``ETHTOOL_A_FEC_STATS`` nested FEC statistics 1384 ===================================== ====== ========================== 1385 1386``ETHTOOL_A_FEC_ACTIVE`` is the bit index of the FEC link mode currently 1387active on the interface. This attribute may not be present if device does 1388not support FEC. 1389 1390``ETHTOOL_A_FEC_MODES`` and ``ETHTOOL_A_FEC_AUTO`` are only meaningful when 1391autonegotiation is disabled. If ``ETHTOOL_A_FEC_AUTO`` is non-zero driver will 1392select the FEC mode automatically based on the parameters of the SFP module. 1393This is equivalent to the ``ETHTOOL_FEC_AUTO`` bit of the ioctl interface. 1394``ETHTOOL_A_FEC_MODES`` carry the current FEC configuration using link mode 1395bits (rather than old ``ETHTOOL_FEC_*`` bits). 1396 1397``ETHTOOL_A_FEC_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in 1398``ETHTOOL_A_HEADER_FLAGS``. 1399Each attribute carries an array of 64bit statistics. First entry in the array 1400contains the total number of events on the port, while the following entries 1401are counters corresponding to lanes/PCS instances. The number of entries in 1402the array will be: 1403 1404+--------------+---------------------------------------------+ 1405| `0` | device does not support FEC statistics | 1406+--------------+---------------------------------------------+ 1407| `1` | device does not support per-lane break down | 1408+--------------+---------------------------------------------+ 1409| `1 + #lanes` | device has full support for FEC stats | 1410+--------------+---------------------------------------------+ 1411 1412Drivers fill in the statistics in the following structure: 1413 1414.. kernel-doc:: include/linux/ethtool.h 1415 :identifiers: ethtool_fec_stats 1416 1417FEC_SET 1418======= 1419 1420Sets FEC parameters like ``ETHTOOL_SFECPARAM`` ioctl request. 1421 1422Request contents: 1423 1424 ===================================== ====== ========================== 1425 ``ETHTOOL_A_FEC_HEADER`` nested request header 1426 ``ETHTOOL_A_FEC_MODES`` bitset configured modes 1427 ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection 1428 ===================================== ====== ========================== 1429 1430``FEC_SET`` is only meaningful when autonegotiation is disabled. Otherwise 1431FEC mode is selected as part of autonegotiation. 1432 1433``ETHTOOL_A_FEC_MODES`` selects which FEC mode should be used. It's recommended 1434to set only one bit, if multiple bits are set driver may choose between them 1435in an implementation specific way. 1436 1437``ETHTOOL_A_FEC_AUTO`` requests the driver to choose FEC mode based on SFP 1438module parameters. This does not mean autonegotiation. 1439 1440MODULE_EEPROM_GET 1441================= 1442 1443Fetch module EEPROM data dump. 1444This interface is designed to allow dumps of at most 1/2 page at once. This 1445means only dumps of 128 (or less) bytes are allowed, without crossing half page 1446boundary located at offset 128. For pages other than 0 only high 128 bytes are 1447accessible. 1448 1449Request contents: 1450 1451 ======================================= ====== ========================== 1452 ``ETHTOOL_A_MODULE_EEPROM_HEADER`` nested request header 1453 ``ETHTOOL_A_MODULE_EEPROM_OFFSET`` u32 offset within a page 1454 ``ETHTOOL_A_MODULE_EEPROM_LENGTH`` u32 amount of bytes to read 1455 ``ETHTOOL_A_MODULE_EEPROM_PAGE`` u8 page number 1456 ``ETHTOOL_A_MODULE_EEPROM_BANK`` u8 bank number 1457 ``ETHTOOL_A_MODULE_EEPROM_I2C_ADDRESS`` u8 page I2C address 1458 ======================================= ====== ========================== 1459 1460If ``ETHTOOL_A_MODULE_EEPROM_BANK`` is not specified, bank 0 is assumed. 1461 1462Kernel response contents: 1463 1464 +---------------------------------------------+--------+---------------------+ 1465 | ``ETHTOOL_A_MODULE_EEPROM_HEADER`` | nested | reply header | 1466 +---------------------------------------------+--------+---------------------+ 1467 | ``ETHTOOL_A_MODULE_EEPROM_DATA`` | binary | array of bytes from | 1468 | | | module EEPROM | 1469 +---------------------------------------------+--------+---------------------+ 1470 1471``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of 1472bytes driver actually read. 1473 1474STATS_GET 1475========= 1476 1477Get standard statistics for the interface. Note that this is not 1478a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined 1479stats. 1480 1481Request contents: 1482 1483 ======================================= ====== ========================== 1484 ``ETHTOOL_A_STATS_HEADER`` nested request header 1485 ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats 1486 ======================================= ====== ========================== 1487 1488Kernel response contents: 1489 1490 +-----------------------------------+--------+--------------------------------+ 1491 | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header | 1492 +-----------------------------------+--------+--------------------------------+ 1493 | ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats | 1494 +-+---------------------------------+--------+--------------------------------+ 1495 | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` | 1496 +-+---------------------------------+--------+--------------------------------+ 1497 | | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names | 1498 +-+---------------------------------+--------+--------------------------------+ 1499 | | ``ETHTOOL_A_STATS_GRP_STAT`` | nested | nest containing a statistic | 1500 +-+---------------------------------+--------+--------------------------------+ 1501 | | ``ETHTOOL_A_STATS_GRP_HIST_RX`` | nested | histogram statistic (Rx) | 1502 +-+---------------------------------+--------+--------------------------------+ 1503 | | ``ETHTOOL_A_STATS_GRP_HIST_TX`` | nested | histogram statistic (Tx) | 1504 +-+---------------------------------+--------+--------------------------------+ 1505 1506Users specify which groups of statistics they are requesting via 1507the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are: 1508 1509 ====================== ======== =============================================== 1510 ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*) 1511 ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*) 1512 ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*) 1513 ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics 1514 ====================== ======== =============================================== 1515 1516Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply. 1517``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains. 1518``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of 1519the statistics in the group, if available. 1520 1521Statistics are added to the ``ETHTOOL_A_STATS_GRP`` nest under 1522``ETHTOOL_A_STATS_GRP_STAT``. ``ETHTOOL_A_STATS_GRP_STAT`` should contain 1523single 8 byte (u64) attribute inside - the type of that attribute is 1524the statistic ID and the value is the value of the statistic. 1525Each group has its own interpretation of statistic IDs. 1526Attribute IDs correspond to strings from the string set identified 1527by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics (such as RMON histogram 1528entries) are also listed inside ``ETHTOOL_A_STATS_GRP`` and do not have 1529a string defined in the string set. 1530 1531RMON "histogram" counters count number of packets within given size range. 1532Because RFC does not specify the ranges beyond the standard 1518 MTU devices 1533differ in definition of buckets. For this reason the definition of packet ranges 1534is left to each driver. 1535 1536``ETHTOOL_A_STATS_GRP_HIST_RX`` and ``ETHTOOL_A_STATS_GRP_HIST_TX`` nests 1537contain the following attributes: 1538 1539 ================================= ====== =================================== 1540 ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket 1541 ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket 1542 ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter 1543 ================================= ====== =================================== 1544 1545Low and high bounds are inclusive, for example: 1546 1547 ============================= ==== ==== 1548 RFC statistic low high 1549 ============================= ==== ==== 1550 etherStatsPkts64Octets 0 64 1551 etherStatsPkts512to1023Octets 512 1023 1552 ============================= ==== ==== 1553 1554PHC_VCLOCKS_GET 1555=============== 1556 1557Query device PHC virtual clocks information. 1558 1559Request contents: 1560 1561 ==================================== ====== ========================== 1562 ``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested request header 1563 ==================================== ====== ========================== 1564 1565Kernel response contents: 1566 1567 ==================================== ====== ========================== 1568 ``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested reply header 1569 ``ETHTOOL_A_PHC_VCLOCKS_NUM`` u32 PHC virtual clocks number 1570 ``ETHTOOL_A_PHC_VCLOCKS_INDEX`` s32 PHC index array 1571 ==================================== ====== ========================== 1572 1573MODULE_GET 1574========== 1575 1576Gets transceiver module parameters. 1577 1578Request contents: 1579 1580 ===================================== ====== ========================== 1581 ``ETHTOOL_A_MODULE_HEADER`` nested request header 1582 ===================================== ====== ========================== 1583 1584Kernel response contents: 1585 1586 ====================================== ====== ========================== 1587 ``ETHTOOL_A_MODULE_HEADER`` nested reply header 1588 ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy 1589 ``ETHTOOL_A_MODULE_POWER_MODE`` u8 operational power mode 1590 ====================================== ====== ========================== 1591 1592The optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute encodes the 1593transceiver module power mode policy enforced by the host. The default policy 1594is driver-dependent, but "auto" is the recommended default and it should be 1595implemented by new drivers and drivers where conformance to a legacy behavior 1596is not critical. 1597 1598The optional ``ETHTHOOL_A_MODULE_POWER_MODE`` attribute encodes the operational 1599power mode policy of the transceiver module. It is only reported when a module 1600is plugged-in. Possible values are: 1601 1602.. kernel-doc:: include/uapi/linux/ethtool.h 1603 :identifiers: ethtool_module_power_mode 1604 1605MODULE_SET 1606========== 1607 1608Sets transceiver module parameters. 1609 1610Request contents: 1611 1612 ====================================== ====== ========================== 1613 ``ETHTOOL_A_MODULE_HEADER`` nested request header 1614 ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy 1615 ====================================== ====== ========================== 1616 1617When set, the optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute is used 1618to set the transceiver module power policy enforced by the host. Possible 1619values are: 1620 1621.. kernel-doc:: include/uapi/linux/ethtool.h 1622 :identifiers: ethtool_module_power_mode_policy 1623 1624For SFF-8636 modules, low power mode is forced by the host according to table 16256-10 in revision 2.10a of the specification. 1626 1627For CMIS modules, low power mode is forced by the host according to table 6-12 1628in revision 5.0 of the specification. 1629 1630Request translation 1631=================== 1632 1633The following table maps ioctl commands to netlink commands providing their 1634functionality. Entries with "n/a" in right column are commands which do not 1635have their netlink replacement yet. Entries which "n/a" in the left column 1636are netlink only. 1637 1638 =================================== ===================================== 1639 ioctl command netlink command 1640 =================================== ===================================== 1641 ``ETHTOOL_GSET`` ``ETHTOOL_MSG_LINKINFO_GET`` 1642 ``ETHTOOL_MSG_LINKMODES_GET`` 1643 ``ETHTOOL_SSET`` ``ETHTOOL_MSG_LINKINFO_SET`` 1644 ``ETHTOOL_MSG_LINKMODES_SET`` 1645 ``ETHTOOL_GDRVINFO`` n/a 1646 ``ETHTOOL_GREGS`` n/a 1647 ``ETHTOOL_GWOL`` ``ETHTOOL_MSG_WOL_GET`` 1648 ``ETHTOOL_SWOL`` ``ETHTOOL_MSG_WOL_SET`` 1649 ``ETHTOOL_GMSGLVL`` ``ETHTOOL_MSG_DEBUG_GET`` 1650 ``ETHTOOL_SMSGLVL`` ``ETHTOOL_MSG_DEBUG_SET`` 1651 ``ETHTOOL_NWAY_RST`` n/a 1652 ``ETHTOOL_GLINK`` ``ETHTOOL_MSG_LINKSTATE_GET`` 1653 ``ETHTOOL_GEEPROM`` n/a 1654 ``ETHTOOL_SEEPROM`` n/a 1655 ``ETHTOOL_GCOALESCE`` ``ETHTOOL_MSG_COALESCE_GET`` 1656 ``ETHTOOL_SCOALESCE`` ``ETHTOOL_MSG_COALESCE_SET`` 1657 ``ETHTOOL_GRINGPARAM`` ``ETHTOOL_MSG_RINGS_GET`` 1658 ``ETHTOOL_SRINGPARAM`` ``ETHTOOL_MSG_RINGS_SET`` 1659 ``ETHTOOL_GPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_GET`` 1660 ``ETHTOOL_SPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_SET`` 1661 ``ETHTOOL_GRXCSUM`` ``ETHTOOL_MSG_FEATURES_GET`` 1662 ``ETHTOOL_SRXCSUM`` ``ETHTOOL_MSG_FEATURES_SET`` 1663 ``ETHTOOL_GTXCSUM`` ``ETHTOOL_MSG_FEATURES_GET`` 1664 ``ETHTOOL_STXCSUM`` ``ETHTOOL_MSG_FEATURES_SET`` 1665 ``ETHTOOL_GSG`` ``ETHTOOL_MSG_FEATURES_GET`` 1666 ``ETHTOOL_SSG`` ``ETHTOOL_MSG_FEATURES_SET`` 1667 ``ETHTOOL_TEST`` n/a 1668 ``ETHTOOL_GSTRINGS`` ``ETHTOOL_MSG_STRSET_GET`` 1669 ``ETHTOOL_PHYS_ID`` n/a 1670 ``ETHTOOL_GSTATS`` n/a 1671 ``ETHTOOL_GTSO`` ``ETHTOOL_MSG_FEATURES_GET`` 1672 ``ETHTOOL_STSO`` ``ETHTOOL_MSG_FEATURES_SET`` 1673 ``ETHTOOL_GPERMADDR`` rtnetlink ``RTM_GETLINK`` 1674 ``ETHTOOL_GUFO`` ``ETHTOOL_MSG_FEATURES_GET`` 1675 ``ETHTOOL_SUFO`` ``ETHTOOL_MSG_FEATURES_SET`` 1676 ``ETHTOOL_GGSO`` ``ETHTOOL_MSG_FEATURES_GET`` 1677 ``ETHTOOL_SGSO`` ``ETHTOOL_MSG_FEATURES_SET`` 1678 ``ETHTOOL_GFLAGS`` ``ETHTOOL_MSG_FEATURES_GET`` 1679 ``ETHTOOL_SFLAGS`` ``ETHTOOL_MSG_FEATURES_SET`` 1680 ``ETHTOOL_GPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_GET`` 1681 ``ETHTOOL_SPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_SET`` 1682 ``ETHTOOL_GRXFH`` n/a 1683 ``ETHTOOL_SRXFH`` n/a 1684 ``ETHTOOL_GGRO`` ``ETHTOOL_MSG_FEATURES_GET`` 1685 ``ETHTOOL_SGRO`` ``ETHTOOL_MSG_FEATURES_SET`` 1686 ``ETHTOOL_GRXRINGS`` n/a 1687 ``ETHTOOL_GRXCLSRLCNT`` n/a 1688 ``ETHTOOL_GRXCLSRULE`` n/a 1689 ``ETHTOOL_GRXCLSRLALL`` n/a 1690 ``ETHTOOL_SRXCLSRLDEL`` n/a 1691 ``ETHTOOL_SRXCLSRLINS`` n/a 1692 ``ETHTOOL_FLASHDEV`` n/a 1693 ``ETHTOOL_RESET`` n/a 1694 ``ETHTOOL_SRXNTUPLE`` n/a 1695 ``ETHTOOL_GRXNTUPLE`` n/a 1696 ``ETHTOOL_GSSET_INFO`` ``ETHTOOL_MSG_STRSET_GET`` 1697 ``ETHTOOL_GRXFHINDIR`` n/a 1698 ``ETHTOOL_SRXFHINDIR`` n/a 1699 ``ETHTOOL_GFEATURES`` ``ETHTOOL_MSG_FEATURES_GET`` 1700 ``ETHTOOL_SFEATURES`` ``ETHTOOL_MSG_FEATURES_SET`` 1701 ``ETHTOOL_GCHANNELS`` ``ETHTOOL_MSG_CHANNELS_GET`` 1702 ``ETHTOOL_SCHANNELS`` ``ETHTOOL_MSG_CHANNELS_SET`` 1703 ``ETHTOOL_SET_DUMP`` n/a 1704 ``ETHTOOL_GET_DUMP_FLAG`` n/a 1705 ``ETHTOOL_GET_DUMP_DATA`` n/a 1706 ``ETHTOOL_GET_TS_INFO`` ``ETHTOOL_MSG_TSINFO_GET`` 1707 ``ETHTOOL_GMODULEINFO`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` 1708 ``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` 1709 ``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET`` 1710 ``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET`` 1711 ``ETHTOOL_GRSSH`` n/a 1712 ``ETHTOOL_SRSSH`` n/a 1713 ``ETHTOOL_GTUNABLE`` n/a 1714 ``ETHTOOL_STUNABLE`` n/a 1715 ``ETHTOOL_GPHYSTATS`` n/a 1716 ``ETHTOOL_PERQUEUE`` n/a 1717 ``ETHTOOL_GLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_GET`` 1718 ``ETHTOOL_MSG_LINKMODES_GET`` 1719 ``ETHTOOL_SLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_SET`` 1720 ``ETHTOOL_MSG_LINKMODES_SET`` 1721 ``ETHTOOL_PHY_GTUNABLE`` n/a 1722 ``ETHTOOL_PHY_STUNABLE`` n/a 1723 ``ETHTOOL_GFECPARAM`` ``ETHTOOL_MSG_FEC_GET`` 1724 ``ETHTOOL_SFECPARAM`` ``ETHTOOL_MSG_FEC_SET`` 1725 n/a ``ETHTOOL_MSG_CABLE_TEST_ACT`` 1726 n/a ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` 1727 n/a ``ETHTOOL_MSG_TUNNEL_INFO_GET`` 1728 n/a ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` 1729 n/a ``ETHTOOL_MSG_MODULE_GET`` 1730 n/a ``ETHTOOL_MSG_MODULE_SET`` 1731 =================================== ===================================== 1732