요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
=============================
2
Netlink interface for ethtool
3
=============================
6
Basic information
7
=================
9
Netlink 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
12
header). This family does not use a specific header, all information in
13
requests and replies is passed using netlink attributes.
15
The ethtool netlink interface uses extended ACK for error and warning
16
reporting, userspace application developers are encouraged to make these
17
messages available to user in a suitable way.
19
Requests can be divided into three categories: "get" (retrieving information),
20
"set" (setting parameters) and "action" (invoking an action).
22
All "set" and "action" type requests require admin privileges
23
(``CAP_NET_ADMIN`` in the namespace). Most "get" type requests are allowed for
24
anyone but there are exceptions (where the response contains sensitive
25
information). In some cases, the request as such is allowed for anyone but
26
unprivileged users have attributes with sensitive information (e.g.
27
wake-on-lan password) omitted.
30
Conventions
31
===========
33
Attributes which represent a boolean value usually use NLA_U8 type so that we
34
can distinguish three states: "on", "off" and "not present" (meaning the
35
information is not available in "get" requests or value is not to be changed
36
in "set" requests). For these attributes, the "true" value should be passed as
37
number 1 but any non-zero value should be understood as "true" by recipient.
38
In the tables below, "bool" denotes NLA_U8 attributes interpreted in this way.
40
In the message structure descriptions below, if an attribute name is suffixed
41
with "+", parent nest can contain multiple attributes of the same type. This
42
implements an array of entries.
44
Attributes that need to be filled-in by device drivers and that are dumped to
45
user space based on whether they are valid or not should not use zero as a
46
valid value. This avoids the need to explicitly signal the validity of the
47
attribute in the device driver API.
50
Request header
51
==============
53
Each request or reply message contains a nested attribute with common header.
54
Structure of this header is
56
============================== ====== =============================
57
``ETHTOOL_A_HEADER_DEV_INDEX`` u32 device ifindex
58
``ETHTOOL_A_HEADER_DEV_NAME`` string device name
59
``ETHTOOL_A_HEADER_FLAGS`` u32 flags common for all requests
60
``ETHTOOL_A_HEADER_PHY_INDEX`` u32 phy device index
61
============================== ====== =============================
63
``ETHTOOL_A_HEADER_DEV_INDEX`` and ``ETHTOOL_A_HEADER_DEV_NAME`` identify the
64
device message relates to. One of them is sufficient in requests, if both are
65
used, they must identify the same device. Some requests, e.g. global string
66
sets, do not require device identification. Most ``GET`` requests also allow
67
dump requests without device identification to query the same information for
68
all devices providing it (each device in a separate message).
70
``ETHTOOL_A_HEADER_FLAGS`` is a bitmap of request flags common for all request
71
types. The interpretation of these flags is the same for all request types but
72
the flags may not apply to requests. Recognized flags are:
74
================================= ===================================
75
``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply
76
``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT)
77
``ETHTOOL_FLAG_STATS`` include optional device statistics
78
================================= ===================================
80
New request flags should follow the general idea that if the flag is not set,
81
the behaviour is backward compatible, i.e. requests from old clients not aware
82
of the flag should be interpreted the way the client expects. A client must
83
not set flags it does not understand.
85
``ETHTOOL_A_HEADER_PHY_INDEX`` identifies the Ethernet PHY the message relates to.
86
As there are numerous commands that are related to PHY configuration, and because
87
there may be more than one PHY on the link, the PHY index can be passed in the
88
request for the commands that needs it. It is, however, not mandatory, and if it
89
is not passed for commands that target a PHY, the net_device.phydev pointer
90
is used.
92
Bit sets
93
========
95
For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32``
96
type is used. For arbitrary length bitmaps, ethtool netlink uses a nested
97
attribute with contents of one of two forms: compact (two binary bitmaps
98
representing bit values and mask of affected bits) and bit-by-bit (list of
99
bits identified by either index or name).
101
Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together
102
with their values which saves a round trip (when the bitset is passed in a
103
request) or at least a second request (when the bitset is in a reply). This is
104
useful for one shot applications like traditional ethtool command. On the
105
other hand, long running applications like ethtool monitor (displaying
106
notifications) or network management daemons may prefer fetching the names
107
only once and using compact form to save message size. Notifications from
108
ethtool netlink interface always use compact form for bitsets.
110
A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK``
111
not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests
112
modifying a bitmap, the former changes the bit set in mask to values set in
113
value and preserves the rest; the latter sets the bits set in the bitmap and
114
clears the rest.
116
Compact form: nested (bitset) attribute contents:
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
============================ ====== ============================
125
Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits
126
rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte
127
order, words ordered from least significant to most significant (i.e. the same
128
way as bitmaps are passed with ioctl interface).
130
For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are
131
mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if
132
``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair);
133
if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not
134
allowed (bitset represents a single bitmap.
136
Kernel bit set length may differ from userspace length if older application is
137
used on newer kernel or vice versa. If userspace bitmap is longer, an error is
138
issued only if the request actually tries to set values of some bits not
139
recognized by kernel.
141
Bit-by-bit form: nested (bitset) attribute contents:
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
+-+-+--------------------------------+--------+-----------------------------+
159
Bit size is optional for bit-by-bit form. ``ETHTOOL_A_BITSET_BITS`` nest can
160
only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an
161
arbitrary number of them. A bit may be identified by its index or by its
162
name. 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
164
index exceeds kernel bit length or if name is not recognized.
166
When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as
167
a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in
168
such case. Such bitset represents a bitmap with listed bits set and the rest
169
zero.
171
In requests, application can use either form. Form used by kernel in reply is
172
determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request
173
header. Semantics of value and mask depends on the attribute.
176
List of message types
177
=====================
179
All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix
180
according to message purpose:
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
============== ======================================
192
Userspace to kernel:
194
===================================== =================================
195
``ETHTOOL_MSG_STRSET_GET`` get string set
196
``ETHTOOL_MSG_LINKINFO_GET`` get link settings
197
``ETHTOOL_MSG_LINKINFO_SET`` set link settings
198
``ETHTOOL_MSG_LINKMODES_GET`` get link modes info
199
``ETHTOOL_MSG_LINKMODES_SET`` set link modes info
200
``ETHTOOL_MSG_LINKSTATE_GET`` get link state
201
``ETHTOOL_MSG_DEBUG_GET`` get debugging settings
202
``ETHTOOL_MSG_DEBUG_SET`` set debugging settings
203
``ETHTOOL_MSG_WOL_GET`` get wake-on-lan settings
204
``ETHTOOL_MSG_WOL_SET`` set wake-on-lan settings
205
``ETHTOOL_MSG_FEATURES_GET`` get device features
206
``ETHTOOL_MSG_FEATURES_SET`` set device features
207
``ETHTOOL_MSG_PRIVFLAGS_GET`` get private flags
208
``ETHTOOL_MSG_PRIVFLAGS_SET`` set private flags
209
``ETHTOOL_MSG_RINGS_GET`` get ring sizes
210
``ETHTOOL_MSG_RINGS_SET`` set ring sizes
211
``ETHTOOL_MSG_CHANNELS_GET`` get channel counts
212
``ETHTOOL_MSG_CHANNELS_SET`` set channel counts
213
``ETHTOOL_MSG_COALESCE_GET`` get coalescing parameters
214
``ETHTOOL_MSG_COALESCE_SET`` set coalescing parameters
215
``ETHTOOL_MSG_PAUSE_GET`` get pause parameters
216
``ETHTOOL_MSG_PAUSE_SET`` set pause parameters
217
``ETHTOOL_MSG_EEE_GET`` get EEE settings
218
``ETHTOOL_MSG_EEE_SET`` set EEE settings
219
``ETHTOOL_MSG_TSINFO_GET`` get timestamping info
220
``ETHTOOL_MSG_CABLE_TEST_ACT`` action start cable test
221
``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` action start raw TDR cable test
222
``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info
223
``ETHTOOL_MSG_FEC_GET`` get FEC settings
224
``ETHTOOL_MSG_FEC_SET`` set FEC settings
225
``ETHTOOL_MSG_MODULE_EEPROM_GET`` read SFP module EEPROM
226
``ETHTOOL_MSG_STATS_GET`` get standard statistics
227
``ETHTOOL_MSG_PHC_VCLOCKS_GET`` get PHC virtual clocks info
228
``ETHTOOL_MSG_MODULE_SET`` set transceiver module parameters
229
``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters
230
``ETHTOOL_MSG_PSE_SET`` set PSE parameters
231
``ETHTOOL_MSG_PSE_GET`` get PSE parameters
232
``ETHTOOL_MSG_RSS_GET`` get RSS settings
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
236
``ETHTOOL_MSG_MM_GET`` get MAC merge layer state
237
``ETHTOOL_MSG_MM_SET`` set MAC merge layer parameters
238
``ETHTOOL_MSG_MODULE_FW_FLASH_ACT`` flash transceiver module firmware
239
``ETHTOOL_MSG_PHY_GET`` get Ethernet PHY information
240
``ETHTOOL_MSG_TSCONFIG_GET`` get hw timestamping configuration
241
``ETHTOOL_MSG_TSCONFIG_SET`` set hw timestamping configuration
242
``ETHTOOL_MSG_RSS_SET`` set RSS settings
243
``ETHTOOL_MSG_RSS_CREATE_ACT`` create an additional RSS context
244
``ETHTOOL_MSG_RSS_DELETE_ACT`` delete an additional RSS context
245
===================================== =================================
247
Kernel to userspace:
249
======================================== =================================
250
``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents
251
``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings
252
``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification
253
``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info
254
``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification
255
``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info
256
``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings
257
``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification
258
``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings
259
``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification
260
``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features
261
``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET
262
``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification
263
``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags
264
``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags
265
``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes
266
``ETHTOOL_MSG_RINGS_NTF`` ring sizes
267
``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts
268
``ETHTOOL_MSG_CHANNELS_NTF`` channel counts
269
``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters
270
``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters
271
``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters
272
``ETHTOOL_MSG_PAUSE_NTF`` pause parameters
273
``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings
274
``ETHTOOL_MSG_EEE_NTF`` EEE settings
275
``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info
276
``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results
277
``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results
278
``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info
279
``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings
280
``ETHTOOL_MSG_FEC_NTF`` FEC settings
281
``ETHTOOL_MSG_MODULE_EEPROM_GET_REPLY`` read SFP module EEPROM
282
``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics
283
``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info
284
``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters
285
``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters
286
``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings
287
``ETHTOOL_MSG_RSS_NTF`` RSS settings
288
``ETHTOOL_MSG_PLCA_GET_CFG_REPLY`` PLCA RS parameters
289
``ETHTOOL_MSG_PLCA_GET_STATUS_REPLY`` PLCA RS status
290
``ETHTOOL_MSG_PLCA_NTF`` PLCA RS parameters
291
``ETHTOOL_MSG_MM_GET_REPLY`` MAC merge layer status
292
``ETHTOOL_MSG_MODULE_FW_FLASH_NTF`` transceiver module flash updates
293
``ETHTOOL_MSG_PHY_GET_REPLY`` Ethernet PHY information
294
``ETHTOOL_MSG_PHY_NTF`` Ethernet PHY information change
295
``ETHTOOL_MSG_TSCONFIG_GET_REPLY`` hw timestamping configuration
296
``ETHTOOL_MSG_TSCONFIG_SET_REPLY`` new hw timestamping configuration
297
``ETHTOOL_MSG_PSE_NTF`` PSE events notification
298
``ETHTOOL_MSG_RSS_NTF`` RSS settings notification
299
``ETHTOOL_MSG_RSS_CREATE_ACT_REPLY`` create an additional RSS context
300
``ETHTOOL_MSG_RSS_CREATE_NTF`` additional RSS context created
301
``ETHTOOL_MSG_RSS_DELETE_NTF`` additional RSS context deleted
302
======================================== =================================
304
``GET`` requests are sent by userspace applications to retrieve device
305
information. They usually do not contain any message specific attributes.
306
Kernel replies with corresponding "GET_REPLY" message. For most types, ``GET``
307
request with ``NLM_F_DUMP`` and no device identification can be used to query
308
the information for all devices supporting the request.
310
If the data can be also modified, corresponding ``SET`` message with the same
311
layout as corresponding ``GET_REPLY`` is used to request changes. Only
312
attributes where a change is requested are included in such request (also, not
313
all attributes may be changed). Replies to most ``SET`` request consist only
314
of error code and extack; if kernel provides additional data, it is sent in
315
the form of corresponding ``SET_REPLY`` message which can be suppressed by
316
setting ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header.
318
Data modification also triggers sending a ``NTF`` message with a notification.
319
These usually bear only a subset of attributes which was affected by the
320
change. The same notification is issued if the data is modified using other
321
means (mostly ioctl ethtool interface). Unlike notifications from ethtool
322
netlink code which are only sent if something actually changed, notifications
323
triggered by ioctl interface may be sent even if the request did not actually
324
change any data.
326
``ACT`` messages request kernel (driver) to perform a specific action. If some
327
information is reported by kernel (which can be suppressed by setting
328
``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header), the reply takes form of
329
an ``ACT_REPLY`` message. Performing an action also triggers a notification
330
(``NTF`` message).
332
Later sections describe the format and semantics of these messages.
335
STRSET_GET
336
==========
338
Requests contents of a string set as provided by ioctl commands
339
``ETHTOOL_GSSET_INFO`` and ``ETHTOOL_GSTRINGS.`` String sets are not user
340
writeable so that the corresponding ``STRSET_SET`` message is only used in
341
kernel replies. There are two types of string sets: global (independent of
342
a device, e.g. device feature names) and device specific (e.g. device private
343
flags).
345
Request contents:
347
+---------------------------------------+--------+------------------------+
348
| ``ETHTOOL_A_STRSET_HEADER`` | nested | request header |
349
+---------------------------------------+--------+------------------------+
350
| ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | string set to request |
351
+-+-------------------------------------+--------+------------------------+
352
| | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set |
353
+-+-+-----------------------------------+--------+------------------------+
354
| | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id |
355
+-+-+-----------------------------------+--------+------------------------+
357
Kernel response contents:
359
+---------------------------------------+--------+-----------------------+
360
| ``ETHTOOL_A_STRSET_HEADER`` | nested | reply header |
361
+---------------------------------------+--------+-----------------------+
362
| ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | array of string sets |
363
+-+-------------------------------------+--------+-----------------------+
364
| | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set |
365
+-+-+-----------------------------------+--------+-----------------------+
366
| | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id |
367
+-+-+-----------------------------------+--------+-----------------------+
368
| | | ``ETHTOOL_A_STRINGSET_COUNT`` | u32 | number of strings |
369
+-+-+-----------------------------------+--------+-----------------------+
370
| | | ``ETHTOOL_A_STRINGSET_STRINGS`` | nested | array of strings |
371
+-+-+-+---------------------------------+--------+-----------------------+
372
| | | | ``ETHTOOL_A_STRINGS_STRING+`` | nested | one string |
373
+-+-+-+-+-------------------------------+--------+-----------------------+
374
| | | | | ``ETHTOOL_A_STRING_INDEX`` | u32 | string index |
375
+-+-+-+-+-------------------------------+--------+-----------------------+
376
| | | | | ``ETHTOOL_A_STRING_VALUE`` | string | string value |
377
+-+-+-+-+-------------------------------+--------+-----------------------+
378
| ``ETHTOOL_A_STRSET_COUNTS_ONLY`` | flag | return only counts |
379
+---------------------------------------+--------+-----------------------+
381
Device identification in request header is optional. Depending on its presence
382
a and ``NLM_F_DUMP`` flag, there are three type of ``STRSET_GET`` requests:
384
- no ``NLM_F_DUMP,`` no device: get "global" stringsets
385
- no ``NLM_F_DUMP``, with device: get string sets related to the device
386
- ``NLM_F_DUMP``, no device: get device related string sets for all devices
388
If there is no ``ETHTOOL_A_STRSET_STRINGSETS`` array, all string sets of
389
requested type are returned, otherwise only those specified in the request.
390
Flag ``ETHTOOL_A_STRSET_COUNTS_ONLY`` tells kernel to only return string
391
counts of the sets, not the actual strings.
394
LINKINFO_GET
395
============
397
Requests link settings as provided by ``ETHTOOL_GLINKSETTINGS`` except for
398
link modes and autonegotiation related information. The request does not use
399
any attributes.
401
Request contents:
403
==================================== ====== ==========================
404
``ETHTOOL_A_LINKINFO_HEADER`` nested request header
405
==================================== ====== ==========================
407
Kernel response contents:
409
==================================== ====== ==========================
410
``ETHTOOL_A_LINKINFO_HEADER`` nested reply header
411
``ETHTOOL_A_LINKINFO_PORT`` u8 physical port
412
``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address
413
``ETHTOOL_A_LINKINFO_TP_MDIX`` u8 MDI(-X) status
414
``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control
415
``ETHTOOL_A_LINKINFO_TRANSCEIVER`` u8 transceiver
416
==================================== ====== ==========================
418
Attributes and their values have the same meaning as matching members of the
419
corresponding ioctl structures.
421
``LINKINFO_GET`` allows dump requests (kernel returns reply message for all
422
devices supporting the request).
425
LINKINFO_SET
426
============
428
``LINKINFO_SET`` request allows setting some of the attributes reported by
429
``LINKINFO_GET``.
431
Request contents:
433
==================================== ====== ==========================
434
``ETHTOOL_A_LINKINFO_HEADER`` nested request header
435
``ETHTOOL_A_LINKINFO_PORT`` u8 physical port
436
``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address
437
``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control
438
==================================== ====== ==========================
440
MDI(-X) status and transceiver cannot be set, request with the corresponding
441
attributes is rejected.
444
LINKMODES_GET
445
=============
447
Requests link modes (supported, advertised and peer advertised) and related
448
information (autonegotiation status, link speed and duplex) as provided by
449
``ETHTOOL_GLINKSETTINGS``. The request does not use any attributes.
451
Request contents:
453
==================================== ====== ==========================
454
``ETHTOOL_A_LINKMODES_HEADER`` nested request header
455
==================================== ====== ==========================
457
Kernel response contents:
459
========================================== ====== ==========================
460
``ETHTOOL_A_LINKMODES_HEADER`` nested reply header
461
``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status
462
``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes
463
``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes
464
``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s)
465
``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode
466
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode
467
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_STATE`` u8 Master/slave port state
468
``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching
469
========================================== ====== ==========================
471
For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask
472
represents supported modes. ``ETHTOOL_A_LINKMODES_PEER`` in the reply is a bit
473
list.
475
``LINKMODES_GET`` allows dump requests (kernel returns reply messages for all
476
devices supporting the request).
479
LINKMODES_SET
480
=============
482
Request contents:
484
========================================== ====== ==========================
485
``ETHTOOL_A_LINKMODES_HEADER`` nested request header
486
``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status
487
``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes
488
``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes
489
``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s)
490
``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode
491
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode
492
``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching
493
``ETHTOOL_A_LINKMODES_LANES`` u32 lanes
494
========================================== ====== ==========================
496
``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If
497
autonegotiation is on (either set now or kept from before), advertised modes
498
are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one
499
of speed, duplex and lanes is specified, kernel adjusts advertised modes to all
500
supported modes matching speed, duplex, lanes or all (whatever is specified).
501
This autoselection is done on ethtool side with ioctl interface, netlink
502
interface is supposed to allow requesting changes without knowing what exactly
503
kernel supports.
506
LINKSTATE_GET
507
=============
509
Requests link state information. Link up/down flag (as provided by
510
``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might
511
be provided as well. In general, extended state describes reasons for why a port
512
is down, or why it operates in some non-obvious mode. This request does not have
513
any attributes.
515
Request contents:
517
==================================== ====== ==========================
518
``ETHTOOL_A_LINKSTATE_HEADER`` nested request header
519
==================================== ====== ==========================
521
Kernel response contents:
523
==================================== ====== ============================
524
``ETHTOOL_A_LINKSTATE_HEADER`` nested reply header
525
``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down)
526
``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index
527
``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value
528
``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state
529
``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate
530
``ETHTOOL_A_LINKSTATE_EXT_DOWN_CNT`` u32 count of link down events
531
==================================== ====== ============================
533
For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns
534
carrier flag provided by ``netif_carrier_ok()`` but there are drivers which
535
define their own handler.
537
``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are
538
optional values. ethtool core can provide either both
539
``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``,
540
or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them.
542
``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all
543
devices supporting the request).
546
Link extended states:
548
================================================ ============================================
549
``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or
550
issues therein
552
``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training
554
``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer
555
or forward error correction sublayer
557
``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues
559
``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected
561
``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable,
562
e.g., unsupported cable
564
``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure
565
during reading or parsing the data
567
``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm
569
``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the
570
power required from cable or module
572
``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated
574
``ETHTOOL_LINK_EXT_STATE_MODULE`` Transceiver module issue
575
================================================ ============================================
577
Link extended substates:
579
Autoneg substates:
581
=============================================================== ================================
582
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down
584
``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side
586
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed
588
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force
589
mode or there is no agreement of
590
speed
592
``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes
593
in both sides are mismatched
595
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator
596
=============================================================== ================================
598
Link training substates:
600
=========================================================================== ====================
601
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not
602
recognized, the
603
lock failed
605
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not
606
occur before
607
timeout
609
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not
610
send ready signal
611
after training
612
process
614
``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not
615
ready yet
616
=========================================================================== ====================
618
Link logical mismatch substates:
620
================================================================ ===============================
621
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was
622
not locked in first phase -
623
block lock
625
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was
626
not locked in second phase -
627
alignment markers lock
629
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did
630
not get align status
632
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is
633
not locked
635
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is
636
not locked
637
================================================================ ===============================
639
Bad signal integrity substates:
641
================================================================= =============================
642
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical
643
errors
645
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to
646
operate the cable at a rate
647
that is not formally
648
supported, which led to
649
signal integrity issues
651
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_REFERENCE_CLOCK_LOST`` The external clock signal for
652
SerDes is too weak or
653
unavailable.
655
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_ALOS`` The received signal for
656
SerDes is too weak because
657
analog loss of signal.
658
================================================================= =============================
660
Cable issue substates:
662
=================================================== ============================================
663
``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable
665
``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure
666
=================================================== ============================================
668
Transceiver module issue substates:
670
=================================================== ============================================
671
``ETHTOOL_LINK_EXT_SUBSTATE_MODULE_CMIS_NOT_READY`` The CMIS Module State Machine did not reach
672
the ModuleReady state. For example, if the
673
module is stuck at ModuleFault state
674
=================================================== ============================================
676
DEBUG_GET
677
=========
679
Requests debugging settings of a device. At the moment, only message mask is
680
provided.
682
Request contents:
684
==================================== ====== ==========================
685
``ETHTOOL_A_DEBUG_HEADER`` nested request header
686
==================================== ====== ==========================
688
Kernel response contents:
690
==================================== ====== ==========================
691
``ETHTOOL_A_DEBUG_HEADER`` nested reply header
692
``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask
693
==================================== ====== ==========================
695
The message mask (``ETHTOOL_A_DEBUG_MSGMASK``) is equal to message level as
696
provided by ``ETHTOOL_GMSGLVL`` and set by ``ETHTOOL_SMSGLVL`` in ioctl
697
interface. While it is called message level there for historical reasons, most
698
drivers and almost all newer drivers use it as a mask of enabled message
699
classes (represented by ``NETIF_MSG_*`` constants); therefore netlink
700
interface follows its actual use in practice.
702
``DEBUG_GET`` allows dump requests (kernel returns reply messages for all
703
devices supporting the request).
706
DEBUG_SET
707
=========
709
Set or update debugging settings of a device. At the moment, only message mask
710
is supported.
712
Request contents:
714
==================================== ====== ==========================
715
``ETHTOOL_A_DEBUG_HEADER`` nested request header
716
``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask
717
==================================== ====== ==========================
719
``ETHTOOL_A_DEBUG_MSGMASK`` bit set allows setting or modifying mask of
720
enabled debugging message types for the device.
723
WOL_GET
724
=======
726
Query device wake-on-lan settings. Unlike most "GET" type requests,
727
``ETHTOOL_MSG_WOL_GET`` requires (netns) ``CAP_NET_ADMIN`` privileges as it
728
(potentially) provides SecureOn(tm) password which is confidential.
730
Request contents:
732
==================================== ====== ==========================
733
``ETHTOOL_A_WOL_HEADER`` nested request header
734
==================================== ====== ==========================
736
Kernel response contents:
738
==================================== ====== ==========================
739
``ETHTOOL_A_WOL_HEADER`` nested reply header
740
``ETHTOOL_A_WOL_MODES`` bitset mask of enabled WoL modes
741
``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password
742
==================================== ====== ==========================
744
In reply, ``ETHTOOL_A_WOL_MODES`` mask consists of modes supported by the
745
device, value of modes which are enabled. ``ETHTOOL_A_WOL_SOPASS`` is only
746
included in reply if ``WAKE_MAGICSECURE`` mode is supported.
749
WOL_SET
750
=======
752
Set or update wake-on-lan settings.
754
Request contents:
756
==================================== ====== ==========================
757
``ETHTOOL_A_WOL_HEADER`` nested request header
758
``ETHTOOL_A_WOL_MODES`` bitset enabled WoL modes
759
``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password
760
==================================== ====== ==========================
762
``ETHTOOL_A_WOL_SOPASS`` is only allowed for devices supporting
763
``WAKE_MAGICSECURE`` mode.
766
FEATURES_GET
767
============
769
Gets netdev features like ``ETHTOOL_GFEATURES`` ioctl request.
771
Request contents:
773
==================================== ====== ==========================
774
``ETHTOOL_A_FEATURES_HEADER`` nested request header
775
==================================== ====== ==========================
777
Kernel response contents:
779
==================================== ====== ==========================
780
``ETHTOOL_A_FEATURES_HEADER`` nested reply header
781
``ETHTOOL_A_FEATURES_HW`` bitset dev->hw_features
782
``ETHTOOL_A_FEATURES_WANTED`` bitset dev->wanted_features
783
``ETHTOOL_A_FEATURES_ACTIVE`` bitset dev->features
784
``ETHTOOL_A_FEATURES_NOCHANGE`` bitset NETIF_F_NEVER_CHANGE
785
==================================== ====== ==========================
787
Bitmaps in kernel response have the same meaning as bitmaps used in ioctl
788
interference but attribute names are different (they are based on
789
corresponding members of struct net_device). Legacy "flags" are not provided,
790
if userspace needs them (most likely only ethtool for backward compatibility),
791
it can calculate their values from related feature bits itself.
792
ETHA_FEATURES_HW uses mask consisting of all features recognized by kernel (to
793
provide all names when using verbose bitmap format), the other three use no
794
mask (simple bit lists).
797
FEATURES_SET
798
============
800
Request to set netdev features like ``ETHTOOL_SFEATURES`` ioctl request.
802
Request contents:
804
==================================== ====== ==========================
805
``ETHTOOL_A_FEATURES_HEADER`` nested request header
806
``ETHTOOL_A_FEATURES_WANTED`` bitset requested features
807
==================================== ====== ==========================
809
Kernel response contents:
811
==================================== ====== ==========================
812
``ETHTOOL_A_FEATURES_HEADER`` nested reply header
813
``ETHTOOL_A_FEATURES_WANTED`` bitset diff wanted vs. result
814
``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active
815
==================================== ====== ==========================
817
Request contains only one bitset which can be either value/mask pair (request
818
to change specific feature bits and leave the rest) or only a value (request
819
to set all features to specified set).
821
As request is subject to netdev_change_features() sanity checks, optional
822
kernel reply (can be suppressed by ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request
823
header) informs client about the actual result. ``ETHTOOL_A_FEATURES_WANTED``
824
reports the difference between client request and actual result: mask consists
825
of bits which differ between requested features and result (dev->features
826
after the operation), value consists of values of these bits in the request
827
(i.e. negated values from resulting features). ``ETHTOOL_A_FEATURES_ACTIVE``
828
reports the difference between old and new dev->features: mask consists of
829
bits which have changed, values are their values in new dev->features (after
830
the operation).
832
``ETHTOOL_MSG_FEATURES_NTF`` notification is sent not only if device features
833
are modified using ``ETHTOOL_MSG_FEATURES_SET`` request or on of ethtool ioctl
834
request but also each time features are modified with netdev_update_features()
835
or netdev_change_features().
838
PRIVFLAGS_GET
839
=============
841
Gets private flags like ``ETHTOOL_GPFLAGS`` ioctl request.
843
Request contents:
845
==================================== ====== ==========================
846
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header
847
==================================== ====== ==========================
849
Kernel response contents:
851
==================================== ====== ==========================
852
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested reply header
853
``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags
854
==================================== ====== ==========================
856
``ETHTOOL_A_PRIVFLAGS_FLAGS`` is a bitset with values of device private flags.
857
These flags are defined by driver, their number and names (and also meaning)
858
are device dependent. For compact bitset format, names can be retrieved as
859
``ETH_SS_PRIV_FLAGS`` string set. If verbose bitset format is requested,
860
response uses all private flags supported by the device as mask so that client
861
gets the full information without having to fetch the string set with names.
864
PRIVFLAGS_SET
865
=============
867
Sets or modifies values of device private flags like ``ETHTOOL_SPFLAGS``
868
ioctl request.
870
Request contents:
872
==================================== ====== ==========================
873
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header
874
``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags
875
==================================== ====== ==========================
877
``ETHTOOL_A_PRIVFLAGS_FLAGS`` can either set the whole set of private flags or
878
modify only values of some of them.
881
RINGS_GET
882
=========
884
Gets ring sizes like ``ETHTOOL_GRINGPARAM`` ioctl request.
886
Request contents:
888
==================================== ====== ==========================
889
``ETHTOOL_A_RINGS_HEADER`` nested request header
890
==================================== ====== ==========================
892
Kernel response contents:
894
======================================= ====== ===========================
895
``ETHTOOL_A_RINGS_HEADER`` nested reply header
896
``ETHTOOL_A_RINGS_RX_MAX`` u32 max size of RX ring
897
``ETHTOOL_A_RINGS_RX_MINI_MAX`` u32 max size of RX mini ring
898
``ETHTOOL_A_RINGS_RX_JUMBO_MAX`` u32 max size of RX jumbo ring
899
``ETHTOOL_A_RINGS_TX_MAX`` u32 max size of TX ring
900
``ETHTOOL_A_RINGS_RX`` u32 size of RX ring
901
``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring
902
``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring
903
``ETHTOOL_A_RINGS_TX`` u32 size of TX ring
904
``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring
905
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split
906
``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE
907
``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode
908
``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode
909
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer
910
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN_MAX`` u32 max size of TX push buffer
911
``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of
912
header / data split
913
``ETHTOOL_A_RINGS_HDS_THRESH_MAX`` u32 max threshold of
914
header / data split
915
======================================= ====== ===========================
917
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with
918
page-flipping TCP zero-copy receive (``getsockopt(TCP_ZEROCOPY_RECEIVE)``).
919
If enabled the device is configured to place frame headers and data into
920
separate buffers. The device configuration must make it possible to receive
921
full memory pages of data, for example because MTU is high enough or through
922
HW-GRO.
924
``ETHTOOL_A_RINGS_[RX|TX]_PUSH`` flag is used to enable descriptor fast
925
path to send or receive packets. In ordinary path, driver fills descriptors in DRAM and
926
notifies NIC hardware. In fast path, driver pushes descriptors to the device
927
through MMIO writes, thus reducing the latency. However, enabling this feature
928
may increase the CPU cost. Drivers may enforce additional per-packet
929
eligibility checks (e.g. on packet size).
931
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` specifies the maximum number of bytes of a
932
transmitted packet a driver can push directly to the underlying device
933
('push' mode). Pushing some of the payload bytes to the device has the
934
advantages of reducing latency for small packets by avoiding DMA mapping (same
935
as ``ETHTOOL_A_RINGS_TX_PUSH`` parameter) as well as allowing the underlying
936
device to process packet headers ahead of fetching its payload.
937
This can help the device to make fast actions based on the packet's headers.
938
This is similar to the "tx-copybreak" parameter, which copies the packet to a
939
preallocated DMA memory area instead of mapping new memory. However,
940
tx-push-buff parameter copies the packet directly to the device to allow the
941
device to take faster actions on the packet.
943
RINGS_SET
944
=========
946
Sets ring sizes like ``ETHTOOL_SRINGPARAM`` ioctl request.
948
Request contents:
950
==================================== ====== ===========================
951
``ETHTOOL_A_RINGS_HEADER`` nested reply header
952
``ETHTOOL_A_RINGS_RX`` u32 size of RX ring
953
``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring
954
``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring
955
``ETHTOOL_A_RINGS_TX`` u32 size of TX ring
956
``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring
957
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split
958
``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE
959
``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode
960
``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode
961
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer
962
``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of header / data split
963
==================================== ====== ===========================
965
Kernel checks that requested ring sizes do not exceed limits reported by
966
driver. Driver may impose additional constraints and may not support all
967
attributes.
970
``ETHTOOL_A_RINGS_CQE_SIZE`` specifies the completion queue event size.
971
Completion queue events (CQE) are the events posted by NIC to indicate the
972
completion status of a packet when the packet is sent (like send success or
973
error) or received (like pointers to packet fragments). The CQE size parameter
974
enables to modify the CQE size other than default size if NIC supports it.
975
A bigger CQE can have more receive buffer pointers, and in turn the NIC can
976
transfer a bigger frame from wire. Based on the NIC hardware, the overall
977
completion queue size can be adjusted in the driver if CQE size is modified.
979
``ETHTOOL_A_RINGS_HDS_THRESH`` specifies the threshold value of
980
header / data split feature. If a received packet size is larger than this
981
threshold value, header and data will be split.
983
CHANNELS_GET
984
============
986
Gets channel counts like ``ETHTOOL_GCHANNELS`` ioctl request.
988
Request contents:
990
==================================== ====== ==========================
991
``ETHTOOL_A_CHANNELS_HEADER`` nested request header
992
==================================== ====== ==========================
994
Kernel response contents:
996
===================================== ====== ==========================
997
``ETHTOOL_A_CHANNELS_HEADER`` nested reply header
998
``ETHTOOL_A_CHANNELS_RX_MAX`` u32 max receive channels
999
``ETHTOOL_A_CHANNELS_TX_MAX`` u32 max transmit channels
1000
``ETHTOOL_A_CHANNELS_OTHER_MAX`` u32 max other channels
1001
``ETHTOOL_A_CHANNELS_COMBINED_MAX`` u32 max combined channels
1002
``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count
1003
``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count
1004
``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count
1005
``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count
1006
===================================== ====== ==========================
1009
CHANNELS_SET
1010
============
1012
Sets channel counts like ``ETHTOOL_SCHANNELS`` ioctl request.
1014
Request contents:
1016
===================================== ====== ==========================
1017
``ETHTOOL_A_CHANNELS_HEADER`` nested request header
1018
``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count
1019
``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count
1020
``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count
1021
``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count
1022
===================================== ====== ==========================
1024
Kernel checks that requested channel counts do not exceed limits reported by
1025
driver. Driver may impose additional constraints and may not support all
1026
attributes.
1029
COALESCE_GET
1030
============
1032
Gets coalescing parameters like ``ETHTOOL_GCOALESCE`` ioctl request.
1034
Request contents:
1036
==================================== ====== ==========================
1037
``ETHTOOL_A_COALESCE_HEADER`` nested request header
1038
==================================== ====== ==========================
1040
Kernel response contents:
1042
=========================================== ====== =======================
1043
``ETHTOOL_A_COALESCE_HEADER`` nested reply header
1044
``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx
1045
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx
1046
``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ
1047
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ
1048
``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx
1049
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx
1050
``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ
1051
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ
1052
``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update
1053
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce
1054
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce
1055
``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate
1056
``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx
1057
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx
1058
``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx
1059
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx
1060
``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate
1061
``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx
1062
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx
1063
``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx
1064
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx
1065
``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval
1066
``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx
1067
``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx
1068
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx
1069
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx
1070
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx
1071
``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx
1072
``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx
1073
=========================================== ====== =======================
1075
Attributes are only included in reply if their value is not zero or the
1076
corresponding bit in ``ethtool_ops::supported_coalesce_params`` is set (i.e.
1077
they are declared as supported by driver).
1079
Timer reset mode (``ETHTOOL_A_COALESCE_USE_CQE_TX`` and
1080
``ETHTOOL_A_COALESCE_USE_CQE_RX``) controls the interaction between packet
1081
arrival and the various time based delay parameters. By default timers are
1082
expected to limit the max delay between any packet arrival/departure and a
1083
corresponding interrupt. In this mode timer should be started by packet
1084
arrival (sometimes delivery of previous interrupt) and reset when interrupt
1085
is delivered.
1086
Setting the appropriate attribute to 1 will enable ``CQE`` mode, where
1087
each packet event resets the timer. In this mode timer is used to force
1088
the interrupt if queue goes idle, while busy queues depend on the packet
1089
limit to trigger interrupts.
1091
Tx aggregation consists of copying frames into a contiguous buffer so that they
1092
can be submitted as a single IO operation. ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES``
1093
describes the maximum size in bytes for the submitted buffer.
1094
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` describes the maximum number of frames
1095
that can be aggregated into a single buffer.
1096
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` describes the amount of time in usecs,
1097
counted since the first packet arrival in an aggregated block, after which the
1098
block should be sent.
1099
This feature is mainly of interest for specific USB devices which does not cope
1100
well with frequent small-sized URBs transmissions.
1102
``ETHTOOL_A_COALESCE_RX_PROFILE`` and ``ETHTOOL_A_COALESCE_TX_PROFILE`` refer
1103
to DIM parameters, see `Generic Network Dynamic Interrupt Moderation (Net DIM)
1104
<https://www.kernel.org/doc/Documentation/networking/net_dim.rst>`_.
1106
COALESCE_SET
1107
============
1109
Sets coalescing parameters like ``ETHTOOL_SCOALESCE`` ioctl request.
1111
Request contents:
1113
=========================================== ====== =======================
1114
``ETHTOOL_A_COALESCE_HEADER`` nested request header
1115
``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx
1116
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx
1117
``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ
1118
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ
1119
``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx
1120
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx
1121
``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ
1122
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ
1123
``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update
1124
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce
1125
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce
1126
``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate
1127
``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx
1128
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx
1129
``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx
1130
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx
1131
``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate
1132
``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx
1133
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx
1134
``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx
1135
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx
1136
``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval
1137
``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx
1138
``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx
1139
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx
1140
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx
1141
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx
1142
``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx
1143
``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx
1144
=========================================== ====== =======================
1146
Request is rejected if it attributes declared as unsupported by driver (i.e.
1147
such that the corresponding bit in ``ethtool_ops::supported_coalesce_params``
1148
is not set), regardless of their values. Driver may impose additional
1149
constraints on coalescing parameters and their values.
1151
Compared to requests issued via the ``ioctl()`` netlink version of this request
1152
will try harder to make sure that values specified by the user have been applied
1153
and may call the driver twice.
1156
PAUSE_GET
1157
=========
1159
Gets pause frame settings like ``ETHTOOL_GPAUSEPARAM`` ioctl request.
1161
Request contents:
1163
===================================== ====== ==========================
1164
``ETHTOOL_A_PAUSE_HEADER`` nested request header
1165
``ETHTOOL_A_PAUSE_STATS_SRC`` u32 source of statistics
1166
===================================== ====== ==========================
1168
``ETHTOOL_A_PAUSE_STATS_SRC`` is optional. It takes values from:
1170
.. kernel-doc:: include/uapi/linux/ethtool.h
1171
:identifiers: ethtool_mac_stats_src
1173
If absent from the request, stats will be provided with
1174
an ``ETHTOOL_A_PAUSE_STATS_SRC`` attribute in the response equal to
1175
``ETHTOOL_MAC_STATS_SRC_AGGREGATE``.
1177
Kernel response contents:
1179
===================================== ====== ==========================
1180
``ETHTOOL_A_PAUSE_HEADER`` nested request header
1181
``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation
1182
``ETHTOOL_A_PAUSE_RX`` bool receive pause frames
1183
``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames
1184
``ETHTOOL_A_PAUSE_STATS`` nested pause statistics
1185
===================================== ====== ==========================
1187
``ETHTOOL_A_PAUSE_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set
1188
in ``ETHTOOL_A_HEADER_FLAGS``.
1189
It will be empty if driver did not report any statistics. Drivers fill in
1190
the statistics in the following structure:
1192
.. kernel-doc:: include/linux/ethtool.h
1193
:identifiers: ethtool_pause_stats
1195
Each member has a corresponding attribute defined.
1197
PAUSE_SET
1198
=========
1200
Sets pause parameters like ``ETHTOOL_GPAUSEPARAM`` ioctl request.
1202
Request contents:
1204
===================================== ====== ==========================
1205
``ETHTOOL_A_PAUSE_HEADER`` nested request header
1206
``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation
1207
``ETHTOOL_A_PAUSE_RX`` bool receive pause frames
1208
``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames
1209
===================================== ====== ==========================
1212
EEE_GET
1213
=======
1215
Gets Energy Efficient Ethernet settings like ``ETHTOOL_GEEE`` ioctl request.
1217
Request contents:
1219
===================================== ====== ==========================
1220
``ETHTOOL_A_EEE_HEADER`` nested request header
1221
===================================== ====== ==========================
1223
Kernel response contents:
1225
===================================== ====== ==========================
1226
``ETHTOOL_A_EEE_HEADER`` nested request header
1227
``ETHTOOL_A_EEE_MODES_OURS`` bool supported/advertised modes
1228
``ETHTOOL_A_EEE_MODES_PEER`` bool peer advertised link modes
1229
``ETHTOOL_A_EEE_ACTIVE`` bool EEE is actively used
1230
``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled
1231
``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled
1232
``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us)
1233
===================================== ====== ==========================
1235
In ``ETHTOOL_A_EEE_MODES_OURS``, mask consists of link modes for which EEE is
1236
enabled, value of link modes for which EEE is advertised. Link modes for which
1237
peer advertises EEE are listed in ``ETHTOOL_A_EEE_MODES_PEER`` (no mask). The
1238
netlink interface allows reporting EEE status for all link modes but only
1239
first 32 are provided by the ``ethtool_ops`` callback.
1242
EEE_SET
1243
=======
1245
Sets Energy Efficient Ethernet parameters like ``ETHTOOL_SEEE`` ioctl request.
1247
Request contents:
1249
===================================== ====== ==========================
1250
``ETHTOOL_A_EEE_HEADER`` nested request header
1251
``ETHTOOL_A_EEE_MODES_OURS`` bool advertised modes
1252
``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled
1253
``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled
1254
``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us)
1255
===================================== ====== ==========================
1257
``ETHTOOL_A_EEE_MODES_OURS`` is used to either list link modes to advertise
1258
EEE for (if there is no mask) or specify changes to the list (if there is
1259
a mask). The netlink interface allows reporting EEE status for all link modes
1260
but only first 32 can be set at the moment as that is what the ``ethtool_ops``
1261
callback supports.
1264
TSINFO_GET
1265
==========
1267
Gets timestamping information like ``ETHTOOL_GET_TS_INFO`` ioctl request.
1269
Request contents:
1271
======================================== ====== ============================
1272
``ETHTOOL_A_TSINFO_HEADER`` nested request header
1273
``ETHTOOL_A_TSINFO_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
1274
======================================== ====== ============================
1276
Kernel response contents:
1278
===================================== ====== ==========================
1279
``ETHTOOL_A_TSINFO_HEADER`` nested request header
1280
``ETHTOOL_A_TSINFO_TIMESTAMPING`` bitset SO_TIMESTAMPING flags
1281
``ETHTOOL_A_TSINFO_TX_TYPES`` bitset supported Tx types
1282
``ETHTOOL_A_TSINFO_RX_FILTERS`` bitset supported Rx filters
1283
``ETHTOOL_A_TSINFO_PHC_INDEX`` u32 PTP hw clock index
1284
``ETHTOOL_A_TSINFO_STATS`` nested HW timestamping statistics
1285
===================================== ====== ==========================
1287
``ETHTOOL_A_TSINFO_PHC_INDEX`` is absent if there is no associated PHC (there
1288
is no special value for this case). The bitset attributes are omitted if they
1289
would be empty (no bit set).
1291
Additional hardware timestamping statistics response contents:
1293
================================================== ====== =====================
1294
``ETHTOOL_A_TS_STAT_TX_PKTS`` uint Packets with Tx
1295
HW timestamps
1296
``ETHTOOL_A_TS_STAT_TX_LOST`` uint Tx HW timestamp
1297
not arrived count
1298
``ETHTOOL_A_TS_STAT_TX_ERR`` uint HW error request
1299
Tx timestamp count
1300
``ETHTOOL_A_TS_STAT_TX_ONESTEP_PKTS_UNCONFIRMED`` uint Packets with one-step
1301
HW TX timestamps with
1302
unconfirmed delivery
1303
================================================== ====== =====================
1305
CABLE_TEST
1306
==========
1308
Start a cable test.
1310
Request contents:
1312
==================================== ====== ==========================
1313
``ETHTOOL_A_CABLE_TEST_HEADER`` nested request header
1314
==================================== ====== ==========================
1316
Notification contents:
1318
An Ethernet cable typically contains 1, 2 or 4 pairs. The length of
1319
the pair can only be measured when there is a fault in the pair and
1320
hence a reflection. Information about the fault may not be available,
1321
depending on the specific hardware. Hence the contents of the notify
1322
message are mostly optional. The attributes can be repeated an
1323
arbitrary number of times, in an arbitrary order, for an arbitrary
1324
number of pairs.
1326
The example shows the notification sent when the test is completed for
1327
a T2 cable, i.e. two pairs. One pair is OK and hence has no length
1328
information. The second pair has a fault and does have length
1329
information.
1331
+---------------------------------------------+--------+---------------------+
1332
| ``ETHTOOL_A_CABLE_TEST_HEADER`` | nested | reply header |
1333
+---------------------------------------------+--------+---------------------+
1334
| ``ETHTOOL_A_CABLE_TEST_STATUS`` | u8 | completed |
1335
+---------------------------------------------+--------+---------------------+
1336
| ``ETHTOOL_A_CABLE_TEST_NTF_NEST`` | nested | all the results |
1337
+-+-------------------------------------------+--------+---------------------+
1338
| | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test result |
1339
+-+-+-----------------------------------------+--------+---------------------+
1340
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
1341
+-+-+-----------------------------------------+--------+---------------------+
1342
| | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code |
1343
+-+-+-----------------------------------------+--------+---------------------+
1344
| | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test results |
1345
+-+-+-----------------------------------------+--------+---------------------+
1346
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
1347
+-+-+-----------------------------------------+--------+---------------------+
1348
| | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code |
1349
+-+-+-----------------------------------------+--------+---------------------+
1350
| | | ``ETHTOOL_A_CABLE_RESULT_SRC`` | u32 | information source |
1351
+-+-+-----------------------------------------+--------+---------------------+
1352
| | ``ETHTOOL_A_CABLE_NEST_FAULT_LENGTH`` | nested | cable length |
1353
+-+-+-----------------------------------------+--------+---------------------+
1354
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR`` | u8 | pair number |
1355
+-+-+-----------------------------------------+--------+---------------------+
1356
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_CM`` | u32 | length in cm |
1357
+-+-+-----------------------------------------+--------+---------------------+
1358
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_SRC`` | u32 | information source |
1359
+-+-+-----------------------------------------+--------+---------------------+
1362
CABLE_TEST TDR
1363
==============
1365
Start a cable test and report raw TDR data
1367
Request contents:
1369
+--------------------------------------------+--------+-----------------------+
1370
| ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header |
1371
+--------------------------------------------+--------+-----------------------+
1372
| ``ETHTOOL_A_CABLE_TEST_TDR_CFG`` | nested | test configuration |
1373
+-+------------------------------------------+--------+-----------------------+
1374
| | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | first data distance |
1375
+-+-+----------------------------------------+--------+-----------------------+
1376
| | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | last data distance |
1377
+-+-+----------------------------------------+--------+-----------------------+
1378
| | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step |
1379
+-+-+----------------------------------------+--------+-----------------------+
1380
| | ``ETHTOOL_A_CABLE_TEST_TDR_CFG_PAIR`` | u8 | pair to test |
1381
+-+-+----------------------------------------+--------+-----------------------+
1383
The ETHTOOL_A_CABLE_TEST_TDR_CFG is optional, as well as all members
1384
of the nest. All distances are expressed in centimeters. The PHY takes
1385
the distances as a guide, and rounds to the nearest distance it
1386
actually supports. If a pair is passed, only that one pair will be
1387
tested. Otherwise all pairs are tested.
1389
Notification contents:
1391
Raw TDR data is gathered by sending a pulse down the cable and
1392
recording the amplitude of the reflected pulse for a given distance.
1394
It can take a number of seconds to collect TDR data, especial if the
1395
full 100 meters is probed at 1 meter intervals. When the test is
1396
started a notification will be sent containing just
1397
ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value
1398
ETHTOOL_A_CABLE_TEST_NTF_STATUS_STARTED.
1400
When the test has completed a second notification will be sent
1401
containing ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value
1402
ETHTOOL_A_CABLE_TEST_NTF_STATUS_COMPLETED and the TDR data.
1404
The message may optionally contain the amplitude of the pulse send
1405
down the cable. This is measured in mV. A reflection should not be
1406
bigger than transmitted pulse.
1408
Before the raw TDR data should be an ETHTOOL_A_CABLE_TDR_NEST_STEP
1409
nest containing information about the distance along the cable for the
1410
first reading, the last reading, and the step between each
1411
reading. Distances are measured in centimeters. These should be the
1412
exact values the PHY used. These may be different to what the user
1413
requested, if the native measurement resolution is greater than 1 cm.
1415
For each step along the cable, a ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE is
1416
used to report the amplitude of the reflection for a given pair.
1418
+---------------------------------------------+--------+----------------------+
1419
| ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header |
1420
+---------------------------------------------+--------+----------------------+
1421
| ``ETHTOOL_A_CABLE_TEST_TDR_STATUS`` | u8 | completed |
1422
+---------------------------------------------+--------+----------------------+
1423
| ``ETHTOOL_A_CABLE_TEST_TDR_NTF_NEST`` | nested | all the results |
1424
+-+-------------------------------------------+--------+----------------------+
1425
| | ``ETHTOOL_A_CABLE_TDR_NEST_PULSE`` | nested | TX Pulse amplitude |
1426
+-+-+-----------------------------------------+--------+----------------------+
1427
| | | ``ETHTOOL_A_CABLE_PULSE_mV`` | s16 | Pulse amplitude |
1428
+-+-+-----------------------------------------+--------+----------------------+
1429
| | ``ETHTOOL_A_CABLE_NEST_STEP`` | nested | TDR step info |
1430
+-+-+-----------------------------------------+--------+----------------------+
1431
| | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | First data distance |
1432
+-+-+-----------------------------------------+--------+----------------------+
1433
| | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | Last data distance |
1434
+-+-+-----------------------------------------+--------+----------------------+
1435
| | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step|
1436
+-+-+-----------------------------------------+--------+----------------------+
1437
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
1438
+-+-+-----------------------------------------+--------+----------------------+
1439
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
1440
+-+-+-----------------------------------------+--------+----------------------+
1441
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
1442
+-+-+-----------------------------------------+--------+----------------------+
1443
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
1444
+-+-+-----------------------------------------+--------+----------------------+
1445
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
1446
+-+-+-----------------------------------------+--------+----------------------+
1447
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
1448
+-+-+-----------------------------------------+--------+----------------------+
1449
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
1450
+-+-+-----------------------------------------+--------+----------------------+
1451
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
1452
+-+-+-----------------------------------------+--------+----------------------+
1453
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
1454
+-+-+-----------------------------------------+--------+----------------------+
1456
TUNNEL_INFO
1457
===========
1459
Gets information about the tunnel state NIC is aware of.
1461
Request contents:
1463
===================================== ====== ==========================
1464
``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header
1465
===================================== ====== ==========================
1467
Kernel response contents:
1469
+---------------------------------------------+--------+---------------------+
1470
| ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header |
1471
+---------------------------------------------+--------+---------------------+
1472
| ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables |
1473
+-+-------------------------------------------+--------+---------------------+
1474
| | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table |
1475
+-+-+-----------------------------------------+--------+---------------------+
1476
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the |
1477
| | | | | table |
1478
+-+-+-----------------------------------------+--------+---------------------+
1479
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which |
1480
| | | | | table can hold |
1481
+-+-+-----------------------------------------+--------+---------------------+
1482
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port |
1483
+-+-+-+---------------------------------------+--------+---------------------+
1484
| | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port |
1485
+-+-+-+---------------------------------------+--------+---------------------+
1486
| | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type |
1487
+-+-+-+---------------------------------------+--------+---------------------+
1489
For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that
1490
the table contains static entries, hard-coded by the NIC.
1492
FEC_GET
1493
=======
1495
Gets FEC configuration and state like ``ETHTOOL_GFECPARAM`` ioctl request.
1497
Request contents:
1499
===================================== ====== ==========================
1500
``ETHTOOL_A_FEC_HEADER`` nested request header
1501
===================================== ====== ==========================
1503
Kernel response contents:
1505
===================================== ====== ==========================
1506
``ETHTOOL_A_FEC_HEADER`` nested request header
1507
``ETHTOOL_A_FEC_MODES`` bitset configured modes
1508
``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection
1509
``ETHTOOL_A_FEC_ACTIVE`` u32 index of active FEC mode
1510
``ETHTOOL_A_FEC_STATS`` nested FEC statistics
1511
===================================== ====== ==========================
1513
``ETHTOOL_A_FEC_ACTIVE`` is the bit index of the FEC link mode currently
1514
active on the interface. This attribute may not be present if device does
1515
not support FEC.
1517
``ETHTOOL_A_FEC_MODES`` and ``ETHTOOL_A_FEC_AUTO`` are only meaningful when
1518
autonegotiation is disabled. If ``ETHTOOL_A_FEC_AUTO`` is non-zero driver will
1519
select the FEC mode automatically based on the parameters of the SFP module.
1520
This is equivalent to the ``ETHTOOL_FEC_AUTO`` bit of the ioctl interface.
1521
``ETHTOOL_A_FEC_MODES`` carry the current FEC configuration using link mode
1522
bits (rather than old ``ETHTOOL_FEC_*`` bits).
1524
``ETHTOOL_A_FEC_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in
1525
``ETHTOOL_A_HEADER_FLAGS``.
1526
Each attribute carries an array of 64bit statistics. First entry in the array
1527
contains the total number of events on the port, while the following entries
1528
are counters corresponding to lanes/PCS instances. The number of entries in
1529
the array will be:
1531
+--------------+---------------------------------------------+
1532
| `0` | device does not support FEC statistics |
1533
+--------------+---------------------------------------------+
1534
| `1` | device does not support per-lane break down |
1535
+--------------+---------------------------------------------+
1536
| `1 + #lanes` | device has full support for FEC stats |
1537
+--------------+---------------------------------------------+
1539
Drivers fill in the statistics in the following structure:
1541
.. kernel-doc:: include/linux/ethtool.h
1542
:identifiers: ethtool_fec_stats
1544
Statistics may have FEC bins histogram attribute ``ETHTOOL_A_FEC_STAT_HIST``
1545
as defined in IEEE 802.3ck-2022 and 802.3df-2024. Nested attributes will have
1546
the range of FEC errors in the bin (inclusive) and the amount of error events
1547
in the bin.
1549
FEC_SET
1550
=======
1552
Sets FEC parameters like ``ETHTOOL_SFECPARAM`` ioctl request.
1554
Request contents:
1556
===================================== ====== ==========================
1557
``ETHTOOL_A_FEC_HEADER`` nested request header
1558
``ETHTOOL_A_FEC_MODES`` bitset configured modes
1559
``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection
1560
===================================== ====== ==========================
1562
``FEC_SET`` is only meaningful when autonegotiation is disabled. Otherwise
1563
FEC mode is selected as part of autonegotiation.
1565
``ETHTOOL_A_FEC_MODES`` selects which FEC mode should be used. It's recommended
1566
to set only one bit, if multiple bits are set driver may choose between them
1567
in an implementation specific way.
1569
``ETHTOOL_A_FEC_AUTO`` requests the driver to choose FEC mode based on SFP
1570
module parameters. This does not mean autonegotiation.
1572
MODULE_EEPROM_GET
1573
=================
1575
Fetch module EEPROM data dump.
1576
This interface is designed to allow dumps of at most 1/2 page at once. This
1577
means only dumps of 128 (or less) bytes are allowed, without crossing half page
1578
boundary located at offset 128. For pages other than 0 only high 128 bytes are
1579
accessible.
1581
Request contents:
1583
======================================= ====== ==========================
1584
``ETHTOOL_A_MODULE_EEPROM_HEADER`` nested request header
1585
``ETHTOOL_A_MODULE_EEPROM_OFFSET`` u32 offset within a page
1586
``ETHTOOL_A_MODULE_EEPROM_LENGTH`` u32 amount of bytes to read
1587
``ETHTOOL_A_MODULE_EEPROM_PAGE`` u8 page number
1588
``ETHTOOL_A_MODULE_EEPROM_BANK`` u8 bank number
1589
``ETHTOOL_A_MODULE_EEPROM_I2C_ADDRESS`` u8 page I2C address
1590
======================================= ====== ==========================
1592
If ``ETHTOOL_A_MODULE_EEPROM_BANK`` is not specified, bank 0 is assumed.
1594
Kernel response contents:
1596
+---------------------------------------------+--------+---------------------+
1597
| ``ETHTOOL_A_MODULE_EEPROM_HEADER`` | nested | reply header |
1598
+---------------------------------------------+--------+---------------------+
1599
| ``ETHTOOL_A_MODULE_EEPROM_DATA`` | binary | array of bytes from |
1600
| | | module EEPROM |
1601
+---------------------------------------------+--------+---------------------+
1603
``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of
1604
bytes driver actually read.
1606
STATS_GET
1607
=========
1609
Get standard statistics for the interface. Note that this is not
1610
a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined
1611
stats.
1613
Request contents:
1615
======================================= ====== ==========================
1616
``ETHTOOL_A_STATS_HEADER`` nested request header
1617
``ETHTOOL_A_STATS_SRC`` u32 source of statistics
1618
``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats
1619
======================================= ====== ==========================
1621
Kernel response contents:
1623
+-----------------------------------+--------+--------------------------------+
1624
| ``ETHTOOL_A_STATS_HEADER`` | nested | reply header |
1625
+-----------------------------------+--------+--------------------------------+
1626
| ``ETHTOOL_A_STATS_SRC`` | u32 | source of statistics |
1627
+-----------------------------------+--------+--------------------------------+
1628
| ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats |
1629
+-+---------------------------------+--------+--------------------------------+
1630
| | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` |
1631
+-+---------------------------------+--------+--------------------------------+
1632
| | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names |
1633
+-+---------------------------------+--------+--------------------------------+
1634
| | ``ETHTOOL_A_STATS_GRP_STAT`` | nested | nest containing a statistic |
1635
+-+---------------------------------+--------+--------------------------------+
1636
| | ``ETHTOOL_A_STATS_GRP_HIST_RX`` | nested | histogram statistic (Rx) |
1637
+-+---------------------------------+--------+--------------------------------+
1638
| | ``ETHTOOL_A_STATS_GRP_HIST_TX`` | nested | histogram statistic (Tx) |
1639
+-+---------------------------------+--------+--------------------------------+
1641
Users specify which groups of statistics they are requesting via
1642
the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are:
1644
====================== ======== ===============================================
1645
ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*)
1646
ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*)
1647
ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*)
1648
ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics
1649
ETHTOOL_STATS_PHY phy Additional PHY statistics, not defined by IEEE
1650
====================== ======== ===============================================
1652
Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply.
1653
``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains.
1654
``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of
1655
the statistics in the group, if available.
1657
Statistics are added to the ``ETHTOOL_A_STATS_GRP`` nest under
1658
``ETHTOOL_A_STATS_GRP_STAT``. ``ETHTOOL_A_STATS_GRP_STAT`` should contain
1659
single 8 byte (u64) attribute inside - the type of that attribute is
1660
the statistic ID and the value is the value of the statistic.
1661
Each group has its own interpretation of statistic IDs.
1662
Attribute IDs correspond to strings from the string set identified
1663
by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics (such as RMON histogram
1664
entries) are also listed inside ``ETHTOOL_A_STATS_GRP`` and do not have
1665
a string defined in the string set.
1667
RMON "histogram" counters count number of packets within given size range.
1668
Because RFC does not specify the ranges beyond the standard 1518 MTU devices
1669
differ in definition of buckets. For this reason the definition of packet ranges
1670
is left to each driver.
1672
``ETHTOOL_A_STATS_GRP_HIST_RX`` and ``ETHTOOL_A_STATS_GRP_HIST_TX`` nests
1673
contain the following attributes:
1675
================================= ====== ===================================
1676
ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket
1677
ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket
1678
ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter
1679
================================= ====== ===================================
1681
Low and high bounds are inclusive, for example:
1683
============================= ==== ====
1684
RFC statistic low high
1685
============================= ==== ====
1686
etherStatsPkts64Octets 0 64
1687
etherStatsPkts512to1023Octets 512 1023
1688
============================= ==== ====
1690
``ETHTOOL_A_STATS_SRC`` is optional. Similar to ``PAUSE_GET``, it takes values
1691
from ``enum ethtool_mac_stats_src``. If absent from the request, stats will be
1692
provided with an ``ETHTOOL_A_STATS_SRC`` attribute in the response equal to
1693
``ETHTOOL_MAC_STATS_SRC_AGGREGATE``.
1695
PHC_VCLOCKS_GET
1696
===============
1698
Query device PHC virtual clocks information.
1700
Request contents:
1702
==================================== ====== ==========================
1703
``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested request header
1704
==================================== ====== ==========================
1706
Kernel response contents:
1708
==================================== ====== ==========================
1709
``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested reply header
1710
``ETHTOOL_A_PHC_VCLOCKS_NUM`` u32 PHC virtual clocks number
1711
``ETHTOOL_A_PHC_VCLOCKS_INDEX`` s32 PHC index array
1712
==================================== ====== ==========================
1714
MODULE_GET
1715
==========
1717
Gets transceiver module parameters.
1719
Request contents:
1721
===================================== ====== ==========================
1722
``ETHTOOL_A_MODULE_HEADER`` nested request header
1723
===================================== ====== ==========================
1725
Kernel response contents:
1727
====================================== ====== ==========================
1728
``ETHTOOL_A_MODULE_HEADER`` nested reply header
1729
``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy
1730
``ETHTOOL_A_MODULE_POWER_MODE`` u8 operational power mode
1731
====================================== ====== ==========================
1733
The optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute encodes the
1734
transceiver module power mode policy enforced by the host. The default policy
1735
is driver-dependent, but "auto" is the recommended default and it should be
1736
implemented by new drivers and drivers where conformance to a legacy behavior
1737
is not critical.
1739
The optional ``ETHTHOOL_A_MODULE_POWER_MODE`` attribute encodes the operational
1740
power mode policy of the transceiver module. It is only reported when a module
1741
is plugged-in. Possible values are:
1743
.. kernel-doc:: include/uapi/linux/ethtool.h
1744
:identifiers: ethtool_module_power_mode
1746
MODULE_SET
1747
==========
1749
Sets transceiver module parameters.
1751
Request contents:
1753
====================================== ====== ==========================
1754
``ETHTOOL_A_MODULE_HEADER`` nested request header
1755
``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy
1756
====================================== ====== ==========================
1758
When set, the optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute is used
1759
to set the transceiver module power policy enforced by the host. Possible
1760
values are:
1762
.. kernel-doc:: include/uapi/linux/ethtool.h
1763
:identifiers: ethtool_module_power_mode_policy
1765
For SFF-8636 modules, low power mode is forced by the host according to table
1766
6-10 in revision 2.10a of the specification.
1768
For CMIS modules, low power mode is forced by the host according to table 6-12
1769
in revision 5.0 of the specification.
1771
PSE_GET
1772
=======
1774
Gets PSE attributes.
1776
Request contents:
1778
===================================== ====== ==========================
1779
``ETHTOOL_A_PSE_HEADER`` nested request header
1780
===================================== ====== ==========================
1782
Kernel response contents:
1784
========================================== ====== =============================
1785
``ETHTOOL_A_PSE_HEADER`` nested reply header
1786
``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` u32 Operational state of the PoDL
1787
PSE functions
1788
``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` u32 power detection status of the
1789
PoDL PSE.
1790
``ETHTOOL_A_C33_PSE_ADMIN_STATE`` u32 Operational state of the PoE
1791
PSE functions.
1792
``ETHTOOL_A_C33_PSE_PW_D_STATUS`` u32 power detection status of the
1793
PoE PSE.
1794
``ETHTOOL_A_C33_PSE_PW_CLASS`` u32 power class of the PoE PSE.
1795
``ETHTOOL_A_C33_PSE_ACTUAL_PW`` u32 actual power drawn on the
1796
PoE PSE.
1797
``ETHTOOL_A_C33_PSE_EXT_STATE`` u32 power extended state of the
1798
PoE PSE.
1799
``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` u32 power extended substatus of
1800
the PoE PSE.
1801
``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` u32 currently configured power
1802
limit of the PoE PSE.
1803
``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested Supported power limit
1804
configuration ranges.
1805
``ETHTOOL_A_PSE_PW_D_ID`` u32 Index of the PSE power domain
1806
``ETHTOOL_A_PSE_PRIO_MAX`` u32 Priority maximum configurable
1807
on the PoE PSE
1808
``ETHTOOL_A_PSE_PRIO`` u32 Priority of the PoE PSE
1809
currently configured
1810
========================================== ====== =============================
1812
When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` attribute identifies
1813
the operational state of the PoDL PSE functions. The operational state of the
1814
PSE function can be changed using the ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL``
1815
action. This attribute corresponds to ``IEEE 802.3-2018`` 30.15.1.1.2
1816
aPoDLPSEAdminState. Possible values are:
1818
.. kernel-doc:: include/uapi/linux/ethtool.h
1819
:identifiers: ethtool_podl_pse_admin_state
1821
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_STATE`` implementing
1822
``IEEE 802.3-2022`` 30.9.1.1.2 aPSEAdminState.
1824
.. kernel-doc:: include/uapi/linux/ethtool.h
1825
:identifiers: ethtool_c33_pse_admin_state
1827
When set, the optional ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` attribute identifies
1828
the power detection status of the PoDL PSE. The status depend on internal PSE
1829
state machine and automatic PD classification support. This attribute
1830
corresponds to ``IEEE 802.3-2018`` 30.15.1.1.3 aPoDLPSEPowerDetectionStatus.
1831
Possible values are:
1833
.. kernel-doc:: include/uapi/linux/ethtool.h
1834
:identifiers: ethtool_podl_pse_pw_d_status
1836
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_PW_D_STATUS`` implementing
1837
``IEEE 802.3-2022`` 30.9.1.1.5 aPSEPowerDetectionStatus.
1839
.. kernel-doc:: include/uapi/linux/ethtool.h
1840
:identifiers: ethtool_c33_pse_pw_d_status
1842
When set, the optional ``ETHTOOL_A_C33_PSE_PW_CLASS`` attribute identifies
1843
the power class of the C33 PSE. It depends on the class negotiated between
1844
the PSE and the PD. This attribute corresponds to ``IEEE 802.3-2022``
1845
30.9.1.1.8 aPSEPowerClassification.
1847
When set, the optional ``ETHTOOL_A_C33_PSE_ACTUAL_PW`` attribute identifies
1848
the actual power drawn by the C33 PSE. This attribute corresponds to
1849
``IEEE 802.3-2022`` 30.9.1.1.23 aPSEActualPower. Actual power is reported
1850
in mW.
1852
When set, the optional ``ETHTOOL_A_C33_PSE_EXT_STATE`` attribute identifies
1853
the extended error state of the C33 PSE. Possible values are:
1855
.. kernel-doc:: include/uapi/linux/ethtool.h
1856
:identifiers: ethtool_c33_pse_ext_state
1858
When set, the optional ``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` attribute identifies
1859
the extended error state of the C33 PSE. Possible values are:
1860
Possible values are:
1862
.. kernel-doc:: include/uapi/linux/ethtool.h
1863
:identifiers: ethtool_c33_pse_ext_substate_class_num_events
1864
ethtool_c33_pse_ext_substate_error_condition
1865
ethtool_c33_pse_ext_substate_mr_pse_enable
1866
ethtool_c33_pse_ext_substate_option_detect_ted
1867
ethtool_c33_pse_ext_substate_option_vport_lim
1868
ethtool_c33_pse_ext_substate_ovld_detected
1869
ethtool_c33_pse_ext_substate_pd_dll_power_type
1870
ethtool_c33_pse_ext_substate_power_not_available
1871
ethtool_c33_pse_ext_substate_short_detected
1873
When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` attribute
1874
identifies the C33 PSE power limit in mW.
1876
When set the optional ``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested attribute
1877
identifies the C33 PSE power limit ranges through
1878
``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MIN`` and
1879
``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MAX``.
1880
If the controller works with fixed classes, the min and max values will be
1881
equal.
1883
The ``ETHTOOL_A_PSE_PW_D_ID`` attribute identifies the index of PSE power
1884
domain.
1886
When set, the optional ``ETHTOOL_A_PSE_PRIO_MAX`` attribute identifies
1887
the PSE maximum priority value.
1888
When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to
1889
identifies the currently configured PSE priority.
1890
For a description of PSE priority attributes, see ``PSE_SET``.
1892
PSE_SET
1893
=======
1895
Sets PSE parameters.
1897
Request contents:
1899
====================================== ====== =============================
1900
``ETHTOOL_A_PSE_HEADER`` nested request header
1901
``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` u32 Control PoDL PSE Admin state
1902
``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` u32 Control PSE Admin state
1903
``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` u32 Control PoE PSE available
1904
power limit
1905
``ETHTOOL_A_PSE_PRIO`` u32 Control priority of the
1906
PoE PSE
1907
====================================== ====== =============================
1909
When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` attribute is used
1910
to control PoDL PSE Admin functions. This option implements
1911
``IEEE 802.3-2018`` 30.15.1.2.1 acPoDLPSEAdminControl. See
1912
``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` for supported values.
1914
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` implementing
1915
``IEEE 802.3-2022`` 30.9.1.2.1 acPSEAdminControl.
1917
When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` attribute is
1918
used to control the available power value limit for C33 PSE in milliwatts.
1919
This attribute corresponds to the `pse_available_power` variable described in
1920
``IEEE 802.3-2022`` 33.2.4.4 Variables and `pse_avail_pwr` in 145.2.5.4
1921
Variables, which are described in power classes.
1923
It was decided to use milliwatts for this interface to unify it with other
1924
power monitoring interfaces, which also use milliwatts, and to align with
1925
various existing products that document power consumption in watts rather than
1926
classes. If power limit configuration based on classes is needed, the
1927
conversion can be done in user space, for example by ethtool.
1929
When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to
1930
control the PSE priority. Allowed priority value are between zero and
1931
the value of ``ETHTOOL_A_PSE_PRIO_MAX`` attribute.
1933
A lower value indicates a higher priority, meaning that a priority value
1934
of 0 corresponds to the highest port priority.
1935
Port priority serves two functions:
1937
- Power-up Order: After a reset, ports are powered up in order of their
1938
priority from highest to lowest. Ports with higher priority
1939
(lower values) power up first.
1940
- Shutdown Order: When the power budget is exceeded, ports with lower
1941
priority (higher values) are turned off first.
1943
PSE_NTF
1944
=======
1946
Notify PSE events.
1948
Notification contents:
1950
=============================== ====== ========================
1951
``ETHTOOL_A_PSE_HEADER`` nested request header
1952
``ETHTOOL_A_PSE_EVENTS`` bitset PSE events
1953
=============================== ====== ========================
1955
When set, the optional ``ETHTOOL_A_PSE_EVENTS`` attribute identifies the
1956
PSE events.
1958
.. kernel-doc:: include/uapi/linux/ethtool_netlink_generated.h
1959
:identifiers: ethtool_pse_event
1961
RSS_GET
1962
=======
1964
Get indirection table, hash key and hash function info associated with a
1965
RSS context of an interface similar to ``ETHTOOL_GRSSH`` ioctl request.
1967
Request contents:
1969
===================================== ====== ============================
1970
``ETHTOOL_A_RSS_HEADER`` nested request header
1971
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
1972
``ETHTOOL_A_RSS_START_CONTEXT`` u32 start context number (dumps)
1973
===================================== ====== ============================
1975
``ETHTOOL_A_RSS_CONTEXT`` specifies which RSS context number to query,
1976
if not set context 0 (the main context) is queried. Dumps can be filtered
1977
by device (only listing contexts of a given netdev). Filtering single
1978
context number is not supported but ``ETHTOOL_A_RSS_START_CONTEXT``
1979
can be used to start dumping context from the given number (primarily
1980
used to ignore context 0s and only dump additional contexts).
1982
Kernel response contents:
1984
===================================== ====== ===============================
1985
``ETHTOOL_A_RSS_HEADER`` nested reply header
1986
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
1987
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
1988
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
1989
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
1990
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
1991
``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash
1992
===================================== ====== ===============================
1994
ETHTOOL_A_RSS_HFUNC attribute is bitmap indicating the hash function
1995
being used. Current supported options are toeplitz, xor or crc32.
1996
ETHTOOL_A_RSS_INDIR attribute returns RSS indirection table where each byte
1997
indicates queue number.
1998
ETHTOOL_A_RSS_INPUT_XFRM attribute is a bitmap indicating the type of
1999
transformation applied to the input protocol fields before given to the RSS
2000
hfunc. Current supported options are symmetric-xor and symmetric-or-xor.
2001
ETHTOOL_A_RSS_FLOW_HASH carries per-flow type bitmask of which header
2002
fields are included in the hash calculation.
2004
RSS_SET
2005
=======
2007
Request contents:
2009
===================================== ====== ==============================
2010
``ETHTOOL_A_RSS_HEADER`` nested request header
2011
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
2012
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
2013
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
2014
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
2015
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
2016
``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash
2017
===================================== ====== ==============================
2019
``ETHTOOL_A_RSS_INDIR`` is the minimal RSS table the user expects. Kernel and
2020
the device driver may replicate the table if its smaller than smallest table
2021
size supported by the device. For example if user requests ``[0, 1]`` but the
2022
device needs at least 8 entries - the real table in use will end up being
2023
``[0, 1, 0, 1, 0, 1, 0, 1]``. Most devices require the table size to be power
2024
of 2, so tables which size is not a power of 2 will likely be rejected.
2025
Using table of size 0 will reset the indirection table to the default.
2027
RSS_CREATE_ACT
2028
==============
2030
Request contents:
2032
===================================== ====== ==============================
2033
``ETHTOOL_A_RSS_HEADER`` nested request header
2034
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
2035
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
2036
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
2037
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
2038
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
2039
===================================== ====== ==============================
2041
Kernel response contents:
2043
===================================== ====== ==============================
2044
``ETHTOOL_A_RSS_HEADER`` nested request header
2045
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
2046
===================================== ====== ==============================
2048
Create an additional RSS context, if ``ETHTOOL_A_RSS_CONTEXT`` is not
2049
specified kernel will allocate one automatically.
2051
RSS_DELETE_ACT
2052
==============
2054
Request contents:
2056
===================================== ====== ==============================
2057
``ETHTOOL_A_RSS_HEADER`` nested request header
2058
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
2059
===================================== ====== ==============================
2061
Delete an additional RSS context.
2063
PLCA_GET_CFG
2064
============
2066
Gets the IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance
2067
(PLCA) Reconciliation Sublayer (RS) attributes.
2069
Request contents:
2071
===================================== ====== ==========================
2072
``ETHTOOL_A_PLCA_HEADER`` nested request header
2073
===================================== ====== ==========================
2075
Kernel response contents:
2077
====================================== ====== =============================
2078
``ETHTOOL_A_PLCA_HEADER`` nested reply header
2079
``ETHTOOL_A_PLCA_VERSION`` u16 Supported PLCA management
2080
interface standard/version
2081
``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State
2082
``ETHTOOL_A_PLCA_NODE_ID`` u32 PLCA unique local node ID
2083
``ETHTOOL_A_PLCA_NODE_CNT`` u32 Number of PLCA nodes on the
2084
network, including the
2085
coordinator
2086
``ETHTOOL_A_PLCA_TO_TMR`` u32 Transmit Opportunity Timer
2087
value in bit-times (BT)
2088
``ETHTOOL_A_PLCA_BURST_CNT`` u32 Number of additional packets
2089
the node is allowed to send
2090
within a single TO
2091
``ETHTOOL_A_PLCA_BURST_TMR`` u32 Time to wait for the MAC to
2092
transmit a new frame before
2093
terminating the burst
2094
====================================== ====== =============================
2096
When set, the optional ``ETHTOOL_A_PLCA_VERSION`` attribute indicates which
2097
standard and version the PLCA management interface complies to. When not set,
2098
the interface is vendor-specific and (possibly) supplied by the driver.
2099
The OPEN Alliance SIG specifies a standard register map for 10BASE-T1S PHYs
2100
embedding the PLCA Reconciliation Sublayer. See "10BASE-T1S PLCA Management
2101
Registers" at https://www.opensig.org/about/specifications/.
2103
When set, the optional ``ETHTOOL_A_PLCA_ENABLED`` attribute indicates the
2104
administrative state of the PLCA RS. When not set, the node operates in "plain"
2105
CSMA/CD mode. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.1
2106
aPLCAAdminState / 30.16.1.2.1 acPLCAAdminControl.
2108
When set, the optional ``ETHTOOL_A_PLCA_NODE_ID`` attribute indicates the
2109
configured local node ID of the PHY. This ID determines which transmit
2110
opportunity (TO) is reserved for the node to transmit into. This option is
2111
corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.4 aPLCALocalNodeID. The valid
2112
range for this attribute is [0 .. 255] where 255 means "not configured".
2114
When set, the optional ``ETHTOOL_A_PLCA_NODE_CNT`` attribute indicates the
2115
configured maximum number of PLCA nodes on the mixing-segment. This number
2116
determines the total number of transmit opportunities generated during a
2117
PLCA cycle. This attribute is relevant only for the PLCA coordinator, which is
2118
the node with aPLCALocalNodeID set to 0. Follower nodes ignore this setting.
2119
This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.3
2120
aPLCANodeCount. The valid range for this attribute is [1 .. 255].
2122
When set, the optional ``ETHTOOL_A_PLCA_TO_TMR`` attribute indicates the
2123
configured value of the transmit opportunity timer in bit-times. This value
2124
must be set equal across all nodes sharing the medium for PLCA to work
2125
correctly. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.5
2126
aPLCATransmitOpportunityTimer. The valid range for this attribute is
2127
[0 .. 255].
2129
When set, the optional ``ETHTOOL_A_PLCA_BURST_CNT`` attribute indicates the
2130
configured number of extra packets that the node is allowed to send during a
2131
single transmit opportunity. By default, this attribute is 0, meaning that
2132
the node can only send a single frame per TO. When greater than 0, the PLCA RS
2133
keeps the TO after any transmission, waiting for the MAC to send a new frame
2134
for up to aPLCABurstTimer BTs. This can only happen a number of times per PLCA
2135
cycle up to the value of this parameter. After that, the burst is over and the
2136
normal counting of TOs resumes. This option is corresponding to
2137
``IEEE 802.3cg-2019`` 30.16.1.1.6 aPLCAMaxBurstCount. The valid range for this
2138
attribute is [0 .. 255].
2140
When set, the optional ``ETHTOOL_A_PLCA_BURST_TMR`` attribute indicates how
2141
many bit-times the PLCA RS waits for the MAC to initiate a new transmission
2142
when aPLCAMaxBurstCount is greater than 0. If the MAC fails to send a new
2143
frame within this time, the burst ends and the counting of TOs resumes.
2144
Otherwise, the new frame is sent as part of the current burst. This option
2145
is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.7 aPLCABurstTimer. The
2146
valid range for this attribute is [0 .. 255]. Although, the value should be
2147
set greater than the Inter-Frame-Gap (IFG) time of the MAC (plus some margin)
2148
for PLCA burst mode to work as intended.
2150
PLCA_SET_CFG
2151
============
2153
Sets PLCA RS parameters.
2155
Request contents:
2157
====================================== ====== =============================
2158
``ETHTOOL_A_PLCA_HEADER`` nested request header
2159
``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State
2160
``ETHTOOL_A_PLCA_NODE_ID`` u8 PLCA unique local node ID
2161
``ETHTOOL_A_PLCA_NODE_CNT`` u8 Number of PLCA nodes on the
2162
network, including the
2163
coordinator
2164
``ETHTOOL_A_PLCA_TO_TMR`` u8 Transmit Opportunity Timer
2165
value in bit-times (BT)
2166
``ETHTOOL_A_PLCA_BURST_CNT`` u8 Number of additional packets
2167
the node is allowed to send
2168
within a single TO
2169
``ETHTOOL_A_PLCA_BURST_TMR`` u8 Time to wait for the MAC to
2170
transmit a new frame before
2171
terminating the burst
2172
====================================== ====== =============================
2174
For a description of each attribute, see ``PLCA_GET_CFG``.
2176
PLCA_GET_STATUS
2177
===============
2179
Gets PLCA RS status information.
2181
Request contents:
2183
===================================== ====== ==========================
2184
``ETHTOOL_A_PLCA_HEADER`` nested request header
2185
===================================== ====== ==========================
2187
Kernel response contents:
2189
====================================== ====== =============================
2190
``ETHTOOL_A_PLCA_HEADER`` nested reply header
2191
``ETHTOOL_A_PLCA_STATUS`` u8 PLCA RS operational status
2192
====================================== ====== =============================
2194
When set, the ``ETHTOOL_A_PLCA_STATUS`` attribute indicates whether the node is
2195
detecting the presence of the BEACON on the network. This flag is
2196
corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.2 aPLCAStatus.
2198
MM_GET
2199
======
2201
Retrieve 802.3 MAC Merge parameters.
2203
Request contents:
2205
==================================== ====== ==========================
2206
``ETHTOOL_A_MM_HEADER`` nested request header
2207
==================================== ====== ==========================
2209
Kernel response contents:
2211
================================= ====== ===================================
2212
``ETHTOOL_A_MM_HEADER`` nested request header
2213
``ETHTOOL_A_MM_PMAC_ENABLED`` bool set if RX of preemptible and SMD-V
2214
frames is enabled
2215
``ETHTOOL_A_MM_TX_ENABLED`` bool set if TX of preemptible frames is
2216
administratively enabled (might be
2217
inactive if verification failed)
2218
``ETHTOOL_A_MM_TX_ACTIVE`` bool set if TX of preemptible frames is
2219
operationally enabled
2220
``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 minimum size of transmitted
2221
non-final fragments, in octets
2222
``ETHTOOL_A_MM_RX_MIN_FRAG_SIZE`` u32 minimum size of received non-final
2223
fragments, in octets
2224
``ETHTOOL_A_MM_VERIFY_ENABLED`` bool set if TX of SMD-V frames is
2225
administratively enabled
2226
``ETHTOOL_A_MM_VERIFY_STATUS`` u8 state of the verification function
2227
``ETHTOOL_A_MM_VERIFY_TIME`` u32 delay between verification attempts
2228
``ETHTOOL_A_MM_MAX_VERIFY_TIME``` u32 maximum verification interval
2229
supported by device
2230
``ETHTOOL_A_MM_STATS`` nested IEEE 802.3-2018 subclause 30.14.1
2231
oMACMergeEntity statistics counters
2232
================================= ====== ===================================
2234
The attributes are populated by the device driver through the following
2235
structure:
2237
.. kernel-doc:: include/linux/ethtool.h
2238
:identifiers: ethtool_mm_state
2240
The ``ETHTOOL_A_MM_VERIFY_STATUS`` will report one of the values from
2242
.. kernel-doc:: include/uapi/linux/ethtool.h
2243
:identifiers: ethtool_mm_verify_status
2245
If ``ETHTOOL_A_MM_VERIFY_ENABLED`` was passed as false in the ``MM_SET``
2246
command, ``ETHTOOL_A_MM_VERIFY_STATUS`` will report either
2247
``ETHTOOL_MM_VERIFY_STATUS_INITIAL`` or ``ETHTOOL_MM_VERIFY_STATUS_DISABLED``,
2248
otherwise it should report one of the other states.
2250
It is recommended that drivers start with the pMAC disabled, and enable it upon
2251
user space request. It is also recommended that user space does not depend upon
2252
the default values from ``ETHTOOL_MSG_MM_GET`` requests.
2254
``ETHTOOL_A_MM_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in
2255
``ETHTOOL_A_HEADER_FLAGS``. The attribute will be empty if driver did not
2256
report any statistics. Drivers fill in the statistics in the following
2257
structure:
2259
.. kernel-doc:: include/linux/ethtool.h
2260
:identifiers: ethtool_mm_stats
2262
MM_SET
2263
======
2265
Modifies the configuration of the 802.3 MAC Merge layer.
2267
Request contents:
2269
================================= ====== ==========================
2270
``ETHTOOL_A_MM_VERIFY_TIME`` u32 see MM_GET description
2271
``ETHTOOL_A_MM_VERIFY_ENABLED`` bool see MM_GET description
2272
``ETHTOOL_A_MM_TX_ENABLED`` bool see MM_GET description
2273
``ETHTOOL_A_MM_PMAC_ENABLED`` bool see MM_GET description
2274
``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 see MM_GET description
2275
================================= ====== ==========================
2277
The attributes are propagated to the driver through the following structure:
2279
.. kernel-doc:: include/linux/ethtool.h
2280
:identifiers: ethtool_mm_cfg
2282
MODULE_FW_FLASH_ACT
2283
===================
2285
Flashes transceiver module firmware.
2287
Request contents:
2289
======================================= ====== ===========================
2290
``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` nested request header
2291
``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` string firmware image file name
2292
``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` u32 transceiver module password
2293
======================================= ====== ===========================
2295
The firmware update process consists of three logical steps:
2297
1. Downloading a firmware image to the transceiver module and validating it.
2298
2. Running the firmware image.
2299
3. Committing the firmware image so that it is run upon reset.
2301
When flash command is given, those three steps are taken in that order.
2303
This message merely schedules the update process and returns immediately
2304
without blocking. The process then runs asynchronously.
2305
Since it can take several minutes to complete, during the update process
2306
notifications are emitted from the kernel to user space updating it about
2307
the status and progress.
2309
The ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` attribute encodes the firmware
2310
image file name. The firmware image is downloaded to the transceiver module,
2311
validated, run and committed.
2313
The optional ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` attribute encodes a password
2314
that might be required as part of the transceiver module firmware update
2315
process.
2317
The firmware update process can take several minutes to complete. Therefore,
2318
during the update process notifications are emitted from the kernel to user
2319
space updating it about the status and progress.
2323
Notification contents:
2325
+---------------------------------------------------+--------+----------------+
2326
| ``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` | nested | reply header |
2327
+---------------------------------------------------+--------+----------------+
2328
| ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` | u32 | status |
2329
+---------------------------------------------------+--------+----------------+
2330
| ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` | string | status message |
2331
+---------------------------------------------------+--------+----------------+
2332
| ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` | uint | progress |
2333
+---------------------------------------------------+--------+----------------+
2334
| ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL`` | uint | total |
2335
+---------------------------------------------------+--------+----------------+
2337
The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` attribute encodes the current status
2338
of the firmware update process. Possible values are:
2340
.. kernel-doc:: include/uapi/linux/ethtool.h
2341
:identifiers: ethtool_module_fw_flash_status
2343
The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` attribute encodes a status message
2344
string.
2346
The ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` and ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL``
2347
attributes encode the completed and total amount of work, respectively.
2349
PHY_GET
2350
=======
2352
Retrieve information about a given Ethernet PHY sitting on the link. The DO
2353
operation returns all available information about dev->phydev. User can also
2354
specify a PHY_INDEX, in which case the DO request returns information about that
2355
specific PHY.
2357
As there can be more than one PHY, the DUMP operation can be used to list the PHYs
2358
present on a given interface, by passing an interface index or name in
2359
the dump request.
2361
For more information, refer to :ref:`phy_link_topology`
2363
Request contents:
2365
==================================== ====== ==========================
2366
``ETHTOOL_A_PHY_HEADER`` nested request header
2367
==================================== ====== ==========================
2369
Kernel response contents:
2371
===================================== ====== ===============================
2372
``ETHTOOL_A_PHY_HEADER`` nested request header
2373
``ETHTOOL_A_PHY_INDEX`` u32 the phy's unique index, that can
2374
be used for phy-specific
2375
requests
2376
``ETHTOOL_A_PHY_DRVNAME`` string the phy driver name
2377
``ETHTOOL_A_PHY_NAME`` string the phy device name
2378
``ETHTOOL_A_PHY_UPSTREAM_TYPE`` u32 the type of device this phy is
2379
connected to
2380
``ETHTOOL_A_PHY_UPSTREAM_INDEX`` u32 the PHY index of the upstream
2381
PHY
2382
``ETHTOOL_A_PHY_UPSTREAM_SFP_NAME`` string if this PHY is connected to
2383
its parent PHY through an SFP
2384
bus, the name of this sfp bus
2385
``ETHTOOL_A_PHY_DOWNSTREAM_SFP_NAME`` string if the phy controls an sfp bus,
2386
the name of the sfp bus
2387
===================================== ====== ===============================
2389
When ``ETHTOOL_A_PHY_UPSTREAM_TYPE`` is PHY_UPSTREAM_PHY, the PHY's parent is
2390
another PHY.
2392
TSCONFIG_GET
2393
============
2395
Retrieves the information about the current hardware timestamping source and
2396
configuration.
2398
It is similar to the deprecated ``SIOCGHWTSTAMP`` ioctl request.
2400
Request contents:
2402
==================================== ====== ==========================
2403
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
2404
==================================== ====== ==========================
2406
Kernel response contents:
2408
======================================== ====== ============================
2409
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
2410
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
2411
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
2412
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
2413
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
2414
======================================== ====== ============================
2416
When set the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` attribute identifies the
2417
source of the hw timestamping provider. It is composed by
2418
``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_INDEX`` attribute which describe the index of
2419
the PTP device and ``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_QUALIFIER`` which describe
2420
the qualifier of the timestamp.
2422
When set the ``ETHTOOL_A_TSCONFIG_TX_TYPES``, ``ETHTOOL_A_TSCONFIG_RX_FILTERS``
2423
and the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` attributes identify the Tx
2424
type, the Rx filter and the flags configured for the current hw timestamping
2425
provider. The attributes are propagated to the driver through the following
2426
structure:
2428
.. kernel-doc:: include/linux/net_tstamp.h
2429
:identifiers: kernel_hwtstamp_config
2431
TSCONFIG_SET
2432
============
2434
Set the information about the current hardware timestamping source and
2435
configuration.
2437
It is similar to the deprecated ``SIOCSHWTSTAMP`` ioctl request.
2439
Request contents:
2441
======================================== ====== ============================
2442
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
2443
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
2444
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
2445
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
2446
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
2447
======================================== ====== ============================
2449
Kernel response contents:
2451
======================================== ====== ============================
2452
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
2453
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
2454
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
2455
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
2456
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
2457
======================================== ====== ============================
2459
For a description of each attribute, see ``TSCONFIG_GET``.
2461
Request translation
2462
===================
2464
The following table maps ioctl commands to netlink commands providing their
2465
functionality. Entries with "n/a" in right column are commands which do not
2466
have their netlink replacement yet. Entries which "n/a" in the left column
2467
are netlink only.
2469
=================================== =====================================
2470
ioctl command netlink command
2471
=================================== =====================================
2472
``ETHTOOL_GSET`` ``ETHTOOL_MSG_LINKINFO_GET``
2473
``ETHTOOL_MSG_LINKMODES_GET``
2474
``ETHTOOL_SSET`` ``ETHTOOL_MSG_LINKINFO_SET``
2475
``ETHTOOL_MSG_LINKMODES_SET``
2476
``ETHTOOL_GDRVINFO`` n/a
2477
``ETHTOOL_GREGS`` n/a
2478
``ETHTOOL_GWOL`` ``ETHTOOL_MSG_WOL_GET``
2479
``ETHTOOL_SWOL`` ``ETHTOOL_MSG_WOL_SET``
2480
``ETHTOOL_GMSGLVL`` ``ETHTOOL_MSG_DEBUG_GET``
2481
``ETHTOOL_SMSGLVL`` ``ETHTOOL_MSG_DEBUG_SET``
2482
``ETHTOOL_NWAY_RST`` n/a
2483
``ETHTOOL_GLINK`` ``ETHTOOL_MSG_LINKSTATE_GET``
2484
``ETHTOOL_GEEPROM`` n/a
2485
``ETHTOOL_SEEPROM`` n/a
2486
``ETHTOOL_GCOALESCE`` ``ETHTOOL_MSG_COALESCE_GET``
2487
``ETHTOOL_SCOALESCE`` ``ETHTOOL_MSG_COALESCE_SET``
2488
``ETHTOOL_GRINGPARAM`` ``ETHTOOL_MSG_RINGS_GET``
2489
``ETHTOOL_SRINGPARAM`` ``ETHTOOL_MSG_RINGS_SET``
2490
``ETHTOOL_GPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_GET``
2491
``ETHTOOL_SPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_SET``
2492
``ETHTOOL_GRXCSUM`` ``ETHTOOL_MSG_FEATURES_GET``
2493
``ETHTOOL_SRXCSUM`` ``ETHTOOL_MSG_FEATURES_SET``
2494
``ETHTOOL_GTXCSUM`` ``ETHTOOL_MSG_FEATURES_GET``
2495
``ETHTOOL_STXCSUM`` ``ETHTOOL_MSG_FEATURES_SET``
2496
``ETHTOOL_GSG`` ``ETHTOOL_MSG_FEATURES_GET``
2497
``ETHTOOL_SSG`` ``ETHTOOL_MSG_FEATURES_SET``
2498
``ETHTOOL_TEST`` n/a
2499
``ETHTOOL_GSTRINGS`` ``ETHTOOL_MSG_STRSET_GET``
2500
``ETHTOOL_PHYS_ID`` n/a
2501
``ETHTOOL_GSTATS`` n/a
2502
``ETHTOOL_GTSO`` ``ETHTOOL_MSG_FEATURES_GET``
2503
``ETHTOOL_STSO`` ``ETHTOOL_MSG_FEATURES_SET``
2504
``ETHTOOL_GPERMADDR`` rtnetlink ``RTM_GETLINK``
2505
``ETHTOOL_GUFO`` ``ETHTOOL_MSG_FEATURES_GET``
2506
``ETHTOOL_SUFO`` ``ETHTOOL_MSG_FEATURES_SET``
2507
``ETHTOOL_GGSO`` ``ETHTOOL_MSG_FEATURES_GET``
2508
``ETHTOOL_SGSO`` ``ETHTOOL_MSG_FEATURES_SET``
2509
``ETHTOOL_GFLAGS`` ``ETHTOOL_MSG_FEATURES_GET``
2510
``ETHTOOL_SFLAGS`` ``ETHTOOL_MSG_FEATURES_SET``
2511
``ETHTOOL_GPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_GET``
2512
``ETHTOOL_SPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_SET``
2513
``ETHTOOL_GRXFH`` ``ETHTOOL_MSG_RSS_GET``
2514
``ETHTOOL_SRXFH`` ``ETHTOOL_MSG_RSS_SET``
2515
``ETHTOOL_GGRO`` ``ETHTOOL_MSG_FEATURES_GET``
2516
``ETHTOOL_SGRO`` ``ETHTOOL_MSG_FEATURES_SET``
2517
``ETHTOOL_GRXRINGS`` n/a
2518
``ETHTOOL_GRXCLSRLCNT`` n/a
2519
``ETHTOOL_GRXCLSRULE`` n/a
2520
``ETHTOOL_GRXCLSRLALL`` n/a
2521
``ETHTOOL_SRXCLSRLDEL`` n/a
2522
``ETHTOOL_SRXCLSRLINS`` n/a
2523
``ETHTOOL_FLASHDEV`` n/a
2524
``ETHTOOL_RESET`` n/a
2525
``ETHTOOL_SRXNTUPLE`` n/a
2526
``ETHTOOL_GRXNTUPLE`` n/a
2527
``ETHTOOL_GSSET_INFO`` ``ETHTOOL_MSG_STRSET_GET``
2528
``ETHTOOL_GRXFHINDIR`` ``ETHTOOL_MSG_RSS_GET``
2529
``ETHTOOL_SRXFHINDIR`` ``ETHTOOL_MSG_RSS_SET``
2530
``ETHTOOL_GFEATURES`` ``ETHTOOL_MSG_FEATURES_GET``
2531
``ETHTOOL_SFEATURES`` ``ETHTOOL_MSG_FEATURES_SET``
2532
``ETHTOOL_GCHANNELS`` ``ETHTOOL_MSG_CHANNELS_GET``
2533
``ETHTOOL_SCHANNELS`` ``ETHTOOL_MSG_CHANNELS_SET``
2534
``ETHTOOL_SET_DUMP`` n/a
2535
``ETHTOOL_GET_DUMP_FLAG`` n/a
2536
``ETHTOOL_GET_DUMP_DATA`` n/a
2537
``ETHTOOL_GET_TS_INFO`` ``ETHTOOL_MSG_TSINFO_GET``
2538
``ETHTOOL_GMODULEINFO`` ``ETHTOOL_MSG_MODULE_EEPROM_GET``
2539
``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET``
2540
``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET``
2541
``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET``
2542
``ETHTOOL_GRSSH`` ``ETHTOOL_MSG_RSS_GET``
2543
``ETHTOOL_SRSSH`` n/a
2544
``ETHTOOL_GTUNABLE`` n/a
2545
``ETHTOOL_STUNABLE`` n/a
2546
``ETHTOOL_GPHYSTATS`` n/a
2547
``ETHTOOL_PERQUEUE`` n/a
2548
``ETHTOOL_GLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_GET``
2549
``ETHTOOL_MSG_LINKMODES_GET``
2550
``ETHTOOL_SLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_SET``
2551
``ETHTOOL_MSG_LINKMODES_SET``
2552
``ETHTOOL_PHY_GTUNABLE`` n/a
2553
``ETHTOOL_PHY_STUNABLE`` n/a
2554
``ETHTOOL_GFECPARAM`` ``ETHTOOL_MSG_FEC_GET``
2555
``ETHTOOL_SFECPARAM`` ``ETHTOOL_MSG_FEC_SET``
2556
n/a ``ETHTOOL_MSG_CABLE_TEST_ACT``
2557
n/a ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT``
2558
n/a ``ETHTOOL_MSG_TUNNEL_INFO_GET``
2559
n/a ``ETHTOOL_MSG_PHC_VCLOCKS_GET``
2560
n/a ``ETHTOOL_MSG_MODULE_GET``
2561
n/a ``ETHTOOL_MSG_MODULE_SET``
2562
n/a ``ETHTOOL_MSG_PLCA_GET_CFG``
2563
n/a ``ETHTOOL_MSG_PLCA_SET_CFG``
2564
n/a ``ETHTOOL_MSG_PLCA_GET_STATUS``
2565
n/a ``ETHTOOL_MSG_MM_GET``
2566
n/a ``ETHTOOL_MSG_MM_SET``
2567
n/a ``ETHTOOL_MSG_MODULE_FW_FLASH_ACT``
2568
n/a ``ETHTOOL_MSG_PHY_GET``
2569
``SIOCGHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_GET``
2570
``SIOCSHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_SET``
2571
=================================== =====================================
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
기본 정보
1-29ethtool netlink 인터페이스는 generic netlink family `ethtool`을 사용합니다. 사용자 공간은 UAPI 헤더 `<linux/ethtool_netlink.h>`의 `ETHTOOL_GENL_NAME`과 `ETHTOOL_GENL_VERSION` 매크로를 사용해야 합니다. family 전용 헤더는 없으며 요청과 응답의 모든 정보는 netlink attribute로 전달됩니다.
오류와 경고는 extended ACK로 보고하므로 애플리케이션은 이 메시지를 사용자에게 적절히 보여 주는 것이 좋습니다. 요청은 정보 조회용 `get`, 파라미터 설정용 `set`, 동작 실행용 `action`으로 나뉩니다. 모든 set과 action은 해당 namespace의 `CAP_NET_ADMIN` 권한이 필요합니다. 대부분의 get은 누구나 쓸 수 있지만 민감한 정보가 있으면 권한을 요구하거나 WoL password 같은 attribute를 비권한 응답에서 생략합니다.
=============================
Netlink interface for ethtool
=============================
Basic information
=================
Netlink interface for ethtool uses generic netlink family ``ethtool``
(userspace application should use macros ``ETHTOOL_GENL_NAME`` and
``ETHTOOL_GENL_VERSION`` defined in ``<linux/ethtool_netlink.h>`` uapi
header). This family does not use a specific header, all information in
requests and replies is passed using netlink attributes.
The ethtool netlink interface uses extended ACK for error and warning
reporting, userspace application developers are encouraged to make these
messages available to user in a suitable way.
Requests can be divided into three categories: "get" (retrieving information),
"set" (setting parameters) and "action" (invoking an action).
All "set" and "action" type requests require admin privileges
(``CAP_NET_ADMIN`` in the namespace). Most "get" type requests are allowed for
anyone but there are exceptions (where the response contains sensitive
information). In some cases, the request as such is allowed for anyone but
unprivileged users have attributes with sensitive information (e.g.
wake-on-lan password) omitted.
표기 규칙
30-49boolean attribute는 보통 `NLA_U8`로 표현해 on, off, 미제공의 세 상태를 구분합니다. true를 보낼 때는 1을 쓰되 수신자는 0이 아닌 모든 값을 true로 해석합니다. 아래 표에서 `bool`은 이런 방식의 `NLA_U8`을 뜻합니다.
attribute 이름 뒤의 `+`는 부모 nest 안에 같은 유형의 attribute가 여러 개 올 수 있다는 뜻이며 배열을 구현합니다. 드라이버가 채우고 유효할 때만 사용자 공간으로 dump하는 값은 0을 유효값으로 쓰지 않는 것이 좋습니다. 그러면 별도 validity 신호가 필요하지 않습니다.
Conventions
===========
Attributes which represent a boolean value usually use NLA_U8 type so that we
can distinguish three states: "on", "off" and "not present" (meaning the
information is not available in "get" requests or value is not to be changed
in "set" requests). For these attributes, the "true" value should be passed as
number 1 but any non-zero value should be understood as "true" by recipient.
In the tables below, "bool" denotes NLA_U8 attributes interpreted in this way.
In the message structure descriptions below, if an attribute name is suffixed
with "+", parent nest can contain multiple attributes of the same type. This
implements an array of entries.
Attributes that need to be filled-in by device drivers and that are dumped to
user space based on whether they are valid or not should not use zero as a
valid value. This avoids the need to explicitly signal the validity of the
attribute in the device driver API.
공통 요청 헤더
50-91각 요청과 응답에는 공통 헤더 nest가 있습니다. `ETHTOOL_A_HEADER_DEV_INDEX`는 ifindex, `ETHTOOL_A_HEADER_DEV_NAME`은 장치 이름, `ETHTOOL_A_HEADER_FLAGS`는 공통 요청 flag, `ETHTOOL_A_HEADER_PHY_INDEX`는 PHY index입니다.
요청에서는 index나 name 중 하나만으로 장치를 지정할 수 있고 둘을 모두 보내면 같은 장치를 가리켜야 합니다. global string set처럼 장치 지정이 필요 없는 요청도 있습니다. 대부분의 GET은 장치 없이 dump 요청을 보내 지원하는 모든 장치의 응답을 메시지별로 받을 수 있습니다.
공통 flag는 `ETHTOOL_FLAG_COMPACT_BITSETS`(응답 bitset을 compact 형식으로), `ETHTOOL_FLAG_OMIT_REPLY`(SET/ACT의 선택 응답 생략), `ETHTOOL_FLAG_STATS`(선택 통계 포함)입니다. 새 flag는 설정하지 않았을 때 구형 client가 기대한 동작과 호환되어야 하며 client는 이해하지 못하는 flag를 설정하면 안 됩니다.
여러 PHY가 연결된 링크에서는 `ETHTOOL_A_HEADER_PHY_INDEX`로 대상 PHY를 고를 수 있습니다. 생략하면 PHY 대상 명령은 `net_device.phydev`를 사용합니다.
Request header
==============
Each request or reply message contains a nested attribute with common header.
Structure of this header is
============================== ====== =============================
``ETHTOOL_A_HEADER_DEV_INDEX`` u32 device ifindex
``ETHTOOL_A_HEADER_DEV_NAME`` string device name
``ETHTOOL_A_HEADER_FLAGS`` u32 flags common for all requests
``ETHTOOL_A_HEADER_PHY_INDEX`` u32 phy device index
============================== ====== =============================
``ETHTOOL_A_HEADER_DEV_INDEX`` and ``ETHTOOL_A_HEADER_DEV_NAME`` identify the
device message relates to. One of them is sufficient in requests, if both are
used, they must identify the same device. Some requests, e.g. global string
sets, do not require device identification. Most ``GET`` requests also allow
dump requests without device identification to query the same information for
all devices providing it (each device in a separate message).
``ETHTOOL_A_HEADER_FLAGS`` is a bitmap of request flags common for all request
types. The interpretation of these flags is the same for all request types but
the flags may not apply to requests. Recognized flags are:
================================= ===================================
``ETHTOOL_FLAG_COMPACT_BITSETS`` use compact format bitsets in reply
``ETHTOOL_FLAG_OMIT_REPLY`` omit optional reply (_SET and _ACT)
``ETHTOOL_FLAG_STATS`` include optional device statistics
================================= ===================================
New request flags should follow the general idea that if the flag is not set,
the behaviour is backward compatible, i.e. requests from old clients not aware
of the flag should be interpreted the way the client expects. A client must
not set flags it does not understand.
``ETHTOOL_A_HEADER_PHY_INDEX`` identifies the Ethernet PHY the message relates to.
As there are numerous commands that are related to PHY configuration, and because
there may be more than one PHY on the link, the PHY index can be passed in the
request for the commands that needs it. It is, however, not mandatory, and if it
is not passed for commands that target a PHY, the net_device.phydev pointer
is used.
Bit set 인코딩
92-175짧고 길이가 비교적 고정된 bitmap은 표준 `NLA_BITFIELD32`를 씁니다. 임의 길이는 compact 형식과 bit-by-bit 형식 중 하나를 담은 nested attribute로 표현합니다. compact는 값과 영향받는 bit의 mask를 binary bitmap 두 개로 보내고, verbose 형식은 index 또는 이름으로 식별한 bit 목록을 보냅니다.
verbose 형식은 symbolic name을 값과 함께 보내 일회성 ethtool 명령의 추가 왕복을 줄입니다. 장시간 실행하는 monitor나 관리 daemon은 이름을 한 번만 받은 뒤 compact 형식으로 메시지 크기를 줄일 수 있습니다. notification의 bitset은 항상 compact 형식입니다.
`ETHTOOL_A_BITSET_NOMASK`가 없으면 value/mask 쌍입니다. mask에 설정된 bit만 value대로 바꾸고 나머지는 보존합니다. NOMASK가 있으면 단일 bitmap으로 해석해 나열된 bit를 설정하고 나머지를 지웁니다.
compact nest에는 `NOMASK`, `SIZE`, `VALUE`, `MASK`가 있습니다. value와 mask는 SIZE를 32bit 배수로 올림한 길이 이상이어야 하고 host byte order의 32bit word를 least-significant word부터 배치합니다. SIZE와 VALUE는 필수이며 value/mask 쌍이면 MASK도 필수입니다. kernel과 사용자 공간 길이가 다를 때 사용자 bitmap이 더 길어도 kernel이 모르는 bit를 실제로 설정하려 할 때만 오류입니다.
bit-by-bit nest는 선택적 SIZE와 `BITS` 배열을 가지며 각 `BIT`은 `INDEX`, `NAME`, 설정 여부 `VALUE`로 표현합니다. index나 name이 유효하지 않으면 요청이 실패합니다. NOMASK 단일 bitmap에서는 BIT_VALUE를 쓰지 않습니다. 요청은 두 형식 모두 허용하고 응답 형식은 헤더의 `ETHTOOL_FLAG_COMPACT_BITSETS`가 정합니다.
Bit sets
========
For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32``
type is used. For arbitrary length bitmaps, ethtool netlink uses a nested
attribute with contents of one of two forms: compact (two binary bitmaps
representing bit values and mask of affected bits) and bit-by-bit (list of
bits identified by either index or name).
Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together
with their values which saves a round trip (when the bitset is passed in a
request) or at least a second request (when the bitset is in a reply). This is
useful for one shot applications like traditional ethtool command. On the
other hand, long running applications like ethtool monitor (displaying
notifications) or network management daemons may prefer fetching the names
only once and using compact form to save message size. Notifications from
ethtool netlink interface always use compact form for bitsets.
A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK``
not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests
modifying a bitmap, the former changes the bit set in mask to values set in
value and preserves the rest; the latter sets the bits set in the bitmap and
clears the rest.
Compact form: nested (bitset) attribute contents:
============================ ====== ============================
``ETHTOOL_A_BITSET_NOMASK`` flag no mask, only a list
``ETHTOOL_A_BITSET_SIZE`` u32 number of significant bits
``ETHTOOL_A_BITSET_VALUE`` binary bitmap of bit values
``ETHTOOL_A_BITSET_MASK`` binary bitmap of valid bits
============================ ====== ============================
Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits
rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte
order, words ordered from least significant to most significant (i.e. the same
way as bitmaps are passed with ioctl interface).
For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are
mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if
``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair);
if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not
allowed (bitset represents a single bitmap.
Kernel bit set length may differ from userspace length if older application is
used on newer kernel or vice versa. If userspace bitmap is longer, an error is
issued only if the request actually tries to set values of some bits not
recognized by kernel.
Bit-by-bit form: nested (bitset) attribute contents:
+------------------------------------+--------+-----------------------------+
| ``ETHTOOL_A_BITSET_NOMASK`` | flag | no mask, only a list |
+------------------------------------+--------+-----------------------------+
| ``ETHTOOL_A_BITSET_SIZE`` | u32 | number of significant bits |
+------------------------------------+--------+-----------------------------+
| ``ETHTOOL_A_BITSET_BITS`` | nested | array of bits |
+-+----------------------------------+--------+-----------------------------+
| | ``ETHTOOL_A_BITSET_BITS_BIT+`` | nested | one bit |
+-+-+--------------------------------+--------+-----------------------------+
| | | ``ETHTOOL_A_BITSET_BIT_INDEX`` | u32 | bit index (0 for LSB) |
+-+-+--------------------------------+--------+-----------------------------+
| | | ``ETHTOOL_A_BITSET_BIT_NAME`` | string | bit name |
+-+-+--------------------------------+--------+-----------------------------+
| | | ``ETHTOOL_A_BITSET_BIT_VALUE`` | flag | present if bit is set |
+-+-+--------------------------------+--------+-----------------------------+
Bit size is optional for bit-by-bit form. ``ETHTOOL_A_BITSET_BITS`` nest can
only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an
arbitrary number of them. A bit may be identified by its index or by its
name. When used in requests, listed bits are set to 0 or 1 according to
``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved. A request fails if
index exceeds kernel bit length or if name is not recognized.
When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as
a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in
such case. Such bitset represents a bitmap with listed bits set and the rest
zero.
In requests, application can use either form. Form used by kernel in reply is
determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request
header. Semantics of value and mask depends on the attribute.
메시지 유형
176-334메시지 상수는 `ETHTOOL_CMD_` 접두사와 목적별 suffix를 사용합니다. `_GET`, `_SET`, `_ACT`는 사용자 공간 요청이고 `_GET_REPLY`, `_SET_REPLY`, `_ACT_REPLY`는 kernel 응답, `_NTF`는 notification입니다. 문서 표는 string set, link 정보와 mode/state, debug, WoL, feature/private flag, ring/channel/coalesce/pause/EEE, timestamp, cable/TDR, tunnel/FEC/module/statistics/PHC, PSE/RSS/PLCA/MAC Merge, firmware flash, PHY와 timestamp 구성의 양방향 명령을 모두 열거합니다.
GET은 보통 명령별 attribute 없이 정보를 요청하며 kernel은 GET_REPLY로 답합니다. 많은 유형은 장치 식별 없는 `NLM_F_DUMP`로 모든 지원 장치를 조회할 수 있습니다. 변경 가능한 데이터는 GET_REPLY와 같은 layout의 SET으로 보내되 바꿀 attribute만 포함합니다.
대부분의 SET 응답은 error code와 extack뿐입니다. 추가 데이터가 있으면 SET_REPLY로 오며 `ETHTOOL_FLAG_OMIT_REPLY`로 생략할 수 있습니다. 변경은 영향받은 일부 attribute를 담은 NTF도 발생시킵니다. ioctl에서 시작한 notification은 실제 변화가 없어도 올 수 있지만 netlink 변경 notification은 값이 실제로 바뀔 때만 옵니다.
ACT는 kernel 또는 driver에 특정 동작을 요청합니다. 선택 결과는 ACT_REPLY로 오고 Omit Reply로 억제할 수 있으며, 동작 실행도 NTF를 발생시킵니다.
List of message types
=====================
All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix
according to message purpose:
============== ======================================
``_GET`` userspace request to retrieve data
``_SET`` userspace request to set data
``_ACT`` userspace request to perform an action
``_GET_REPLY`` kernel reply to a ``GET`` request
``_SET_REPLY`` kernel reply to a ``SET`` request
``_ACT_REPLY`` kernel reply to an ``ACT`` request
``_NTF`` kernel notification
============== ======================================
Userspace to kernel:
===================================== =================================
``ETHTOOL_MSG_STRSET_GET`` get string set
``ETHTOOL_MSG_LINKINFO_GET`` get link settings
``ETHTOOL_MSG_LINKINFO_SET`` set link settings
``ETHTOOL_MSG_LINKMODES_GET`` get link modes info
``ETHTOOL_MSG_LINKMODES_SET`` set link modes info
``ETHTOOL_MSG_LINKSTATE_GET`` get link state
``ETHTOOL_MSG_DEBUG_GET`` get debugging settings
``ETHTOOL_MSG_DEBUG_SET`` set debugging settings
``ETHTOOL_MSG_WOL_GET`` get wake-on-lan settings
``ETHTOOL_MSG_WOL_SET`` set wake-on-lan settings
``ETHTOOL_MSG_FEATURES_GET`` get device features
``ETHTOOL_MSG_FEATURES_SET`` set device features
``ETHTOOL_MSG_PRIVFLAGS_GET`` get private flags
``ETHTOOL_MSG_PRIVFLAGS_SET`` set private flags
``ETHTOOL_MSG_RINGS_GET`` get ring sizes
``ETHTOOL_MSG_RINGS_SET`` set ring sizes
``ETHTOOL_MSG_CHANNELS_GET`` get channel counts
``ETHTOOL_MSG_CHANNELS_SET`` set channel counts
``ETHTOOL_MSG_COALESCE_GET`` get coalescing parameters
``ETHTOOL_MSG_COALESCE_SET`` set coalescing parameters
``ETHTOOL_MSG_PAUSE_GET`` get pause parameters
``ETHTOOL_MSG_PAUSE_SET`` set pause parameters
``ETHTOOL_MSG_EEE_GET`` get EEE settings
``ETHTOOL_MSG_EEE_SET`` set EEE settings
``ETHTOOL_MSG_TSINFO_GET`` get timestamping info
``ETHTOOL_MSG_CABLE_TEST_ACT`` action start cable test
``ETHTOOL_MSG_CABLE_TEST_TDR_ACT`` action start raw TDR cable test
``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info
``ETHTOOL_MSG_FEC_GET`` get FEC settings
``ETHTOOL_MSG_FEC_SET`` set FEC settings
``ETHTOOL_MSG_MODULE_EEPROM_GET`` read SFP module EEPROM
``ETHTOOL_MSG_STATS_GET`` get standard statistics
``ETHTOOL_MSG_PHC_VCLOCKS_GET`` get PHC virtual clocks info
``ETHTOOL_MSG_MODULE_SET`` set transceiver module parameters
``ETHTOOL_MSG_MODULE_GET`` get transceiver module parameters
``ETHTOOL_MSG_PSE_SET`` set PSE parameters
``ETHTOOL_MSG_PSE_GET`` get PSE parameters
``ETHTOOL_MSG_RSS_GET`` get RSS settings
``ETHTOOL_MSG_PLCA_GET_CFG`` get PLCA RS parameters
``ETHTOOL_MSG_PLCA_SET_CFG`` set PLCA RS parameters
``ETHTOOL_MSG_PLCA_GET_STATUS`` get PLCA RS status
``ETHTOOL_MSG_MM_GET`` get MAC merge layer state
``ETHTOOL_MSG_MM_SET`` set MAC merge layer parameters
``ETHTOOL_MSG_MODULE_FW_FLASH_ACT`` flash transceiver module firmware
``ETHTOOL_MSG_PHY_GET`` get Ethernet PHY information
``ETHTOOL_MSG_TSCONFIG_GET`` get hw timestamping configuration
``ETHTOOL_MSG_TSCONFIG_SET`` set hw timestamping configuration
``ETHTOOL_MSG_RSS_SET`` set RSS settings
``ETHTOOL_MSG_RSS_CREATE_ACT`` create an additional RSS context
``ETHTOOL_MSG_RSS_DELETE_ACT`` delete an additional RSS context
===================================== =================================
Kernel to userspace:
======================================== =================================
``ETHTOOL_MSG_STRSET_GET_REPLY`` string set contents
``ETHTOOL_MSG_LINKINFO_GET_REPLY`` link settings
``ETHTOOL_MSG_LINKINFO_NTF`` link settings notification
``ETHTOOL_MSG_LINKMODES_GET_REPLY`` link modes info
``ETHTOOL_MSG_LINKMODES_NTF`` link modes notification
``ETHTOOL_MSG_LINKSTATE_GET_REPLY`` link state info
``ETHTOOL_MSG_DEBUG_GET_REPLY`` debugging settings
``ETHTOOL_MSG_DEBUG_NTF`` debugging settings notification
``ETHTOOL_MSG_WOL_GET_REPLY`` wake-on-lan settings
``ETHTOOL_MSG_WOL_NTF`` wake-on-lan settings notification
``ETHTOOL_MSG_FEATURES_GET_REPLY`` device features
``ETHTOOL_MSG_FEATURES_SET_REPLY`` optional reply to FEATURES_SET
``ETHTOOL_MSG_FEATURES_NTF`` netdev features notification
``ETHTOOL_MSG_PRIVFLAGS_GET_REPLY`` private flags
``ETHTOOL_MSG_PRIVFLAGS_NTF`` private flags
``ETHTOOL_MSG_RINGS_GET_REPLY`` ring sizes
``ETHTOOL_MSG_RINGS_NTF`` ring sizes
``ETHTOOL_MSG_CHANNELS_GET_REPLY`` channel counts
``ETHTOOL_MSG_CHANNELS_NTF`` channel counts
``ETHTOOL_MSG_COALESCE_GET_REPLY`` coalescing parameters
``ETHTOOL_MSG_COALESCE_NTF`` coalescing parameters
``ETHTOOL_MSG_PAUSE_GET_REPLY`` pause parameters
``ETHTOOL_MSG_PAUSE_NTF`` pause parameters
``ETHTOOL_MSG_EEE_GET_REPLY`` EEE settings
``ETHTOOL_MSG_EEE_NTF`` EEE settings
``ETHTOOL_MSG_TSINFO_GET_REPLY`` timestamping info
``ETHTOOL_MSG_CABLE_TEST_NTF`` Cable test results
``ETHTOOL_MSG_CABLE_TEST_TDR_NTF`` Cable test TDR results
``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info
``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings
``ETHTOOL_MSG_FEC_NTF`` FEC settings
``ETHTOOL_MSG_MODULE_EEPROM_GET_REPLY`` read SFP module EEPROM
``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics
``ETHTOOL_MSG_PHC_VCLOCKS_GET_REPLY`` PHC virtual clocks info
``ETHTOOL_MSG_MODULE_GET_REPLY`` transceiver module parameters
``ETHTOOL_MSG_PSE_GET_REPLY`` PSE parameters
``ETHTOOL_MSG_RSS_GET_REPLY`` RSS settings
``ETHTOOL_MSG_RSS_NTF`` RSS settings
``ETHTOOL_MSG_PLCA_GET_CFG_REPLY`` PLCA RS parameters
``ETHTOOL_MSG_PLCA_GET_STATUS_REPLY`` PLCA RS status
``ETHTOOL_MSG_PLCA_NTF`` PLCA RS parameters
``ETHTOOL_MSG_MM_GET_REPLY`` MAC merge layer status
``ETHTOOL_MSG_MODULE_FW_FLASH_NTF`` transceiver module flash updates
``ETHTOOL_MSG_PHY_GET_REPLY`` Ethernet PHY information
``ETHTOOL_MSG_PHY_NTF`` Ethernet PHY information change
``ETHTOOL_MSG_TSCONFIG_GET_REPLY`` hw timestamping configuration
``ETHTOOL_MSG_TSCONFIG_SET_REPLY`` new hw timestamping configuration
``ETHTOOL_MSG_PSE_NTF`` PSE events notification
``ETHTOOL_MSG_RSS_NTF`` RSS settings notification
``ETHTOOL_MSG_RSS_CREATE_ACT_REPLY`` create an additional RSS context
``ETHTOOL_MSG_RSS_CREATE_NTF`` additional RSS context created
``ETHTOOL_MSG_RSS_DELETE_NTF`` additional RSS context deleted
======================================== =================================
``GET`` requests are sent by userspace applications to retrieve device
information. They usually do not contain any message specific attributes.
Kernel replies with corresponding "GET_REPLY" message. For most types, ``GET``
request with ``NLM_F_DUMP`` and no device identification can be used to query
the information for all devices supporting the request.
If the data can be also modified, corresponding ``SET`` message with the same
layout as corresponding ``GET_REPLY`` is used to request changes. Only
attributes where a change is requested are included in such request (also, not
all attributes may be changed). Replies to most ``SET`` request consist only
of error code and extack; if kernel provides additional data, it is sent in
the form of corresponding ``SET_REPLY`` message which can be suppressed by
setting ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header.
Data modification also triggers sending a ``NTF`` message with a notification.
These usually bear only a subset of attributes which was affected by the
change. The same notification is issued if the data is modified using other
means (mostly ioctl ethtool interface). Unlike notifications from ethtool
netlink code which are only sent if something actually changed, notifications
triggered by ioctl interface may be sent even if the request did not actually
change any data.
``ACT`` messages request kernel (driver) to perform a specific action. If some
information is reported by kernel (which can be suppressed by setting
``ETHTOOL_FLAG_OMIT_REPLY`` flag in request header), the reply takes form of
an ``ACT_REPLY`` message. Performing an action also triggers a notification
(``NTF`` message).
Later sections describe the format and semantics of these messages.
STRSET_GET
335-393`STRSET_GET`은 ioctl의 `ETHTOOL_GSSET_INFO`와 `ETHTOOL_GSTRINGS`가 제공하는 string set을 조회합니다. set은 사용자 쓰기가 불가능하고 `STRSET_SET`은 kernel 응답에만 씁니다. 장치와 무관한 feature name 같은 global set과 private flag 같은 장치별 set이 있습니다.
요청은 공통 HEADER와 선택할 `STRINGSETS` 배열을 담고 각 항목은 `STRINGSET_ID`입니다. 응답은 set ID, string count, index/value 쌍의 string 배열을 반환합니다. `COUNTS_ONLY`면 실제 문자열 없이 개수만 받습니다.
장치 없음+비dump는 global set, 장치 지정+비dump는 그 장치의 set, 장치 없음+dump는 모든 장치별 set을 조회합니다. 요청 배열을 생략하면 해당 유형의 모든 set을 반환합니다.
STRSET_GET
==========
Requests contents of a string set as provided by ioctl commands
``ETHTOOL_GSSET_INFO`` and ``ETHTOOL_GSTRINGS.`` String sets are not user
writeable so that the corresponding ``STRSET_SET`` message is only used in
kernel replies. There are two types of string sets: global (independent of
a device, e.g. device feature names) and device specific (e.g. device private
flags).
Request contents:
+---------------------------------------+--------+------------------------+
| ``ETHTOOL_A_STRSET_HEADER`` | nested | request header |
+---------------------------------------+--------+------------------------+
| ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | string set to request |
+-+-------------------------------------+--------+------------------------+
| | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set |
+-+-+-----------------------------------+--------+------------------------+
| | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id |
+-+-+-----------------------------------+--------+------------------------+
Kernel response contents:
+---------------------------------------+--------+-----------------------+
| ``ETHTOOL_A_STRSET_HEADER`` | nested | reply header |
+---------------------------------------+--------+-----------------------+
| ``ETHTOOL_A_STRSET_STRINGSETS`` | nested | array of string sets |
+-+-------------------------------------+--------+-----------------------+
| | ``ETHTOOL_A_STRINGSETS_STRINGSET+`` | nested | one string set |
+-+-+-----------------------------------+--------+-----------------------+
| | | ``ETHTOOL_A_STRINGSET_ID`` | u32 | set id |
+-+-+-----------------------------------+--------+-----------------------+
| | | ``ETHTOOL_A_STRINGSET_COUNT`` | u32 | number of strings |
+-+-+-----------------------------------+--------+-----------------------+
| | | ``ETHTOOL_A_STRINGSET_STRINGS`` | nested | array of strings |
+-+-+-+---------------------------------+--------+-----------------------+
| | | | ``ETHTOOL_A_STRINGS_STRING+`` | nested | one string |
+-+-+-+-+-------------------------------+--------+-----------------------+
| | | | | ``ETHTOOL_A_STRING_INDEX`` | u32 | string index |
+-+-+-+-+-------------------------------+--------+-----------------------+
| | | | | ``ETHTOOL_A_STRING_VALUE`` | string | string value |
+-+-+-+-+-------------------------------+--------+-----------------------+
| ``ETHTOOL_A_STRSET_COUNTS_ONLY`` | flag | return only counts |
+---------------------------------------+--------+-----------------------+
Device identification in request header is optional. Depending on its presence
a and ``NLM_F_DUMP`` flag, there are three type of ``STRSET_GET`` requests:
- no ``NLM_F_DUMP,`` no device: get "global" stringsets
- no ``NLM_F_DUMP``, with device: get string sets related to the device
- ``NLM_F_DUMP``, no device: get device related string sets for all devices
If there is no ``ETHTOOL_A_STRSET_STRINGSETS`` array, all string sets of
requested type are returned, otherwise only those specified in the request.
Flag ``ETHTOOL_A_STRSET_COUNTS_ONLY`` tells kernel to only return string
counts of the sets, not the actual strings.
LINKINFO_GET과 LINKINFO_SET
394-443`LINKINFO_GET`은 `ETHTOOL_GLINKSETTINGS` 중 link mode와 autonegotiation을 제외한 정보를 조회합니다. 응답은 물리 port, PHY MDIO address, MDI(-X) status/control, transceiver를 포함하며 ioctl 구조체의 대응 필드와 의미가 같습니다. 모든 장치 dump를 지원합니다.
`LINKINFO_SET`은 physical port, PHY address, MDI(-X) control을 바꿀 수 있습니다. MDI(-X) status와 transceiver는 설정할 수 없으며 해당 attribute를 보내면 거부됩니다.
LINKINFO_GET
============
Requests link settings as provided by ``ETHTOOL_GLINKSETTINGS`` except for
link modes and autonegotiation related information. The request does not use
any attributes.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_LINKINFO_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_LINKINFO_HEADER`` nested reply header
``ETHTOOL_A_LINKINFO_PORT`` u8 physical port
``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address
``ETHTOOL_A_LINKINFO_TP_MDIX`` u8 MDI(-X) status
``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control
``ETHTOOL_A_LINKINFO_TRANSCEIVER`` u8 transceiver
==================================== ====== ==========================
Attributes and their values have the same meaning as matching members of the
corresponding ioctl structures.
``LINKINFO_GET`` allows dump requests (kernel returns reply message for all
devices supporting the request).
LINKINFO_SET
============
``LINKINFO_SET`` request allows setting some of the attributes reported by
``LINKINFO_GET``.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_LINKINFO_HEADER`` nested request header
``ETHTOOL_A_LINKINFO_PORT`` u8 physical port
``ETHTOOL_A_LINKINFO_PHYADDR`` u8 phy MDIO address
``ETHTOOL_A_LINKINFO_TP_MDIX_CTRL`` u8 MDI(-X) control
==================================== ====== ==========================
MDI(-X) status and transceiver cannot be set, request with the corresponding
attributes is rejected.
LINKMODES_GET과 LINKMODES_SET
444-505`LINKMODES_GET`은 `ETHTOOL_GLINKSETTINGS`의 지원·광고·peer 광고 mode와 autonegotiation, 속도, duplex, master/slave 구성·상태, PHY rate matching을 반환합니다. `OURS` value는 광고 mode이고 mask는 지원 mode이며 `PEER`는 단일 bit list입니다. 모든 장치 dump를 지원합니다.
`LINKMODES_SET`은 autonegotiation, 광고 mode, 속도, duplex, master/slave 구성, rate matching, lane 수를 설정합니다. autonegotiation이 켜져 있고 OURS를 직접 보내지 않은 채 speed/duplex/lanes 중 하나를 지정하면 kernel이 지원 mode 중 조건에 맞는 모든 광고 mode를 자동 선택합니다. 이는 사용자 공간이 kernel 지원 집합을 미리 몰라도 변경을 요청할 수 있게 합니다.
LINKMODES_GET
=============
Requests link modes (supported, advertised and peer advertised) and related
information (autonegotiation status, link speed and duplex) as provided by
``ETHTOOL_GLINKSETTINGS``. The request does not use any attributes.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_LINKMODES_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
========================================== ====== ==========================
``ETHTOOL_A_LINKMODES_HEADER`` nested reply header
``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status
``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes
``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes
``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s)
``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_STATE`` u8 Master/slave port state
``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching
========================================== ====== ==========================
For ``ETHTOOL_A_LINKMODES_OURS``, value represents advertised modes and mask
represents supported modes. ``ETHTOOL_A_LINKMODES_PEER`` in the reply is a bit
list.
``LINKMODES_GET`` allows dump requests (kernel returns reply messages for all
devices supporting the request).
LINKMODES_SET
=============
Request contents:
========================================== ====== ==========================
``ETHTOOL_A_LINKMODES_HEADER`` nested request header
``ETHTOOL_A_LINKMODES_AUTONEG`` u8 autonegotiation status
``ETHTOOL_A_LINKMODES_OURS`` bitset advertised link modes
``ETHTOOL_A_LINKMODES_PEER`` bitset partner link modes
``ETHTOOL_A_LINKMODES_SPEED`` u32 link speed (Mb/s)
``ETHTOOL_A_LINKMODES_DUPLEX`` u8 duplex mode
``ETHTOOL_A_LINKMODES_MASTER_SLAVE_CFG`` u8 Master/slave port mode
``ETHTOOL_A_LINKMODES_RATE_MATCHING`` u8 PHY rate matching
``ETHTOOL_A_LINKMODES_LANES`` u32 lanes
========================================== ====== ==========================
``ETHTOOL_A_LINKMODES_OURS`` bit set allows setting advertised link modes. If
autonegotiation is on (either set now or kept from before), advertised modes
are not changed (no ``ETHTOOL_A_LINKMODES_OURS`` attribute) and at least one
of speed, duplex and lanes is specified, kernel adjusts advertised modes to all
supported modes matching speed, duplex, lanes or all (whatever is specified).
This autoselection is done on ethtool side with ioctl interface, netlink
interface is supposed to allow requesting changes without knowing what exactly
kernel supports.
LINKSTATE_GET과 확장 상태
506-675`LINKSTATE_GET`은 `ETHTOOL_GLINK`의 up/down, 현재·최대 Signal Quality Index, 확장 상태/하위 상태, link down event 수를 조회합니다. 보통 LINK는 `netif_carrier_ok()`의 carrier flag지만 driver가 자체 handler를 둘 수 있습니다. 확장 state와 substate는 둘 다, state만, 또는 모두 생략될 수 있으며 dump를 지원합니다.
확장 state는 autonegotiation 문제, link training 실패, PCS/FEC 논리 불일치, signal integrity 불량, cable 없음/문제, EEPROM 문제, calibration 실패, power budget 초과, 과열, transceiver module 문제를 구분합니다.
autoneg substate는 peer 미탐지, ACK 미수신, next-page 교환 실패, force mode에서 peer/속도 합의 없음, FEC mismatch, Highest Common Denominator 없음입니다. link training은 KR frame lock 실패, inhibit timeout, peer receiver-ready 미설정, remote fault를 구분합니다.
logical mismatch는 PCS block lock·alignment marker lock·align status 실패, FC-FEC와 RS-FEC unlock을 구분합니다. signal integrity는 많은 physical error, 미지원 rate, SerDes reference clock 소실, SerDes analog loss of signal을 나타냅니다. cable은 미지원 cable 또는 test 실패, module은 CMIS state machine이 ModuleReady에 도달하지 못한 경우를 보고합니다.
LINKSTATE_GET
=============
Requests link state information. Link up/down flag (as provided by
``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might
be provided as well. In general, extended state describes reasons for why a port
is down, or why it operates in some non-obvious mode. This request does not have
any attributes.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_LINKSTATE_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ============================
``ETHTOOL_A_LINKSTATE_HEADER`` nested reply header
``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down)
``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index
``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value
``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state
``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate
``ETHTOOL_A_LINKSTATE_EXT_DOWN_CNT`` u32 count of link down events
==================================== ====== ============================
For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns
carrier flag provided by ``netif_carrier_ok()`` but there are drivers which
define their own handler.
``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are
optional values. ethtool core can provide either both
``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``,
or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them.
``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all
devices supporting the request).
Link extended states:
================================================ ============================================
``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or
issues therein
``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training
``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer
or forward error correction sublayer
``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues
``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected
``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable,
e.g., unsupported cable
``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure
during reading or parsing the data
``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm
``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the
power required from cable or module
``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated
``ETHTOOL_LINK_EXT_STATE_MODULE`` Transceiver module issue
================================================ ============================================
Link extended substates:
Autoneg substates:
=============================================================== ================================
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down
``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force
mode or there is no agreement of
speed
``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes
in both sides are mismatched
``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator
=============================================================== ================================
Link training substates:
=========================================================================== ====================
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not
recognized, the
lock failed
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not
occur before
timeout
``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not
send ready signal
after training
process
``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not
ready yet
=========================================================================== ====================
Link logical mismatch substates:
================================================================ ===============================
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was
not locked in first phase -
block lock
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was
not locked in second phase -
alignment markers lock
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did
not get align status
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is
not locked
``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is
not locked
================================================================ ===============================
Bad signal integrity substates:
================================================================= =============================
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical
errors
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to
operate the cable at a rate
that is not formally
supported, which led to
signal integrity issues
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_REFERENCE_CLOCK_LOST`` The external clock signal for
SerDes is too weak or
unavailable.
``ETHTOOL_LINK_EXT_SUBSTATE_BSI_SERDES_ALOS`` The received signal for
SerDes is too weak because
analog loss of signal.
================================================================= =============================
Cable issue substates:
=================================================== ============================================
``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable
``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure
=================================================== ============================================
Transceiver module issue substates:
=================================================== ============================================
``ETHTOOL_LINK_EXT_SUBSTATE_MODULE_CMIS_NOT_READY`` The CMIS Module State Machine did not reach
the ModuleReady state. For example, if the
module is stuck at ModuleFault state
=================================================== ============================================
DEBUG_GET과 DEBUG_SET
676-722DEBUG_GET/SET은 현재 `ETHTOOL_A_DEBUG_MSGMASK` bitset만 조회·변경합니다. ioctl의 `ETHTOOL_GMSGLVL`/`ETHTOOL_SMSGLVL` message level과 같지만 실제로는 대부분의 driver가 `NETIF_MSG_*` message class enable mask로 쓰므로 netlink도 그 의미를 따릅니다. GET은 모든 장치 dump를 지원합니다.
DEBUG_GET
=========
Requests debugging settings of a device. At the moment, only message mask is
provided.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_DEBUG_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_DEBUG_HEADER`` nested reply header
``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask
==================================== ====== ==========================
The message mask (``ETHTOOL_A_DEBUG_MSGMASK``) is equal to message level as
provided by ``ETHTOOL_GMSGLVL`` and set by ``ETHTOOL_SMSGLVL`` in ioctl
interface. While it is called message level there for historical reasons, most
drivers and almost all newer drivers use it as a mask of enabled message
classes (represented by ``NETIF_MSG_*`` constants); therefore netlink
interface follows its actual use in practice.
``DEBUG_GET`` allows dump requests (kernel returns reply messages for all
devices supporting the request).
DEBUG_SET
=========
Set or update debugging settings of a device. At the moment, only message mask
is supported.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_DEBUG_HEADER`` nested request header
``ETHTOOL_A_DEBUG_MSGMASK`` bitset message mask
==================================== ====== ==========================
``ETHTOOL_A_DEBUG_MSGMASK`` bit set allows setting or modifying mask of
enabled debugging message types for the device.
WOL_GET과 WOL_SET
723-765WOL_GET은 WoL 지원/활성 mode bitset과 SecureOn password를 조회합니다. 비밀 password가 포함될 수 있어 일반 GET과 달리 netns의 `CAP_NET_ADMIN`이 필요합니다. MODES mask는 장치 지원 mode, value는 활성 mode이고, `SOPASS`는 `WAKE_MAGICSECURE`를 지원할 때만 응답에 포함됩니다.
WOL_SET은 활성 mode와 SecureOn password를 갱신합니다. password attribute는 장치가 `WAKE_MAGICSECURE`를 지원할 때만 허용됩니다.
WOL_GET
=======
Query device wake-on-lan settings. Unlike most "GET" type requests,
``ETHTOOL_MSG_WOL_GET`` requires (netns) ``CAP_NET_ADMIN`` privileges as it
(potentially) provides SecureOn(tm) password which is confidential.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_WOL_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_WOL_HEADER`` nested reply header
``ETHTOOL_A_WOL_MODES`` bitset mask of enabled WoL modes
``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password
==================================== ====== ==========================
In reply, ``ETHTOOL_A_WOL_MODES`` mask consists of modes supported by the
device, value of modes which are enabled. ``ETHTOOL_A_WOL_SOPASS`` is only
included in reply if ``WAKE_MAGICSECURE`` mode is supported.
WOL_SET
=======
Set or update wake-on-lan settings.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_WOL_HEADER`` nested request header
``ETHTOOL_A_WOL_MODES`` bitset enabled WoL modes
``ETHTOOL_A_WOL_SOPASS`` binary SecureOn(tm) password
==================================== ====== ==========================
``ETHTOOL_A_WOL_SOPASS`` is only allowed for devices supporting
``WAKE_MAGICSECURE`` mode.
FEATURES_GET과 FEATURES_SET
766-837FEATURES_GET은 ioctl `ETHTOOL_GFEATURES`처럼 `dev->hw_features`, `dev->wanted_features`, 현재 `dev->features`, `NETIF_F_NEVER_CHANGE`를 bitset으로 반환합니다. legacy flags는 제공하지 않으며 필요한 사용자 공간은 관련 feature bit에서 계산합니다. HW mask는 kernel이 아는 모든 feature를 담아 verbose 응답에서 이름을 제공하고 나머지는 단일 bit list입니다.
FEATURES_SET은 WANTED bitset으로 특정 bit만 value/mask 방식으로 바꾸거나 NOMASK value로 전체 집합을 설정합니다. `netdev_change_features()` 검사를 거치므로 실제 결과가 요청과 다를 수 있습니다. 선택 응답의 WANTED는 요청과 결과 차이, ACTIVE는 이전과 새 active feature 차이를 mask/value로 보고합니다.
`FEATURES_NTF`는 netlink SET이나 ethtool ioctl뿐 아니라 `netdev_update_features()` 또는 `netdev_change_features()`로 feature가 바뀔 때마다 전송됩니다.
FEATURES_GET
============
Gets netdev features like ``ETHTOOL_GFEATURES`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_FEATURES_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_FEATURES_HEADER`` nested reply header
``ETHTOOL_A_FEATURES_HW`` bitset dev->hw_features
``ETHTOOL_A_FEATURES_WANTED`` bitset dev->wanted_features
``ETHTOOL_A_FEATURES_ACTIVE`` bitset dev->features
``ETHTOOL_A_FEATURES_NOCHANGE`` bitset NETIF_F_NEVER_CHANGE
==================================== ====== ==========================
Bitmaps in kernel response have the same meaning as bitmaps used in ioctl
interference but attribute names are different (they are based on
corresponding members of struct net_device). Legacy "flags" are not provided,
if userspace needs them (most likely only ethtool for backward compatibility),
it can calculate their values from related feature bits itself.
ETHA_FEATURES_HW uses mask consisting of all features recognized by kernel (to
provide all names when using verbose bitmap format), the other three use no
mask (simple bit lists).
FEATURES_SET
============
Request to set netdev features like ``ETHTOOL_SFEATURES`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_FEATURES_HEADER`` nested request header
``ETHTOOL_A_FEATURES_WANTED`` bitset requested features
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_FEATURES_HEADER`` nested reply header
``ETHTOOL_A_FEATURES_WANTED`` bitset diff wanted vs. result
``ETHTOOL_A_FEATURES_ACTIVE`` bitset diff old vs. new active
==================================== ====== ==========================
Request contains only one bitset which can be either value/mask pair (request
to change specific feature bits and leave the rest) or only a value (request
to set all features to specified set).
As request is subject to netdev_change_features() sanity checks, optional
kernel reply (can be suppressed by ``ETHTOOL_FLAG_OMIT_REPLY`` flag in request
header) informs client about the actual result. ``ETHTOOL_A_FEATURES_WANTED``
reports the difference between client request and actual result: mask consists
of bits which differ between requested features and result (dev->features
after the operation), value consists of values of these bits in the request
(i.e. negated values from resulting features). ``ETHTOOL_A_FEATURES_ACTIVE``
reports the difference between old and new dev->features: mask consists of
bits which have changed, values are their values in new dev->features (after
the operation).
``ETHTOOL_MSG_FEATURES_NTF`` notification is sent not only if device features
are modified using ``ETHTOOL_MSG_FEATURES_SET`` request or on of ethtool ioctl
request but also each time features are modified with netdev_update_features()
or netdev_change_features().
PRIVFLAGS_GET과 PRIVFLAGS_SET
838-880PRIVFLAGS_GET/SET은 ioctl `ETHTOOL_GPFLAGS`/`ETHTOOL_SPFLAGS`와 같은 driver private flag를 다룹니다. flag 수, 이름과 의미는 장치 의존적입니다. compact 응답의 이름은 `ETH_SS_PRIV_FLAGS` string set으로 조회하고 verbose 응답은 지원하는 모든 private flag를 mask로 보내 별도 이름 조회를 피합니다. SET은 전체 집합을 교체하거나 일부 값만 수정할 수 있습니다.
PRIVFLAGS_GET
=============
Gets private flags like ``ETHTOOL_GPFLAGS`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested reply header
``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags
==================================== ====== ==========================
``ETHTOOL_A_PRIVFLAGS_FLAGS`` is a bitset with values of device private flags.
These flags are defined by driver, their number and names (and also meaning)
are device dependent. For compact bitset format, names can be retrieved as
``ETH_SS_PRIV_FLAGS`` string set. If verbose bitset format is requested,
response uses all private flags supported by the device as mask so that client
gets the full information without having to fetch the string set with names.
PRIVFLAGS_SET
=============
Sets or modifies values of device private flags like ``ETHTOOL_SPFLAGS``
ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_PRIVFLAGS_HEADER`` nested request header
``ETHTOOL_A_PRIVFLAGS_FLAGS`` bitset private flags
==================================== ====== ==========================
``ETHTOOL_A_PRIVFLAGS_FLAGS`` can either set the whole set of private flags or
modify only values of some of them.
RINGS_GET과 RINGS_SET
881-982RINGS_GET은 RX, RX mini, RX jumbo, TX ring의 최대·현재 크기, RX buffer 길이, TCP header/data split, CQE 크기, TX/RX push mode, TX push buffer 현재·최대 길이, header/data split threshold와 최대값을 반환합니다.
TCP_DATA_SPLIT은 `getsockopt(TCP_ZEROCOPY_RECEIVE)` page-flipping zero-copy 수신에 쓸 수 있도록 header와 data를 별도 buffer에 배치하는지 나타냅니다. MTU나 HW-GRO 등을 통해 full page data 수신이 가능해야 합니다.
RX/TX PUSH는 DRAM descriptor를 채우고 NIC에 알리는 일반 경로 대신 MMIO write로 descriptor를 직접 밀어 latency를 줄이지만 CPU 비용이 늘 수 있습니다. TX_PUSH_BUF_LEN은 payload 일부까지 장치에 직접 복사해 작은 packet의 DMA mapping을 피하고 장치가 header를 먼저 처리하게 합니다.
RINGS_SET은 driver가 보고한 최대값과 추가 제약 안에서 같은 현재값을 설정합니다. CQE_SIZE는 completion event 크기를 바꾸며 큰 CQE는 더 많은 receive buffer pointer를 담을 수 있습니다. HDS_THRESH보다 큰 수신 packet은 header와 data를 분리합니다.
RINGS_GET
=========
Gets ring sizes like ``ETHTOOL_GRINGPARAM`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_RINGS_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
======================================= ====== ===========================
``ETHTOOL_A_RINGS_HEADER`` nested reply header
``ETHTOOL_A_RINGS_RX_MAX`` u32 max size of RX ring
``ETHTOOL_A_RINGS_RX_MINI_MAX`` u32 max size of RX mini ring
``ETHTOOL_A_RINGS_RX_JUMBO_MAX`` u32 max size of RX jumbo ring
``ETHTOOL_A_RINGS_TX_MAX`` u32 max size of TX ring
``ETHTOOL_A_RINGS_RX`` u32 size of RX ring
``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring
``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring
``ETHTOOL_A_RINGS_TX`` u32 size of TX ring
``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split
``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE
``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode
``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN_MAX`` u32 max size of TX push buffer
``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of
header / data split
``ETHTOOL_A_RINGS_HDS_THRESH_MAX`` u32 max threshold of
header / data split
======================================= ====== ===========================
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` indicates whether the device is usable with
page-flipping TCP zero-copy receive (``getsockopt(TCP_ZEROCOPY_RECEIVE)``).
If enabled the device is configured to place frame headers and data into
separate buffers. The device configuration must make it possible to receive
full memory pages of data, for example because MTU is high enough or through
HW-GRO.
``ETHTOOL_A_RINGS_[RX|TX]_PUSH`` flag is used to enable descriptor fast
path to send or receive packets. In ordinary path, driver fills descriptors in DRAM and
notifies NIC hardware. In fast path, driver pushes descriptors to the device
through MMIO writes, thus reducing the latency. However, enabling this feature
may increase the CPU cost. Drivers may enforce additional per-packet
eligibility checks (e.g. on packet size).
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` specifies the maximum number of bytes of a
transmitted packet a driver can push directly to the underlying device
('push' mode). Pushing some of the payload bytes to the device has the
advantages of reducing latency for small packets by avoiding DMA mapping (same
as ``ETHTOOL_A_RINGS_TX_PUSH`` parameter) as well as allowing the underlying
device to process packet headers ahead of fetching its payload.
This can help the device to make fast actions based on the packet's headers.
This is similar to the "tx-copybreak" parameter, which copies the packet to a
preallocated DMA memory area instead of mapping new memory. However,
tx-push-buff parameter copies the packet directly to the device to allow the
device to take faster actions on the packet.
RINGS_SET
=========
Sets ring sizes like ``ETHTOOL_SRINGPARAM`` ioctl request.
Request contents:
==================================== ====== ===========================
``ETHTOOL_A_RINGS_HEADER`` nested reply header
``ETHTOOL_A_RINGS_RX`` u32 size of RX ring
``ETHTOOL_A_RINGS_RX_MINI`` u32 size of RX mini ring
``ETHTOOL_A_RINGS_RX_JUMBO`` u32 size of RX jumbo ring
``ETHTOOL_A_RINGS_TX`` u32 size of TX ring
``ETHTOOL_A_RINGS_RX_BUF_LEN`` u32 size of buffers on the ring
``ETHTOOL_A_RINGS_TCP_DATA_SPLIT`` u8 TCP header / data split
``ETHTOOL_A_RINGS_CQE_SIZE`` u32 Size of TX/RX CQE
``ETHTOOL_A_RINGS_TX_PUSH`` u8 flag of TX Push mode
``ETHTOOL_A_RINGS_RX_PUSH`` u8 flag of RX Push mode
``ETHTOOL_A_RINGS_TX_PUSH_BUF_LEN`` u32 size of TX push buffer
``ETHTOOL_A_RINGS_HDS_THRESH`` u32 threshold of header / data split
==================================== ====== ===========================
Kernel checks that requested ring sizes do not exceed limits reported by
driver. Driver may impose additional constraints and may not support all
attributes.
``ETHTOOL_A_RINGS_CQE_SIZE`` specifies the completion queue event size.
Completion queue events (CQE) are the events posted by NIC to indicate the
completion status of a packet when the packet is sent (like send success or
error) or received (like pointers to packet fragments). The CQE size parameter
enables to modify the CQE size other than default size if NIC supports it.
A bigger CQE can have more receive buffer pointers, and in turn the NIC can
transfer a bigger frame from wire. Based on the NIC hardware, the overall
completion queue size can be adjusted in the driver if CQE size is modified.
``ETHTOOL_A_RINGS_HDS_THRESH`` specifies the threshold value of
header / data split feature. If a received packet size is larger than this
threshold value, header and data will be split.
CHANNELS_GET과 CHANNELS_SET
983-1028CHANNELS_GET은 RX, TX, other, combined channel의 최대 수와 현재 수를 반환합니다. CHANNELS_SET은 네 현재 count를 설정하며 kernel은 driver가 보고한 최대를 넘지 않는지 검사합니다. driver는 추가 제약을 둘 수 있고 일부 attribute를 지원하지 않을 수 있습니다.
CHANNELS_GET
============
Gets channel counts like ``ETHTOOL_GCHANNELS`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_CHANNELS_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
===================================== ====== ==========================
``ETHTOOL_A_CHANNELS_HEADER`` nested reply header
``ETHTOOL_A_CHANNELS_RX_MAX`` u32 max receive channels
``ETHTOOL_A_CHANNELS_TX_MAX`` u32 max transmit channels
``ETHTOOL_A_CHANNELS_OTHER_MAX`` u32 max other channels
``ETHTOOL_A_CHANNELS_COMBINED_MAX`` u32 max combined channels
``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count
``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count
``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count
``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count
===================================== ====== ==========================
CHANNELS_SET
============
Sets channel counts like ``ETHTOOL_SCHANNELS`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_CHANNELS_HEADER`` nested request header
``ETHTOOL_A_CHANNELS_RX_COUNT`` u32 receive channel count
``ETHTOOL_A_CHANNELS_TX_COUNT`` u32 transmit channel count
``ETHTOOL_A_CHANNELS_OTHER_COUNT`` u32 other channel count
``ETHTOOL_A_CHANNELS_COMBINED_COUNT`` u32 combined channel count
===================================== ====== ==========================
Kernel checks that requested channel counts do not exceed limits reported by
driver. Driver may impose additional constraints and may not support all
attributes.
COALESCE_GET과 COALESCE_SET
1029-1155COALESCE는 normal/IRQ RX·TX의 지연 usec와 최대 packet 수, 통계 갱신 간격, adaptive RX/TX, low/high packet-rate threshold와 각 모드 파라미터, sampling interval, CQE timer reset mode, TX aggregation, RX/TX DIM profile을 조회·설정합니다. 응답은 값이 0이 아니거나 `ethtool_ops::supported_coalesce_params`가 지원으로 선언한 attribute만 포함합니다.
기본 timer mode는 첫 packet에서 시작해 interrupt가 전달될 때 reset하므로 어떤 packet도 최대 delay를 넘지 않게 합니다. `USE_CQE_TX/RX=1`은 각 packet event마다 timer를 reset해 queue가 idle일 때 timer가 interrupt를 강제하고 busy queue는 packet limit으로 interrupt를 발생시킵니다.
TX aggregation은 frame을 연속 buffer로 복사해 한 번의 I/O로 제출합니다. MAX_BYTES, MAX_FRAMES, 첫 packet부터 block을 보낼 때까지 TIME_USECS를 설정하며 작은 URB를 자주 처리하기 어려운 일부 USB 장치에 유용합니다. RX/TX PROFILE은 Net DIM 파라미터입니다.
SET은 driver가 지원하지 않는 attribute를 값과 무관하게 거부하고 추가 제약을 적용할 수 있습니다. netlink 구현은 ioctl보다 사용자 값 적용 여부를 더 엄격히 확인하며 필요하면 driver를 두 번 호출할 수 있습니다.
COALESCE_GET
============
Gets coalescing parameters like ``ETHTOOL_GCOALESCE`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_COALESCE_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
=========================================== ====== =======================
``ETHTOOL_A_COALESCE_HEADER`` nested reply header
``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx
``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ
``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx
``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ
``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce
``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate
``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx
``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx
``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate
``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx
``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx
``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval
``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx
``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx
``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx
``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx
=========================================== ====== =======================
Attributes are only included in reply if their value is not zero or the
corresponding bit in ``ethtool_ops::supported_coalesce_params`` is set (i.e.
they are declared as supported by driver).
Timer reset mode (``ETHTOOL_A_COALESCE_USE_CQE_TX`` and
``ETHTOOL_A_COALESCE_USE_CQE_RX``) controls the interaction between packet
arrival and the various time based delay parameters. By default timers are
expected to limit the max delay between any packet arrival/departure and a
corresponding interrupt. In this mode timer should be started by packet
arrival (sometimes delivery of previous interrupt) and reset when interrupt
is delivered.
Setting the appropriate attribute to 1 will enable ``CQE`` mode, where
each packet event resets the timer. In this mode timer is used to force
the interrupt if queue goes idle, while busy queues depend on the packet
limit to trigger interrupts.
Tx aggregation consists of copying frames into a contiguous buffer so that they
can be submitted as a single IO operation. ``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES``
describes the maximum size in bytes for the submitted buffer.
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` describes the maximum number of frames
that can be aggregated into a single buffer.
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` describes the amount of time in usecs,
counted since the first packet arrival in an aggregated block, after which the
block should be sent.
This feature is mainly of interest for specific USB devices which does not cope
well with frequent small-sized URBs transmissions.
``ETHTOOL_A_COALESCE_RX_PROFILE`` and ``ETHTOOL_A_COALESCE_TX_PROFILE`` refer
to DIM parameters, see `Generic Network Dynamic Interrupt Moderation (Net DIM)
<https://www.kernel.org/doc/Documentation/networking/net_dim.rst>`_.
COALESCE_SET
============
Sets coalescing parameters like ``ETHTOOL_SCOALESCE`` ioctl request.
Request contents:
=========================================== ====== =======================
``ETHTOOL_A_COALESCE_HEADER`` nested request header
``ETHTOOL_A_COALESCE_RX_USECS`` u32 delay (us), normal Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES`` u32 max packets, normal Rx
``ETHTOOL_A_COALESCE_RX_USECS_IRQ`` u32 delay (us), Rx in IRQ
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_IRQ`` u32 max packets, Rx in IRQ
``ETHTOOL_A_COALESCE_TX_USECS`` u32 delay (us), normal Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES`` u32 max packets, normal Tx
``ETHTOOL_A_COALESCE_TX_USECS_IRQ`` u32 delay (us), Tx in IRQ
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_IRQ`` u32 IRQ packets, Tx in IRQ
``ETHTOOL_A_COALESCE_STATS_BLOCK_USECS`` u32 delay of stats update
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_RX`` bool adaptive Rx coalesce
``ETHTOOL_A_COALESCE_USE_ADAPTIVE_TX`` bool adaptive Tx coalesce
``ETHTOOL_A_COALESCE_PKT_RATE_LOW`` u32 threshold for low rate
``ETHTOOL_A_COALESCE_RX_USECS_LOW`` u32 delay (us), low Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_LOW`` u32 max packets, low Rx
``ETHTOOL_A_COALESCE_TX_USECS_LOW`` u32 delay (us), low Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_LOW`` u32 max packets, low Tx
``ETHTOOL_A_COALESCE_PKT_RATE_HIGH`` u32 threshold for high rate
``ETHTOOL_A_COALESCE_RX_USECS_HIGH`` u32 delay (us), high Rx
``ETHTOOL_A_COALESCE_RX_MAX_FRAMES_HIGH`` u32 max packets, high Rx
``ETHTOOL_A_COALESCE_TX_USECS_HIGH`` u32 delay (us), high Tx
``ETHTOOL_A_COALESCE_TX_MAX_FRAMES_HIGH`` u32 max packets, high Tx
``ETHTOOL_A_COALESCE_RATE_SAMPLE_INTERVAL`` u32 rate sampling interval
``ETHTOOL_A_COALESCE_USE_CQE_TX`` bool timer reset mode, Tx
``ETHTOOL_A_COALESCE_USE_CQE_RX`` bool timer reset mode, Rx
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_BYTES`` u32 max aggr size, Tx
``ETHTOOL_A_COALESCE_TX_AGGR_MAX_FRAMES`` u32 max aggr packets, Tx
``ETHTOOL_A_COALESCE_TX_AGGR_TIME_USECS`` u32 time (us), aggr, Tx
``ETHTOOL_A_COALESCE_RX_PROFILE`` nested profile of DIM, Rx
``ETHTOOL_A_COALESCE_TX_PROFILE`` nested profile of DIM, Tx
=========================================== ====== =======================
Request is rejected if it attributes declared as unsupported by driver (i.e.
such that the corresponding bit in ``ethtool_ops::supported_coalesce_params``
is not set), regardless of their values. Driver may impose additional
constraints on coalescing parameters and their values.
Compared to requests issued via the ``ioctl()`` netlink version of this request
will try harder to make sure that values specified by the user have been applied
and may call the driver twice.
PAUSE_GET과 PAUSE_SET
1156-1211PAUSE_GET은 pause autonegotiation, RX pause, TX pause와 선택 통계를 반환합니다. 요청의 선택적 `PAUSE_STATS_SRC`는 `enum ethtool_mac_stats_src` 값이며 생략하면 응답 source는 `ETHTOOL_MAC_STATS_SRC_AGGREGATE`입니다.
헤더 flag에 `ETHTOOL_FLAG_STATS`가 있을 때 `PAUSE_STATS`를 보고하며 driver 통계가 없으면 빈 nest입니다. 구조는 `struct ethtool_pause_stats`의 각 member에 대응합니다. PAUSE_SET은 AUTONEG, RX, TX boolean을 설정합니다.
PAUSE_GET
=========
Gets pause frame settings like ``ETHTOOL_GPAUSEPARAM`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_PAUSE_HEADER`` nested request header
``ETHTOOL_A_PAUSE_STATS_SRC`` u32 source of statistics
===================================== ====== ==========================
``ETHTOOL_A_PAUSE_STATS_SRC`` is optional. It takes values from:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_mac_stats_src
If absent from the request, stats will be provided with
an ``ETHTOOL_A_PAUSE_STATS_SRC`` attribute in the response equal to
``ETHTOOL_MAC_STATS_SRC_AGGREGATE``.
Kernel response contents:
===================================== ====== ==========================
``ETHTOOL_A_PAUSE_HEADER`` nested request header
``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation
``ETHTOOL_A_PAUSE_RX`` bool receive pause frames
``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames
``ETHTOOL_A_PAUSE_STATS`` nested pause statistics
===================================== ====== ==========================
``ETHTOOL_A_PAUSE_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set
in ``ETHTOOL_A_HEADER_FLAGS``.
It will be empty if driver did not report any statistics. Drivers fill in
the statistics in the following structure:
.. kernel-doc:: include/linux/ethtool.h
:identifiers: ethtool_pause_stats
Each member has a corresponding attribute defined.
PAUSE_SET
=========
Sets pause parameters like ``ETHTOOL_GPAUSEPARAM`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_PAUSE_HEADER`` nested request header
``ETHTOOL_A_PAUSE_AUTONEG`` bool pause autonegotiation
``ETHTOOL_A_PAUSE_RX`` bool receive pause frames
``ETHTOOL_A_PAUSE_TX`` bool transmit pause frames
===================================== ====== ==========================
EEE_GET과 EEE_SET
1212-1263EEE_GET은 지원/광고 mode, peer 광고 mode, 현재 active 여부, enable 여부, TX LPI enable과 timeout usec를 반환합니다. OURS mask는 EEE enabled mode, value는 광고 mode이고 PEER는 peer가 광고한 단일 bit list입니다. netlink는 모든 link mode 상태를 보고할 수 있지만 `ethtool_ops` 콜백은 첫 32개만 제공합니다.
EEE_SET은 광고 mode 전체 또는 mask로 지정한 일부, EEE enable, TX LPI enable과 timer를 설정합니다. 현재 콜백 제약 때문에 설정 가능한 mode는 첫 32개입니다.
EEE_GET
=======
Gets Energy Efficient Ethernet settings like ``ETHTOOL_GEEE`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_EEE_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
===================================== ====== ==========================
``ETHTOOL_A_EEE_HEADER`` nested request header
``ETHTOOL_A_EEE_MODES_OURS`` bool supported/advertised modes
``ETHTOOL_A_EEE_MODES_PEER`` bool peer advertised link modes
``ETHTOOL_A_EEE_ACTIVE`` bool EEE is actively used
``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled
``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled
``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us)
===================================== ====== ==========================
In ``ETHTOOL_A_EEE_MODES_OURS``, mask consists of link modes for which EEE is
enabled, value of link modes for which EEE is advertised. Link modes for which
peer advertises EEE are listed in ``ETHTOOL_A_EEE_MODES_PEER`` (no mask). The
netlink interface allows reporting EEE status for all link modes but only
first 32 are provided by the ``ethtool_ops`` callback.
EEE_SET
=======
Sets Energy Efficient Ethernet parameters like ``ETHTOOL_SEEE`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_EEE_HEADER`` nested request header
``ETHTOOL_A_EEE_MODES_OURS`` bool advertised modes
``ETHTOOL_A_EEE_ENABLED`` bool EEE is enabled
``ETHTOOL_A_EEE_TX_LPI_ENABLED`` bool Tx lpi enabled
``ETHTOOL_A_EEE_TX_LPI_TIMER`` u32 Tx lpi timeout (in us)
===================================== ====== ==========================
``ETHTOOL_A_EEE_MODES_OURS`` is used to either list link modes to advertise
EEE for (if there is no mask) or specify changes to the list (if there is
a mask). The netlink interface allows reporting EEE status for all link modes
but only first 32 can be set at the moment as that is what the ``ethtool_ops``
callback supports.
TSINFO_GET
1264-1304TSINFO_GET은 `ETHTOOL_GET_TS_INFO`처럼 SO_TIMESTAMPING flag, 지원 TX type, RX filter, PHC index와 hardware timestamp 통계를 조회합니다. 요청에서 선택적으로 PTP hardware clock provider를 지정합니다. 연결된 PHC가 없으면 PHC_INDEX를 생략하고 빈 bitset도 생략합니다.
통계는 TX hardware timestamp packet 수, timestamp가 오지 않은 수, hardware error 요청 수, 전달이 확인되지 않은 one-step TX timestamp packet 수를 포함합니다.
TSINFO_GET
==========
Gets timestamping information like ``ETHTOOL_GET_TS_INFO`` ioctl request.
Request contents:
======================================== ====== ============================
``ETHTOOL_A_TSINFO_HEADER`` nested request header
``ETHTOOL_A_TSINFO_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
======================================== ====== ============================
Kernel response contents:
===================================== ====== ==========================
``ETHTOOL_A_TSINFO_HEADER`` nested request header
``ETHTOOL_A_TSINFO_TIMESTAMPING`` bitset SO_TIMESTAMPING flags
``ETHTOOL_A_TSINFO_TX_TYPES`` bitset supported Tx types
``ETHTOOL_A_TSINFO_RX_FILTERS`` bitset supported Rx filters
``ETHTOOL_A_TSINFO_PHC_INDEX`` u32 PTP hw clock index
``ETHTOOL_A_TSINFO_STATS`` nested HW timestamping statistics
===================================== ====== ==========================
``ETHTOOL_A_TSINFO_PHC_INDEX`` is absent if there is no associated PHC (there
is no special value for this case). The bitset attributes are omitted if they
would be empty (no bit set).
Additional hardware timestamping statistics response contents:
================================================== ====== =====================
``ETHTOOL_A_TS_STAT_TX_PKTS`` uint Packets with Tx
HW timestamps
``ETHTOOL_A_TS_STAT_TX_LOST`` uint Tx HW timestamp
not arrived count
``ETHTOOL_A_TS_STAT_TX_ERR`` uint HW error request
Tx timestamp count
``ETHTOOL_A_TS_STAT_TX_ONESTEP_PKTS_UNCONFIRMED`` uint Packets with one-step
HW TX timestamps with
unconfirmed delivery
================================================== ====== =====================
CABLE_TEST와 CABLE_TEST_TDR
1305-1455CABLE_TEST action은 케이블 검사를 시작합니다. Ethernet cable은 보통 1, 2, 4 pair이며 길이는 fault 반사가 있을 때만 측정할 수 있습니다. hardware에 따라 fault 정보가 없을 수 있어 notification의 대부분 attribute는 선택적이고 임의 순서·횟수로 pair별 반복될 수 있습니다. 결과는 pair, code, source와 fault length(cm), source를 중첩해 보고합니다.
CABLE_TEST_TDR은 raw time-domain reflectometry 데이터를 요청합니다. 선택 구성 nest는 첫/마지막 거리, step 거리와 특정 pair를 cm 단위로 지정합니다. PHY는 실제 지원 해상도에 맞게 반올림하며 pair 생략 시 모두 검사합니다.
TDR은 pulse를 보내 거리별 반사 진폭을 기록하므로 100m를 1m 간격으로 재면 수초가 걸릴 수 있습니다. 시작할 때 STARTED status notification, 완료할 때 COMPLETED와 데이터를 보냅니다. 선택적으로 송신 pulse mV를 포함하며 반사는 송신 pulse보다 크지 않아야 합니다.
결과 앞의 STEP nest는 PHY가 실제 사용한 첫/마지막/간격을 cm로 알리고, 각 거리에서 pair 번호와 반사 진폭 mV를 AMPLITUDE nest로 반복합니다.
CABLE_TEST
==========
Start a cable test.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_CABLE_TEST_HEADER`` nested request header
==================================== ====== ==========================
Notification contents:
An Ethernet cable typically contains 1, 2 or 4 pairs. The length of
the pair can only be measured when there is a fault in the pair and
hence a reflection. Information about the fault may not be available,
depending on the specific hardware. Hence the contents of the notify
message are mostly optional. The attributes can be repeated an
arbitrary number of times, in an arbitrary order, for an arbitrary
number of pairs.
The example shows the notification sent when the test is completed for
a T2 cable, i.e. two pairs. One pair is OK and hence has no length
information. The second pair has a fault and does have length
information.
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_CABLE_TEST_HEADER`` | nested | reply header |
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_CABLE_TEST_STATUS`` | u8 | completed |
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_CABLE_TEST_NTF_NEST`` | nested | all the results |
+-+-------------------------------------------+--------+---------------------+
| | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test result |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code |
+-+-+-----------------------------------------+--------+---------------------+
| | ``ETHTOOL_A_CABLE_NEST_RESULT`` | nested | cable test results |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_CODE`` | u8 | result code |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_RESULT_SRC`` | u32 | information source |
+-+-+-----------------------------------------+--------+---------------------+
| | ``ETHTOOL_A_CABLE_NEST_FAULT_LENGTH`` | nested | cable length |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_CM`` | u32 | length in cm |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_SRC`` | u32 | information source |
+-+-+-----------------------------------------+--------+---------------------+
CABLE_TEST TDR
==============
Start a cable test and report raw TDR data
Request contents:
+--------------------------------------------+--------+-----------------------+
| ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header |
+--------------------------------------------+--------+-----------------------+
| ``ETHTOOL_A_CABLE_TEST_TDR_CFG`` | nested | test configuration |
+-+------------------------------------------+--------+-----------------------+
| | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | first data distance |
+-+-+----------------------------------------+--------+-----------------------+
| | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | last data distance |
+-+-+----------------------------------------+--------+-----------------------+
| | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step |
+-+-+----------------------------------------+--------+-----------------------+
| | ``ETHTOOL_A_CABLE_TEST_TDR_CFG_PAIR`` | u8 | pair to test |
+-+-+----------------------------------------+--------+-----------------------+
The ETHTOOL_A_CABLE_TEST_TDR_CFG is optional, as well as all members
of the nest. All distances are expressed in centimeters. The PHY takes
the distances as a guide, and rounds to the nearest distance it
actually supports. If a pair is passed, only that one pair will be
tested. Otherwise all pairs are tested.
Notification contents:
Raw TDR data is gathered by sending a pulse down the cable and
recording the amplitude of the reflected pulse for a given distance.
It can take a number of seconds to collect TDR data, especial if the
full 100 meters is probed at 1 meter intervals. When the test is
started a notification will be sent containing just
ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value
ETHTOOL_A_CABLE_TEST_NTF_STATUS_STARTED.
When the test has completed a second notification will be sent
containing ETHTOOL_A_CABLE_TEST_TDR_STATUS with the value
ETHTOOL_A_CABLE_TEST_NTF_STATUS_COMPLETED and the TDR data.
The message may optionally contain the amplitude of the pulse send
down the cable. This is measured in mV. A reflection should not be
bigger than transmitted pulse.
Before the raw TDR data should be an ETHTOOL_A_CABLE_TDR_NEST_STEP
nest containing information about the distance along the cable for the
first reading, the last reading, and the step between each
reading. Distances are measured in centimeters. These should be the
exact values the PHY used. These may be different to what the user
requested, if the native measurement resolution is greater than 1 cm.
For each step along the cable, a ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE is
used to report the amplitude of the reflection for a given pair.
+---------------------------------------------+--------+----------------------+
| ``ETHTOOL_A_CABLE_TEST_TDR_HEADER`` | nested | reply header |
+---------------------------------------------+--------+----------------------+
| ``ETHTOOL_A_CABLE_TEST_TDR_STATUS`` | u8 | completed |
+---------------------------------------------+--------+----------------------+
| ``ETHTOOL_A_CABLE_TEST_TDR_NTF_NEST`` | nested | all the results |
+-+-------------------------------------------+--------+----------------------+
| | ``ETHTOOL_A_CABLE_TDR_NEST_PULSE`` | nested | TX Pulse amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_PULSE_mV`` | s16 | Pulse amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | ``ETHTOOL_A_CABLE_NEST_STEP`` | nested | TDR step info |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_STEP_FIRST_DISTANCE`` | u32 | First data distance |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_STEP_LAST_DISTANCE`` | u32 | Last data distance |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_STEP_STEP_DISTANCE`` | u32 | distance of each step|
+-+-+-----------------------------------------+--------+----------------------+
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | ``ETHTOOL_A_CABLE_TDR_NEST_AMPLITUDE`` | nested | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_RESULTS_PAIR`` | u8 | pair number |
+-+-+-----------------------------------------+--------+----------------------+
| | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude |
+-+-+-----------------------------------------+--------+----------------------+
TUNNEL_INFO
1456-1491TUNNEL_INFO_GET은 NIC가 인식하는 tunnel offload 상태를 반환합니다. 응답에는 여러 UDP port table이 있고 각 table은 최대 크기, 담을 수 있는 tunnel type bitset, offload된 UDP port와 tunnel type entry를 포함합니다. `TUNNEL_UDP_TABLE_TYPES`가 비어 있으면 NIC에 hard-code된 static entry table입니다.
TUNNEL_INFO
===========
Gets information about the tunnel state NIC is aware of.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header |
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables |
+-+-------------------------------------------+--------+---------------------+
| | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the |
| | | | | table |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which |
| | | | | table can hold |
+-+-+-----------------------------------------+--------+---------------------+
| | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port |
+-+-+-+---------------------------------------+--------+---------------------+
| | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port |
+-+-+-+---------------------------------------+--------+---------------------+
| | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type |
+-+-+-+---------------------------------------+--------+---------------------+
For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that
the table contains static entries, hard-coded by the NIC.
FEC_GET과 FEC_SET
1492-1571FEC_GET은 구성 mode bitset, 자동 선택, 현재 active FEC mode의 bit index와 선택 통계를 반환합니다. 장치가 FEC를 지원하지 않으면 ACTIVE가 없을 수 있습니다. MODES와 AUTO는 autonegotiation이 꺼졌을 때만 의미가 있으며 AUTO는 SFP 파라미터에 따라 driver가 선택하게 하는 것으로 link autonegotiation과는 다릅니다.
`ETHTOOL_FLAG_STATS`가 있으면 FEC 통계를 64bit 배열로 반환합니다. 첫 값은 port 합계이고 뒤에는 lane/PCS별 값입니다. 길이 0은 미지원, 1은 lane 분해 미지원, `1 + #lanes`는 완전 지원입니다. IEEE 802.3ck-2022/802.3df-2024 정의의 error 범위와 event 수를 담은 histogram도 올 수 있습니다.
FEC_SET은 autonegotiation이 꺼진 링크에서 mode 또는 SFP 기반 AUTO를 설정합니다. mode bit는 하나만 권장하며 여러 개면 driver가 구현별 방식으로 고릅니다.
FEC_GET
=======
Gets FEC configuration and state like ``ETHTOOL_GFECPARAM`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_FEC_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
===================================== ====== ==========================
``ETHTOOL_A_FEC_HEADER`` nested request header
``ETHTOOL_A_FEC_MODES`` bitset configured modes
``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection
``ETHTOOL_A_FEC_ACTIVE`` u32 index of active FEC mode
``ETHTOOL_A_FEC_STATS`` nested FEC statistics
===================================== ====== ==========================
``ETHTOOL_A_FEC_ACTIVE`` is the bit index of the FEC link mode currently
active on the interface. This attribute may not be present if device does
not support FEC.
``ETHTOOL_A_FEC_MODES`` and ``ETHTOOL_A_FEC_AUTO`` are only meaningful when
autonegotiation is disabled. If ``ETHTOOL_A_FEC_AUTO`` is non-zero driver will
select the FEC mode automatically based on the parameters of the SFP module.
This is equivalent to the ``ETHTOOL_FEC_AUTO`` bit of the ioctl interface.
``ETHTOOL_A_FEC_MODES`` carry the current FEC configuration using link mode
bits (rather than old ``ETHTOOL_FEC_*`` bits).
``ETHTOOL_A_FEC_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in
``ETHTOOL_A_HEADER_FLAGS``.
Each attribute carries an array of 64bit statistics. First entry in the array
contains the total number of events on the port, while the following entries
are counters corresponding to lanes/PCS instances. The number of entries in
the array will be:
+--------------+---------------------------------------------+
| `0` | device does not support FEC statistics |
+--------------+---------------------------------------------+
| `1` | device does not support per-lane break down |
+--------------+---------------------------------------------+
| `1 + #lanes` | device has full support for FEC stats |
+--------------+---------------------------------------------+
Drivers fill in the statistics in the following structure:
.. kernel-doc:: include/linux/ethtool.h
:identifiers: ethtool_fec_stats
Statistics may have FEC bins histogram attribute ``ETHTOOL_A_FEC_STAT_HIST``
as defined in IEEE 802.3ck-2022 and 802.3df-2024. Nested attributes will have
the range of FEC errors in the bin (inclusive) and the amount of error events
in the bin.
FEC_SET
=======
Sets FEC parameters like ``ETHTOOL_SFECPARAM`` ioctl request.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_FEC_HEADER`` nested request header
``ETHTOOL_A_FEC_MODES`` bitset configured modes
``ETHTOOL_A_FEC_AUTO`` bool FEC mode auto selection
===================================== ====== ==========================
``FEC_SET`` is only meaningful when autonegotiation is disabled. Otherwise
FEC mode is selected as part of autonegotiation.
``ETHTOOL_A_FEC_MODES`` selects which FEC mode should be used. It's recommended
to set only one bit, if multiple bits are set driver may choose between them
in an implementation specific way.
``ETHTOOL_A_FEC_AUTO`` requests the driver to choose FEC mode based on SFP
module parameters. This does not mean autonegotiation.
MODULE_EEPROM_GET
1572-1605MODULE_EEPROM_GET은 transceiver module EEPROM을 한 번에 최대 반 page, 즉 128바이트 이하로 읽으며 offset 128의 half-page 경계를 넘을 수 없습니다. page 0 이외에는 상위 128바이트만 접근할 수 있습니다.
요청은 page 내 offset, 길이, page, bank, I2C address를 지정합니다. bank를 생략하면 0입니다. 응답 DATA 길이는 driver가 실제로 읽은 byte 수와 같습니다.
MODULE_EEPROM_GET
=================
Fetch module EEPROM data dump.
This interface is designed to allow dumps of at most 1/2 page at once. This
means only dumps of 128 (or less) bytes are allowed, without crossing half page
boundary located at offset 128. For pages other than 0 only high 128 bytes are
accessible.
Request contents:
======================================= ====== ==========================
``ETHTOOL_A_MODULE_EEPROM_HEADER`` nested request header
``ETHTOOL_A_MODULE_EEPROM_OFFSET`` u32 offset within a page
``ETHTOOL_A_MODULE_EEPROM_LENGTH`` u32 amount of bytes to read
``ETHTOOL_A_MODULE_EEPROM_PAGE`` u8 page number
``ETHTOOL_A_MODULE_EEPROM_BANK`` u8 bank number
``ETHTOOL_A_MODULE_EEPROM_I2C_ADDRESS`` u8 page I2C address
======================================= ====== ==========================
If ``ETHTOOL_A_MODULE_EEPROM_BANK`` is not specified, bank 0 is assumed.
Kernel response contents:
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_MODULE_EEPROM_HEADER`` | nested | reply header |
+---------------------------------------------+--------+---------------------+
| ``ETHTOOL_A_MODULE_EEPROM_DATA`` | binary | array of bytes from |
| | | module EEPROM |
+---------------------------------------------+--------+---------------------+
``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of
bytes driver actually read.
STATS_GET
1606-1694STATS_GET은 driver 정의 통계를 노출한 `ETHTOOL_GSTATS`의 재구현이 아니라 표준 인터페이스 통계를 제공합니다. 요청은 선택적 source와 group bitset을 지정합니다. group은 IEEE 802.3 MAC, PHY, MAC Control, RFC 2819 RMON, 추가 비IEEE PHY 통계입니다.
응답의 각 `STATS_GRP`는 group ID, 이름용 string set ID, 개별 statistic과 RX/TX histogram을 담습니다. 일반 statistic은 ID를 attribute type으로, u64 값을 payload로 하는 하나의 attribute입니다. ID는 string set의 이름과 대응합니다. RMON처럼 복합 통계는 별도 string 없이 group 안에 둡니다.
RMON histogram bucket 범위는 큰 MTU에서 표준이 정하지 않아 driver가 정의합니다. LOW와 HI는 모두 포함 경계이고 VAL은 packet counter입니다. 예를 들어 64-octet bucket은 0~64, 512~1023 bucket은 두 값 범위를 포함합니다. STATS_SRC 생략 시 aggregate source를 사용합니다.
STATS_GET
=========
Get standard statistics for the interface. Note that this is not
a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined
stats.
Request contents:
======================================= ====== ==========================
``ETHTOOL_A_STATS_HEADER`` nested request header
``ETHTOOL_A_STATS_SRC`` u32 source of statistics
``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats
======================================= ====== ==========================
Kernel response contents:
+-----------------------------------+--------+--------------------------------+
| ``ETHTOOL_A_STATS_HEADER`` | nested | reply header |
+-----------------------------------+--------+--------------------------------+
| ``ETHTOOL_A_STATS_SRC`` | u32 | source of statistics |
+-----------------------------------+--------+--------------------------------+
| ``ETHTOOL_A_STATS_GRP`` | nested | one or more group of stats |
+-+---------------------------------+--------+--------------------------------+
| | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` |
+-+---------------------------------+--------+--------------------------------+
| | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names |
+-+---------------------------------+--------+--------------------------------+
| | ``ETHTOOL_A_STATS_GRP_STAT`` | nested | nest containing a statistic |
+-+---------------------------------+--------+--------------------------------+
| | ``ETHTOOL_A_STATS_GRP_HIST_RX`` | nested | histogram statistic (Rx) |
+-+---------------------------------+--------+--------------------------------+
| | ``ETHTOOL_A_STATS_GRP_HIST_TX`` | nested | histogram statistic (Tx) |
+-+---------------------------------+--------+--------------------------------+
Users specify which groups of statistics they are requesting via
the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are:
====================== ======== ===============================================
ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*)
ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*)
ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*)
ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics
ETHTOOL_STATS_PHY phy Additional PHY statistics, not defined by IEEE
====================== ======== ===============================================
Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply.
``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains.
``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of
the statistics in the group, if available.
Statistics are added to the ``ETHTOOL_A_STATS_GRP`` nest under
``ETHTOOL_A_STATS_GRP_STAT``. ``ETHTOOL_A_STATS_GRP_STAT`` should contain
single 8 byte (u64) attribute inside - the type of that attribute is
the statistic ID and the value is the value of the statistic.
Each group has its own interpretation of statistic IDs.
Attribute IDs correspond to strings from the string set identified
by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics (such as RMON histogram
entries) are also listed inside ``ETHTOOL_A_STATS_GRP`` and do not have
a string defined in the string set.
RMON "histogram" counters count number of packets within given size range.
Because RFC does not specify the ranges beyond the standard 1518 MTU devices
differ in definition of buckets. For this reason the definition of packet ranges
is left to each driver.
``ETHTOOL_A_STATS_GRP_HIST_RX`` and ``ETHTOOL_A_STATS_GRP_HIST_TX`` nests
contain the following attributes:
================================= ====== ===================================
ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket
ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket
ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter
================================= ====== ===================================
Low and high bounds are inclusive, for example:
============================= ==== ====
RFC statistic low high
============================= ==== ====
etherStatsPkts64Octets 0 64
etherStatsPkts512to1023Octets 512 1023
============================= ==== ====
``ETHTOOL_A_STATS_SRC`` is optional. Similar to ``PAUSE_GET``, it takes values
from ``enum ethtool_mac_stats_src``. If absent from the request, stats will be
provided with an ``ETHTOOL_A_STATS_SRC`` attribute in the response equal to
``ETHTOOL_MAC_STATS_SRC_AGGREGATE``.
PHC_VCLOCKS_GET
1695-1713PHC_VCLOCKS_GET은 장치의 PTP Hardware Clock virtual clock 개수와 signed PHC index 배열을 반환합니다.
PHC_VCLOCKS_GET
===============
Query device PHC virtual clocks information.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
==================================== ====== ==========================
``ETHTOOL_A_PHC_VCLOCKS_HEADER`` nested reply header
``ETHTOOL_A_PHC_VCLOCKS_NUM`` u32 PHC virtual clocks number
``ETHTOOL_A_PHC_VCLOCKS_INDEX`` s32 PHC index array
==================================== ====== ==========================
MODULE_GET과 MODULE_SET
1714-1770MODULE_GET은 transceiver module의 host-enforced power mode policy와 현재 operational power mode를 반환합니다. policy 기본값은 driver 의존적이지만 새 driver에는 `auto`가 권장됩니다. operational mode는 module이 꽂혀 있을 때만 보고합니다.
MODULE_SET은 host가 강제할 power policy를 설정합니다. SFF-8636 module은 규격 2.10a 표 6-10, CMIS module은 규격 5.0 표 6-12에 따라 low-power mode를 강제합니다.
MODULE_GET
==========
Gets transceiver module parameters.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_MODULE_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
====================================== ====== ==========================
``ETHTOOL_A_MODULE_HEADER`` nested reply header
``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy
``ETHTOOL_A_MODULE_POWER_MODE`` u8 operational power mode
====================================== ====== ==========================
The optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute encodes the
transceiver module power mode policy enforced by the host. The default policy
is driver-dependent, but "auto" is the recommended default and it should be
implemented by new drivers and drivers where conformance to a legacy behavior
is not critical.
The optional ``ETHTHOOL_A_MODULE_POWER_MODE`` attribute encodes the operational
power mode policy of the transceiver module. It is only reported when a module
is plugged-in. Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_module_power_mode
MODULE_SET
==========
Sets transceiver module parameters.
Request contents:
====================================== ====== ==========================
``ETHTOOL_A_MODULE_HEADER`` nested request header
``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` u8 power mode policy
====================================== ====== ==========================
When set, the optional ``ETHTOOL_A_MODULE_POWER_MODE_POLICY`` attribute is used
to set the transceiver module power policy enforced by the host. Possible
values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_module_power_mode_policy
For SFF-8636 modules, low power mode is forced by the host according to table
6-10 in revision 2.10a of the specification.
For CMIS modules, low power mode is forced by the host according to table 6-12
in revision 5.0 of the specification.
PSE_GET, PSE_SET과 PSE_NTF
1771-1960PSE_GET은 PoDL과 Clause 33 PoE PSE의 admin state와 power detection status, PoE power class, 실제 소비 전력(mW), 확장 state/substate, 가용 power limit과 지원 범위, power domain index, 최대·현재 priority를 반환합니다. PoDL state/status는 IEEE 802.3-2018 30.15, C33 값은 IEEE 802.3-2022 30.9의 관리 객체에 대응합니다.
C33 actual power와 power limit은 mW입니다. power limit range의 min/max가 같으면 controller가 고정 class로 동작합니다. 확장 오류 substate는 class event, error condition, PSE enable, detection, virtual-port limit, overload, PD DLL power type, power 부족, short 감지 등을 세분합니다.
PSE_SET은 PoDL/C33 admin control, C33 available power limit(mW), priority를 설정합니다. 전력 단위를 class가 아니라 mW로 정해 다른 power monitoring interface 및 watt 단위 제품 문서와 통일했고 class 변환은 ethtool 같은 사용자 공간에서 할 수 있습니다.
priority는 0부터 `PSE_PRIO_MAX`까지이며 작은 값일수록 높습니다. reset 뒤 높은 priority port부터 전원을 켜고 power budget 초과 시 낮은 priority, 즉 큰 값 port부터 끕니다. PSE_NTF의 EVENTS bitset은 PSE event를 알립니다.
PSE_GET
=======
Gets PSE attributes.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_PSE_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
========================================== ====== =============================
``ETHTOOL_A_PSE_HEADER`` nested reply header
``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` u32 Operational state of the PoDL
PSE functions
``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` u32 power detection status of the
PoDL PSE.
``ETHTOOL_A_C33_PSE_ADMIN_STATE`` u32 Operational state of the PoE
PSE functions.
``ETHTOOL_A_C33_PSE_PW_D_STATUS`` u32 power detection status of the
PoE PSE.
``ETHTOOL_A_C33_PSE_PW_CLASS`` u32 power class of the PoE PSE.
``ETHTOOL_A_C33_PSE_ACTUAL_PW`` u32 actual power drawn on the
PoE PSE.
``ETHTOOL_A_C33_PSE_EXT_STATE`` u32 power extended state of the
PoE PSE.
``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` u32 power extended substatus of
the PoE PSE.
``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` u32 currently configured power
limit of the PoE PSE.
``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested Supported power limit
configuration ranges.
``ETHTOOL_A_PSE_PW_D_ID`` u32 Index of the PSE power domain
``ETHTOOL_A_PSE_PRIO_MAX`` u32 Priority maximum configurable
on the PoE PSE
``ETHTOOL_A_PSE_PRIO`` u32 Priority of the PoE PSE
currently configured
========================================== ====== =============================
When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` attribute identifies
the operational state of the PoDL PSE functions. The operational state of the
PSE function can be changed using the ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL``
action. This attribute corresponds to ``IEEE 802.3-2018`` 30.15.1.1.2
aPoDLPSEAdminState. Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_podl_pse_admin_state
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_STATE`` implementing
``IEEE 802.3-2022`` 30.9.1.1.2 aPSEAdminState.
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_c33_pse_admin_state
When set, the optional ``ETHTOOL_A_PODL_PSE_PW_D_STATUS`` attribute identifies
the power detection status of the PoDL PSE. The status depend on internal PSE
state machine and automatic PD classification support. This attribute
corresponds to ``IEEE 802.3-2018`` 30.15.1.1.3 aPoDLPSEPowerDetectionStatus.
Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_podl_pse_pw_d_status
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_PW_D_STATUS`` implementing
``IEEE 802.3-2022`` 30.9.1.1.5 aPSEPowerDetectionStatus.
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_c33_pse_pw_d_status
When set, the optional ``ETHTOOL_A_C33_PSE_PW_CLASS`` attribute identifies
the power class of the C33 PSE. It depends on the class negotiated between
the PSE and the PD. This attribute corresponds to ``IEEE 802.3-2022``
30.9.1.1.8 aPSEPowerClassification.
When set, the optional ``ETHTOOL_A_C33_PSE_ACTUAL_PW`` attribute identifies
the actual power drawn by the C33 PSE. This attribute corresponds to
``IEEE 802.3-2022`` 30.9.1.1.23 aPSEActualPower. Actual power is reported
in mW.
When set, the optional ``ETHTOOL_A_C33_PSE_EXT_STATE`` attribute identifies
the extended error state of the C33 PSE. Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_c33_pse_ext_state
When set, the optional ``ETHTOOL_A_C33_PSE_EXT_SUBSTATE`` attribute identifies
the extended error state of the C33 PSE. Possible values are:
Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_c33_pse_ext_substate_class_num_events
ethtool_c33_pse_ext_substate_error_condition
ethtool_c33_pse_ext_substate_mr_pse_enable
ethtool_c33_pse_ext_substate_option_detect_ted
ethtool_c33_pse_ext_substate_option_vport_lim
ethtool_c33_pse_ext_substate_ovld_detected
ethtool_c33_pse_ext_substate_pd_dll_power_type
ethtool_c33_pse_ext_substate_power_not_available
ethtool_c33_pse_ext_substate_short_detected
When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PW_LIMIT`` attribute
identifies the C33 PSE power limit in mW.
When set the optional ``ETHTOOL_A_C33_PSE_PW_LIMIT_RANGES`` nested attribute
identifies the C33 PSE power limit ranges through
``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MIN`` and
``ETHTOOL_A_C33_PSE_PWR_VAL_LIMIT_RANGE_MAX``.
If the controller works with fixed classes, the min and max values will be
equal.
The ``ETHTOOL_A_PSE_PW_D_ID`` attribute identifies the index of PSE power
domain.
When set, the optional ``ETHTOOL_A_PSE_PRIO_MAX`` attribute identifies
the PSE maximum priority value.
When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to
identifies the currently configured PSE priority.
For a description of PSE priority attributes, see ``PSE_SET``.
PSE_SET
=======
Sets PSE parameters.
Request contents:
====================================== ====== =============================
``ETHTOOL_A_PSE_HEADER`` nested request header
``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` u32 Control PoDL PSE Admin state
``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` u32 Control PSE Admin state
``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` u32 Control PoE PSE available
power limit
``ETHTOOL_A_PSE_PRIO`` u32 Control priority of the
PoE PSE
====================================== ====== =============================
When set, the optional ``ETHTOOL_A_PODL_PSE_ADMIN_CONTROL`` attribute is used
to control PoDL PSE Admin functions. This option implements
``IEEE 802.3-2018`` 30.15.1.2.1 acPoDLPSEAdminControl. See
``ETHTOOL_A_PODL_PSE_ADMIN_STATE`` for supported values.
The same goes for ``ETHTOOL_A_C33_PSE_ADMIN_CONTROL`` implementing
``IEEE 802.3-2022`` 30.9.1.2.1 acPSEAdminControl.
When set, the optional ``ETHTOOL_A_C33_PSE_AVAIL_PWR_LIMIT`` attribute is
used to control the available power value limit for C33 PSE in milliwatts.
This attribute corresponds to the `pse_available_power` variable described in
``IEEE 802.3-2022`` 33.2.4.4 Variables and `pse_avail_pwr` in 145.2.5.4
Variables, which are described in power classes.
It was decided to use milliwatts for this interface to unify it with other
power monitoring interfaces, which also use milliwatts, and to align with
various existing products that document power consumption in watts rather than
classes. If power limit configuration based on classes is needed, the
conversion can be done in user space, for example by ethtool.
When set, the optional ``ETHTOOL_A_PSE_PRIO`` attributes is used to
control the PSE priority. Allowed priority value are between zero and
the value of ``ETHTOOL_A_PSE_PRIO_MAX`` attribute.
A lower value indicates a higher priority, meaning that a priority value
of 0 corresponds to the highest port priority.
Port priority serves two functions:
- Power-up Order: After a reset, ports are powered up in order of their
priority from highest to lowest. Ports with higher priority
(lower values) power up first.
- Shutdown Order: When the power budget is exceeded, ports with lower
priority (higher values) are turned off first.
PSE_NTF
=======
Notify PSE events.
Notification contents:
=============================== ====== ========================
``ETHTOOL_A_PSE_HEADER`` nested request header
``ETHTOOL_A_PSE_EVENTS`` bitset PSE events
=============================== ====== ========================
When set, the optional ``ETHTOOL_A_PSE_EVENTS`` attribute identifies the
PSE events.
.. kernel-doc:: include/uapi/linux/ethtool_netlink_generated.h
:identifiers: ethtool_pse_event
RSS 조회, 설정, 생성과 삭제
1961-2062RSS_GET은 interface의 RSS context별 indirection table, hash key, hash function과 입력 변환, flow type별 hash header field를 조회합니다. context를 생략하면 main context 0입니다. dump는 netdev로 filter하고 `START_CONTEXT`로 특정 번호부터 시작할 수 있지만 단일 context filter는 지원하지 않습니다.
HFUNC bitmap은 toeplitz, xor, crc32 등을 나타냅니다. INDIR의 각 byte는 queue 번호이고 INPUT_XFRM은 symmetric-xor 또는 symmetric-or-xor 같은 hash 입력 변환입니다. FLOW_HASH는 flow type별로 hash에 넣을 header field bitmask입니다.
RSS_SET에서 사용자 table이 장치 최소보다 작으면 kernel/driver가 반복해 확장할 수 있습니다. 예를 들어 `[0,1]`을 최소 8 entry 장치에 넣으면 `[0,1,0,1,0,1,0,1]`이 됩니다. 많은 장치는 2의 거듭제곱 크기를 요구하고 크기 0은 기본 table로 reset합니다.
RSS_CREATE_ACT는 추가 context를 만들며 번호를 생략하면 kernel이 할당하고 응답으로 번호를 돌려줍니다. RSS_DELETE_ACT는 지정한 추가 context를 삭제합니다.
RSS_GET
=======
Get indirection table, hash key and hash function info associated with a
RSS context of an interface similar to ``ETHTOOL_GRSSH`` ioctl request.
Request contents:
===================================== ====== ============================
``ETHTOOL_A_RSS_HEADER`` nested request header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
``ETHTOOL_A_RSS_START_CONTEXT`` u32 start context number (dumps)
===================================== ====== ============================
``ETHTOOL_A_RSS_CONTEXT`` specifies which RSS context number to query,
if not set context 0 (the main context) is queried. Dumps can be filtered
by device (only listing contexts of a given netdev). Filtering single
context number is not supported but ``ETHTOOL_A_RSS_START_CONTEXT``
can be used to start dumping context from the given number (primarily
used to ignore context 0s and only dump additional contexts).
Kernel response contents:
===================================== ====== ===============================
``ETHTOOL_A_RSS_HEADER`` nested reply header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash
===================================== ====== ===============================
ETHTOOL_A_RSS_HFUNC attribute is bitmap indicating the hash function
being used. Current supported options are toeplitz, xor or crc32.
ETHTOOL_A_RSS_INDIR attribute returns RSS indirection table where each byte
indicates queue number.
ETHTOOL_A_RSS_INPUT_XFRM attribute is a bitmap indicating the type of
transformation applied to the input protocol fields before given to the RSS
hfunc. Current supported options are symmetric-xor and symmetric-or-xor.
ETHTOOL_A_RSS_FLOW_HASH carries per-flow type bitmask of which header
fields are included in the hash calculation.
RSS_SET
=======
Request contents:
===================================== ====== ==============================
``ETHTOOL_A_RSS_HEADER`` nested request header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
``ETHTOOL_A_RSS_FLOW_HASH`` nested Header fields included in hash
===================================== ====== ==============================
``ETHTOOL_A_RSS_INDIR`` is the minimal RSS table the user expects. Kernel and
the device driver may replicate the table if its smaller than smallest table
size supported by the device. For example if user requests ``[0, 1]`` but the
device needs at least 8 entries - the real table in use will end up being
``[0, 1, 0, 1, 0, 1, 0, 1]``. Most devices require the table size to be power
of 2, so tables which size is not a power of 2 will likely be rejected.
Using table of size 0 will reset the indirection table to the default.
RSS_CREATE_ACT
==============
Request contents:
===================================== ====== ==============================
``ETHTOOL_A_RSS_HEADER`` nested request header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
``ETHTOOL_A_RSS_HFUNC`` u32 RSS hash func
``ETHTOOL_A_RSS_INDIR`` binary Indir table bytes
``ETHTOOL_A_RSS_HKEY`` binary Hash key bytes
``ETHTOOL_A_RSS_INPUT_XFRM`` u32 RSS input data transformation
===================================== ====== ==============================
Kernel response contents:
===================================== ====== ==============================
``ETHTOOL_A_RSS_HEADER`` nested request header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
===================================== ====== ==============================
Create an additional RSS context, if ``ETHTOOL_A_RSS_CONTEXT`` is not
specified kernel will allocate one automatically.
RSS_DELETE_ACT
==============
Request contents:
===================================== ====== ==============================
``ETHTOOL_A_RSS_HEADER`` nested request header
``ETHTOOL_A_RSS_CONTEXT`` u32 context number
===================================== ====== ==============================
Delete an additional RSS context.
PLCA 구성과 상태
2063-2197PLCA_GET_CFG는 IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance RS의 version, enable, local node ID, node 수, Transmit Opportunity timer, burst count와 burst timer를 조회합니다. VERSION이 없으면 vendor-specific interface입니다. OPEN Alliance는 10BASE-T1S PHY용 표준 register map을 정의합니다.
ENABLED가 없으면 plain CSMA/CD입니다. NODE_ID 0~255 중 255는 미구성이며 0은 coordinator입니다. NODE_CNT 1~255는 mixing segment의 coordinator 포함 node 수이자 한 PLCA cycle의 TO 수이고 follower는 이 값을 무시합니다. TO_TMR 0~255 bit-time은 공유 매체의 모든 node에서 같아야 합니다.
BURST_CNT 0이면 TO마다 한 frame만 보내고, 0보다 크면 전송 뒤 BURST_TMR 동안 다음 MAC frame을 기다려 지정 횟수만큼 같은 TO에서 추가 전송합니다. BURST_TMR은 0~255 bit-time이며 MAC IFG보다 margin을 포함해 커야 합니다.
PLCA_SET_CFG는 GET과 같은 enable, ID, count, timer를 설정합니다. PLCA_GET_STATUS의 STATUS는 node가 network의 BEACON을 감지하는지 나타내며 IEEE 관리 객체 `aPLCAStatus`에 대응합니다.
PLCA_GET_CFG
============
Gets the IEEE 802.3cg-2019 Clause 148 Physical Layer Collision Avoidance
(PLCA) Reconciliation Sublayer (RS) attributes.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_PLCA_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
====================================== ====== =============================
``ETHTOOL_A_PLCA_HEADER`` nested reply header
``ETHTOOL_A_PLCA_VERSION`` u16 Supported PLCA management
interface standard/version
``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State
``ETHTOOL_A_PLCA_NODE_ID`` u32 PLCA unique local node ID
``ETHTOOL_A_PLCA_NODE_CNT`` u32 Number of PLCA nodes on the
network, including the
coordinator
``ETHTOOL_A_PLCA_TO_TMR`` u32 Transmit Opportunity Timer
value in bit-times (BT)
``ETHTOOL_A_PLCA_BURST_CNT`` u32 Number of additional packets
the node is allowed to send
within a single TO
``ETHTOOL_A_PLCA_BURST_TMR`` u32 Time to wait for the MAC to
transmit a new frame before
terminating the burst
====================================== ====== =============================
When set, the optional ``ETHTOOL_A_PLCA_VERSION`` attribute indicates which
standard and version the PLCA management interface complies to. When not set,
the interface is vendor-specific and (possibly) supplied by the driver.
The OPEN Alliance SIG specifies a standard register map for 10BASE-T1S PHYs
embedding the PLCA Reconciliation Sublayer. See "10BASE-T1S PLCA Management
Registers" at https://www.opensig.org/about/specifications/.
When set, the optional ``ETHTOOL_A_PLCA_ENABLED`` attribute indicates the
administrative state of the PLCA RS. When not set, the node operates in "plain"
CSMA/CD mode. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.1
aPLCAAdminState / 30.16.1.2.1 acPLCAAdminControl.
When set, the optional ``ETHTOOL_A_PLCA_NODE_ID`` attribute indicates the
configured local node ID of the PHY. This ID determines which transmit
opportunity (TO) is reserved for the node to transmit into. This option is
corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.4 aPLCALocalNodeID. The valid
range for this attribute is [0 .. 255] where 255 means "not configured".
When set, the optional ``ETHTOOL_A_PLCA_NODE_CNT`` attribute indicates the
configured maximum number of PLCA nodes on the mixing-segment. This number
determines the total number of transmit opportunities generated during a
PLCA cycle. This attribute is relevant only for the PLCA coordinator, which is
the node with aPLCALocalNodeID set to 0. Follower nodes ignore this setting.
This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.3
aPLCANodeCount. The valid range for this attribute is [1 .. 255].
When set, the optional ``ETHTOOL_A_PLCA_TO_TMR`` attribute indicates the
configured value of the transmit opportunity timer in bit-times. This value
must be set equal across all nodes sharing the medium for PLCA to work
correctly. This option is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.5
aPLCATransmitOpportunityTimer. The valid range for this attribute is
[0 .. 255].
When set, the optional ``ETHTOOL_A_PLCA_BURST_CNT`` attribute indicates the
configured number of extra packets that the node is allowed to send during a
single transmit opportunity. By default, this attribute is 0, meaning that
the node can only send a single frame per TO. When greater than 0, the PLCA RS
keeps the TO after any transmission, waiting for the MAC to send a new frame
for up to aPLCABurstTimer BTs. This can only happen a number of times per PLCA
cycle up to the value of this parameter. After that, the burst is over and the
normal counting of TOs resumes. This option is corresponding to
``IEEE 802.3cg-2019`` 30.16.1.1.6 aPLCAMaxBurstCount. The valid range for this
attribute is [0 .. 255].
When set, the optional ``ETHTOOL_A_PLCA_BURST_TMR`` attribute indicates how
many bit-times the PLCA RS waits for the MAC to initiate a new transmission
when aPLCAMaxBurstCount is greater than 0. If the MAC fails to send a new
frame within this time, the burst ends and the counting of TOs resumes.
Otherwise, the new frame is sent as part of the current burst. This option
is corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.7 aPLCABurstTimer. The
valid range for this attribute is [0 .. 255]. Although, the value should be
set greater than the Inter-Frame-Gap (IFG) time of the MAC (plus some margin)
for PLCA burst mode to work as intended.
PLCA_SET_CFG
============
Sets PLCA RS parameters.
Request contents:
====================================== ====== =============================
``ETHTOOL_A_PLCA_HEADER`` nested request header
``ETHTOOL_A_PLCA_ENABLED`` u8 PLCA Admin State
``ETHTOOL_A_PLCA_NODE_ID`` u8 PLCA unique local node ID
``ETHTOOL_A_PLCA_NODE_CNT`` u8 Number of PLCA nodes on the
network, including the
coordinator
``ETHTOOL_A_PLCA_TO_TMR`` u8 Transmit Opportunity Timer
value in bit-times (BT)
``ETHTOOL_A_PLCA_BURST_CNT`` u8 Number of additional packets
the node is allowed to send
within a single TO
``ETHTOOL_A_PLCA_BURST_TMR`` u8 Time to wait for the MAC to
transmit a new frame before
terminating the burst
====================================== ====== =============================
For a description of each attribute, see ``PLCA_GET_CFG``.
PLCA_GET_STATUS
===============
Gets PLCA RS status information.
Request contents:
===================================== ====== ==========================
``ETHTOOL_A_PLCA_HEADER`` nested request header
===================================== ====== ==========================
Kernel response contents:
====================================== ====== =============================
``ETHTOOL_A_PLCA_HEADER`` nested reply header
``ETHTOOL_A_PLCA_STATUS`` u8 PLCA RS operational status
====================================== ====== =============================
When set, the ``ETHTOOL_A_PLCA_STATUS`` attribute indicates whether the node is
detecting the presence of the BEACON on the network. This flag is
corresponding to ``IEEE 802.3cg-2019`` 30.16.1.1.2 aPLCAStatus.
802.3 MAC Merge 조회와 설정
2198-2281MM_GET은 pMAC RX enable, preemptible TX의 admin/active 상태, TX/RX non-final fragment 최소 크기, SMD-V verification enable/status/time/max time과 선택 통계를 반환합니다. driver는 `struct ethtool_mm_state`로 채우며 verification status는 `enum ethtool_mm_verify_status` 값입니다.
verification을 MM_SET에서 끄면 status는 INITIAL 또는 DISABLED이고, 켜면 다른 verification 상태여야 합니다. driver는 pMAC을 기본 disabled로 시작해 사용자 요청으로 켜는 것이 권장되며 사용자 공간은 MM_GET의 기본값에 의존하면 안 됩니다. STATS flag가 있으면 `struct ethtool_mm_stats`를 반환하고 미보고 시 빈 nest입니다.
MM_SET은 verify time/enable, preemptible TX enable, pMAC enable과 TX minimum fragment size를 `struct ethtool_mm_cfg`를 통해 driver에 전달합니다.
MM_GET
======
Retrieve 802.3 MAC Merge parameters.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_MM_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
================================= ====== ===================================
``ETHTOOL_A_MM_HEADER`` nested request header
``ETHTOOL_A_MM_PMAC_ENABLED`` bool set if RX of preemptible and SMD-V
frames is enabled
``ETHTOOL_A_MM_TX_ENABLED`` bool set if TX of preemptible frames is
administratively enabled (might be
inactive if verification failed)
``ETHTOOL_A_MM_TX_ACTIVE`` bool set if TX of preemptible frames is
operationally enabled
``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 minimum size of transmitted
non-final fragments, in octets
``ETHTOOL_A_MM_RX_MIN_FRAG_SIZE`` u32 minimum size of received non-final
fragments, in octets
``ETHTOOL_A_MM_VERIFY_ENABLED`` bool set if TX of SMD-V frames is
administratively enabled
``ETHTOOL_A_MM_VERIFY_STATUS`` u8 state of the verification function
``ETHTOOL_A_MM_VERIFY_TIME`` u32 delay between verification attempts
``ETHTOOL_A_MM_MAX_VERIFY_TIME``` u32 maximum verification interval
supported by device
``ETHTOOL_A_MM_STATS`` nested IEEE 802.3-2018 subclause 30.14.1
oMACMergeEntity statistics counters
================================= ====== ===================================
The attributes are populated by the device driver through the following
structure:
.. kernel-doc:: include/linux/ethtool.h
:identifiers: ethtool_mm_state
The ``ETHTOOL_A_MM_VERIFY_STATUS`` will report one of the values from
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_mm_verify_status
If ``ETHTOOL_A_MM_VERIFY_ENABLED`` was passed as false in the ``MM_SET``
command, ``ETHTOOL_A_MM_VERIFY_STATUS`` will report either
``ETHTOOL_MM_VERIFY_STATUS_INITIAL`` or ``ETHTOOL_MM_VERIFY_STATUS_DISABLED``,
otherwise it should report one of the other states.
It is recommended that drivers start with the pMAC disabled, and enable it upon
user space request. It is also recommended that user space does not depend upon
the default values from ``ETHTOOL_MSG_MM_GET`` requests.
``ETHTOOL_A_MM_STATS`` are reported if ``ETHTOOL_FLAG_STATS`` was set in
``ETHTOOL_A_HEADER_FLAGS``. The attribute will be empty if driver did not
report any statistics. Drivers fill in the statistics in the following
structure:
.. kernel-doc:: include/linux/ethtool.h
:identifiers: ethtool_mm_stats
MM_SET
======
Modifies the configuration of the 802.3 MAC Merge layer.
Request contents:
================================= ====== ==========================
``ETHTOOL_A_MM_VERIFY_TIME`` u32 see MM_GET description
``ETHTOOL_A_MM_VERIFY_ENABLED`` bool see MM_GET description
``ETHTOOL_A_MM_TX_ENABLED`` bool see MM_GET description
``ETHTOOL_A_MM_PMAC_ENABLED`` bool see MM_GET description
``ETHTOOL_A_MM_TX_MIN_FRAG_SIZE`` u32 see MM_GET description
================================= ====== ==========================
The attributes are propagated to the driver through the following structure:
.. kernel-doc:: include/linux/ethtool.h
:identifiers: ethtool_mm_cfg
MODULE_FW_FLASH_ACT
2282-2348MODULE_FW_FLASH_ACT는 transceiver module firmware를 갱신합니다. image를 module로 download하고 검증한 뒤 실행하고, reset 뒤에도 쓰도록 commit하는 세 단계를 순서대로 수행합니다.
요청은 firmware image file name과 선택 password를 담습니다. 명령은 작업을 schedule한 뒤 즉시 반환하고 실제 update는 비동기로 수분간 실행됩니다. kernel은 status code/message와 완료량 DONE, 전체량 TOTAL notification을 보내 진행률을 알립니다.
MODULE_FW_FLASH_ACT
===================
Flashes transceiver module firmware.
Request contents:
======================================= ====== ===========================
``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` nested request header
``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` string firmware image file name
``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` u32 transceiver module password
======================================= ====== ===========================
The firmware update process consists of three logical steps:
1. Downloading a firmware image to the transceiver module and validating it.
2. Running the firmware image.
3. Committing the firmware image so that it is run upon reset.
When flash command is given, those three steps are taken in that order.
This message merely schedules the update process and returns immediately
without blocking. The process then runs asynchronously.
Since it can take several minutes to complete, during the update process
notifications are emitted from the kernel to user space updating it about
the status and progress.
The ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` attribute encodes the firmware
image file name. The firmware image is downloaded to the transceiver module,
validated, run and committed.
The optional ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` attribute encodes a password
that might be required as part of the transceiver module firmware update
process.
The firmware update process can take several minutes to complete. Therefore,
during the update process notifications are emitted from the kernel to user
space updating it about the status and progress.
Notification contents:
+---------------------------------------------------+--------+----------------+
| ``ETHTOOL_A_MODULE_FW_FLASH_HEADER`` | nested | reply header |
+---------------------------------------------------+--------+----------------+
| ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` | u32 | status |
+---------------------------------------------------+--------+----------------+
| ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` | string | status message |
+---------------------------------------------------+--------+----------------+
| ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` | uint | progress |
+---------------------------------------------------+--------+----------------+
| ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL`` | uint | total |
+---------------------------------------------------+--------+----------------+
The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` attribute encodes the current status
of the firmware update process. Possible values are:
.. kernel-doc:: include/uapi/linux/ethtool.h
:identifiers: ethtool_module_fw_flash_status
The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` attribute encodes a status message
string.
The ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` and ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL``
attributes encode the completed and total amount of work, respectively.
PHY_GET
2349-2391PHY_GET DO는 기본 `dev->phydev` 또는 요청의 PHY_INDEX가 지정한 Ethernet PHY 정보를 반환합니다. 한 링크에 PHY가 여러 개일 수 있어 interface index/name을 넣은 DUMP로 전체 topology를 열거할 수 있습니다.
응답은 고유 PHY index, driver/device name, upstream 장치 type/index, parent PHY와 연결하는 SFP bus 이름, PHY가 제어하는 downstream SFP bus 이름을 포함합니다. UPSTREAM_TYPE이 `PHY_UPSTREAM_PHY`면 parent도 PHY입니다.
PHY_GET
=======
Retrieve information about a given Ethernet PHY sitting on the link. The DO
operation returns all available information about dev->phydev. User can also
specify a PHY_INDEX, in which case the DO request returns information about that
specific PHY.
As there can be more than one PHY, the DUMP operation can be used to list the PHYs
present on a given interface, by passing an interface index or name in
the dump request.
For more information, refer to :ref:`phy_link_topology`
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_PHY_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
===================================== ====== ===============================
``ETHTOOL_A_PHY_HEADER`` nested request header
``ETHTOOL_A_PHY_INDEX`` u32 the phy's unique index, that can
be used for phy-specific
requests
``ETHTOOL_A_PHY_DRVNAME`` string the phy driver name
``ETHTOOL_A_PHY_NAME`` string the phy device name
``ETHTOOL_A_PHY_UPSTREAM_TYPE`` u32 the type of device this phy is
connected to
``ETHTOOL_A_PHY_UPSTREAM_INDEX`` u32 the PHY index of the upstream
PHY
``ETHTOOL_A_PHY_UPSTREAM_SFP_NAME`` string if this PHY is connected to
its parent PHY through an SFP
bus, the name of this sfp bus
``ETHTOOL_A_PHY_DOWNSTREAM_SFP_NAME`` string if the phy controls an sfp bus,
the name of the sfp bus
===================================== ====== ===============================
When ``ETHTOOL_A_PHY_UPSTREAM_TYPE`` is PHY_UPSTREAM_PHY, the PHY's parent is
another PHY.
TSCONFIG_GET과 TSCONFIG_SET
2392-2460TSCONFIG_GET은 deprecated `SIOCGHWTSTAMP`와 유사하게 현재 hardware timestamp provider와 구성을 조회합니다. provider nest의 INDEX는 PTP 장치 index, QUALIFIER는 timestamp 종류를 설명합니다. TX type, RX filter, hwtstamp flag는 현재 provider에 설정된 `struct kernel_hwtstamp_config` 값입니다.
TSCONFIG_SET은 deprecated `SIOCSHWTSTAMP` 대신 같은 provider, TX type, RX filter, flag를 설정하고 새 구성을 같은 형식으로 응답합니다.
TSCONFIG_GET
============
Retrieves the information about the current hardware timestamping source and
configuration.
It is similar to the deprecated ``SIOCGHWTSTAMP`` ioctl request.
Request contents:
==================================== ====== ==========================
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
==================================== ====== ==========================
Kernel response contents:
======================================== ====== ============================
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
======================================== ====== ============================
When set the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` attribute identifies the
source of the hw timestamping provider. It is composed by
``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_INDEX`` attribute which describe the index of
the PTP device and ``ETHTOOL_A_TS_HWTSTAMP_PROVIDER_QUALIFIER`` which describe
the qualifier of the timestamp.
When set the ``ETHTOOL_A_TSCONFIG_TX_TYPES``, ``ETHTOOL_A_TSCONFIG_RX_FILTERS``
and the ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` attributes identify the Tx
type, the Rx filter and the flags configured for the current hw timestamping
provider. The attributes are propagated to the driver through the following
structure:
.. kernel-doc:: include/linux/net_tstamp.h
:identifiers: kernel_hwtstamp_config
TSCONFIG_SET
============
Set the information about the current hardware timestamping source and
configuration.
It is similar to the deprecated ``SIOCSHWTSTAMP`` ioctl request.
Request contents:
======================================== ====== ============================
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
======================================== ====== ============================
Kernel response contents:
======================================== ====== ============================
``ETHTOOL_A_TSCONFIG_HEADER`` nested request header
``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` nested PTP hw clock provider
``ETHTOOL_A_TSCONFIG_TX_TYPES`` bitset hwtstamp Tx type
``ETHTOOL_A_TSCONFIG_RX_FILTERS`` bitset hwtstamp Rx filter
``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` u32 hwtstamp flags
======================================== ====== ============================
For a description of each attribute, see ``TSCONFIG_GET``.
ioctl 요청 대응표
2461-2571마지막 표는 기존 ethtool ioctl과 netlink 명령의 대응 관계를 보존합니다. LINKINFO/LINKMODES, WoL, DEBUG, LINKSTATE, COALESCE, RINGS, PAUSE, FEATURES, STRSET, PRIVFLAGS, RSS, CHANNELS, TSINFO, MODULE EEPROM, EEE, FEC, hardware timestamp 구성에는 netlink 대응이 있습니다.
GDRVINFO, GREGS, NWAY_RST, 일반 EEPROM, TEST, PHYS_ID, driver-defined GSTATS, RX classifier/tunable/dump/reset 등은 이 표 기준으로 아직 `n/a`입니다. 반대로 cable test/TDR, tunnel info, PHC virtual clocks, module power, PLCA, MAC Merge, module firmware flash와 PHY topology는 netlink 전용입니다. permanent address는 ethtool netlink가 아니라 rtnetlink `RTM_GETLINK`로 조회합니다.
`SIOCGHWTSTAMP`와 `SIOCSHWTSTAMP`는 각각 `ETHTOOL_MSG_TSCONFIG_GET`과 `ETHTOOL_MSG_TSCONFIG_SET`에 대응합니다. 원문의 전체 명령별 매핑 표는 아래 보존 블록에서 그대로 확인할 수 있습니다.
Request translation
===================
The following table maps ioctl commands to netlink commands providing their
functionality. Entries with "n/a" in right column are commands which do not
have their netlink replacement yet. Entries which "n/a" in the left column
are netlink only.
=================================== =====================================
ioctl command netlink command
=================================== =====================================
``ETHTOOL_GSET`` ``ETHTOOL_MSG_LINKINFO_GET``
``ETHTOOL_MSG_LINKMODES_GET``
``ETHTOOL_SSET`` ``ETHTOOL_MSG_LINKINFO_SET``
``ETHTOOL_MSG_LINKMODES_SET``
``ETHTOOL_GDRVINFO`` n/a
``ETHTOOL_GREGS`` n/a
``ETHTOOL_GWOL`` ``ETHTOOL_MSG_WOL_GET``
``ETHTOOL_SWOL`` ``ETHTOOL_MSG_WOL_SET``
``ETHTOOL_GMSGLVL`` ``ETHTOOL_MSG_DEBUG_GET``
``ETHTOOL_SMSGLVL`` ``ETHTOOL_MSG_DEBUG_SET``
``ETHTOOL_NWAY_RST`` n/a
``ETHTOOL_GLINK`` ``ETHTOOL_MSG_LINKSTATE_GET``
``ETHTOOL_GEEPROM`` n/a
``ETHTOOL_SEEPROM`` n/a
``ETHTOOL_GCOALESCE`` ``ETHTOOL_MSG_COALESCE_GET``
``ETHTOOL_SCOALESCE`` ``ETHTOOL_MSG_COALESCE_SET``
``ETHTOOL_GRINGPARAM`` ``ETHTOOL_MSG_RINGS_GET``
``ETHTOOL_SRINGPARAM`` ``ETHTOOL_MSG_RINGS_SET``
``ETHTOOL_GPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_GET``
``ETHTOOL_SPAUSEPARAM`` ``ETHTOOL_MSG_PAUSE_SET``
``ETHTOOL_GRXCSUM`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SRXCSUM`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GTXCSUM`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_STXCSUM`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GSG`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SSG`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_TEST`` n/a
``ETHTOOL_GSTRINGS`` ``ETHTOOL_MSG_STRSET_GET``
``ETHTOOL_PHYS_ID`` n/a
``ETHTOOL_GSTATS`` n/a
``ETHTOOL_GTSO`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_STSO`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GPERMADDR`` rtnetlink ``RTM_GETLINK``
``ETHTOOL_GUFO`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SUFO`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GGSO`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SGSO`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GFLAGS`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SFLAGS`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_GET``
``ETHTOOL_SPFLAGS`` ``ETHTOOL_MSG_PRIVFLAGS_SET``
``ETHTOOL_GRXFH`` ``ETHTOOL_MSG_RSS_GET``
``ETHTOOL_SRXFH`` ``ETHTOOL_MSG_RSS_SET``
``ETHTOOL_GGRO`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SGRO`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GRXRINGS`` n/a
``ETHTOOL_GRXCLSRLCNT`` n/a
``ETHTOOL_GRXCLSRULE`` n/a
``ETHTOOL_GRXCLSRLALL`` n/a
``ETHTOOL_SRXCLSRLDEL`` n/a
``ETHTOOL_SRXCLSRLINS`` n/a
``ETHTOOL_FLASHDEV`` n/a
``ETHTOOL_RESET`` n/a
``ETHTOOL_SRXNTUPLE`` n/a
``ETHTOOL_GRXNTUPLE`` n/a
``ETHTOOL_GSSET_INFO`` ``ETHTOOL_MSG_STRSET_GET``
``ETHTOOL_GRXFHINDIR`` ``ETHTOOL_MSG_RSS_GET``
``ETHTOOL_SRXFHINDIR`` ``ETHTOOL_MSG_RSS_SET``
``ETHTOOL_GFEATURES`` ``ETHTOOL_MSG_FEATURES_GET``
``ETHTOOL_SFEATURES`` ``ETHTOOL_MSG_FEATURES_SET``
``ETHTOOL_GCHANNELS`` ``ETHTOOL_MSG_CHANNELS_GET``
``ETHTOOL_SCHANNELS`` ``ETHTOOL_MSG_CHANNELS_SET``
``ETHTOOL_SET_DUMP`` n/a
``ETHTOOL_GET_DUMP_FLAG`` n/a
``ETHTOOL_GET_DUMP_DATA`` n/a
``ETHTOOL_GET_TS_INFO`` ``ETHTOOL_MSG_TSINFO_GET``
``ETHTOOL_GMODULEINFO`` ``ETHTOOL_MSG_MODULE_EEPROM_GET``
``ETHTOOL_GMODULEEEPROM`` ``ETHTOOL_MSG_MODULE_EEPROM_GET``
``ETHTOOL_GEEE`` ``ETHTOOL_MSG_EEE_GET``
``ETHTOOL_SEEE`` ``ETHTOOL_MSG_EEE_SET``
``ETHTOOL_GRSSH`` ``ETHTOOL_MSG_RSS_GET``
``ETHTOOL_SRSSH`` n/a
``ETHTOOL_GTUNABLE`` n/a
``ETHTOOL_STUNABLE`` n/a
``ETHTOOL_GPHYSTATS`` n/a
``ETHTOOL_PERQUEUE`` n/a
``ETHTOOL_GLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_GET``
``ETHTOOL_MSG_LINKMODES_GET``
``ETHTOOL_SLINKSETTINGS`` ``ETHTOOL_MSG_LINKINFO_SET``
``ETHTOOL_MSG_LINKMODES_SET``
``ETHTOOL_PHY_GTUNABLE`` n/a
``ETHTOOL_PHY_STUNABLE`` n/a
``ETHTOOL_GFECPARAM`` ``ETHTOOL_MSG_FEC_GET``
``ETHTOOL_SFECPARAM`` ``ETHTOOL_MSG_FEC_SET``
n/a ``ETHTOOL_MSG_CABLE_TEST_ACT``
n/a ``ETHTOOL_MSG_CABLE_TEST_TDR_ACT``
n/a ``ETHTOOL_MSG_TUNNEL_INFO_GET``
n/a ``ETHTOOL_MSG_PHC_VCLOCKS_GET``
n/a ``ETHTOOL_MSG_MODULE_GET``
n/a ``ETHTOOL_MSG_MODULE_SET``
n/a ``ETHTOOL_MSG_PLCA_GET_CFG``
n/a ``ETHTOOL_MSG_PLCA_SET_CFG``
n/a ``ETHTOOL_MSG_PLCA_GET_STATUS``
n/a ``ETHTOOL_MSG_MM_GET``
n/a ``ETHTOOL_MSG_MM_SET``
n/a ``ETHTOOL_MSG_MODULE_FW_FLASH_ACT``
n/a ``ETHTOOL_MSG_PHY_GET``
``SIOCGHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_GET``
``SIOCSHWTSTAMP`` ``ETHTOOL_MSG_TSCONFIG_SET``
=================================== =====================================
요약·해설
ethtool-netlink.rst:1-2571이 인터페이스는 전통적인 ethtool ioctl을 확장 가능한 generic netlink 메시지로 옮깁니다. 공통 장치/PHY 헤더, 부분 갱신 가능한 임의 길이 bitset, GET/SET/ACT/NTF 수명 주기를 공유하고 각 기능은 별도의 attribute schema를 사용합니다.
긴 명령 목록을 구현 관점의 기능군으로 묶었습니다.
변경 및 동작 요청은 선택 응답과 비동기 notification으로 이어집니다.