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
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.
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
29 .Nd IEEE 802.3 Ethernet parameters and statistics
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.
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.
41 Values that are statistics are visible
43 whereas properties are visible using the
46 subcommand. Tunables are properties that can be changed using the
49 subcommand. A more useful summary of current operational
50 state can be seen with the
56 The following statistics are accessible with
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
62 appended. For example,
64 is the 64-bit version of the
66 statistic. These are indicated with the special suffix
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.
76 Advertises 100 Mbps full-duplex support.
77 .It Sy adv_cap_100gfdx
78 Advertises 100 Gbps support.
80 Advertises 100 Mbps half-duplex support.
82 Advertises 100BASE-T4 support.
84 Advertises 10 Mbps full-duplex support.
86 Advertises 10 Gbps support.
88 Advertises 10 Mbps half-duplex support.
89 .It Sy adv_cap_2500fdx
90 Advertises 2.5 Gbps support.
92 Advertises 50 Gbps support.
94 Advertises 40 Gbps support.
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.
104 Advertises flow control support.
106 Remote fault status sent to peer.
108 Mis-aligned frames received.
110 Broadcast frames received.
112 Broadcast frames transmitted.
114 Device supports 1000 Mbps full-duplex.
116 Device supports 1000 Mbps half-duplex.
118 Device supports 100 Mbps full-duplex.
120 Device supports 100 Gbps.
122 Device supports 100 Mbps half-duplex.
124 Device supports 100BASE-T4.
126 Device supports 10 Mbps full-duplex.
128 Device supports 10 Gpbs.
130 Device supports 10 Mbps half-duplex.
132 Device supports 2.5 Gbps.
134 Device supports 50 Gpbs.
136 Device supports 40 Gpbs.
138 Device supports 25 Gpbs.
140 Device supports 5 Gbps.
142 Device supports asymmetric flow control.
144 Device supports auto-negotiation.
146 Device supports symmetric flow control.
148 Device supports remote fault notification.
149 .It Sy carrier_errors
150 Frames dropped due to loss of link.
154 Transmits deferred due to link activity.
156 Frames dropped due to too many collisions.
158 Frames received with bad frame checksum.
159 .It Sy first_collisions
160 Frames with at least one collision.
164 Link speed in bits per second.
165 .It Sy ipackets Ns Op Sy 64
166 Frames received successfully.
170 Asymmetric flow control; works together with
172 See the description for it below.
174 Link was auto-negotiated.
176 Link duplex status, values as follows:
177 .Bl -column "0" infinity
179 .It 1 Ta Half-duplex.
180 .It 2 Ta Full-duplex.
183 Link flow control available; works together with
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.
194 Link state; 0 for down, 1 for up.
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.
202 Peer supports 100 Mbps full-duplex.
203 .It Sy lp_cap_100gfdx
204 Peer supports 100 Gbps full-duplex.
206 Peer supports 100 Mbps half-duplex.
208 Peer supports 100BASE-T4.
210 Peer supports 10 Mbps full-duplex.
212 Peer supports 10 Gbps.
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.
220 Peer supports 50 Gbps.
222 Peer supports 40 Gbps.
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.
230 Peer advertises flow control support.
232 Peer announces a remote fault.
234 Generic receive errors.
236 Generic transmit errors.
237 .It Sy multi_collisions
238 Frames with more than one collision.
240 Multicast frames received.
242 Multicast frames transmitted.
244 Receive frames dropped due to lack of resources.
246 Transmit frames dropped due to lack of resources.
247 .It Sy obytes Ns Op Sy 64
248 Bytes (octets) transmitted successfully.
253 .It Sy opackets Ns Op Sy 64
254 Frames successfully transmitted.
256 Interface is in promiscuous mode.
257 .It Sy rbytes Ns Op Sy 64
258 Bytes (octets) received successfully.
260 Frames received that were too short.
263 .It Sy toolong_errors
264 Frames received that were too long.
265 .It Sy tx_late_collisions
266 Late collisions on transmit.
270 Frames received with no local recipient.
274 Transceiver vendor and device ID.
276 Identifies the type of transceiver in use. Values are as follows:
278 .It 0 Ta Unknown or undefined.
289 The following parameters are accessible with
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
294 and are documented in its man page rather than here.
296 .Bl -tag -width adv_1000hdx_cap
298 Link speed, in Mbps per second (dladm only).
300 Link duplex, either "full" or "half".
302 Link state, either "up" or "down".
304 Maximum link frame size in bytes. See
307 Flow control setting, one of \(dqno\(dq, \(dqtx\(dq, \(dqrx\(dq, or \(dqbi\(dq.
310 .It Sy adv_10gfdx_cap
311 Advertising 10 Gbps support.
313 Enable 10 Gbps support.
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.
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.
325 .It Sy adv_100fdx_cap
326 Advertising 100 Mbps full-duplex support.
328 Enable 100 Mbps full-duplex.
330 .It Sy adv_100hdx_cap
331 Advertising 100 Mbps half-duplex support.
333 Enable 100 Mbps half-duplex.
336 Advertising 10 Mbps full-duplex support.
338 Enable 100 Mbps full-duplex.
341 Advertising 10 Mbps half-duplex support.
343 Enable 10 Mbps half-duplex.
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
350 recommended for use whenever possible; without auto-negotiation the link
351 will usually not operate unless both partners are configured to use the
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).
358 The first of the following modes that is supported by both partners is
359 selected as the link negotiation result:
361 .Bl -bullet -offset indent -compact
365 1000 Mbps full-duplex (1000fdx)
367 1000 Mbps half-duplex (1000hdx)
369 100 Mbps full-duplex (100fdx)
373 100 Mbps half-duplex (100hdx)
375 10 Mbps full-duplex (10fdx)
377 10 Mbps half-duplex (10hdx)
380 Advertisement of these modes can be enabled or disabled by setting the
386 Auto-negotiation may also be disabled, by setting the
388 property to 0. In this case, the highest enabled link mode (using the above
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.
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.
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.
405 The flow control mode used is driven by the
407 property. It has the following meanings:
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.
417 The statistics for flow control
418 .Po Sy adv_cap_pause , adv_cap_asmpause , lp_cap_pause , lp_cap_asmpause ,
423 are based on the properties exchanged in the auto-negotiation and are
424 confusing as a result. Administrators are advised to use the
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.
437 Note that the use of frames carrying more than 1500 bytes of payload is
438 not standardized, even though it is common practice.
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
448 Care must be taken to ensure that all communication parties agree on the same
449 size, or communication may cease to function properly.
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.
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
465 .Ss Data Link Provider Interface (DLPI) Details
467 The correct method for applications to access Ethernet devices directly
468 is to use the DLPI. See
472 for further information.
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.)
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)
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.
490 Ethernet drivers on the support both DLPI style 1 and style 2 operation.
491 Additionally, it is possible to configure provide
493 names to interfaces using the
496 subcommand. Such vanity names are only accessible using DLPI style 1.
498 There may be other mechanisms available to configure link layer properties.
501 files could be used to do this. It is deprecated in favor of
505 .Sh INTERFACE STABILITY
506 When present, the statistics and properties presented here
509 However, note that not every Ethernet device supports all of these,
510 and some devices may support additional statistics and properties.
512 The DLPI and IEEE 802.3 itself are
523 .%T IEEE 802.3: Ethernet
524 .%Q IEEE Standards Association
527 .%B Data Link Provider Interface (DLPI)
532 .%B STREAMs Programming Guide
533 .%Q Sun Microsystems, Inc.