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