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