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 ``ETHTOOL_A_HEADER_PHY_INDEX`` u32 phy device index 61 ============================== ====== ============================= 62 63``ETHTOOL_A_HEADER_DEV_INDEX`` and ``ETHTOOL_A_HEADER_DEV_NAME`` identify the 64device message relates to. One of them is sufficient in requests, if both are 65used, they must identify the same device. Some requests, e.g. global string 66sets, do not require device identification. Most ``GET`` requests also allow 67dump requests without device identification to query the same information for 68all devices providing it (each device in a separate message). 69 70``ETHTOOL_A_HEADER_FLAGS`` is a bitmap of request flags common for all request 71types. The interpretation of these flags is the same for all request types but 72the flags may not apply to requests. Recognized flags are: 73 74 ================================= =================================== 75 ``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply 76 ``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT) 77 ``ETHTOOL_FLAG_STATS`` include optional device statistics 78 ================================= =================================== 79 80New request flags should follow the general idea that if the flag is not set, 81the behaviour is backward compatible, i.e. requests from old clients not aware 82of the flag should be interpreted the way the client expects. A client must 83not set flags it does not understand. 84 85``ETHTOOL_A_HEADER_PHY_INDEX`` identifies the Ethernet PHY the message relates to. 86As there are numerous commands that are related to PHY configuration, and because 87there may be more than one PHY on the link, the PHY index can be passed in the 88request for the commands that needs it. It is, however, not mandatory, and if it 89is not passed for commands that target a PHY, the net_device.phydev pointer 90is used. 91 92Bit sets 93======== 94 95For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32`` 96type is used. For arbitrary length bitmaps, ethtool netlink uses a nested 97attribute with contents of one of two forms: compact (two binary bitmaps 98representing bit values and mask of affected bits) and bit-by-bit (list of 99bits identified by index or name). 100 101Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together 102with their values which saves a round trip (when the bitset is passed in a 103request) or at least a second request (when the bitset is in a reply). This is 104useful for one shot applications like traditional ethtool command. On the 105other hand, long running applications like ethtool monitor (displaying 106notifications) or network management daemons may prefer fetching the names 107only once and using compact form to save message size. Notifications from 108ethtool netlink interface always use compact form for bitsets. 109 110A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK`` 111not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests 112modifying a bitmap, the former changes the bit set in mask to values set in 113value and preserves the rest; the latter sets the bits set in the bitmap and 114clears the rest. 115 116Compact form: nested (bitset) attribute contents: 117 118 ============================ ====== ============================ 119 ``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list 120 ``ETHTOOL_A_BITSET_SIZE`` u32 number of significant bits 121 ``ETHTOOL_A_BITSET_VALUE`` binary bitmap of bit values 122 ``ETHTOOL_A_BITSET_MASK`` binary bitmap of valid bits 123 ============================ ====== ============================ 124 125Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits 126rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte 127order, words ordered from least significant to most significant (i.e. the same 128way as bitmaps are passed with ioctl interface). 129 130For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are 131mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if 132``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair); 133if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not 134allowed (bitset represents a single bitmap. 135 136Kernel bit set length may differ from userspace length if older application is 137used on newer kernel or vice versa. If userspace bitmap is longer, an error is 138issued only if the request actually tries to set values of some bits not 139recognized by kernel. 140 141Bit-by-bit form: nested (bitset) attribute contents: 142 143 +------------------------------------+--------+-----------------------------+ 144 | ``ETHTOOL_A_BITSET_NOMASK`` | flag | no mask, only a list | 145 +------------------------------------+--------+-----------------------------+ 146 | ``ETHTOOL_A_BITSET_SIZE`` | u32 | number of significant bits | 147 +------------------------------------+--------+-----------------------------+ 148 | ``ETHTOOL_A_BITSET_BITS`` | nested | array of bits | 149 +-+----------------------------------+--------+-----------------------------+ 150 | | ``ETHTOOL_A_BITSET_BITS_BIT+`` | nested | one bit | 151 +-+-+--------------------------------+--------+-----------------------------+ 152 | | | ``ETHTOOL_A_BITSET_BIT_INDEX`` | u32 | bit index (0 for LSB) | 153 +-+-+--------------------------------+--------+-----------------------------+ 154 | | | ``ETHTOOL_A_BITSET_BIT_NAME`` | string | bit name | 155 +-+-+--------------------------------+--------+-----------------------------+ 156 | | | ``ETHTOOL_A_BITSET_BIT_VALUE`` | flag | present if bit is set | 157 +-+-+--------------------------------+--------+-----------------------------+ 158 159For bit-by-bit form, ``ETHTOOL_A_BITSET_SIZE`` is optional, and 160``ETHTOOL_A_BITSET_BITS`` is mandatory. ``ETHTOOL_A_BITSET_BITS`` nest can 161only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an 162arbitrary number of them. A bit may be identified by its index or by its 163name. When used in requests, listed bits are set to 0 or 1 according to 164``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved. 165 166A request fails if index exceeds kernel bit length or if name is not 167recognized. If both name and index are set, the request will fail if they 168point to different bits. 169 170When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as 171a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in 172such case. Such bitset represents a bitmap with listed bits set and the rest 173zero. 174 175In requests, application can use either form. Form used by kernel in reply is 176determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request 177header. Semantics of value and mask depends on the attribute. 178 179 180List of message types 181===================== 182 183All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix 184according to message purpose: 185 186 ============== ====================================== 187 ``_GET`` userspace request to retrieve data 188 ``_SET`` userspace request to set data 189 ``_ACT`` userspace request to perform an action 190 ``_GET_REPLY`` kernel reply to a ``GET`` request 191 ``_SET_REPLY`` kernel reply to a ``SET`` request 192 ``_ACT_REPLY`` kernel reply to an ``ACT`` request 193 ``_NTF`` kernel notification 194 ============== ====================================== 195 196Userspace to kernel: 197 198 ===================================== ================================= 199 ``ETHTOOL_MSG_STRSET_GET`` get string set 200 ``ETHTOOL_MSG_LINKINFO_GET`` get link settings 201 ``ETHTOOL_MSG_LINKINFO_SET`` set link settings 202 ``ETHTOOL_MSG_LINKMODES_GET`` get link modes info 203 ``ETHTOOL_MSG_LINKMODES_SET`` set link modes info 204 ``ETHTOOL_MSG_LINKSTATE_GET`` get link state 205 ``ETHTOOL_MSG_DEBUG_GET`` get debugging settings 206 ``ETHTOOL_MSG_DEBUG_SET`` set debugging settings 207 ``ETHTOOL_MSG_WOL_GET`` get wake-on-lan settings 208 ``ETHTOOL_MSG_WOL_SET`` set wake-on-lan settings 209 ``ETHTOOL_MSG_FEATURES_GET`` get device features 210 ``ETHTOOL_MSG_FEATURES_SET`` set device features 211 ``ETHTOOL_MSG_PRIVFLAGS_GET`` get private flags 212 ``ETHTOOL_MSG_PRIVFLAGS_SET`` set private flags 213 ``ETHTOOL_MSG_RINGS_GET`` get ring sizes 214 ``ETHTOOL_MSG_RINGS_SET`` set ring sizes 215 ``ETHTOOL_MSG_CHANNELS_GET`` get channel counts 216 ``ETHTOOL_MSG_CHANNELS_SET`` set channel counts 217 ``ETHTOOL_MSG_COALESCE_GET`` get coalescing parameters 218 ``ETHTOOL_MSG_COALESCE_SET`` set coalescing parameters 219 ``ETHTOOL_MSG_PAUSE_GET`` get pause parameters 220 ``ETHTOOL_MSG_PAUSE_SET`` set pause parameters 221 ``ETHTOOL_MSG_EEE_GET`` get EEE settings 222 ``ETHTOOL_MSG_EEE_SET`` set EEE settings 223 ``ETHTOOL_MSG_TSINFO_GET`` get timestamping info 224 ``ETHTOOL_MSG_CABLE_TEST_ACT`` action start cable test 225 ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` action start raw TDR cable test 226 ``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info 227 ``ETHTOOL_MSG_FEC_GET`` get FEC settings 228 ``ETHTOOL_MSG_FEC_SET`` set FEC settings 229 ``ETHTOOL_MSG_MODULE_EEPROM_GET`` read SFP module EEPROM 230 ``ETHTOOL_MSG_STATS_GET`` get standard statistics 231 ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` get PHC virtual clocks info 232 ``ETHTOOL_MSG_MODULE_SET`` set transceiver module parameters 233 ``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters 234 ``ETHTOOL_MSG_PSE_SET`` set PSE parameters 235 ``ETHTOOL_MSG_PSE_GET`` get PSE parameters 236 ``ETHTOOL_MSG_RSS_GET`` get RSS settings 237 ``ETHTOOL_MSG_PLCA_GET_CFG`` get PLCA RS parameters 238 ``ETHTOOL_MSG_PLCA_SET_CFG`` set PLCA RS parameters 239 ``ETHTOOL_MSG_PLCA_GET_STATUS`` get PLCA RS status 240 ``ETHTOOL_MSG_MM_GET`` get MAC merge layer state 241 ``ETHTOOL_MSG_MM_SET`` set MAC merge layer parameters 242 ``ETHTOOL_MSG_MODULE_FW_FLASH_ACT`` flash transceiver module firmware 243 ``ETHTOOL_MSG_PHY_GET`` get Ethernet PHY information 244 ``ETHTOOL_MSG_TSCONFIG_GET`` get hw timestamping configuration 245 ``ETHTOOL_MSG_TSCONFIG_SET`` set hw timestamping configuration 246 ``ETHTOOL_MSG_RSS_SET`` set RSS settings 247 ``ETHTOOL_MSG_RSS_CREATE_ACT`` create an additional RSS context 248 ``ETHTOOL_MSG_RSS_DELETE_ACT`` delete an additional RSS context 249 ``ETHTOOL_MSG_MSE_GET`` get MSE diagnostic data 250 ===================================== ================================= 251 252Kernel to userspace: 253 254 ======================================== ================================= 255 ``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents 256 ``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings 257 ``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification 258 ``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info 259 ``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification 260 ``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info 261 ``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings 262 ``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification 263 ``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings 264 ``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification 265 ``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features 266 ``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET 267 ``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification 268 ``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags 269 ``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags 270 ``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes 271 ``ETHTOOL_MSG_RINGS_NTF`` ring sizes 272 ``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts 273 ``ETHTOOL_MSG_CHANNELS_NTF`` channel counts 274 ``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters 275 ``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters 276 ``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters 277 ``ETHTOOL_MSG_PAUSE_NTF`` pause parameters 278 ``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings 279 ``ETHTOOL_MSG_EEE_NTF`` EEE settings 280 ``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info 281 ``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results 282 ``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results 283 ``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info 284 ``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings 285 ``ETHTOOL_MSG_FEC_NTF`` FEC settings 286 ``ETHTOOL_MSG_MODULE_EEPROM_GET_REPLY`` read SFP module EEPROM 287 ``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics 288 ``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info 289 ``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters 290 ``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters 291 ``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings 292 ``ETHTOOL_MSG_RSS_NTF`` RSS settings 293 ``ETHTOOL_MSG_PLCA_GET_CFG_REPLY`` PLCA RS parameters 294 ``ETHTOOL_MSG_PLCA_GET_STATUS_REPLY`` PLCA RS status 295 ``ETHTOOL_MSG_PLCA_NTF`` PLCA RS parameters 296 ``ETHTOOL_MSG_MM_GET_REPLY`` MAC merge layer status 297 ``ETHTOOL_MSG_MODULE_FW_FLASH_NTF`` transceiver module flash updates 298 ``ETHTOOL_MSG_PHY_GET_REPLY`` Ethernet PHY information 299 ``ETHTOOL_MSG_PHY_NTF`` Ethernet PHY information change 300 ``ETHTOOL_MSG_TSCONFIG_GET_REPLY`` hw timestamping configuration 301 ``ETHTOOL_MSG_TSCONFIG_SET_REPLY`` new hw timestamping configuration 302 ``ETHTOOL_MSG_PSE_NTF`` PSE events notification 303 ``ETHTOOL_MSG_RSS_NTF`` RSS settings notification 304 ``ETHTOOL_MSG_RSS_CREATE_ACT_REPLY`` create an additional RSS context 305 ``ETHTOOL_MSG_RSS_CREATE_NTF`` additional RSS context created 306 ``ETHTOOL_MSG_RSS_DELETE_NTF`` additional RSS context deleted 307 ``ETHTOOL_MSG_MSE_GET_REPLY`` MSE diagnostic data 308 ======================================== ================================= 309 310``GET`` requests are sent by userspace applications to retrieve device 311information. They usually do not contain any message specific attributes. 312Kernel replies with corresponding "GET_REPLY" message. For most types, ``GET`` 313request with ``NLM_F_DUMP`` and no device identification can be used to query 314the information for all devices supporting the request. 315 316If the data can be also modified, corresponding ``SET`` message with the same 317layout as corresponding ``GET_REPLY`` is used to request changes. Only 318attributes where a change is requested are included in such request (also, not 319all attributes may be changed). Replies to most ``SET`` request consist only 320of error code and extack; if kernel provides additional data, it is sent in 321the form of corresponding ``SET_REPLY`` message which can be suppressed by 322setting ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header. 323 324Data modification also triggers sending a ``NTF`` message with a notification. 325These usually bear only a subset of attributes which was affected by the 326change. The same notification is issued if the data is modified using other 327means (mostly ioctl ethtool interface). Unlike notifications from ethtool 328netlink code which are only sent if something actually changed, notifications 329triggered by ioctl interface may be sent even if the request did not actually 330change any data. 331 332``ACT`` messages request kernel (driver) to perform a specific action. If some 333information is reported by kernel (which can be suppressed by setting 334``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header), the reply takes form of 335an ``ACT_REPLY`` message. Performing an action also triggers a notification 336(``NTF`` message). 337 338Later sections describe the format and semantics of these messages. 339 340 341STRSET_GET 342========== 343 344Requests contents of a string set as provided by ioctl commands 345``ETHTOOL_GSSET_INFO`` and ``ETHTOOL_GSTRINGS.`` String sets are not user 346writeable so that the corresponding ``STRSET_SET`` message is only used in 347kernel replies. There are two types of string sets: global (independent of 348a device, e.g. device feature names) and device specific (e.g. device private 349flags). 350 351Request contents: 352 353 +---------------------------------------+--------+------------------------+ 354 | ``ETHTOOL_A_STRSET_HEADER`` | nested | request header | 355 +---------------------------------------+--------+------------------------+ 356 | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | string set to request | 357 +-+-------------------------------------+--------+------------------------+ 358 | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | 359 +-+-+-----------------------------------+--------+------------------------+ 360 | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | 361 +-+-+-----------------------------------+--------+------------------------+ 362 363Kernel response contents: 364 365 +---------------------------------------+--------+-----------------------+ 366 | ``ETHTOOL_A_STRSET_HEADER`` | nested | reply header | 367 +---------------------------------------+--------+-----------------------+ 368 | ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | array of string sets | 369 +-+-------------------------------------+--------+-----------------------+ 370 | | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set | 371 +-+-+-----------------------------------+--------+-----------------------+ 372 | | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id | 373 +-+-+-----------------------------------+--------+-----------------------+ 374 | | | ``ETHTOOL_A_STRINGSET_COUNT`` | u32 | number of strings | 375 +-+-+-----------------------------------+--------+-----------------------+ 376 | | | ``ETHTOOL_A_STRINGSET_STRINGS`` | nested | array of strings | 377 +-+-+-+---------------------------------+--------+-----------------------+ 378 | | | | ``ETHTOOL_A_STRINGS_STRING+`` | nested | one string | 379 +-+-+-+-+-------------------------------+--------+-----------------------+ 380 | | | | | ``ETHTOOL_A_STRING_INDEX`` | u32 | string index | 381 +-+-+-+-+-------------------------------+--------+-----------------------+ 382 | | | | | ``ETHTOOL_A_STRING_VALUE`` | string | string value | 383 +-+-+-+-+-------------------------------+--------+-----------------------+ 384 | ``ETHTOOL_A_STRSET_COUNTS_ONLY`` | flag | return only counts | 385 +---------------------------------------+--------+-----------------------+ 386 387Device identification in request header is optional. Depending on its presence 388a and ``NLM_F_DUMP`` flag, there are three type of ``STRSET_GET`` requests: 389 390 - no ``NLM_F_DUMP,`` no device: get "global" stringsets 391 - no ``NLM_F_DUMP``, with device: get string sets related to the device 392 - ``NLM_F_DUMP``, no device: get device related string sets for all devices 393 394If there is no ``ETHTOOL_A_STRSET_STRINGSETS`` array, all string sets of 395requested type are returned, otherwise only those specified in the request. 396Flag ``ETHTOOL_A_STRSET_COUNTS_ONLY`` tells kernel to only return string 397counts of the sets, not the actual strings. 398 399 400LINKINFO_GET 401============ 402 403Requests link settings as provided by ``ETHTOOL_GLINKSETTINGS`` except for 404link modes and autonegotiation related information. The request does not use 405any attributes. 406 407Request contents: 408 409 ==================================== ====== ========================== 410 ``ETHTOOL_A_LINKINFO_HEADER`` nested request header 411 ==================================== ====== ========================== 412 413Kernel response contents: 414 415 ==================================== ====== ========================== 416 ``ETHTOOL_A_LINKINFO_HEADER`` nested reply header 417 ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port 418 ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address 419 ``ETHTOOL_A_LINKINFO_TP_MDIX`` u8 MDI(-X) status 420 ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control 421 ``ETHTOOL_A_LINKINFO_TRANSCEIVER`` u8 transceiver 422 ==================================== ====== ========================== 423 424Attributes and their values have the same meaning as matching members of the 425corresponding ioctl structures. 426 427``LINKINFO_GET`` allows dump requests (kernel returns reply message for all 428devices supporting the request). 429 430 431LINKINFO_SET 432============ 433 434``LINKINFO_SET`` request allows setting some of the attributes reported by 435``LINKINFO_GET``. 436 437Request contents: 438 439 ==================================== ====== ========================== 440 ``ETHTOOL_A_LINKINFO_HEADER`` nested request header 441 ``ETHTOOL_A_LINKINFO_PORT`` u8 physical port 442 ``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address 443 ``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control 444 ==================================== ====== ========================== 445 446MDI(-X) status and transceiver cannot be set, request with the corresponding 447attributes is rejected. 448 449 450LINKMODES_GET 451============= 452 453Requests link modes (supported, advertised and peer advertised) and related 454information (autonegotiation status, link speed and duplex) as provided by 455``ETHTOOL_GLINKSETTINGS``. The request does not use any attributes. 456 457Request contents: 458 459 ==================================== ====== ========================== 460 ``ETHTOOL_A_LINKMODES_HEADER`` nested request header 461 ==================================== ====== ========================== 462 463Kernel response contents: 464 465 ========================================== ====== ========================== 466 ``ETHTOOL_A_LINKMODES_HEADER`` nested reply header 467 ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status 468 ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes 469 ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes 470 ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) 471 ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode 472 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode 473 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_STATE`` u8 Master/slave port state 474 ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching 475 ========================================== ====== ========================== 476 477For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask 478represents supported modes. ``ETHTOOL_A_LINKMODES_PEER`` in the reply is a bit 479list. 480 481``LINKMODES_GET`` allows dump requests (kernel returns reply messages for all 482devices supporting the request). 483 484 485LINKMODES_SET 486============= 487 488Request contents: 489 490 ========================================== ====== ========================== 491 ``ETHTOOL_A_LINKMODES_HEADER`` nested request header 492 ``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status 493 ``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes 494 ``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes 495 ``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s) 496 ``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode 497 ``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode 498 ``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching 499 ``ETHTOOL_A_LINKMODES_LANES`` u32 lanes 500 ========================================== ====== ========================== 501 502``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If 503autonegotiation is on (either set now or kept from before), advertised modes 504are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one 505of speed, duplex and lanes is specified, kernel adjusts advertised modes to all 506supported modes matching speed, duplex, lanes or all (whatever is specified). 507This autoselection is done on ethtool side with ioctl interface, netlink 508interface is supposed to allow requesting changes without knowing what exactly 509kernel supports. 510 511 512LINKSTATE_GET 513============= 514 515Requests link state information. Link up/down flag (as provided by 516``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might 517be provided as well. In general, extended state describes reasons for why a port 518is down, or why it operates in some non-obvious mode. This request does not have 519any attributes. 520 521Request contents: 522 523 ==================================== ====== ========================== 524 ``ETHTOOL_A_LINKSTATE_HEADER`` nested request header 525 ==================================== ====== ========================== 526 527Kernel response contents: 528 529 ==================================== ====== ============================ 530 ``ETHTOOL_A_LINKSTATE_HEADER`` nested reply header 531 ``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down) 532 ``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index 533 ``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value 534 ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state 535 ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate 536 ``ETHTOOL_A_LINKSTATE_EXT_DOWN_CNT`` u32 count of link down events 537 ==================================== ====== ============================ 538 539For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns 540carrier flag provided by ``netif_carrier_ok()`` but there are drivers which 541define their own handler. 542 543``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are 544optional values. ethtool core can provide either both 545``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``, 546or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them. 547 548``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all 549devices supporting the request). 550 551 552Link extended states: 553 554 ================================================ ============================================ 555 ``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or 556 issues therein 557 558 ``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training 559 560 ``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer 561 or forward error correction sublayer 562 563 ``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues 564 565 ``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected 566 567 ``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable, 568 e.g., unsupported cable 569 570 ``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure 571 during reading or parsing the data 572 573 ``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm 574 575 ``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the 576 power required from cable or module 577 578 ``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated 579 580 ``ETHTOOL_LINK_EXT_STATE_MODULE`` Transceiver module issue 581 ================================================ ============================================ 582 583Link extended substates: 584 585 Autoneg substates: 586 587 =============================================================== ================================ 588 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down 589 590 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side 591 592 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed 593 594 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force 595 mode or there is no agreement of 596 speed 597 598 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes 599 in both sides are mismatched 600 601 ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator 602 =============================================================== ================================ 603 604 Link training substates: 605 606 =========================================================================== ==================== 607 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not 608 recognized, the 609 lock failed 610 611 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not 612 occur before 613 timeout 614 615 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not 616 send ready signal 617 after training 618 process 619 620 ``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not 621 ready yet 622 =========================================================================== ==================== 623 624 Link logical mismatch substates: 625 626 ================================================================ =============================== 627 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was 628 not locked in first phase - 629 block lock 630 631 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was 632 not locked in second phase - 633 alignment markers lock 634 635 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did 636 not get align status 637 638 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is 639 not locked 640 641 ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is 642 not locked 643 ================================================================ =============================== 644 645 Bad signal integrity substates: 646 647 ================================================================= ============================= 648 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical 649 errors 650 651 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to 652 operate the cable at a rate 653 that is not formally 654 supported, which led to 655 signal integrity issues 656 657 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_REFERENCE_CLOCK_LOST`` The external clock signal for 658 SerDes is too weak or 659 unavailable. 660 661 ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_ALOS`` The received signal for 662 SerDes is too weak because 663 analog loss of signal. 664 ================================================================= ============================= 665 666 Cable issue substates: 667 668 =================================================== ============================================ 669 ``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable 670 671 ``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure 672 =================================================== ============================================ 673 674 Transceiver module issue substates: 675 676 =================================================== ============================================ 677 ``ETHTOOL_LINK_EXT_SUBSTATE_MODULE_CMIS_NOT_READY`` The CMIS Module State Machine did not reach 678 the ModuleReady state. For example, if the 679 module is stuck at ModuleFault state 680 =================================================== ============================================ 681 682DEBUG_GET 683========= 684 685Requests debugging settings of a device. At the moment, only message mask is 686provided. 687 688Request contents: 689 690 ==================================== ====== ========================== 691 ``ETHTOOL_A_DEBUG_HEADER`` nested request header 692 ==================================== ====== ========================== 693 694Kernel response contents: 695 696 ==================================== ====== ========================== 697 ``ETHTOOL_A_DEBUG_HEADER`` nested reply header 698 ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask 699 ==================================== ====== ========================== 700 701The message mask (``ETHTOOL_A_DEBUG_MSGMASK``) is equal to message level as 702provided by ``ETHTOOL_GMSGLVL`` and set by ``ETHTOOL_SMSGLVL`` in ioctl 703interface. While it is called message level there for historical reasons, most 704drivers and almost all newer drivers use it as a mask of enabled message 705classes (represented by ``NETIF_MSG_*`` constants); therefore netlink 706interface follows its actual use in practice. 707 708``DEBUG_GET`` allows dump requests (kernel returns reply messages for all 709devices supporting the request). 710 711 712DEBUG_SET 713========= 714 715Set or update debugging settings of a device. At the moment, only message mask 716is supported. 717 718Request contents: 719 720 ==================================== ====== ========================== 721 ``ETHTOOL_A_DEBUG_HEADER`` nested request header 722 ``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask 723 ==================================== ====== ========================== 724 725``ETHTOOL_A_DEBUG_MSGMASK`` bit set allows setting or modifying mask of 726enabled debugging message types for the device. 727 728 729WOL_GET 730======= 731 732Query device wake-on-lan settings. Unlike most "GET" type requests, 733``ETHTOOL_MSG_WOL_GET`` requires (netns) ``CAP_NET_ADMIN`` privileges as it 734(potentially) provides SecureOn(tm) password which is confidential. 735 736Request contents: 737 738 ==================================== ====== ========================== 739 ``ETHTOOL_A_WOL_HEADER`` nested request header 740 ==================================== ====== ========================== 741 742Kernel response contents: 743 744 ==================================== ====== ========================== 745 ``ETHTOOL_A_WOL_HEADER`` nested reply header 746 ``ETHTOOL_A_WOL_MODES`` bitset mask of enabled WoL modes 747 ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password 748 ==================================== ====== ========================== 749 750In reply, ``ETHTOOL_A_WOL_MODES`` mask consists of modes supported by the 751device, value of modes which are enabled. ``ETHTOOL_A_WOL_SOPASS`` is only 752included in reply if ``WAKE_MAGICSECURE`` mode is supported. 753 754 755WOL_SET 756======= 757 758Set or update wake-on-lan settings. 759 760Request contents: 761 762 ==================================== ====== ========================== 763 ``ETHTOOL_A_WOL_HEADER`` nested request header 764 ``ETHTOOL_A_WOL_MODES`` bitset enabled WoL modes 765 ``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password 766 ==================================== ====== ========================== 767 768``ETHTOOL_A_WOL_SOPASS`` is only allowed for devices supporting 769``WAKE_MAGICSECURE`` mode. 770 771 772FEATURES_GET 773============ 774 775Gets netdev features like ``ETHTOOL_GFEATURES`` ioctl request. 776 777Request contents: 778 779 ==================================== ====== ========================== 780 ``ETHTOOL_A_FEATURES_HEADER`` nested request header 781 ==================================== ====== ========================== 782 783Kernel response contents: 784 785 ==================================== ====== ========================== 786 ``ETHTOOL_A_FEATURES_HEADER`` nested reply header 787 ``ETHTOOL_A_FEATURES_HW`` bitset dev->hw_features 788 ``ETHTOOL_A_FEATURES_WANTED`` bitset dev->wanted_features 789 ``ETHTOOL_A_FEATURES_ACTIVE`` bitset dev->features 790 ``ETHTOOL_A_FEATURES_NOCHANGE`` bitset NETIF_F_NEVER_CHANGE 791 ==================================== ====== ========================== 792 793Bitmaps in kernel response have the same meaning as bitmaps used in ioctl 794interference but attribute names are different (they are based on 795corresponding members of struct net_device). Legacy "flags" are not provided, 796if userspace needs them (most likely only ethtool for backward compatibility), 797it can calculate their values from related feature bits itself. 798ETHA_FEATURES_HW uses mask consisting of all features recognized by kernel (to 799provide all names when using verbose bitmap format), the other three use no 800mask (simple bit lists). 801 802 803FEATURES_SET 804============ 805 806Request to set netdev features like ``ETHTOOL_SFEATURES`` ioctl request. 807 808Request contents: 809 810 ==================================== ====== ========================== 811 ``ETHTOOL_A_FEATURES_HEADER`` nested request header 812 ``ETHTOOL_A_FEATURES_WANTED`` bitset requested features 813 ==================================== ====== ========================== 814 815Kernel response contents: 816 817 ==================================== ====== ========================== 818 ``ETHTOOL_A_FEATURES_HEADER`` nested reply header 819 ``ETHTOOL_A_FEATURES_WANTED`` bitset diff wanted vs. result 820 ``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active 821 ==================================== ====== ========================== 822 823Request contains only one bitset which can be either value/mask pair (request 824to change specific feature bits and leave the rest) or only a value (request 825to set all features to specified set). 826 827As request is subject to netdev_change_features() sanity checks, optional 828kernel reply (can be suppressed by ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request 829header) informs client about the actual result. ``ETHTOOL_A_FEATURES_WANTED`` 830reports the difference between client request and actual result: mask consists 831of bits which differ between requested features and result (dev->features 832after the operation), value consists of values of these bits in the request 833(i.e. negated values from resulting features). ``ETHTOOL_A_FEATURES_ACTIVE`` 834reports the difference between old and new dev->features: mask consists of 835bits which have changed, values are their values in new dev->features (after 836the operation). 837 838``ETHTOOL_MSG_FEATURES_NTF`` notification is sent not only if device features 839are modified using ``ETHTOOL_MSG_FEATURES_SET`` request or on of ethtool ioctl 840request but also each time features are modified with netdev_update_features() 841or netdev_change_features(). 842 843 844PRIVFLAGS_GET 845============= 846 847Gets private flags like ``ETHTOOL_GPFLAGS`` ioctl request. 848 849Request contents: 850 851 ==================================== ====== ========================== 852 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header 853 ==================================== ====== ========================== 854 855Kernel response contents: 856 857 ==================================== ====== ========================== 858 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested reply header 859 ``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags 860 ==================================== ====== ========================== 861 862``ETHTOOL_A_PRIVFLAGS_FLAGS`` is a bitset with values of device private flags. 863These flags are defined by driver, their number and names (and also meaning) 864are device dependent. For compact bitset format, names can be retrieved as 865``ETH_SS_PRIV_FLAGS`` string set. If verbose bitset format is requested, 866response uses all private flags supported by the device as mask so that client 867gets the full information without having to fetch the string set with names. 868 869 870PRIVFLAGS_SET 871============= 872 873Sets or modifies values of device private flags like ``ETHTOOL_SPFLAGS`` 874ioctl request. 875 876Request contents: 877 878 ==================================== ====== ========================== 879 ``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header 880 ``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags 881 ==================================== ====== ========================== 882 883``ETHTOOL_A_PRIVFLAGS_FLAGS`` can either set the whole set of private flags or 884modify only values of some of them. 885 886 887RINGS_GET 888========= 889 890Gets ring sizes like ``ETHTOOL_GRINGPARAM`` ioctl request. 891 892Request contents: 893 894 ==================================== ====== ========================== 895 ``ETHTOOL_A_RINGS_HEADER`` nested request header 896 ==================================== ====== ========================== 897 898Kernel response contents: 899 900 ======================================= ====== =========================== 901 ``ETHTOOL_A_RINGS_HEADER`` nested reply header 902 ``ETHTOOL_A_RINGS_RX_MAX`` u32 max size of RX ring 903 ``ETHTOOL_A_RINGS_RX_MINI_MAX`` u32 max size of RX mini ring 904 ``ETHTOOL_A_RINGS_RX_JUMBO_MAX`` u32 max size of RX jumbo ring 905 ``ETHTOOL_A_RINGS_TX_MAX`` u32 max size of TX ring 906 ``ETHTOOL_A_RINGS_RX`` u32 size of RX ring 907 ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring 908 ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring 909 ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring 910 ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring 911 ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split 912 ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE 913 ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode 914 ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode 915 ``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer 916 ``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN_MAX`` u32 max size of TX push buffer 917 ``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of 918 header / data split 919 ``ETHTOOL_A_RINGS_HDS_THRESH_MAX`` u32 max threshold of 920 header / data split 921 ======================================= ====== =========================== 922 923``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with 924page-flipping TCP zero-copy receive (``getsockopt(TCP_ZEROCOPY_RECEIVE)``). 925If enabled the device is configured to place frame headers and data into 926separate buffers. The device configuration must make it possible to receive 927full memory pages of data, for example because MTU is high enough or through 928HW-GRO. 929 930``ETHTOOL_A_RINGS_[RX|TX]_PUSH`` flag is used to enable descriptor fast 931path to send or receive packets. In ordinary path, driver fills descriptors in DRAM and 932notifies NIC hardware. In fast path, driver pushes descriptors to the device 933through MMIO writes, thus reducing the latency. However, enabling this feature 934may increase the CPU cost. Drivers may enforce additional per-packet 935eligibility checks (e.g. on packet size). 936 937``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` specifies the maximum number of bytes of a 938transmitted packet a driver can push directly to the underlying device 939('push' mode). Pushing some of the payload bytes to the device has the 940advantages of reducing latency for small packets by avoiding DMA mapping (same 941as ``ETHTOOL_A_RINGS_TX_PUSH`` parameter) as well as allowing the underlying 942device to process packet headers ahead of fetching its payload. 943This can help the device to make fast actions based on the packet's headers. 944This is similar to the "tx-copybreak" parameter, which copies the packet to a 945preallocated DMA memory area instead of mapping new memory. However, 946tx-push-buff parameter copies the packet directly to the device to allow the 947device to take faster actions on the packet. 948 949RINGS_SET 950========= 951 952Sets ring sizes like ``ETHTOOL_SRINGPARAM`` ioctl request. 953 954Request contents: 955 956 ==================================== ====== =========================== 957 ``ETHTOOL_A_RINGS_HEADER`` nested reply header 958 ``ETHTOOL_A_RINGS_RX`` u32 size of RX ring 959 ``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring 960 ``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring 961 ``ETHTOOL_A_RINGS_TX`` u32 size of TX ring 962 ``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring 963 ``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split 964 ``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE 965 ``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode 966 ``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode 967 ``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer 968 ``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of header / data split 969 ==================================== ====== =========================== 970 971Kernel checks that requested ring sizes do not exceed limits reported by 972driver. Driver may impose additional constraints and may not support all 973attributes. 974 975 976``ETHTOOL_A_RINGS_CQE_SIZE`` specifies the completion queue event size. 977Completion queue events (CQE) are the events posted by NIC to indicate the 978completion status of a packet when the packet is sent (like send success or 979error) or received (like pointers to packet fragments). The CQE size parameter 980enables to modify the CQE size other than default size if NIC supports it. 981A bigger CQE can have more receive buffer pointers, and in turn the NIC can 982transfer a bigger frame from wire. Based on the NIC hardware, the overall 983completion queue size can be adjusted in the driver if CQE size is modified. 984 985``ETHTOOL_A_RINGS_HDS_THRESH`` specifies the threshold value of 986header / data split feature. If a received packet size is larger than this 987threshold value, header and data will be split. 988 989CHANNELS_GET 990============ 991 992Gets channel counts like ``ETHTOOL_GCHANNELS`` ioctl request. 993 994Request contents: 995 996 ==================================== ====== ========================== 997 ``ETHTOOL_A_CHANNELS_HEADER`` nested request header 998 ==================================== ====== ========================== 999 1000Kernel response contents: 1001 1002 ===================================== ====== ========================== 1003 ``ETHTOOL_A_CHANNELS_HEADER`` nested reply header 1004 ``ETHTOOL_A_CHANNELS_RX_MAX`` u32 max receive channels 1005 ``ETHTOOL_A_CHANNELS_TX_MAX`` u32 max transmit channels 1006 ``ETHTOOL_A_CHANNELS_OTHER_MAX`` u32 max other channels 1007 ``ETHTOOL_A_CHANNELS_COMBINED_MAX`` u32 max combined channels 1008 ``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count 1009 ``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count 1010 ``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count 1011 ``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count 1012 ===================================== ====== ========================== 1013 1014 1015CHANNELS_SET 1016============ 1017 1018Sets channel counts like ``ETHTOOL_SCHANNELS`` ioctl request. 1019 1020Request contents: 1021 1022 ===================================== ====== ========================== 1023 ``ETHTOOL_A_CHANNELS_HEADER`` nested request header 1024 ``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count 1025 ``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count 1026 ``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count 1027 ``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count 1028 ===================================== ====== ========================== 1029 1030Kernel checks that requested channel counts do not exceed limits reported by 1031driver. Driver may impose additional constraints and may not support all 1032attributes. 1033 1034 1035COALESCE_GET 1036============ 1037 1038Gets coalescing parameters like ``ETHTOOL_GCOALESCE`` ioctl request. 1039 1040Request contents: 1041 1042 ==================================== ====== ========================== 1043 ``ETHTOOL_A_COALESCE_HEADER`` nested request header 1044 ==================================== ====== ========================== 1045 1046Kernel response contents: 1047 1048 =========================================== ====== ======================= 1049 ``ETHTOOL_A_COALESCE_HEADER`` nested reply header 1050 ``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx 1051 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx 1052 ``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ 1053 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ 1054 ``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx 1055 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx 1056 ``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ 1057 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ 1058 ``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update 1059 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce 1060 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce 1061 ``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate 1062 ``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx 1063 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx 1064 ``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx 1065 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx 1066 ``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate 1067 ``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx 1068 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx 1069 ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx 1070 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx 1071 ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval 1072 ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx 1073 ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx 1074 ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx 1075 ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx 1076 ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx 1077 ``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx 1078 ``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx 1079 =========================================== ====== ======================= 1080 1081Attributes are only included in reply if their value is not zero or the 1082corresponding bit in ``ethtool_ops::supported_coalesce_params`` is set (i.e. 1083they are declared as supported by driver). 1084 1085Timer reset mode (``ETHTOOL_A_COALESCE_USE_CQE_TX`` and 1086``ETHTOOL_A_COALESCE_USE_CQE_RX``) controls the interaction between packet 1087arrival and the various time based delay parameters. By default timers are 1088expected to limit the max delay between any packet arrival/departure and a 1089corresponding interrupt. In this mode timer should be started by packet 1090arrival (sometimes delivery of previous interrupt) and reset when interrupt 1091is delivered. 1092Setting the appropriate attribute to 1 will enable ``CQE`` mode, where 1093each packet event resets the timer. In this mode timer is used to force 1094the interrupt if queue goes idle, while busy queues depend on the packet 1095limit to trigger interrupts. 1096 1097Tx aggregation consists of copying frames into a contiguous buffer so that they 1098can be submitted as a single IO operation. ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` 1099describes the maximum size in bytes for the submitted buffer. 1100``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` describes the maximum number of frames 1101that can be aggregated into a single buffer. 1102``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` describes the amount of time in usecs, 1103counted since the first packet arrival in an aggregated block, after which the 1104block should be sent. 1105This feature is mainly of interest for specific USB devices which does not cope 1106well with frequent small-sized URBs transmissions. 1107 1108``ETHTOOL_A_COALESCE_RX_PROFILE`` and ``ETHTOOL_A_COALESCE_TX_PROFILE`` refer 1109to DIM parameters, see `Generic Network Dynamic Interrupt Moderation (Net DIM) 1110<https://www.kernel.org/doc/Documentation/networking/net_dim.rst>`_. 1111 1112COALESCE_SET 1113============ 1114 1115Sets coalescing parameters like ``ETHTOOL_SCOALESCE`` ioctl request. 1116 1117Request contents: 1118 1119 =========================================== ====== ======================= 1120 ``ETHTOOL_A_COALESCE_HEADER`` nested request header 1121 ``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx 1122 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx 1123 ``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ 1124 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ 1125 ``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx 1126 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx 1127 ``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ 1128 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ 1129 ``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update 1130 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce 1131 ``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce 1132 ``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate 1133 ``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx 1134 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx 1135 ``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx 1136 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx 1137 ``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate 1138 ``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx 1139 ``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx 1140 ``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx 1141 ``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx 1142 ``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval 1143 ``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx 1144 ``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx 1145 ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx 1146 ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx 1147 ``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx 1148 ``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx 1149 ``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx 1150 =========================================== ====== ======================= 1151 1152Request is rejected if it attributes declared as unsupported by driver (i.e. 1153such that the corresponding bit in ``ethtool_ops::supported_coalesce_params`` 1154is not set), regardless of their values. Driver may impose additional 1155constraints on coalescing parameters and their values. 1156 1157Compared to requests issued via the ``ioctl()`` netlink version of this request 1158will try harder to make sure that values specified by the user have been applied 1159and may call the driver twice. 1160 1161 1162PAUSE_GET 1163========= 1164 1165Gets pause frame settings like ``ETHTOOL_GPAUSEPARAM`` ioctl request. 1166 1167Request contents: 1168 1169 ===================================== ====== ========================== 1170 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1171 ``ETHTOOL_A_PAUSE_STATS_SRC`` u32 source of statistics 1172 ===================================== ====== ========================== 1173 1174``ETHTOOL_A_PAUSE_STATS_SRC`` is optional. It takes values from: 1175 1176.. kernel-doc:: include/uapi/linux/ethtool.h 1177 :identifiers: ethtool_mac_stats_src 1178 1179If absent from the request, stats will be provided with 1180an ``ETHTOOL_A_PAUSE_STATS_SRC`` attribute in the response equal to 1181``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. 1182 1183Kernel response contents: 1184 1185 ===================================== ====== ========================== 1186 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1187 ``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation 1188 ``ETHTOOL_A_PAUSE_RX`` bool receive pause frames 1189 ``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames 1190 ``ETHTOOL_A_PAUSE_STATS`` nested pause statistics 1191 ===================================== ====== ========================== 1192 1193``ETHTOOL_A_PAUSE_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set 1194in ``ETHTOOL_A_HEADER_FLAGS``. 1195It will be empty if driver did not report any statistics. Drivers fill in 1196the statistics in the following structure: 1197 1198.. kernel-doc:: include/linux/ethtool.h 1199 :identifiers: ethtool_pause_stats 1200 1201Each member has a corresponding attribute defined. 1202 1203PAUSE_SET 1204========= 1205 1206Sets pause parameters like ``ETHTOOL_GPAUSEPARAM`` ioctl request. 1207 1208Request contents: 1209 1210 ===================================== ====== ========================== 1211 ``ETHTOOL_A_PAUSE_HEADER`` nested request header 1212 ``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation 1213 ``ETHTOOL_A_PAUSE_RX`` bool receive pause frames 1214 ``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames 1215 ===================================== ====== ========================== 1216 1217 1218EEE_GET 1219======= 1220 1221Gets Energy Efficient Ethernet settings like ``ETHTOOL_GEEE`` ioctl request. 1222 1223Request contents: 1224 1225 ===================================== ====== ========================== 1226 ``ETHTOOL_A_EEE_HEADER`` nested request header 1227 ===================================== ====== ========================== 1228 1229Kernel response contents: 1230 1231 ===================================== ====== ========================== 1232 ``ETHTOOL_A_EEE_HEADER`` nested request header 1233 ``ETHTOOL_A_EEE_MODES_OURS`` bool supported/advertised modes 1234 ``ETHTOOL_A_EEE_MODES_PEER`` bool peer advertised link modes 1235 ``ETHTOOL_A_EEE_ACTIVE`` bool EEE is actively used 1236 ``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled 1237 ``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled 1238 ``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us) 1239 ===================================== ====== ========================== 1240 1241In ``ETHTOOL_A_EEE_MODES_OURS``, mask consists of link modes for which EEE is 1242enabled, value of link modes for which EEE is advertised. Link modes for which 1243peer advertises EEE are listed in ``ETHTOOL_A_EEE_MODES_PEER`` (no mask). The 1244netlink interface allows reporting EEE status for all link modes but only 1245first 32 are provided by the ``ethtool_ops`` callback. 1246 1247 1248EEE_SET 1249======= 1250 1251Sets Energy Efficient Ethernet parameters like ``ETHTOOL_SEEE`` ioctl request. 1252 1253Request contents: 1254 1255 ===================================== ====== ========================== 1256 ``ETHTOOL_A_EEE_HEADER`` nested request header 1257 ``ETHTOOL_A_EEE_MODES_OURS`` bool advertised modes 1258 ``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled 1259 ``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled 1260 ``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us) 1261 ===================================== ====== ========================== 1262 1263``ETHTOOL_A_EEE_MODES_OURS`` is used to either list link modes to advertise 1264EEE for (if there is no mask) or specify changes to the list (if there is 1265a mask). The netlink interface allows reporting EEE status for all link modes 1266but only first 32 can be set at the moment as that is what the ``ethtool_ops`` 1267callback supports. 1268 1269 1270TSINFO_GET 1271========== 1272 1273Gets timestamping information like ``ETHTOOL_GET_TS_INFO`` ioctl request. 1274 1275Request contents: 1276 1277 ======================================== ====== ============================ 1278 ``ETHTOOL_A_TSINFO_HEADER`` nested request header 1279 ``ETHTOOL_A_TSINFO_HWTSTAMP_PROVIDER`` nested PTP hw clock provider 1280 ======================================== ====== ============================ 1281 1282Kernel response contents: 1283 1284 ===================================== ====== ========================== 1285 ``ETHTOOL_A_TSINFO_HEADER`` nested request header 1286 ``ETHTOOL_A_TSINFO_TIMESTAMPING`` bitset SO_TIMESTAMPING flags 1287 ``ETHTOOL_A_TSINFO_TX_TYPES`` bitset supported Tx types 1288 ``ETHTOOL_A_TSINFO_RX_FILTERS`` bitset supported Rx filters 1289 ``ETHTOOL_A_TSINFO_PHC_INDEX`` u32 PTP hw clock index 1290 ``ETHTOOL_A_TSINFO_STATS`` nested HW timestamping statistics 1291 ===================================== ====== ========================== 1292 1293``ETHTOOL_A_TSINFO_PHC_INDEX`` is absent if there is no associated PHC (there 1294is no special value for this case). The bitset attributes are omitted if they 1295would be empty (no bit set). 1296 1297Additional hardware timestamping statistics response contents: 1298 1299 ================================================== ====== ===================== 1300 ``ETHTOOL_A_TS_STAT_TX_PKTS`` uint Packets with Tx 1301 HW timestamps 1302 ``ETHTOOL_A_TS_STAT_TX_LOST`` uint Tx HW timestamp 1303 not arrived count 1304 ``ETHTOOL_A_TS_STAT_TX_ERR`` uint HW error request 1305 Tx timestamp count 1306 ``ETHTOOL_A_TS_STAT_TX_ONESTEP_PKTS_UNCONFIRMED`` uint Packets with one-step 1307 HW TX timestamps with 1308 unconfirmed delivery 1309 ================================================== ====== ===================== 1310 1311CABLE_TEST 1312========== 1313 1314Start a cable test. 1315 1316Request contents: 1317 1318 ==================================== ====== ========================== 1319 ``ETHTOOL_A_CABLE_TEST_HEADER`` nested request header 1320 ==================================== ====== ========================== 1321 1322Notification contents: 1323 1324An Ethernet cable typically contains 1, 2 or 4 pairs. The length of 1325the pair can only be measured when there is a fault in the pair and 1326hence a reflection. Information about the fault may not be available, 1327depending on the specific hardware. Hence the contents of the notify 1328message are mostly optional. The attributes can be repeated an 1329arbitrary number of times, in an arbitrary order, for an arbitrary 1330number of pairs. 1331 1332The example shows the notification sent when the test is completed for 1333a T2 cable, i.e. two pairs. One pair is OK and hence has no length 1334information. The second pair has a fault and does have length 1335information. 1336 1337 +---------------------------------------------+--------+---------------------+ 1338 | ``ETHTOOL_A_CABLE_TEST_HEADER`` | nested | reply header | 1339 +---------------------------------------------+--------+---------------------+ 1340 | ``ETHTOOL_A_CABLE_TEST_STATUS`` | u8 | completed | 1341 +---------------------------------------------+--------+---------------------+ 1342 | ``ETHTOOL_A_CABLE_TEST_NTF_NEST`` | nested | all the results | 1343 +-+-------------------------------------------+--------+---------------------+ 1344 | | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test result | 1345 +-+-+-----------------------------------------+--------+---------------------+ 1346 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1347 +-+-+-----------------------------------------+--------+---------------------+ 1348 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code | 1349 +-+-+-----------------------------------------+--------+---------------------+ 1350 | | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test results | 1351 +-+-+-----------------------------------------+--------+---------------------+ 1352 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1353 +-+-+-----------------------------------------+--------+---------------------+ 1354 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code | 1355 +-+-+-----------------------------------------+--------+---------------------+ 1356 | | | ``ETHTOOL_A_CABLE_RESULT_SRC`` | u32 | information source | 1357 +-+-+-----------------------------------------+--------+---------------------+ 1358 | | ``ETHTOOL_A_CABLE_NEST_FAULT_LENGTH`` | nested | cable length | 1359 +-+-+-----------------------------------------+--------+---------------------+ 1360 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR`` | u8 | pair number | 1361 +-+-+-----------------------------------------+--------+---------------------+ 1362 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_CM`` | u32 | length in cm | 1363 +-+-+-----------------------------------------+--------+---------------------+ 1364 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_SRC`` | u32 | information source | 1365 +-+-+-----------------------------------------+--------+---------------------+ 1366 1367 1368CABLE_TEST TDR 1369============== 1370 1371Start a cable test and report raw TDR data 1372 1373Request contents: 1374 1375 +--------------------------------------------+--------+-----------------------+ 1376 | ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header | 1377 +--------------------------------------------+--------+-----------------------+ 1378 | ``ETHTOOL_A_CABLE_TEST_TDR_CFG`` | nested | test configuration | 1379 +-+------------------------------------------+--------+-----------------------+ 1380 | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | first data distance | 1381 +-+-+----------------------------------------+--------+-----------------------+ 1382 | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | last data distance | 1383 +-+-+----------------------------------------+--------+-----------------------+ 1384 | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step | 1385 +-+-+----------------------------------------+--------+-----------------------+ 1386 | | ``ETHTOOL_A_CABLE_TEST_TDR_CFG_PAIR`` | u8 | pair to test | 1387 +-+-+----------------------------------------+--------+-----------------------+ 1388 1389The ETHTOOL_A_CABLE_TEST_TDR_CFG is optional, as well as all members 1390of the nest. All distances are expressed in centimeters. The PHY takes 1391the distances as a guide, and rounds to the nearest distance it 1392actually supports. If a pair is passed, only that one pair will be 1393tested. Otherwise all pairs are tested. 1394 1395Notification contents: 1396 1397Raw TDR data is gathered by sending a pulse down the cable and 1398recording the amplitude of the reflected pulse for a given distance. 1399 1400It can take a number of seconds to collect TDR data, especial if the 1401full 100 meters is probed at 1 meter intervals. When the test is 1402started a notification will be sent containing just 1403ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value 1404ETHTOOL_A_CABLE_TEST_NTF_STATUS_STARTED. 1405 1406When the test has completed a second notification will be sent 1407containing ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value 1408ETHTOOL_A_CABLE_TEST_NTF_STATUS_COMPLETED and the TDR data. 1409 1410The message may optionally contain the amplitude of the pulse send 1411down the cable. This is measured in mV. A reflection should not be 1412bigger than transmitted pulse. 1413 1414Before the raw TDR data should be an ETHTOOL_A_CABLE_TDR_NEST_STEP 1415nest containing information about the distance along the cable for the 1416first reading, the last reading, and the step between each 1417reading. Distances are measured in centimeters. These should be the 1418exact values the PHY used. These may be different to what the user 1419requested, if the native measurement resolution is greater than 1 cm. 1420 1421For each step along the cable, a ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE is 1422used to report the amplitude of the reflection for a given pair. 1423 1424 +---------------------------------------------+--------+----------------------+ 1425 | ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header | 1426 +---------------------------------------------+--------+----------------------+ 1427 | ``ETHTOOL_A_CABLE_TEST_TDR_STATUS`` | u8 | completed | 1428 +---------------------------------------------+--------+----------------------+ 1429 | ``ETHTOOL_A_CABLE_TEST_TDR_NTF_NEST`` | nested | all the results | 1430 +-+-------------------------------------------+--------+----------------------+ 1431 | | ``ETHTOOL_A_CABLE_TDR_NEST_PULSE`` | nested | TX Pulse amplitude | 1432 +-+-+-----------------------------------------+--------+----------------------+ 1433 | | | ``ETHTOOL_A_CABLE_PULSE_mV`` | s16 | Pulse amplitude | 1434 +-+-+-----------------------------------------+--------+----------------------+ 1435 | | ``ETHTOOL_A_CABLE_NEST_STEP`` | nested | TDR step info | 1436 +-+-+-----------------------------------------+--------+----------------------+ 1437 | | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | First data distance | 1438 +-+-+-----------------------------------------+--------+----------------------+ 1439 | | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | Last data distance | 1440 +-+-+-----------------------------------------+--------+----------------------+ 1441 | | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step| 1442 +-+-+-----------------------------------------+--------+----------------------+ 1443 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1444 +-+-+-----------------------------------------+--------+----------------------+ 1445 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1446 +-+-+-----------------------------------------+--------+----------------------+ 1447 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1448 +-+-+-----------------------------------------+--------+----------------------+ 1449 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1450 +-+-+-----------------------------------------+--------+----------------------+ 1451 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1452 +-+-+-----------------------------------------+--------+----------------------+ 1453 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1454 +-+-+-----------------------------------------+--------+----------------------+ 1455 | | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude | 1456 +-+-+-----------------------------------------+--------+----------------------+ 1457 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number | 1458 +-+-+-----------------------------------------+--------+----------------------+ 1459 | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | 1460 +-+-+-----------------------------------------+--------+----------------------+ 1461 1462TUNNEL_INFO 1463=========== 1464 1465Gets information about the tunnel state NIC is aware of. 1466 1467Request contents: 1468 1469 ===================================== ====== ========================== 1470 ``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header 1471 ===================================== ====== ========================== 1472 1473Kernel response contents: 1474 1475 +---------------------------------------------+--------+---------------------+ 1476 | ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header | 1477 +---------------------------------------------+--------+---------------------+ 1478 | ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables | 1479 +-+-------------------------------------------+--------+---------------------+ 1480 | | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table | 1481 +-+-+-----------------------------------------+--------+---------------------+ 1482 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the | 1483 | | | | | table | 1484 +-+-+-----------------------------------------+--------+---------------------+ 1485 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which | 1486 | | | | | table can hold | 1487 +-+-+-----------------------------------------+--------+---------------------+ 1488 | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port | 1489 +-+-+-+---------------------------------------+--------+---------------------+ 1490 | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port | 1491 +-+-+-+---------------------------------------+--------+---------------------+ 1492 | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type | 1493 +-+-+-+---------------------------------------+--------+---------------------+ 1494 1495For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that 1496the table contains static entries, hard-coded by the NIC. 1497 1498FEC_GET 1499======= 1500 1501Gets FEC configuration and state like ``ETHTOOL_GFECPARAM`` ioctl request. 1502 1503Request contents: 1504 1505 ===================================== ====== ========================== 1506 ``ETHTOOL_A_FEC_HEADER`` nested request header 1507 ===================================== ====== ========================== 1508 1509Kernel response contents: 1510 1511 ===================================== ====== ========================== 1512 ``ETHTOOL_A_FEC_HEADER`` nested request header 1513 ``ETHTOOL_A_FEC_MODES`` bitset configured modes 1514 ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection 1515 ``ETHTOOL_A_FEC_ACTIVE`` u32 index of active FEC mode 1516 ``ETHTOOL_A_FEC_STATS`` nested FEC statistics 1517 ===================================== ====== ========================== 1518 1519``ETHTOOL_A_FEC_ACTIVE`` is the bit index of the FEC link mode currently 1520active on the interface. This attribute may not be present if device does 1521not support FEC. 1522 1523``ETHTOOL_A_FEC_MODES`` and ``ETHTOOL_A_FEC_AUTO`` are only meaningful when 1524autonegotiation is disabled. If ``ETHTOOL_A_FEC_AUTO`` is non-zero driver will 1525select the FEC mode automatically based on the parameters of the SFP module. 1526This is equivalent to the ``ETHTOOL_FEC_AUTO`` bit of the ioctl interface. 1527``ETHTOOL_A_FEC_MODES`` carry the current FEC configuration using link mode 1528bits (rather than old ``ETHTOOL_FEC_*`` bits). 1529 1530``ETHTOOL_A_FEC_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in 1531``ETHTOOL_A_HEADER_FLAGS``. 1532Each attribute carries an array of 64bit statistics. First entry in the array 1533contains the total number of events on the port, while the following entries 1534are counters corresponding to lanes/PCS instances. The number of entries in 1535the array will be: 1536 1537+--------------+---------------------------------------------+ 1538| `0` | device does not support FEC statistics | 1539+--------------+---------------------------------------------+ 1540| `1` | device does not support per-lane break down | 1541+--------------+---------------------------------------------+ 1542| `1 + #lanes` | device has full support for FEC stats | 1543+--------------+---------------------------------------------+ 1544 1545Drivers fill in the statistics in the following structure: 1546 1547.. kernel-doc:: include/linux/ethtool.h 1548 :identifiers: ethtool_fec_stats 1549 1550Statistics may have FEC bins histogram attribute ``ETHTOOL_A_FEC_STAT_HIST`` 1551as defined in IEEE 802.3ck-2022 and 802.3df-2024. Nested attributes will have 1552the range of FEC errors in the bin (inclusive) and the amount of error events 1553in the bin. 1554 1555FEC_SET 1556======= 1557 1558Sets FEC parameters like ``ETHTOOL_SFECPARAM`` ioctl request. 1559 1560Request contents: 1561 1562 ===================================== ====== ========================== 1563 ``ETHTOOL_A_FEC_HEADER`` nested request header 1564 ``ETHTOOL_A_FEC_MODES`` bitset configured modes 1565 ``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection 1566 ===================================== ====== ========================== 1567 1568``FEC_SET`` is only meaningful when autonegotiation is disabled. Otherwise 1569FEC mode is selected as part of autonegotiation. 1570 1571``ETHTOOL_A_FEC_MODES`` selects which FEC mode should be used. It's recommended 1572to set only one bit, if multiple bits are set driver may choose between them 1573in an implementation specific way. 1574 1575``ETHTOOL_A_FEC_AUTO`` requests the driver to choose FEC mode based on SFP 1576module parameters. This does not mean autonegotiation. 1577 1578MODULE_EEPROM_GET 1579================= 1580 1581Fetch module EEPROM data dump. 1582This interface is designed to allow dumps of at most 1/2 page at once. This 1583means only dumps of 128 (or less) bytes are allowed, without crossing half page 1584boundary located at offset 128. For pages other than 0 only high 128 bytes are 1585accessible. 1586 1587Request contents: 1588 1589 ======================================= ====== ========================== 1590 ``ETHTOOL_A_MODULE_EEPROM_HEADER`` nested request header 1591 ``ETHTOOL_A_MODULE_EEPROM_OFFSET`` u32 offset within a page 1592 ``ETHTOOL_A_MODULE_EEPROM_LENGTH`` u32 amount of bytes to read 1593 ``ETHTOOL_A_MODULE_EEPROM_PAGE`` u8 page number 1594 ``ETHTOOL_A_MODULE_EEPROM_BANK`` u8 bank number 1595 ``ETHTOOL_A_MODULE_EEPROM_I2C_ADDRESS`` u8 page I2C address 1596 ======================================= ====== ========================== 1597 1598If ``ETHTOOL_A_MODULE_EEPROM_BANK`` is not specified, bank 0 is assumed. 1599 1600Kernel response contents: 1601 1602 +---------------------------------------------+--------+---------------------+ 1603 | ``ETHTOOL_A_MODULE_EEPROM_HEADER`` | nested | reply header | 1604 +---------------------------------------------+--------+---------------------+ 1605 | ``ETHTOOL_A_MODULE_EEPROM_DATA`` | binary | array of bytes from | 1606 | | | module EEPROM | 1607 +---------------------------------------------+--------+---------------------+ 1608 1609``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of 1610bytes driver actually read. 1611 1612STATS_GET 1613========= 1614 1615Get standard statistics for the interface. Note that this is not 1616a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined 1617stats. 1618 1619Request contents: 1620 1621 ======================================= ====== ========================== 1622 ``ETHTOOL_A_STATS_HEADER`` nested request header 1623 ``ETHTOOL_A_STATS_SRC`` u32 source of statistics 1624 ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats 1625 ======================================= ====== ========================== 1626 1627Kernel response contents: 1628 1629 +-----------------------------------+--------+--------------------------------+ 1630 | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header | 1631 +-----------------------------------+--------+--------------------------------+ 1632 | ``ETHTOOL_A_STATS_SRC`` | u32 | source of statistics | 1633 +-----------------------------------+--------+--------------------------------+ 1634 | ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats | 1635 +-+---------------------------------+--------+--------------------------------+ 1636 | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` | 1637 +-+---------------------------------+--------+--------------------------------+ 1638 | | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names | 1639 +-+---------------------------------+--------+--------------------------------+ 1640 | | ``ETHTOOL_A_STATS_GRP_STAT`` | nested | nest containing a statistic | 1641 +-+---------------------------------+--------+--------------------------------+ 1642 | | ``ETHTOOL_A_STATS_GRP_HIST_RX`` | nested | histogram statistic (Rx) | 1643 +-+---------------------------------+--------+--------------------------------+ 1644 | | ``ETHTOOL_A_STATS_GRP_HIST_TX`` | nested | histogram statistic (Tx) | 1645 +-+---------------------------------+--------+--------------------------------+ 1646 1647Users specify which groups of statistics they are requesting via 1648the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are: 1649 1650 ====================== ======== =============================================== 1651 ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*) 1652 ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*) 1653 ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*) 1654 ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics 1655 ETHTOOL_STATS_PHY phy Additional PHY statistics, not defined by IEEE 1656 ====================== ======== =============================================== 1657 1658Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply. 1659``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains. 1660``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of 1661the statistics in the group, if available. 1662 1663Statistics are added to the ``ETHTOOL_A_STATS_GRP`` nest under 1664``ETHTOOL_A_STATS_GRP_STAT``. ``ETHTOOL_A_STATS_GRP_STAT`` should contain 1665single 8 byte (u64) attribute inside - the type of that attribute is 1666the statistic ID and the value is the value of the statistic. 1667Each group has its own interpretation of statistic IDs. 1668Attribute IDs correspond to strings from the string set identified 1669by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics (such as RMON histogram 1670entries) are also listed inside ``ETHTOOL_A_STATS_GRP`` and do not have 1671a string defined in the string set. 1672 1673RMON "histogram" counters count number of packets within given size range. 1674Because RFC does not specify the ranges beyond the standard 1518 MTU devices 1675differ in definition of buckets. For this reason the definition of packet ranges 1676is left to each driver. 1677 1678``ETHTOOL_A_STATS_GRP_HIST_RX`` and ``ETHTOOL_A_STATS_GRP_HIST_TX`` nests 1679contain the following attributes: 1680 1681 ================================= ====== =================================== 1682 ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket 1683 ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket 1684 ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter 1685 ================================= ====== =================================== 1686 1687Low and high bounds are inclusive, for example: 1688 1689 ============================= ==== ==== 1690 RFC statistic low high 1691 ============================= ==== ==== 1692 etherStatsPkts64Octets 0 64 1693 etherStatsPkts512to1023Octets 512 1023 1694 ============================= ==== ==== 1695 1696``ETHTOOL_A_STATS_SRC`` is optional. Similar to ``PAUSE_GET``, it takes values 1697from ``enum ethtool_mac_stats_src``. If absent from the request, stats will be 1698provided with an ``ETHTOOL_A_STATS_SRC`` attribute in the response equal to 1699``ETHTOOL_MAC_STATS_SRC_AGGREGATE``. 1700 1701PHC_VCLOCKS_GET 1702=============== 1703 1704Query device PHC virtual clocks information. 1705 1706Request contents: 1707 1708 ==================================== ====== ========================== 1709 ``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested request header 1710 ==================================== ====== ========================== 1711 1712Kernel response contents: 1713 1714 ==================================== ====== ========================== 1715 ``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested reply header 1716 ``ETHTOOL_A_PHC_VCLOCKS_NUM`` u32 PHC virtual clocks number 1717 ``ETHTOOL_A_PHC_VCLOCKS_INDEX`` s32 PHC index array 1718 ==================================== ====== ========================== 1719 1720MODULE_GET 1721========== 1722 1723Gets transceiver module parameters. 1724 1725Request contents: 1726 1727 ===================================== ====== ========================== 1728 ``ETHTOOL_A_MODULE_HEADER`` nested request header 1729 ===================================== ====== ========================== 1730 1731Kernel response contents: 1732 1733 ====================================== ====== ========================== 1734 ``ETHTOOL_A_MODULE_HEADER`` nested reply header 1735 ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy 1736 ``ETHTOOL_A_MODULE_POWER_MODE`` u8 operational power mode 1737 ====================================== ====== ========================== 1738 1739The optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute encodes the 1740transceiver module power mode policy enforced by the host. The default policy 1741is driver-dependent, but "auto" is the recommended default and it should be 1742implemented by new drivers and drivers where conformance to a legacy behavior 1743is not critical. 1744 1745The optional ``ETHTHOOL_A_MODULE_POWER_MODE`` attribute encodes the operational 1746power mode policy of the transceiver module. It is only reported when a module 1747is plugged-in. Possible values are: 1748 1749.. kernel-doc:: include/uapi/linux/ethtool.h 1750 :identifiers: ethtool_module_power_mode 1751 1752MODULE_SET 1753========== 1754 1755Sets transceiver module parameters. 1756 1757Request contents: 1758 1759 ====================================== ====== ========================== 1760 ``ETHTOOL_A_MODULE_HEADER`` nested request header 1761 ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy 1762 ====================================== ====== ========================== 1763 1764When set, the optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute is used 1765to set the transceiver module power policy enforced by the host. Possible 1766values are: 1767 1768.. kernel-doc:: include/uapi/linux/ethtool.h 1769 :identifiers: ethtool_module_power_mode_policy 1770 1771For SFF-8636 modules, low power mode is forced by the host according to table 17726-10 in revision 2.10a of the specification. 1773 1774For CMIS modules, low power mode is forced by the host according to table 6-12 1775in revision 5.0 of the specification. 1776 1777PSE_GET 1778======= 1779 1780Gets PSE attributes. 1781 1782Request contents: 1783 1784 ===================================== ====== ========================== 1785 ``ETHTOOL_A_PSE_HEADER`` nested request header 1786 ===================================== ====== ========================== 1787 1788Kernel response contents: 1789 1790 ========================================== ====== ============================= 1791 ``ETHTOOL_A_PSE_HEADER`` nested reply header 1792 ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` u32 Operational state of the PoDL 1793 PSE functions 1794 ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` u32 power detection status of the 1795 PoDL PSE. 1796 ``ETHTOOL_A_C33_PSE_ADMIN_STATE`` u32 Operational state of the PoE 1797 PSE functions. 1798 ``ETHTOOL_A_C33_PSE_PW_D_STATUS`` u32 power detection status of the 1799 PoE PSE. 1800 ``ETHTOOL_A_C33_PSE_PW_CLASS`` u32 power class of the PoE PSE. 1801 ``ETHTOOL_A_C33_PSE_ACTUAL_PW`` u32 actual power drawn on the 1802 PoE PSE. 1803 ``ETHTOOL_A_C33_PSE_EXT_STATE`` u32 power extended state of the 1804 PoE PSE. 1805 ``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` u32 power extended substatus of 1806 the PoE PSE. 1807 ``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` u32 currently configured power 1808 limit of the PoE PSE. 1809 ``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested Supported power limit 1810 configuration ranges. 1811 ``ETHTOOL_A_PSE_PW_D_ID`` u32 Index of the PSE power domain 1812 ``ETHTOOL_A_PSE_PRIO_MAX`` u32 Priority maximum configurable 1813 on the PoE PSE 1814 ``ETHTOOL_A_PSE_PRIO`` u32 Priority of the PoE PSE 1815 currently configured 1816 ========================================== ====== ============================= 1817 1818When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` attribute identifies 1819the operational state of the PoDL PSE functions. The operational state of the 1820PSE function can be changed using the ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` 1821action. This attribute corresponds to ``IEEE 802.3-2018`` 30.15.1.1.2 1822aPoDLPSEAdminState. Possible values are: 1823 1824.. kernel-doc:: include/uapi/linux/ethtool.h 1825 :identifiers: ethtool_podl_pse_admin_state 1826 1827The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_STATE`` implementing 1828``IEEE 802.3-2022`` 30.9.1.1.2 aPSEAdminState. 1829 1830.. kernel-doc:: include/uapi/linux/ethtool.h 1831 :identifiers: ethtool_c33_pse_admin_state 1832 1833When set, the optional ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` attribute identifies 1834the power detection status of the PoDL PSE. The status depend on internal PSE 1835state machine and automatic PD classification support. This attribute 1836corresponds to ``IEEE 802.3-2018`` 30.15.1.1.3 aPoDLPSEPowerDetectionStatus. 1837Possible values are: 1838 1839.. kernel-doc:: include/uapi/linux/ethtool.h 1840 :identifiers: ethtool_podl_pse_pw_d_status 1841 1842The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_PW_D_STATUS`` implementing 1843``IEEE 802.3-2022`` 30.9.1.1.5 aPSEPowerDetectionStatus. 1844 1845.. kernel-doc:: include/uapi/linux/ethtool.h 1846 :identifiers: ethtool_c33_pse_pw_d_status 1847 1848When set, the optional ``ETHTOOL_A_C33_PSE_PW_CLASS`` attribute identifies 1849the power class of the C33 PSE. It depends on the class negotiated between 1850the PSE and the PD. This attribute corresponds to ``IEEE 802.3-2022`` 185130.9.1.1.8 aPSEPowerClassification. 1852 1853When set, the optional ``ETHTOOL_A_C33_PSE_ACTUAL_PW`` attribute identifies 1854the actual power drawn by the C33 PSE. This attribute corresponds to 1855``IEEE 802.3-2022`` 30.9.1.1.23 aPSEActualPower. Actual power is reported 1856in mW. 1857 1858When set, the optional ``ETHTOOL_A_C33_PSE_EXT_STATE`` attribute identifies 1859the extended error state of the C33 PSE. Possible values are: 1860 1861.. kernel-doc:: include/uapi/linux/ethtool.h 1862 :identifiers: ethtool_c33_pse_ext_state 1863 1864When set, the optional ``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` attribute identifies 1865the extended error state of the C33 PSE. Possible values are: 1866Possible values are: 1867 1868.. kernel-doc:: include/uapi/linux/ethtool.h 1869 :identifiers: ethtool_c33_pse_ext_substate_class_num_events 1870 ethtool_c33_pse_ext_substate_error_condition 1871 ethtool_c33_pse_ext_substate_mr_pse_enable 1872 ethtool_c33_pse_ext_substate_option_detect_ted 1873 ethtool_c33_pse_ext_substate_option_vport_lim 1874 ethtool_c33_pse_ext_substate_ovld_detected 1875 ethtool_c33_pse_ext_substate_pd_dll_power_type 1876 ethtool_c33_pse_ext_substate_power_not_available 1877 ethtool_c33_pse_ext_substate_short_detected 1878 1879When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` attribute 1880identifies the C33 PSE power limit in mW. 1881 1882When set the optional ``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested attribute 1883identifies the C33 PSE power limit ranges through 1884``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MIN`` and 1885``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MAX``. 1886If the controller works with fixed classes, the min and max values will be 1887equal. 1888 1889The ``ETHTOOL_A_PSE_PW_D_ID`` attribute identifies the index of PSE power 1890domain. 1891 1892When set, the optional ``ETHTOOL_A_PSE_PRIO_MAX`` attribute identifies 1893the PSE maximum priority value. 1894When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to 1895identifies the currently configured PSE priority. 1896For a description of PSE priority attributes, see ``PSE_SET``. 1897 1898PSE_SET 1899======= 1900 1901Sets PSE parameters. 1902 1903Request contents: 1904 1905 ====================================== ====== ============================= 1906 ``ETHTOOL_A_PSE_HEADER`` nested request header 1907 ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` u32 Control PoDL PSE Admin state 1908 ``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` u32 Control PSE Admin state 1909 ``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` u32 Control PoE PSE available 1910 power limit 1911 ``ETHTOOL_A_PSE_PRIO`` u32 Control priority of the 1912 PoE PSE 1913 ====================================== ====== ============================= 1914 1915When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` attribute is used 1916to control PoDL PSE Admin functions. This option implements 1917``IEEE 802.3-2018`` 30.15.1.2.1 acPoDLPSEAdminControl. See 1918``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` for supported values. 1919 1920The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` implementing 1921``IEEE 802.3-2022`` 30.9.1.2.1 acPSEAdminControl. 1922 1923When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` attribute is 1924used to control the available power value limit for C33 PSE in milliwatts. 1925This attribute corresponds to the `pse_available_power` variable described in 1926``IEEE 802.3-2022`` 33.2.4.4 Variables and `pse_avail_pwr` in 145.2.5.4 1927Variables, which are described in power classes. 1928 1929It was decided to use milliwatts for this interface to unify it with other 1930power monitoring interfaces, which also use milliwatts, and to align with 1931various existing products that document power consumption in watts rather than 1932classes. If power limit configuration based on classes is needed, the 1933conversion can be done in user space, for example by ethtool. 1934 1935When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to 1936control the PSE priority. Allowed priority value are between zero and 1937the value of ``ETHTOOL_A_PSE_PRIO_MAX`` attribute. 1938 1939A lower value indicates a higher priority, meaning that a priority value 1940of 0 corresponds to the highest port priority. 1941Port priority serves two functions: 1942 1943 - Power-up Order: After a reset, ports are powered up in order of their 1944 priority from highest to lowest. Ports with higher priority 1945 (lower values) power up first. 1946 - Shutdown Order: When the power budget is exceeded, ports with lower 1947 priority (higher values) are turned off first. 1948 1949PSE_NTF 1950======= 1951 1952Notify PSE events. 1953 1954Notification contents: 1955 1956 =============================== ====== ======================== 1957 ``ETHTOOL_A_PSE_HEADER`` nested request header 1958 ``ETHTOOL_A_PSE_EVENTS`` bitset PSE events 1959 =============================== ====== ======================== 1960 1961When set, the optional ``ETHTOOL_A_PSE_EVENTS`` attribute identifies the 1962PSE events. 1963 1964.. kernel-doc:: include/uapi/linux/ethtool_netlink_generated.h 1965 :identifiers: ethtool_pse_event 1966 1967RSS_GET 1968======= 1969 1970Get indirection table, hash key and hash function info associated with a 1971RSS context of an interface similar to ``ETHTOOL_GRSSH`` ioctl request. 1972 1973Request contents: 1974 1975===================================== ====== ============================ 1976 ``ETHTOOL_A_RSS_HEADER`` nested request header 1977 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 1978 ``ETHTOOL_A_RSS_START_CONTEXT`` u32 start context number (dumps) 1979===================================== ====== ============================ 1980 1981``ETHTOOL_A_RSS_CONTEXT`` specifies which RSS context number to query, 1982if not set context 0 (the main context) is queried. Dumps can be filtered 1983by device (only listing contexts of a given netdev). Filtering single 1984context number is not supported but ``ETHTOOL_A_RSS_START_CONTEXT`` 1985can be used to start dumping context from the given number (primarily 1986used to ignore context 0s and only dump additional contexts). 1987 1988Kernel response contents: 1989 1990===================================== ====== =============================== 1991 ``ETHTOOL_A_RSS_HEADER`` nested reply header 1992 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 1993 ``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func 1994 ``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes 1995 ``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes 1996 ``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation 1997 ``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash 1998===================================== ====== =============================== 1999 2000ETHTOOL_A_RSS_HFUNC attribute is bitmap indicating the hash function 2001being used. Current supported options are toeplitz, xor or crc32. 2002ETHTOOL_A_RSS_INDIR attribute returns RSS indirection table where each byte 2003indicates queue number. 2004ETHTOOL_A_RSS_INPUT_XFRM attribute is a bitmap indicating the type of 2005transformation applied to the input protocol fields before given to the RSS 2006hfunc. Current supported options are symmetric-xor and symmetric-or-xor. 2007ETHTOOL_A_RSS_FLOW_HASH carries per-flow type bitmask of which header 2008fields are included in the hash calculation. 2009 2010RSS_SET 2011======= 2012 2013Request contents: 2014 2015===================================== ====== ============================== 2016 ``ETHTOOL_A_RSS_HEADER`` nested request header 2017 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 2018 ``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func 2019 ``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes 2020 ``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes 2021 ``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation 2022 ``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash 2023===================================== ====== ============================== 2024 2025``ETHTOOL_A_RSS_INDIR`` is the minimal RSS table the user expects. Kernel and 2026the device driver may replicate the table if its smaller than smallest table 2027size supported by the device. For example if user requests ``[0, 1]`` but the 2028device needs at least 8 entries - the real table in use will end up being 2029``[0, 1, 0, 1, 0, 1, 0, 1]``. Most devices require the table size to be power 2030of 2, so tables which size is not a power of 2 will likely be rejected. 2031Using table of size 0 will reset the indirection table to the default. 2032 2033RSS_CREATE_ACT 2034============== 2035 2036Request contents: 2037 2038===================================== ====== ============================== 2039 ``ETHTOOL_A_RSS_HEADER`` nested request header 2040 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 2041 ``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func 2042 ``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes 2043 ``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes 2044 ``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation 2045===================================== ====== ============================== 2046 2047Kernel response contents: 2048 2049===================================== ====== ============================== 2050 ``ETHTOOL_A_RSS_HEADER`` nested request header 2051 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 2052===================================== ====== ============================== 2053 2054Create an additional RSS context, if ``ETHTOOL_A_RSS_CONTEXT`` is not 2055specified kernel will allocate one automatically. 2056 2057RSS_DELETE_ACT 2058============== 2059 2060Request contents: 2061 2062===================================== ====== ============================== 2063 ``ETHTOOL_A_RSS_HEADER`` nested request header 2064 ``ETHTOOL_A_RSS_CONTEXT`` u32 context number 2065===================================== ====== ============================== 2066 2067Delete an additional RSS context. 2068 2069PLCA_GET_CFG 2070============ 2071 2072Gets the IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance 2073(PLCA) Reconciliation Sublayer (RS) attributes. 2074 2075Request contents: 2076 2077 ===================================== ====== ========================== 2078 ``ETHTOOL_A_PLCA_HEADER`` nested request header 2079 ===================================== ====== ========================== 2080 2081Kernel response contents: 2082 2083 ====================================== ====== ============================= 2084 ``ETHTOOL_A_PLCA_HEADER`` nested reply header 2085 ``ETHTOOL_A_PLCA_VERSION`` u16 Supported PLCA management 2086 interface standard/version 2087 ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State 2088 ``ETHTOOL_A_PLCA_NODE_ID`` u32 PLCA unique local node ID 2089 ``ETHTOOL_A_PLCA_NODE_CNT`` u32 Number of PLCA nodes on the 2090 network, including the 2091 coordinator 2092 ``ETHTOOL_A_PLCA_TO_TMR`` u32 Transmit Opportunity Timer 2093 value in bit-times (BT) 2094 ``ETHTOOL_A_PLCA_BURST_CNT`` u32 Number of additional packets 2095 the node is allowed to send 2096 within a single TO 2097 ``ETHTOOL_A_PLCA_BURST_TMR`` u32 Time to wait for the MAC to 2098 transmit a new frame before 2099 terminating the burst 2100 ====================================== ====== ============================= 2101 2102When set, the optional ``ETHTOOL_A_PLCA_VERSION`` attribute indicates which 2103standard and version the PLCA management interface complies to. When not set, 2104the interface is vendor-specific and (possibly) supplied by the driver. 2105The OPEN Alliance SIG specifies a standard register map for 10BASE-T1S PHYs 2106embedding the PLCA Reconciliation Sublayer. See "10BASE-T1S PLCA Management 2107Registers" at https://www.opensig.org/about/specifications/. 2108 2109When set, the optional ``ETHTOOL_A_PLCA_ENABLED`` attribute indicates the 2110administrative state of the PLCA RS. When not set, the node operates in "plain" 2111CSMA/CD mode. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.1 2112aPLCAAdminState / 30.16.1.2.1 acPLCAAdminControl. 2113 2114When set, the optional ``ETHTOOL_A_PLCA_NODE_ID`` attribute indicates the 2115configured local node ID of the PHY. This ID determines which transmit 2116opportunity (TO) is reserved for the node to transmit into. This option is 2117corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.4 aPLCALocalNodeID. The valid 2118range for this attribute is [0 .. 255] where 255 means "not configured". 2119 2120When set, the optional ``ETHTOOL_A_PLCA_NODE_CNT`` attribute indicates the 2121configured maximum number of PLCA nodes on the mixing-segment. This number 2122determines the total number of transmit opportunities generated during a 2123PLCA cycle. This attribute is relevant only for the PLCA coordinator, which is 2124the node with aPLCALocalNodeID set to 0. Follower nodes ignore this setting. 2125This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.3 2126aPLCANodeCount. The valid range for this attribute is [1 .. 255]. 2127 2128When set, the optional ``ETHTOOL_A_PLCA_TO_TMR`` attribute indicates the 2129configured value of the transmit opportunity timer in bit-times. This value 2130must be set equal across all nodes sharing the medium for PLCA to work 2131correctly. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.5 2132aPLCATransmitOpportunityTimer. The valid range for this attribute is 2133[0 .. 255]. 2134 2135When set, the optional ``ETHTOOL_A_PLCA_BURST_CNT`` attribute indicates the 2136configured number of extra packets that the node is allowed to send during a 2137single transmit opportunity. By default, this attribute is 0, meaning that 2138the node can only send a single frame per TO. When greater than 0, the PLCA RS 2139keeps the TO after any transmission, waiting for the MAC to send a new frame 2140for up to aPLCABurstTimer BTs. This can only happen a number of times per PLCA 2141cycle up to the value of this parameter. After that, the burst is over and the 2142normal counting of TOs resumes. This option is corresponding to 2143``IEEE 802.3cg-2019`` 30.16.1.1.6 aPLCAMaxBurstCount. The valid range for this 2144attribute is [0 .. 255]. 2145 2146When set, the optional ``ETHTOOL_A_PLCA_BURST_TMR`` attribute indicates how 2147many bit-times the PLCA RS waits for the MAC to initiate a new transmission 2148when aPLCAMaxBurstCount is greater than 0. If the MAC fails to send a new 2149frame within this time, the burst ends and the counting of TOs resumes. 2150Otherwise, the new frame is sent as part of the current burst. This option 2151is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.7 aPLCABurstTimer. The 2152valid range for this attribute is [0 .. 255]. Although, the value should be 2153set greater than the Inter-Frame-Gap (IFG) time of the MAC (plus some margin) 2154for PLCA burst mode to work as intended. 2155 2156PLCA_SET_CFG 2157============ 2158 2159Sets PLCA RS parameters. 2160 2161Request contents: 2162 2163 ====================================== ====== ============================= 2164 ``ETHTOOL_A_PLCA_HEADER`` nested request header 2165 ``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State 2166 ``ETHTOOL_A_PLCA_NODE_ID`` u8 PLCA unique local node ID 2167 ``ETHTOOL_A_PLCA_NODE_CNT`` u8 Number of PLCA nodes on the 2168 network, including the 2169 coordinator 2170 ``ETHTOOL_A_PLCA_TO_TMR`` u8 Transmit Opportunity Timer 2171 value in bit-times (BT) 2172 ``ETHTOOL_A_PLCA_BURST_CNT`` u8 Number of additional packets 2173 the node is allowed to send 2174 within a single TO 2175 ``ETHTOOL_A_PLCA_BURST_TMR`` u8 Time to wait for the MAC to 2176 transmit a new frame before 2177 terminating the burst 2178 ====================================== ====== ============================= 2179 2180For a description of each attribute, see ``PLCA_GET_CFG``. 2181 2182PLCA_GET_STATUS 2183=============== 2184 2185Gets PLCA RS status information. 2186 2187Request contents: 2188 2189 ===================================== ====== ========================== 2190 ``ETHTOOL_A_PLCA_HEADER`` nested request header 2191 ===================================== ====== ========================== 2192 2193Kernel response contents: 2194 2195 ====================================== ====== ============================= 2196 ``ETHTOOL_A_PLCA_HEADER`` nested reply header 2197 ``ETHTOOL_A_PLCA_STATUS`` u8 PLCA RS operational status 2198 ====================================== ====== ============================= 2199 2200When set, the ``ETHTOOL_A_PLCA_STATUS`` attribute indicates whether the node is 2201detecting the presence of the BEACON on the network. This flag is 2202corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.2 aPLCAStatus. 2203 2204MM_GET 2205====== 2206 2207Retrieve 802.3 MAC Merge parameters. 2208 2209Request contents: 2210 2211 ==================================== ====== ========================== 2212 ``ETHTOOL_A_MM_HEADER`` nested request header 2213 ==================================== ====== ========================== 2214 2215Kernel response contents: 2216 2217 ================================= ====== =================================== 2218 ``ETHTOOL_A_MM_HEADER`` nested request header 2219 ``ETHTOOL_A_MM_PMAC_ENABLED`` bool set if RX of preemptible and SMD-V 2220 frames is enabled 2221 ``ETHTOOL_A_MM_TX_ENABLED`` bool set if TX of preemptible frames is 2222 administratively enabled (might be 2223 inactive if verification failed) 2224 ``ETHTOOL_A_MM_TX_ACTIVE`` bool set if TX of preemptible frames is 2225 operationally enabled 2226 ``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 minimum size of transmitted 2227 non-final fragments, in octets 2228 ``ETHTOOL_A_MM_RX_MIN_FRAG_SIZE`` u32 minimum size of received non-final 2229 fragments, in octets 2230 ``ETHTOOL_A_MM_VERIFY_ENABLED`` bool set if TX of SMD-V frames is 2231 administratively enabled 2232 ``ETHTOOL_A_MM_VERIFY_STATUS`` u8 state of the verification function 2233 ``ETHTOOL_A_MM_VERIFY_TIME`` u32 delay between verification attempts 2234 ``ETHTOOL_A_MM_MAX_VERIFY_TIME``` u32 maximum verification interval 2235 supported by device 2236 ``ETHTOOL_A_MM_STATS`` nested IEEE 802.3-2018 subclause 30.14.1 2237 oMACMergeEntity statistics counters 2238 ================================= ====== =================================== 2239 2240The attributes are populated by the device driver through the following 2241structure: 2242 2243.. kernel-doc:: include/linux/ethtool.h 2244 :identifiers: ethtool_mm_state 2245 2246The ``ETHTOOL_A_MM_VERIFY_STATUS`` will report one of the values from 2247 2248.. kernel-doc:: include/uapi/linux/ethtool.h 2249 :identifiers: ethtool_mm_verify_status 2250 2251If ``ETHTOOL_A_MM_VERIFY_ENABLED`` was passed as false in the ``MM_SET`` 2252command, ``ETHTOOL_A_MM_VERIFY_STATUS`` will report either 2253``ETHTOOL_MM_VERIFY_STATUS_INITIAL`` or ``ETHTOOL_MM_VERIFY_STATUS_DISABLED``, 2254otherwise it should report one of the other states. 2255 2256It is recommended that drivers start with the pMAC disabled, and enable it upon 2257user space request. It is also recommended that user space does not depend upon 2258the default values from ``ETHTOOL_MSG_MM_GET`` requests. 2259 2260``ETHTOOL_A_MM_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in 2261``ETHTOOL_A_HEADER_FLAGS``. The attribute will be empty if driver did not 2262report any statistics. Drivers fill in the statistics in the following 2263structure: 2264 2265.. kernel-doc:: include/linux/ethtool.h 2266 :identifiers: ethtool_mm_stats 2267 2268MM_SET 2269====== 2270 2271Modifies the configuration of the 802.3 MAC Merge layer. 2272 2273Request contents: 2274 2275 ================================= ====== ========================== 2276 ``ETHTOOL_A_MM_VERIFY_TIME`` u32 see MM_GET description 2277 ``ETHTOOL_A_MM_VERIFY_ENABLED`` bool see MM_GET description 2278 ``ETHTOOL_A_MM_TX_ENABLED`` bool see MM_GET description 2279 ``ETHTOOL_A_MM_PMAC_ENABLED`` bool see MM_GET description 2280 ``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 see MM_GET description 2281 ================================= ====== ========================== 2282 2283The attributes are propagated to the driver through the following structure: 2284 2285.. kernel-doc:: include/linux/ethtool.h 2286 :identifiers: ethtool_mm_cfg 2287 2288MODULE_FW_FLASH_ACT 2289=================== 2290 2291Flashes transceiver module firmware. 2292 2293Request contents: 2294 2295 ======================================= ====== =========================== 2296 ``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` nested request header 2297 ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` string firmware image file name 2298 ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` u32 transceiver module password 2299 ======================================= ====== =========================== 2300 2301The firmware update process consists of three logical steps: 2302 23031. Downloading a firmware image to the transceiver module and validating it. 23042. Running the firmware image. 23053. Committing the firmware image so that it is run upon reset. 2306 2307When flash command is given, those three steps are taken in that order. 2308 2309This message merely schedules the update process and returns immediately 2310without blocking. The process then runs asynchronously. 2311Since it can take several minutes to complete, during the update process 2312notifications are emitted from the kernel to user space updating it about 2313the status and progress. 2314 2315The ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` attribute encodes the firmware 2316image file name. The firmware image is downloaded to the transceiver module, 2317validated, run and committed. 2318 2319The optional ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` attribute encodes a password 2320that might be required as part of the transceiver module firmware update 2321process. 2322 2323The firmware update process can take several minutes to complete. Therefore, 2324during the update process notifications are emitted from the kernel to user 2325space updating it about the status and progress. 2326 2327 2328 2329Notification contents: 2330 2331 +---------------------------------------------------+--------+----------------+ 2332 | ``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` | nested | reply header | 2333 +---------------------------------------------------+--------+----------------+ 2334 | ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` | u32 | status | 2335 +---------------------------------------------------+--------+----------------+ 2336 | ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` | string | status message | 2337 +---------------------------------------------------+--------+----------------+ 2338 | ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` | uint | progress | 2339 +---------------------------------------------------+--------+----------------+ 2340 | ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL`` | uint | total | 2341 +---------------------------------------------------+--------+----------------+ 2342 2343The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` attribute encodes the current status 2344of the firmware update process. Possible values are: 2345 2346.. kernel-doc:: include/uapi/linux/ethtool.h 2347 :identifiers: ethtool_module_fw_flash_status 2348 2349The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` attribute encodes a status message 2350string. 2351 2352The ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` and ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL`` 2353attributes encode the completed and total amount of work, respectively. 2354 2355PHY_GET 2356======= 2357 2358Retrieve information about a given Ethernet PHY sitting on the link. The DO 2359operation returns all available information about dev->phydev. User can also 2360specify a PHY_INDEX, in which case the DO request returns information about that 2361specific PHY. 2362 2363As there can be more than one PHY, the DUMP operation can be used to list the PHYs 2364present on a given interface, by passing an interface index or name in 2365the dump request. 2366 2367For more information, refer to :ref:`phy_link_topology` 2368 2369Request contents: 2370 2371 ==================================== ====== ========================== 2372 ``ETHTOOL_A_PHY_HEADER`` nested request header 2373 ==================================== ====== ========================== 2374 2375Kernel response contents: 2376 2377 ===================================== ====== =============================== 2378 ``ETHTOOL_A_PHY_HEADER`` nested request header 2379 ``ETHTOOL_A_PHY_INDEX`` u32 the phy's unique index, that can 2380 be used for phy-specific 2381 requests 2382 ``ETHTOOL_A_PHY_DRVNAME`` string the phy driver name 2383 ``ETHTOOL_A_PHY_NAME`` string the phy device name 2384 ``ETHTOOL_A_PHY_UPSTREAM_TYPE`` u32 the type of device this phy is 2385 connected to 2386 ``ETHTOOL_A_PHY_UPSTREAM_INDEX`` u32 the PHY index of the upstream 2387 PHY 2388 ``ETHTOOL_A_PHY_UPSTREAM_SFP_NAME`` string if this PHY is connected to 2389 its parent PHY through an SFP 2390 bus, the name of this sfp bus 2391 ``ETHTOOL_A_PHY_DOWNSTREAM_SFP_NAME`` string if the phy controls an sfp bus, 2392 the name of the sfp bus 2393 ===================================== ====== =============================== 2394 2395When ``ETHTOOL_A_PHY_UPSTREAM_TYPE`` is PHY_UPSTREAM_PHY, the PHY's parent is 2396another PHY. 2397 2398TSCONFIG_GET 2399============ 2400 2401Retrieves the information about the current hardware timestamping source and 2402configuration. 2403 2404It is similar to the deprecated ``SIOCGHWTSTAMP`` ioctl request. 2405 2406Request contents: 2407 2408 ==================================== ====== ========================== 2409 ``ETHTOOL_A_TSCONFIG_HEADER`` nested request header 2410 ==================================== ====== ========================== 2411 2412Kernel response contents: 2413 2414 ======================================== ====== ============================ 2415 ``ETHTOOL_A_TSCONFIG_HEADER`` nested request header 2416 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider 2417 ``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type 2418 ``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter 2419 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags 2420 ======================================== ====== ============================ 2421 2422When set the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` attribute identifies the 2423source of the hw timestamping provider. It is composed by 2424``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_INDEX`` attribute which describe the index of 2425the PTP device and ``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_QUALIFIER`` which describe 2426the qualifier of the timestamp. 2427 2428When set the ``ETHTOOL_A_TSCONFIG_TX_TYPES``, ``ETHTOOL_A_TSCONFIG_RX_FILTERS`` 2429and the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` attributes identify the Tx 2430type, the Rx filter and the flags configured for the current hw timestamping 2431provider. The attributes are propagated to the driver through the following 2432structure: 2433 2434.. kernel-doc:: include/linux/net_tstamp.h 2435 :identifiers: kernel_hwtstamp_config 2436 2437TSCONFIG_SET 2438============ 2439 2440Set the information about the current hardware timestamping source and 2441configuration. 2442 2443It is similar to the deprecated ``SIOCSHWTSTAMP`` ioctl request. 2444 2445Request contents: 2446 2447 ======================================== ====== ============================ 2448 ``ETHTOOL_A_TSCONFIG_HEADER`` nested request header 2449 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider 2450 ``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type 2451 ``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter 2452 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags 2453 ======================================== ====== ============================ 2454 2455Kernel response contents: 2456 2457 ======================================== ====== ============================ 2458 ``ETHTOOL_A_TSCONFIG_HEADER`` nested request header 2459 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider 2460 ``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type 2461 ``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter 2462 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags 2463 ======================================== ====== ============================ 2464 2465For a description of each attribute, see ``TSCONFIG_GET``. 2466 2467MSE_GET 2468======= 2469 2470Retrieves detailed Mean Square Error (MSE) diagnostic information from the PHY. 2471 2472Request Contents: 2473 2474 ==================================== ====== ============================ 2475 ``ETHTOOL_A_MSE_HEADER`` nested request header 2476 ==================================== ====== ============================ 2477 2478Kernel Response Contents: 2479 2480 ==================================== ====== ================================ 2481 ``ETHTOOL_A_MSE_HEADER`` nested reply header 2482 ``ETHTOOL_A_MSE_CAPABILITIES`` nested capability/scale info for MSE 2483 measurements 2484 ``ETHTOOL_A_MSE_CHANNEL_A`` nested snapshot for Channel A 2485 ``ETHTOOL_A_MSE_CHANNEL_B`` nested snapshot for Channel B 2486 ``ETHTOOL_A_MSE_CHANNEL_C`` nested snapshot for Channel C 2487 ``ETHTOOL_A_MSE_CHANNEL_D`` nested snapshot for Channel D 2488 ``ETHTOOL_A_MSE_WORST_CHANNEL`` nested snapshot for worst channel 2489 ``ETHTOOL_A_MSE_LINK`` nested snapshot for link-wide aggregate 2490 ==================================== ====== ================================ 2491 2492MSE Capabilities 2493---------------- 2494 2495This nested attribute reports the capability / scaling properties used to 2496interpret snapshot values. 2497 2498 ============================================== ====== ========================= 2499 ``ETHTOOL_A_MSE_CAPABILITIES_MAX_AVERAGE_MSE`` uint max avg_mse scale 2500 ``ETHTOOL_A_MSE_CAPABILITIES_MAX_PEAK_MSE`` uint max peak_mse scale 2501 ``ETHTOOL_A_MSE_CAPABILITIES_REFRESH_RATE_PS`` uint sample rate (picoseconds) 2502 ``ETHTOOL_A_MSE_CAPABILITIES_NUM_SYMBOLS`` uint symbols per HW sample 2503 ============================================== ====== ========================= 2504 2505The max-average/peak fields are included only if the corresponding metric 2506is supported by the PHY. Their absence indicates that the metric is not 2507available. 2508 2509See ``struct phy_mse_capability`` kernel documentation in 2510``include/linux/phy.h``. 2511 2512MSE Snapshot 2513------------ 2514 2515Each per-channel nest contains an atomic snapshot of MSE values for that 2516selector (channel A/B/C/D, worst channel, or link). 2517 2518 ========================================== ====== =================== 2519 ``ETHTOOL_A_MSE_SNAPSHOT_AVERAGE_MSE`` uint average MSE value 2520 ``ETHTOOL_A_MSE_SNAPSHOT_PEAK_MSE`` uint current peak MSE 2521 ``ETHTOOL_A_MSE_SNAPSHOT_WORST_PEAK_MSE`` uint worst-case peak MSE 2522 ========================================== ====== =================== 2523 2524Within each channel nest, only the metrics supported by the PHY will be present. 2525 2526See ``struct phy_mse_snapshot`` kernel documentation in 2527``include/linux/phy.h``. 2528 2529Request translation 2530=================== 2531 2532The following table maps ioctl commands to netlink commands providing their 2533functionality. Entries with "n/a" in right column are commands which do not 2534have their netlink replacement yet. Entries which "n/a" in the left column 2535are netlink only. 2536 2537 =================================== ===================================== 2538 ioctl command netlink command 2539 =================================== ===================================== 2540 ``ETHTOOL_GSET`` ``ETHTOOL_MSG_LINKINFO_GET`` 2541 ``ETHTOOL_MSG_LINKMODES_GET`` 2542 ``ETHTOOL_SSET`` ``ETHTOOL_MSG_LINKINFO_SET`` 2543 ``ETHTOOL_MSG_LINKMODES_SET`` 2544 ``ETHTOOL_GDRVINFO`` n/a 2545 ``ETHTOOL_GREGS`` n/a 2546 ``ETHTOOL_GWOL`` ``ETHTOOL_MSG_WOL_GET`` 2547 ``ETHTOOL_SWOL`` ``ETHTOOL_MSG_WOL_SET`` 2548 ``ETHTOOL_GMSGLVL`` ``ETHTOOL_MSG_DEBUG_GET`` 2549 ``ETHTOOL_SMSGLVL`` ``ETHTOOL_MSG_DEBUG_SET`` 2550 ``ETHTOOL_NWAY_RST`` n/a 2551 ``ETHTOOL_GLINK`` ``ETHTOOL_MSG_LINKSTATE_GET`` 2552 ``ETHTOOL_GEEPROM`` n/a 2553 ``ETHTOOL_SEEPROM`` n/a 2554 ``ETHTOOL_GCOALESCE`` ``ETHTOOL_MSG_COALESCE_GET`` 2555 ``ETHTOOL_SCOALESCE`` ``ETHTOOL_MSG_COALESCE_SET`` 2556 ``ETHTOOL_GRINGPARAM`` ``ETHTOOL_MSG_RINGS_GET`` 2557 ``ETHTOOL_SRINGPARAM`` ``ETHTOOL_MSG_RINGS_SET`` 2558 ``ETHTOOL_GPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_GET`` 2559 ``ETHTOOL_SPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_SET`` 2560 ``ETHTOOL_GRXCSUM`` ``ETHTOOL_MSG_FEATURES_GET`` 2561 ``ETHTOOL_SRXCSUM`` ``ETHTOOL_MSG_FEATURES_SET`` 2562 ``ETHTOOL_GTXCSUM`` ``ETHTOOL_MSG_FEATURES_GET`` 2563 ``ETHTOOL_STXCSUM`` ``ETHTOOL_MSG_FEATURES_SET`` 2564 ``ETHTOOL_GSG`` ``ETHTOOL_MSG_FEATURES_GET`` 2565 ``ETHTOOL_SSG`` ``ETHTOOL_MSG_FEATURES_SET`` 2566 ``ETHTOOL_TEST`` n/a 2567 ``ETHTOOL_GSTRINGS`` ``ETHTOOL_MSG_STRSET_GET`` 2568 ``ETHTOOL_PHYS_ID`` n/a 2569 ``ETHTOOL_GSTATS`` n/a 2570 ``ETHTOOL_GTSO`` ``ETHTOOL_MSG_FEATURES_GET`` 2571 ``ETHTOOL_STSO`` ``ETHTOOL_MSG_FEATURES_SET`` 2572 ``ETHTOOL_GPERMADDR`` rtnetlink ``RTM_GETLINK`` 2573 ``ETHTOOL_GUFO`` ``ETHTOOL_MSG_FEATURES_GET`` 2574 ``ETHTOOL_SUFO`` ``ETHTOOL_MSG_FEATURES_SET`` 2575 ``ETHTOOL_GGSO`` ``ETHTOOL_MSG_FEATURES_GET`` 2576 ``ETHTOOL_SGSO`` ``ETHTOOL_MSG_FEATURES_SET`` 2577 ``ETHTOOL_GFLAGS`` ``ETHTOOL_MSG_FEATURES_GET`` 2578 ``ETHTOOL_SFLAGS`` ``ETHTOOL_MSG_FEATURES_SET`` 2579 ``ETHTOOL_GPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_GET`` 2580 ``ETHTOOL_SPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_SET`` 2581 ``ETHTOOL_GRXFH`` ``ETHTOOL_MSG_RSS_GET`` 2582 ``ETHTOOL_SRXFH`` ``ETHTOOL_MSG_RSS_SET`` 2583 ``ETHTOOL_GGRO`` ``ETHTOOL_MSG_FEATURES_GET`` 2584 ``ETHTOOL_SGRO`` ``ETHTOOL_MSG_FEATURES_SET`` 2585 ``ETHTOOL_GRXRINGS`` n/a 2586 ``ETHTOOL_GRXCLSRLCNT`` n/a 2587 ``ETHTOOL_GRXCLSRULE`` n/a 2588 ``ETHTOOL_GRXCLSRLALL`` n/a 2589 ``ETHTOOL_SRXCLSRLDEL`` n/a 2590 ``ETHTOOL_SRXCLSRLINS`` n/a 2591 ``ETHTOOL_FLASHDEV`` n/a 2592 ``ETHTOOL_RESET`` n/a 2593 ``ETHTOOL_SRXNTUPLE`` n/a 2594 ``ETHTOOL_GRXNTUPLE`` n/a 2595 ``ETHTOOL_GSSET_INFO`` ``ETHTOOL_MSG_STRSET_GET`` 2596 ``ETHTOOL_GRXFHINDIR`` ``ETHTOOL_MSG_RSS_GET`` 2597 ``ETHTOOL_SRXFHINDIR`` ``ETHTOOL_MSG_RSS_SET`` 2598 ``ETHTOOL_GFEATURES`` ``ETHTOOL_MSG_FEATURES_GET`` 2599 ``ETHTOOL_SFEATURES`` ``ETHTOOL_MSG_FEATURES_SET`` 2600 ``ETHTOOL_GCHANNELS`` ``ETHTOOL_MSG_CHANNELS_GET`` 2601 ``ETHTOOL_SCHANNELS`` ``ETHTOOL_MSG_CHANNELS_SET`` 2602 ``ETHTOOL_SET_DUMP`` n/a 2603 ``ETHTOOL_GET_DUMP_FLAG`` n/a 2604 ``ETHTOOL_GET_DUMP_DATA`` n/a 2605 ``ETHTOOL_GET_TS_INFO`` ``ETHTOOL_MSG_TSINFO_GET`` 2606 ``ETHTOOL_GMODULEINFO`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` 2607 ``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET`` 2608 ``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET`` 2609 ``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET`` 2610 ``ETHTOOL_GRSSH`` ``ETHTOOL_MSG_RSS_GET`` 2611 ``ETHTOOL_SRSSH`` n/a 2612 ``ETHTOOL_GTUNABLE`` n/a 2613 ``ETHTOOL_STUNABLE`` n/a 2614 ``ETHTOOL_GPHYSTATS`` n/a 2615 ``ETHTOOL_PERQUEUE`` n/a 2616 ``ETHTOOL_GLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_GET`` 2617 ``ETHTOOL_MSG_LINKMODES_GET`` 2618 ``ETHTOOL_SLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_SET`` 2619 ``ETHTOOL_MSG_LINKMODES_SET`` 2620 ``ETHTOOL_PHY_GTUNABLE`` n/a 2621 ``ETHTOOL_PHY_STUNABLE`` n/a 2622 ``ETHTOOL_GFECPARAM`` ``ETHTOOL_MSG_FEC_GET`` 2623 ``ETHTOOL_SFECPARAM`` ``ETHTOOL_MSG_FEC_SET`` 2624 n/a ``ETHTOOL_MSG_CABLE_TEST_ACT`` 2625 n/a ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` 2626 n/a ``ETHTOOL_MSG_TUNNEL_INFO_GET`` 2627 n/a ``ETHTOOL_MSG_PHC_VCLOCKS_GET`` 2628 n/a ``ETHTOOL_MSG_MODULE_GET`` 2629 n/a ``ETHTOOL_MSG_MODULE_SET`` 2630 n/a ``ETHTOOL_MSG_PLCA_GET_CFG`` 2631 n/a ``ETHTOOL_MSG_PLCA_SET_CFG`` 2632 n/a ``ETHTOOL_MSG_PLCA_GET_STATUS`` 2633 n/a ``ETHTOOL_MSG_MM_GET`` 2634 n/a ``ETHTOOL_MSG_MM_SET`` 2635 n/a ``ETHTOOL_MSG_MODULE_FW_FLASH_ACT`` 2636 n/a ``ETHTOOL_MSG_PHY_GET`` 2637 ``SIOCGHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_GET`` 2638 ``SIOCSHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_SET`` 2639 =================================== ===================================== 2640