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