| blob | a32230c1f09c0cbb9a68785daf903e867e13df1b |
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright 2016 Joyent, Inc.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
5 .\" are met:
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
11 .\"
12 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS
13 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
14 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
15 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
16 .\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
17 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
18 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
19 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 .\" ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
22 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
23 .\"
24 .Dd "Nov 23, 2016"
25 .Dt IEEE802.3 5
26 .Os
27 .Sh NAME
28 .Nm ieee802.3
29 .Nd IEEE 802.3 Ethernet parameters and statistics
30 .Sh DESCRIPTION
31 The IEEE 802.3 standard specifies the details for Ethernet
32 networking.
33 This page describes the various statistics and tunables that device drivers
34 supporting Ethernet commonly offer.
35 .
36 Note that not every device or driver supports every one of these
37 values, and many devices offer additional statistics and tunables that
38 are specific to that hardware.
39 See the device driver's documentation for those specific details.
40 .
41 .Lp
42 Values that are statistics are visible
43 .Xr kstat 1M ,
44 whereas properties are visible using the
45 .Xr dladm 1M
46 .Sy show-linkprop
47 subcommand.
48 Tunables are properties that can be changed using the
49 .Xr dladm 1M
50 .Sy set-linkprop
51 subcommand.
52 A more useful summary of current operational state can be seen with the
53 .Xr dladm 1M
54 .Sy show-ether
55 subcommand.
56 .
57 .Ss Statistics
58 The following statistics are accessible with
59 .Xr kstat 1M .
60 Note that some statistics are available in both 32- and 64-bit counters,
61 in which case the name of the 64 bit statistic will be the same as the
62 32-bit, but with
63 .Dq Sy 64
64 appended.
65 For example,
66 .Sy ipackets64
67 is the 64-bit version of the
68 .Sy ipackets
69 statistic.
70 These are indicated with the special suffix
71 .Op Sy 64
72 in the table below.
73 .
74 .Bl -tag -width tx_late_collisions
75 .It Sy adv_cap_1000fdx
76 Advertises 1000 Mbps full-duplex support.
77 .It Sy adv_cap_1000hdx
78 Advertises 1000 Mbps half-duplex support.
79 .It Sy adv_cap_100fdx
80 Advertises 100 Mbps full-duplex support.
81 .It Sy adv_cap_100gfdx
82 Advertises 100 Gbps support.
83 .It Sy adv_cap_100hdx
84 Advertises 100 Mbps half-duplex support.
85 .It Sy adv_cap_100T4
86 Advertises 100BASE-T4 support.
87 .It Sy adv_cap_10fdx
88 Advertises 10 Mbps full-duplex support.
89 .It Sy adv_cap_10gfdx
90 Advertises 10 Gbps support.
91 .It Sy adv_cap_10hdx
92 Advertises 10 Mbps half-duplex support.
93 .It Sy adv_cap_2500fdx
94 Advertises 2.5 Gbps support.
95 .It Sy adv_cap_50gfdx
96 Advertises 50 Gbps support.
97 .It Sy adv_cap_40gfdx
98 Advertises 40 Gbps support.
99 .It Sy adv_cap_25gfdx
100 Advertises 25 Gbps support.
101 .It Sy adv_cap_5000fdx
102 Advertises 5 Gbps support.
103 .It Sy adv_cap_autoneg
104 Advertises auto-negotiation support.
105 .It Sy adv_cap_asmpause
106 Advertises asymmetric flow control support.
107 .It Sy adv_cap_pause
108 Advertises flow control support.
109 .It Sy adv_rem_fault
110 Remote fault status sent to peer.
111 .It Sy align_errors
112 Mis-aligned frames received.
113 .It Sy brdcstrcv
114 Broadcast frames received.
115 .It Sy brdcstxmt
116 Broadcast frames transmitted.
117 .It Sy cap_1000fdx
118 Device supports 1000 Mbps full-duplex.
119 .It Sy cap_1000hdx
120 Device supports 1000 Mbps half-duplex.
121 .It Sy cap_100fdx
122 Device supports 100 Mbps full-duplex.
123 .It Sy cap_100gfdx
124 Device supports 100 Gbps.
125 .It Sy cap_100hdx
126 Device supports 100 Mbps half-duplex.
127 .It Sy cap_100T4
128 Device supports 100BASE-T4.
129 .It Sy cap_10fdx
130 Device supports 10 Mbps full-duplex.
131 .It Sy cap_10gfdx
132 Device supports 10 Gpbs.
133 .It Sy cap_10hdx
134 Device supports 10 Mbps half-duplex.
135 .It Sy cap_2500fdx
136 Device supports 2.5 Gbps.
137 .It Sy cap_50gfdx
138 Device supports 50 Gpbs.
139 .It Sy cap_40gfdx
140 Device supports 40 Gpbs.
141 .It Sy cap_25gfdx
142 Device supports 25 Gpbs.
143 .It Sy cap_5000fdx
144 Device supports 5 Gbps.
145 .It Sy cap_asmpause
146 Device supports asymmetric flow control.
147 .It Sy cap_autoneg
148 Device supports auto-negotiation.
149 .It Sy cap_pause
150 Device supports symmetric flow control.
151 .It Sy cap_rem_fault
152 Device supports remote fault notification.
153 .It Sy carrier_errors
154 Frames dropped due to loss of link.
155 .It Sy collisions
156 Collisions.
157 .It Sy defer_xmts
158 Transmits deferred due to link activity.
159 .It Sy ex_collisions
160 Frames dropped due to too many collisions.
161 .It Sy fcs_errors
162 Frames received with bad frame checksum.
163 .It Sy first_collisions
164 Frames with at least one collision.
165 .It Sy ierrors
166 Receive errors.
167 .It Sy ifspeed
168 Link speed in bits per second.
169 .It Sy ipackets Ns Op Sy 64
170 Frames received successfully.
171 .It Sy jabber_errors
172 Jabber errors.
173 .It Sy link_asmpause
174 Asymmetric flow control; works together with
175 .Sy link_pause .
176 See the description for it below.
177 .It Sy link_autoneg
178 Link was auto-negotiated.
179 .It Sy link_duplex
180 Link duplex status, values as follows:
181 .Bl -column "0" infinity
182 .It 0 Ta Unknown.
183 .It 1 Ta Half-duplex.
184 .It 2 Ta Full-duplex.
185 .El
186 .It Sy link_pause
187 Link flow control available; works together with
188 .Sy link_asmpause .
189 The meanings of these bits are:
190 .Bl -column "pause" "asmpause"
191 .It Sy pause Ta Sy asmpause Ta Sy meaning
192 .It 0 Ta 0 Ta "No flow control."
193 .It 1 Ta 0 Ta Symmetric flow control.
194 .It 0 Ta 1 Ta Honor received pause frames.
195 .It 1 Ta 1 Ta Send pause frames when congested.
196 .El
197 .It Sy link_state
198 Link state; 0 for down, 1 for up.
199 .It Sy link_up
200 Link is up if 1.
201 .It Sy lp_cap_1000fdx
202 Peer supports 1000 Mbps full-duplex.
203 .It Sy lp_cap_1000hdx
204 Peer supports 1000 Mbps half-duplex.
205 .It Sy lp_cap_100fdx
206 Peer supports 100 Mbps full-duplex.
207 .It Sy lp_cap_100gfdx
208 Peer supports 100 Gbps full-duplex.
209 .It Sy lp_cap_100hdx
210 Peer supports 100 Mbps half-duplex.
211 .It Sy lp_cap_100T4
212 Peer supports 100BASE-T4.
213 .It Sy lp_cap_10fdx
214 Peer supports 10 Mbps full-duplex.
215 .It Sy lp_cap_10gfdx
216 Peer supports 10 Gbps.
217 .It Sy lp_cap_10hdx
218 Peer supports 10 Mbps half-duplex.
219 .It Sy lp_cap_2500fdx
220 Peer supports 2.5 Gbps.
221 .It Sy lp_cap_5000fdx
222 Peer supports 5 Gbps.
223 .It Sy lp_cap_50gfdx
224 Peer supports 50 Gbps.
225 .It Sy lp_cap_40gfdx
226 Peer supports 40 Gbps.
227 .It Sy lp_cap_25gfdx
228 Peer supports 25 Gbps.
229 .It Sy lp_cap_asmpause
230 Peer supports asymmetric flow control.
231 .It Sy lp_cap_autoneg
232 Peer supports auto-negotiation.
233 .It Sy lp_cap_pause
234 Peer advertises flow control support.
235 .It Sy lp_rem_fault
236 Peer announces a remote fault.
237 .It Sy macrv_errors
238 Generic receive errors.
239 .It Sy macxmt_errors
240 Generic transmit errors.
241 .It Sy multi_collisions
242 Frames with more than one collision.
243 .It Sy multircv
244 Multicast frames received.
245 .It Sy multixmt
246 Multicast frames transmitted.
247 .It Sy norcvbuf
248 Receive frames dropped due to lack of resources.
249 .It Sy noxmtbuf
250 Transmit frames dropped due to lack of resources.
251 .It Sy obytes Ns Op Sy 64
252 Bytes (octets) transmitted successfully.
253 .It Sy oerrors
254 Transmit errors.
255 .It Sy oflo
256 Overflow errors.
257 .It Sy opackets Ns Op Sy 64
258 Frames successfully transmitted.
259 .It Sy promisc
260 Interface is in promiscuous mode.
261 .It Sy rbytes Ns Op Sy 64
262 Bytes (octets) received successfully.
263 .It Sy runt_errors
264 Frames received that were too short.
265 .It Sy sqe_errors
266 Squelch errors.
267 .It Sy toolong_errors
268 Frames received that were too long.
269 .It Sy tx_late_collisions
270 Late collisions on transmit.
271 .It Sy uflo
272 Underflow errors.
273 .It Sy unknowns
274 Frames received with no local recipient.
275 .It Sy xcvr_addr
276 Transceiver address.
277 .It Sy xcvr_id
278 Transceiver vendor and device ID.
279 .It Sy xcvr_inuse
280 Identifies the type of transceiver in use.
281 Values are as follows:
282 .Bl -column "0"
283 .It 0 Ta Unknown or undefined.
284 .It 1 Ta None.
285 .It 2 Ta 10 Mbps
286 .It 3 Ta 100BASE-T4
287 .It 4 Ta 100BASE-X
288 .It 5 Ta 100BASE-T2
289 .It 6 Ta 1000BASE-X
290 .It 7 Ta 1000BASE-T
291 .El
292 .El
293 .Ss Properties
294 The following parameters are accessible with
295 .Xr dladm 1M .
296 Some of these are normally read-only.
297 Other properties that are not specific to IEEE 802.3 / Ethernet links are also
298 available via
299 .Xr dladm 1M ,
300 and are documented in its man page rather than here.
301 .
302 .Bl -tag -width adv_1000hdx_cap
303 .It Sy speed
304 Link speed, in Mbps per second (dladm only).
305 .It Sy duplex
306 Link duplex, either "full" or "half".
307 .It Sy state
308 Link state, either "up" or "down".
309 .It Sy mtu
310 Maximum link frame size in bytes.
311 See
312 .Sx Jumbo Frames .
313 .It Sy flowctrl
314 Flow control setting, one of \(dqno\(dq, \(dqtx\(dq, \(dqrx\(dq, or \(dqbi\(dq.
315 See
316 .Sx Flow Control .
317 .It Sy adv_10gfdx_cap
318 Advertising 10 Gbps support.
319 .It Sy en_10gfdx_cap
320 Enable 10 Gbps support.
321 .
322 .It Sy adv_1000fdx_cap
323 Advertising 1000 Mbps full-duplex support.
324 .It Sy en_1000fdx_cap
325 Enable 1000 Mbps full-duplex.
326 .
327 .It Sy adv_1000hdx_cap
328 Advertising 1000 Mbps half-duplex support.
329 .It Sy en_1000hdx_cap
330 Enable 1000 Mbps half-duplex.
331 .
332 .It Sy adv_100fdx_cap
333 Advertising 100 Mbps full-duplex support.
334 .It Sy en_100fdx_cap
335 Enable 100 Mbps full-duplex.
336 .
337 .It Sy adv_100hdx_cap
338 Advertising 100 Mbps half-duplex support.
339 .It Sy en_100hdx_cap
340 Enable 100 Mbps half-duplex.
341 .
342 .It Sy adv_10fdx_cap
343 Advertising 10 Mbps full-duplex support.
344 .It Sy en_10fhdx_cap
345 Enable 100 Mbps full-duplex.
346 .
347 .It Sy adv_10hdx_cap
348 Advertising 10 Mbps half-duplex support.
349 .It Sy en_10fhdx_cap
350 Enable 10 Mbps half-duplex.
351 .El
352 .Ss Auto-negotiation
353 With modern devices, auto-negotiation is normally handled automatically.
354 With 10 Gbps and 1000 Gbps, it is mandatory (10GBASE-T also requires full-duplex
355 operation).
356 It is also
357 .Em strongly
358 recommended for use whenever possible; without auto-negotiation the link
359 will usually not operate unless both partners are configured to use the
360 same link mode.
361 .Lp
362 Auto-negotiation, when enabled, takes place by comparing the local capabilities
363 that have been advertised (which must also be supported by the local device),
364 with the capabilities that have been advertised by the link partner (peer).
365 .
366 The first of the following modes that is supported by both partners is
367 selected as the link negotiation result:
368 .Lp
369 .Bl -bullet -offset indent -compact
370 .It
371 10 Gbps (10gfdx)
372 .It
373 1000 Mbps full-duplex (1000fdx)
374 .It
375 1000 Mbps half-duplex (1000hdx)
376 .It
377 100 Mbps full-duplex (100fdx)
378 .It
379 100BASE-T4 (100T4)
380 .It
381 100 Mbps half-duplex (100hdx)
382 .It
383 10 Mbps full-duplex (10fdx)
384 .It
385 10 Mbps half-duplex (10hdx)
386 .El
387 .Lp
388 Advertisement of these modes can be enabled or disabled by setting the
389 appropriate
390 .Sy en_
391 property in
392 .Xr dladm 1M .
393 .Lp
394 Auto-negotiation may also be disabled, by setting the
395 .Sy adv_autoneg_cap
396 property to 0.
397 In this case, the highest enabled link mode (using the above list) is
398 .Dq forced
399 for the link.
400 .Ss Flow Control
401 Link layer flow control is available on many modern devices, and is mandatory
402 for operation at 10 Gbps.
403 It requires that the link be auto-negotiated, and that the link be full-duplex,
404 in order to function.
405 .Lp
406 Flow control is applied when a receiver becomes congested.
407 In this case the receiver can send a special frame, called a pause frame, to
408 request its partner cease transmitting for a short period of time.
409 .Lp
410 Flow control can be said to be either symmetric, in which case both partners
411 can send and honor pause frames, or asymmetric, in which case one partner
412 may not transmit pause frames.
413 .Lp
414 The flow control mode used is driven by the
415 .Sy flowctrl
416 property.
417 It has the following meanings:
418 .Lp
419 .Bl -column -compact -offset indent Dv
420 .It \(dqno\(dq Ta Neither send, nor honor pause frames.
421 .It \(dqtx\(dq Ta Send pause frames, provided that the peer can support them,
422 but do not honor them.
423 .It \(dqrx\(dq Ta Receive and honor pause frames.
424 .It \(dqbi\(dq Ta Both send and receive (and honor) pause frames.
425 .El
426 .Lp
427 The statistics for flow control
428 .Po Sy adv_cap_pause , adv_cap_asmpause , lp_cap_pause , lp_cap_asmpause ,
429 .Sy link_pause ,
430 and
431 .Sy link_asmpause
432 .Pc
433 are based on the properties exchanged in the auto-negotiation and are
434 confusing as a result.
435 Administrators are advised to use the
436 .Sy flowctrl
437 property instead.
438 .
439 .Ss Jumbo Frames
440 The IEEE 802.3 standard specifies a standard frame size of 1518 bytes,
441 which includes a 4-byte frame checksum, a 14-byte header, and 1500 bytes
442 of payload.
443 Most devices support larger frame sizes than this, and when all possible parties
444 on the same local network can do so, it may be advantageous to choose a larger
445 frame size; 9000 bytes is the most common option, as it allows a transport layer
446 to convey 8 KB (8192) of data, while leaving room for various link, network, and
447 transport layer headers.
448 .Lp
449 Note that the use of frames carrying more than 1500 bytes of payload is
450 not standardized, even though it is common practice.
451 .Lp
452 The
453 .Sy mtu
454 property is used to configure the frame size.
455 Note that this is the size of the payload, and excludes the preamble, checksum,
456 and header.
457 It also excludes the tag for devices that support tagging (see
458 .Sx Virtual LANs
459 below).
460 .Lp
461 Care must be taken to ensure that all communication parties agree on the same
462 size, or communication may cease to function properly.
463 .Lp
464 Note that the
465 .Sy mtu
466 property refers to the link layer property.
467 It may be necessary to configure upper layer protocols such as IP to use a
468 different size when this changes.
469 See
470 .Xr ifconfig 1M .
471 .
472 .Ss Virtual LANs
473 Most devices support virtual LANs (and also priority control tagging) though
474 the use of a 4-byte tag inserted between the frame header and payload.
475 The details of configuration of this are covered in the
476 .Xr dladm 1M
477 manual.
478 .
479 .Ss Data Link Provider Interface (DLPI) Details
480 .
481 The correct method for applications to access Ethernet devices directly
482 is to use the DLPI.
483 See
484 .Xr dlpi 7P
485 and
486 .Xr libdlpi 3LIB
487 for further information.
488 .Lp
489 The following DLPI parameters are presented to applications.
490 .Bl -column -offset indent "Broadcast address"
491 .It Maximum SDU Ta 1500 (or larger, as determined by the Sy mtu No property.)
492 .It Minimum SDU Ta 0
493 .It Address length Ta 6
494 .It MAC type Ta Dv DL_ETHER
495 .It SAP length Ta \(mi2
496 .It Service mode Ta Dv DL_CLDLS
497 .It Broadcast address Ta Li ff:ff:ff:ff:ff:ff No (6 bytes with all bits set)
498 .El
499 .Lp
500 Note that if the application binds to SAP of 0, then standard IEEE 802.3
501 mode is assumed and the frame length is stored in place of the Ethernet type.
502 Frames that arrive with the type field set to 1500 or less, are delivered
503 to applications that bind to SAP 0.
504 .Lp
505 Ethernet drivers on the support both DLPI style 1 and style 2 operation.
506 Additionally, it is possible to configure provide
507 .Dq vanity
508 names to interfaces using the
509 .Xr dladm 1M
510 .Sy rename-link
511 subcommand.
512 Such vanity names are only accessible using DLPI style 1.
513 .Sh NOTES
514 There may be other mechanisms available to configure link layer properties.
515 Historically the
516 .Xr ndd 1M
517 command, and
518 .Xr driver.conf 4
519 files could be used to do this.
520 These methods are deprecated in favor of
521 .Xr dladm 1M
522 properties.
523 .
524 .Sh INTERFACE STABILITY
525 When present, the statistics and properties presented here
526 are
527 .Sy Committed .
528 However, note that not every Ethernet device supports all of these,
529 and some devices may support additional statistics and properties.
530 .Lp
531 The DLPI and IEEE 802.3 itself are
532 .Sy Standard .
533 .Sh SEE ALSO
534 .Xr dladm 1M ,
535 .Xr ifconfig 1M ,
536 .Xr kstat 1M ,
537 .Xr ndd 1M ,
538 .Xr netstat 1M ,
539 .Xr libdlpi 3LIB ,
540 .Xr driver.conf 4 ,
541 .Xr dlpi 7P
542 .Rs
543 .%T IEEE 802.3: Ethernet
544 .%Q IEEE Standards Association
545 .Re
546 .Rs
547 .%B Data Link Provider Interface (DLPI)
548 .%Q The Open Group
549 .%D 1997
550 .Re
551 .Rs
552 .%B STREAMs Programming Guide
553 .%Q Sun Microsystems, Inc.
554 .%D January 2005
555 .Re