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