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