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