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