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