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