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