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