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