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