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