Documentation/networking/ethtool-netlink.rst

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