152d2369aSRobert Mustacchi.\" 252d2369aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 352d2369aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 452d2369aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 552d2369aSRobert Mustacchi.\" 1.0 of the CDDL. 652d2369aSRobert Mustacchi.\" 752d2369aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 852d2369aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 952d2369aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1052d2369aSRobert Mustacchi.\" 1152d2369aSRobert Mustacchi.\" 128c732929SRobert Mustacchi.\" Copyright 2019 Joyent, Inc. 13d77e6e0fSPaul Winder.\" Copyright 2020 RackTop Systems, Inc. 1486e5bb79SLuqman Aden.\" Copyright 2023 Oxide Computer Company 15b632e9f0SJason King.\" Copyright 2023 Jason King 16496cffd8SPeter Tribble.\" Copyright 2023 Peter Tribble 1752d2369aSRobert Mustacchi.\" 18496cffd8SPeter Tribble.Dd July 17, 2023 1952d2369aSRobert Mustacchi.Dt MAC 9E 2052d2369aSRobert Mustacchi.Os 2152d2369aSRobert Mustacchi.Sh NAME 2252d2369aSRobert Mustacchi.Nm mac , 2352d2369aSRobert Mustacchi.Nm GLDv3 2452d2369aSRobert Mustacchi.Nd MAC networking device driver overview 2552d2369aSRobert Mustacchi.Sh SYNOPSIS 2652d2369aSRobert Mustacchi.In sys/mac_provider.h 2752d2369aSRobert Mustacchi.In sys/mac_ether.h 2852d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 2952d2369aSRobert Mustacchiillumos DDI specific 3052d2369aSRobert Mustacchi.Sh DESCRIPTION 3152d2369aSRobert MustacchiThe 3252d2369aSRobert Mustacchi.Sy MAC 3352d2369aSRobert Mustacchiframework provides a means for implementing high-performance networking 3472d3dbb9SYuri Pankovdevice drivers. 3572d3dbb9SYuri PankovIt is the successor to the GLD interfaces and is sometimes referred to as the 3672d3dbb9SYuri PankovGLDv3. 3772d3dbb9SYuri PankovThe remainder of this manual introduces the aspects of writing devices drivers 3872d3dbb9SYuri Pankovthat leverage the MAC framework. 3972d3dbb9SYuri PankovWhile both the GLDv3 and MAC framework refer to the same thing, in this manual 4072d3dbb9SYuri Pankovpage we use the term the 4152d2369aSRobert Mustacchi.Em MAC framework 4252d2369aSRobert Mustacchito refer to the device driver interface. 4352d2369aSRobert Mustacchi.Pp 4472d3dbb9SYuri PankovMAC device drivers are character devices. 4572d3dbb9SYuri PankovThey define the standard 4652d2369aSRobert Mustacchi.Xr _init 9E , 4752d2369aSRobert Mustacchi.Xr _fini 9E , 4852d2369aSRobert Mustacchiand 4952d2369aSRobert Mustacchi.Xr _info 9E 5052d2369aSRobert Mustacchientry points to initialize the module, as well as 5152d2369aSRobert Mustacchi.Xr dev_ops 9S 5252d2369aSRobert Mustacchiand 5352d2369aSRobert Mustacchi.Xr cb_ops 9S 5452d2369aSRobert Mustacchistructures. 5552d2369aSRobert Mustacchi.Pp 5652d2369aSRobert MustacchiThe main interface with MAC is through a series of callbacks defined in 5752d2369aSRobert Mustacchia 5852d2369aSRobert Mustacchi.Xr mac_callbacks 9S 5972d3dbb9SYuri Pankovstructure. 6072d3dbb9SYuri PankovThese callbacks control all the aspects of the device. 6172d3dbb9SYuri PankovThey range from sending data, getting and setting of properties, controlling mac 6272d3dbb9SYuri Pankovaddress filters, and also managing promiscuous mode. 6352d2369aSRobert Mustacchi.Pp 6452d2369aSRobert MustacchiThe MAC framework takes care of many aspects of the device driver's 6572d3dbb9SYuri Pankovmanagement. 6672d3dbb9SYuri PankovA device that uses the MAC framework does not have to worry about creating 6772d3dbb9SYuri Pankovdevice nodes or implementing 6852d2369aSRobert Mustacchi.Xr open 9E 6952d2369aSRobert Mustacchior 7052d2369aSRobert Mustacchi.Xr close 9E 7172d3dbb9SYuri Pankovroutines. 7272d3dbb9SYuri PankovIn addition, all of the work to interact with 73bbf21555SRichard Lowe.Xr dlpi 4P 7452d2369aSRobert Mustacchiis taken care of automatically and transparently. 752c0ebdeeSRobert Mustacchi.Ss High-Level Design 762c0ebdeeSRobert MustacchiAt a high-level, a device driver is chiefly concerned with three general 772c0ebdeeSRobert Mustacchioperations: 782c0ebdeeSRobert Mustacchi.Bl -enum -offset indent 792c0ebdeeSRobert Mustacchi.It 802c0ebdeeSRobert MustacchiSending frames 812c0ebdeeSRobert Mustacchi.It 822c0ebdeeSRobert MustacchiReceiving frames 832c0ebdeeSRobert Mustacchi.It 842c0ebdeeSRobert MustacchiManaging device configuration and metadata 852c0ebdeeSRobert Mustacchi.El 862c0ebdeeSRobert Mustacchi.Pp 872c0ebdeeSRobert MustacchiWhen sending frames, the MAC framework always calls functions registered 882c0ebdeeSRobert Mustacchiin the 892c0ebdeeSRobert Mustacchi.Xr mac_callbacks 9S 902c0ebdeeSRobert Mustacchistructure to have the driver transmit frames on hardware. 912c0ebdeeSRobert MustacchiWhen receiving frames, the driver will generally receive an interrupt which will 922c0ebdeeSRobert Mustacchicause it to check for incoming data and deliver it to the MAC framework. 932c0ebdeeSRobert Mustacchi.Pp 942c0ebdeeSRobert MustacchiConfiguration of a device, such as whether auto-negotiation should be 952c0ebdeeSRobert Mustacchienabled, the speeds that the device supports, the MTU (maximum 962c0ebdeeSRobert Mustacchitransmission unit), and the generation of pause frames are all driven by 972c0ebdeeSRobert Mustacchiproperties. 982c0ebdeeSRobert MustacchiThe functions to get, set, and obtain information about properties are 992c0ebdeeSRobert Mustacchidefined through callback functions specified in the 1002c0ebdeeSRobert Mustacchi.Xr mac_callbacks 9S 1012c0ebdeeSRobert Mustacchistructure. 1022c0ebdeeSRobert MustacchiThe full list of properties and a description of the relevant callbacks 1032c0ebdeeSRobert Mustacchican be found in the 1042c0ebdeeSRobert Mustacchi.Sx PROPERTIES 1052c0ebdeeSRobert Mustacchisection. 1062c0ebdeeSRobert Mustacchi.Pp 1072c0ebdeeSRobert MustacchiThe MAC framework is designed to take advantage of various modern 1082c0ebdeeSRobert Mustacchifeatures provided by hardware, such as checksumming, segmentation 1092c0ebdeeSRobert Mustacchioffload, and hardware filtering. 1102c0ebdeeSRobert MustacchiThe MAC framework assumes none of these advanced features are present 1112c0ebdeeSRobert Mustacchiand allows device drivers to negotiate them through a capability system. 1122c0ebdeeSRobert MustacchiDrivers can declare that they support various capabilities by 1132c0ebdeeSRobert Mustacchiimplementing the optional 1142c0ebdeeSRobert Mustacchi.Xr mc_getcapab 9E 1152c0ebdeeSRobert Mustacchientry point. 1162c0ebdeeSRobert MustacchiEach capability has its associated entry points and structures to fill 1172c0ebdeeSRobert Mustacchiout. 1182c0ebdeeSRobert MustacchiThe capabilities are detailed in the 1192c0ebdeeSRobert Mustacchi.Sx CAPABILITIES 1202c0ebdeeSRobert Mustacchisection. 1212c0ebdeeSRobert Mustacchi.Pp 1222c0ebdeeSRobert MustacchiThe following sections describe the flow of a basic device driver. 1232c0ebdeeSRobert MustacchiFor advanced device drivers, the flow is generally the same. 1242c0ebdeeSRobert MustacchiThe primary distinction is in how frames are sent and received. 12552d2369aSRobert Mustacchi.Ss Initializing MAC Support 1262c0ebdeeSRobert MustacchiFor a device to be used by the MAC framework, it must register with the 12752d2369aSRobert Mustacchiframework and take specific actions during 12852d2369aSRobert Mustacchi.Xr _init 9E , 12952d2369aSRobert Mustacchi.Xr attach 9E , 13052d2369aSRobert Mustacchi.Xr detach 9E , 13152d2369aSRobert Mustacchiand 13252d2369aSRobert Mustacchi.Xr _fini 9E . 13352d2369aSRobert Mustacchi.Pp 13452d2369aSRobert MustacchiAll device drivers have to define a 13552d2369aSRobert Mustacchi.Xr dev_ops 9S 13652d2369aSRobert Mustacchistructure which is pointed to by a 13752d2369aSRobert Mustacchi.Xr modldrv 9S 13852d2369aSRobert Mustacchistructure and the corresponding NULL-terminated 13952d2369aSRobert Mustacchi.Xr modlinkage 9S 14072d3dbb9SYuri Pankovstructure. 14172d3dbb9SYuri PankovThe 14252d2369aSRobert Mustacchi.Xr dev_ops 9S 14352d2369aSRobert Mustacchistructure should have a 14452d2369aSRobert Mustacchi.Xr cb_ops 9S 14552d2369aSRobert Mustacchistructure defined for it; however, it does not need to implement any of 14652d2369aSRobert Mustacchithe standard 14752d2369aSRobert Mustacchi.Xr cb_ops 9S 14886e5bb79SLuqman Adenentry points unless it also exposes a custom set of device nodes not 14986e5bb79SLuqman Adenotherwise managed by the MAC framework. 15086e5bb79SLuqman AdenSee the 15186e5bb79SLuqman Aden.Sx Custom Device Nodes 15286e5bb79SLuqman Adensection for more details. 15352d2369aSRobert Mustacchi.Pp 15452d2369aSRobert MustacchiNormally, in a driver's 15552d2369aSRobert Mustacchi.Xr _init 9E 15652d2369aSRobert Mustacchientry point, it passes its 1572c0ebdeeSRobert Mustacchi.Xr modlinkage 9S 15852d2369aSRobert Mustacchistructure directly to 15952d2369aSRobert Mustacchi.Xr mod_install 9F . 16052d2369aSRobert MustacchiTo properly register with MAC, the driver must call 16152d2369aSRobert Mustacchi.Xr mac_init_ops 9F 16252d2369aSRobert Mustacchibefore it calls 16352d2369aSRobert Mustacchi.Xr mod_install 9F . 16452d2369aSRobert MustacchiIf for some reason the 16552d2369aSRobert Mustacchi.Xr mod_install 9F 16652d2369aSRobert Mustacchifunction fails, then the driver must be removed by a call to 16752d2369aSRobert Mustacchi.Xr mac_fini_ops 9F . 16852d2369aSRobert Mustacchi.Pp 16952d2369aSRobert MustacchiConversely, in the driver's 170b31ca922SChris Fraire.Xr _fini 9E 17152d2369aSRobert Mustacchiroutine, it should call 17252d2369aSRobert Mustacchi.Xr mac_fini_ops 9F 17352d2369aSRobert Mustacchiafter it successfully calls 17452d2369aSRobert Mustacchi.Xr mod_remove 9F . 17552d2369aSRobert MustacchiFor an example of how to use the 17652d2369aSRobert Mustacchi.Xr mac_init_ops 9F 17752d2369aSRobert Mustacchiand 17852d2369aSRobert Mustacchi.Xr mac_fini_ops 9F 17952d2369aSRobert Mustacchifunctions, see the examples section in 18052d2369aSRobert Mustacchi.Xr mac_init_ops 9F . 18186e5bb79SLuqman Aden.Ss Custom Device Nodes 18286e5bb79SLuqman AdenA device may want to provide its own minor nodes as simple character or block 18386e5bb79SLuqman Adendevices backed by the usual 18486e5bb79SLuqman Aden.Xr cb_ops 9S 18586e5bb79SLuqman Adenroutines. 18686e5bb79SLuqman AdenThe MAC framework allows for this by leaving a portion of the minor 18786e5bb79SLuqman Adennumber space available for private driver use. 18886e5bb79SLuqman Aden.Xr mac_private_minor 9F 18986e5bb79SLuqman Adenreturns the first minor number a driver may use for its own purposes, 19086e5bb79SLuqman Adene.g., to pass to 19186e5bb79SLuqman Aden.Xr ddi_create_minor_node 9F . 19286e5bb79SLuqman Aden.Pp 19386e5bb79SLuqman AdenA driver making use of this ability must provide its own 19486e5bb79SLuqman Aden.Xr getinfo 9E 19586e5bb79SLuqman Adenimplementation that is aware of any such minor nodes. 19686e5bb79SLuqman AdenIt must also delegate back to the MAC framework as appropriate via either 19786e5bb79SLuqman Adencalls to 19886e5bb79SLuqman Aden.Xr mac_getinfo 9F 19986e5bb79SLuqman Adenor 20086e5bb79SLuqman Aden.Xr mac_devt_to_instance 9F 20186e5bb79SLuqman Adenfor MAC reserved minor nodes. 20286e5bb79SLuqman AdenIt should also take care to not affect MAC reserved minors, e.g., 20386e5bb79SLuqman Adenremoving all minor nodes associated with a device: 20486e5bb79SLuqman Aden.Bd -literal -offset indent 20586e5bb79SLuqman Aden ddi_remove_minor_node(dip, NULL); 20686e5bb79SLuqman Aden.Ed 20752d2369aSRobert Mustacchi.Ss Registering with MAC 20852d2369aSRobert MustacchiEvery instance of a device should register separately with MAC. 20952d2369aSRobert MustacchiTo register with MAC, a driver must allocate a 21052d2369aSRobert Mustacchi.Xr mac_register 9S 21152d2369aSRobert Mustacchistructure, fill it in, and then call 21252d2369aSRobert Mustacchi.Xr mac_register 9F . 21352d2369aSRobert MustacchiThe 2142c0ebdeeSRobert Mustacchi.Vt mac_register_t 21552d2369aSRobert Mustacchistructure contains information about the device and all of the required 21652d2369aSRobert Mustacchifunction pointers that will be used as callbacks by the framework. 21752d2369aSRobert Mustacchi.Pp 21852d2369aSRobert MustacchiThese steps should all be taken during a device's 21952d2369aSRobert Mustacchi.Xr attach 9E 22072d3dbb9SYuri Pankoventry point. 22172d3dbb9SYuri PankovIt is recommended that the driver perform this sequence of steps after the 22272d3dbb9SYuri Pankovdevice has finished its initialization of the chipset and interrupts, though 22372d3dbb9SYuri Pankovinterrupts should not be enabled at that point. 22452d2369aSRobert MustacchiAfter it calls 22552d2369aSRobert Mustacchi.Xr mac_register 9F 22652d2369aSRobert Mustacchiit will start receiving callbacks from the MAC framework. 22752d2369aSRobert Mustacchi.Pp 22852d2369aSRobert MustacchiTo allocate the registration structure, the driver should call 22952d2369aSRobert Mustacchi.Xr mac_alloc 9F . 23052d2369aSRobert MustacchiDevice drivers should generally always pass the symbol 2312c0ebdeeSRobert Mustacchi.Dv MAC_VERSION 23252d2369aSRobert Mustacchias the argument to 23352d2369aSRobert Mustacchi.Xr mac_alloc 9F . 23452d2369aSRobert MustacchiUpon successful completion, the driver will receive a 2352c0ebdeeSRobert Mustacchi.Vt mac_register_t 23672d3dbb9SYuri Pankovstructure which it should fill in. 23772d3dbb9SYuri PankovThe structure and its members are documented in 23852d2369aSRobert Mustacchi.Xr mac_register 9S . 23952d2369aSRobert Mustacchi.Pp 24052d2369aSRobert MustacchiThe 24152d2369aSRobert Mustacchi.Xr mac_callbacks 9S 24252d2369aSRobert Mustacchistructure is not allocated as a part of the 24352d2369aSRobert Mustacchi.Xr mac_register 9S 24472d3dbb9SYuri Pankovstructure. 24572d3dbb9SYuri PankovIn general, device drivers declare this statically. 24672d3dbb9SYuri PankovSee the 24752d2369aSRobert Mustacchi.Sx MAC Callbacks 24852d2369aSRobert Mustacchisection for more information on how to fill it out. 24952d2369aSRobert Mustacchi.Pp 25052d2369aSRobert MustacchiOnce the structure has been filled in, the driver should call 25152d2369aSRobert Mustacchi.Xr mac_register 9F 25272d3dbb9SYuri Pankovto register itself with MAC. 25372d3dbb9SYuri PankovThe handle that it uses to register with should be part of the driver's soft 25472d3dbb9SYuri Pankovstate. 25572d3dbb9SYuri PankovIt will be used in various other support functions and callbacks. 25652d2369aSRobert Mustacchi.Pp 25752d2369aSRobert MustacchiIf the call is successful, then the device driver 25852d2369aSRobert Mustacchishould enable interrupts and finish any other initialization required. 25952d2369aSRobert MustacchiIf the call to 26052d2369aSRobert Mustacchi.Xr mac_register 9F 26152d2369aSRobert Mustacchifailed, then it should unwind its initialization and should return 2622c0ebdeeSRobert Mustacchi.Dv DDI_FAILURE 26352d2369aSRobert Mustacchifrom its 26452d2369aSRobert Mustacchi.Xr attach 9E 26552d2369aSRobert Mustacchiroutine. 2668c732929SRobert Mustacchi.Pp 2678c732929SRobert MustacchiThe driver does not need to hold onto an allocated 2688c732929SRobert Mustacchi.Xr mac_register 9S 2698c732929SRobert Mustacchistructure after it has called the 2708c732929SRobert Mustacchi.Xr mac_register 9F 2718c732929SRobert Mustacchifunction. 2728c732929SRobert MustacchiWhether the 2738c732929SRobert Mustacchi.Xr mac_register 9F 2748c732929SRobert Mustacchifunction returns successfully or not, the driver may free its 2758c732929SRobert Mustacchi.Xr mac_register 9S 2768c732929SRobert Mustacchistructure by calling the 2778c732929SRobert Mustacchi.Xr mac_free 9F 2788c732929SRobert Mustacchifunction. 27952d2369aSRobert Mustacchi.Ss MAC Callbacks 28052d2369aSRobert MustacchiThe MAC framework interacts with a device driver through a series of 28172d3dbb9SYuri Pankovcallbacks. 28272d3dbb9SYuri PankovThese callbacks are described in their individual manual pages and the 28372d3dbb9SYuri Pankovcollection of callbacks is indicated in the 28452d2369aSRobert Mustacchi.Xr mac_callbacks 9S 28572d3dbb9SYuri Pankovmanual page. 28672d3dbb9SYuri PankovThis section does not focus on the specific functions, but rather on 28772d3dbb9SYuri Pankovinteractions between them and the rest of the device driver framework. 28852d2369aSRobert Mustacchi.Pp 28952d2369aSRobert MustacchiA device driver should make no assumptions about when the various 29052d2369aSRobert Mustacchicallbacks will be called and whether or not they will be called 29172d3dbb9SYuri Pankovsimultaneously. 29272d3dbb9SYuri PankovFor example, a device driver may be asked to transmit data through a call to its 293b31ca922SChris Fraire.Xr mc_tx 9E 29452d2369aSRobert Mustacchientry point while it is being asked to get a device property through a 29552d2369aSRobert Mustacchicall to its 296b31ca922SChris Fraire.Xr mc_getprop 9E 29772d3dbb9SYuri Pankoventry point. 29872d3dbb9SYuri PankovAs such, while some calls may be serialized to the device, such as setting 29972d3dbb9SYuri Pankovproperties, the device driver should always presume that all of its data needs 30072d3dbb9SYuri Pankovto be protected with locks. 30172d3dbb9SYuri PankovWhile the device is holding locks, it is safe for it call the following MAC 30272d3dbb9SYuri Pankovroutines: 30352d2369aSRobert Mustacchi.Bl -bullet -offset indent -compact 30452d2369aSRobert Mustacchi.It 30552d2369aSRobert Mustacchi.Xr mac_hcksum_get 9F 30652d2369aSRobert Mustacchi.It 30752d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F 30852d2369aSRobert Mustacchi.It 30952d2369aSRobert Mustacchi.Xr mac_lso_get 9F 31052d2369aSRobert Mustacchi.It 31152d2369aSRobert Mustacchi.Xr mac_maxsdu_update 9F 31252d2369aSRobert Mustacchi.It 31352d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_link_flowctrl 9F 31452d2369aSRobert Mustacchi.It 31552d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_str 9F 31652d2369aSRobert Mustacchi.It 31752d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint8 9F 31852d2369aSRobert Mustacchi.It 31952d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint32 9F 32052d2369aSRobert Mustacchi.It 32152d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint64 9F 32252d2369aSRobert Mustacchi.It 32352d2369aSRobert Mustacchi.Xr mac_prop_info_set_perm 9F 32452d2369aSRobert Mustacchi.It 32552d2369aSRobert Mustacchi.Xr mac_prop_info_set_range_uint32 9F 32652d2369aSRobert Mustacchi.El 32752d2369aSRobert Mustacchi.Pp 32852d2369aSRobert MustacchiAny other MAC related routines should not be called with locks held, 32952d2369aSRobert Mustacchisuch as 33052d2369aSRobert Mustacchi.Xr mac_link_update 9F 33152d2369aSRobert Mustacchior 33252d2369aSRobert Mustacchi.Xr mac_rx 9F . 33352d2369aSRobert MustacchiOther routines in the DDI may be called while locks are held; however, 33452d2369aSRobert Mustacchidevice driver writers should be careful about calling blocking routines 3352c0ebdeeSRobert Mustacchiwhile locks are held or in interrupt context, even when it is 3362c0ebdeeSRobert Mustacchilegal to do so as this may cause all other callers that need a given 3372c0ebdeeSRobert Mustacchilock to back up behind such an operation. 33852d2369aSRobert Mustacchi.Ss Receiving Data 33952d2369aSRobert MustacchiA device driver will often receive data through the means of an 3402c0ebdeeSRobert Mustacchiinterrupt or by being asked to poll for frames. 3412c0ebdeeSRobert MustacchiWhen this occurs, zero or more frames, each with optional metadata, may 3422c0ebdeeSRobert Mustacchibe ready for the device driver to consume. 34372d3dbb9SYuri PankovOften each frame has a corresponding descriptor which has information about 34472d3dbb9SYuri Pankovwhether or not there were errors or whether or not the device successfully 34572d3dbb9SYuri Pankovchecksummed the packet. 3468c732929SRobert MustacchiIn addition to the per-packet flow described below, there are certain 3478c732929SRobert Mustacchirequirements that drivers must adhere to when programming the hardware 3488c732929SRobert Mustacchito receive data. 3498c732929SRobert MustacchiSee the section 3508c732929SRobert Mustacchi.Sx RECEIVE DESCRIPTOR LAYOUT 3518c732929SRobert Mustacchifor more information. 35252d2369aSRobert Mustacchi.Pp 3532c0ebdeeSRobert MustacchiDuring a single interrupt or poll request, a device driver should process 3542c0ebdeeSRobert Mustacchia fixed number of frames. 35572d3dbb9SYuri PankovFor each frame the device driver should: 35652d2369aSRobert Mustacchi.Bl -enum -offset indent 35752d2369aSRobert Mustacchi.It 3582c0ebdeeSRobert MustacchiEnsure that all of the DMA memory for the descriptor ring is synchronized with 3592c0ebdeeSRobert Mustacchithe 3602c0ebdeeSRobert Mustacchi.Xr ddi_dma_sync 9F 3612c0ebdeeSRobert Mustacchifunction and check the handle for errors if the device driver has enabled DMA 3622c0ebdeeSRobert Mustacchierror reporting as part of the Fault Management Architecture (FMA). 3632c0ebdeeSRobert MustacchiIf the driver does not rely on DMA, then it may skip this step. 3642c0ebdeeSRobert MustacchiIt is recommended that this is performed once per interrupt or poll for 3652c0ebdeeSRobert Mustacchithe entire region and not on a per-packet basis. 3662c0ebdeeSRobert Mustacchi.It 36772d3dbb9SYuri PankovFirst check whether or not the frame has errors. 36872d3dbb9SYuri PankovIf errors were detected, then the frame should not be sent to the operating 36972d3dbb9SYuri Pankovsystem. 37072d3dbb9SYuri PankovIt is recommended that devices keep kstats (see 371b31ca922SChris Fraire.Xr kstat_create 9F 37252d2369aSRobert Mustacchifor more information) and bump the counter whenever such an error is 37372d3dbb9SYuri Pankovdetected. 37472d3dbb9SYuri PankovIf the device distinguishes between the types of errors, then separate kstats 37572d3dbb9SYuri Pankovfor each class of error are recommended. 37672d3dbb9SYuri PankovSee the 37752d2369aSRobert Mustacchi.Sx STATISTICS 37852d2369aSRobert Mustacchisection for more information on the various error cases that should be 37952d2369aSRobert Mustacchiconsidered. 38052d2369aSRobert Mustacchi.It 38152d2369aSRobert MustacchiOnce the frame has been determined to be valid, the device driver should 38252d2369aSRobert Mustacchitransform the frame into a 38352d2369aSRobert Mustacchi.Xr mblk 9S . 38452d2369aSRobert MustacchiSee the section 38552d2369aSRobert Mustacchi.Sx MBLKS AND DMA 38652d2369aSRobert Mustacchifor more information on how to transform and prepare a message block. 38752d2369aSRobert Mustacchi.It 38852d2369aSRobert MustacchiIf the device supports hardware checksumming (see the 38952d2369aSRobert Mustacchi.Sx CAPABILITIES 39052d2369aSRobert Mustacchisection for more information on checksumming), then the device driver 39152d2369aSRobert Mustacchishould set the corresponding checksumming information with a call to 39252d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F . 39352d2369aSRobert Mustacchi.It 39452d2369aSRobert MustacchiIt should then append this new message block to the 39552d2369aSRobert Mustacchi.Em end 39652d2369aSRobert Mustacchiof the message block chain, linking it to the 3972c0ebdeeSRobert Mustacchi.Fa b_next 39872d3dbb9SYuri Pankovpointer. 39972d3dbb9SYuri PankovIt is vitally important that all the frames be chained in the order that they 40072d3dbb9SYuri Pankovwere received. 40172d3dbb9SYuri PankovIf the device driver mistakenly reorders frames, then it may cause performance 40272d3dbb9SYuri Pankovimpacts in the TCP stack and potentially impact application correctness. 40352d2369aSRobert Mustacchi.El 40452d2369aSRobert Mustacchi.Pp 40552d2369aSRobert MustacchiOnce all the frames have been processed and assembled, the device driver 40652d2369aSRobert Mustacchishould deliver them to the rest of the operating system by calling 40752d2369aSRobert Mustacchi.Xr mac_rx 9F . 40852d2369aSRobert MustacchiThe device driver should try to give as many mblk_t structures to the 40972d3dbb9SYuri Pankovsystem at once. 41072d3dbb9SYuri PankovIt 41152d2369aSRobert Mustacchi.Em should not 41252d2369aSRobert Mustacchicall 41352d2369aSRobert Mustacchi.Xr mac_rx 9F 41452d2369aSRobert Mustacchionce for every assembled mblk_t. 41552d2369aSRobert Mustacchi.Pp 41652d2369aSRobert MustacchiThe device driver must not hold any locks across the call to 41752d2369aSRobert Mustacchi.Xr mac_rx 9F . 41852d2369aSRobert MustacchiWhen this function is called, received data will be pushed through the 41952d2369aSRobert Mustacchinetworking stack and some replies may be generated and given to the 42052d2369aSRobert Mustacchidriver to send out. 42152d2369aSRobert Mustacchi.Pp 42252d2369aSRobert MustacchiIt is not the device driver's responsibility to determine whether or not 42372d3dbb9SYuri Pankovthe system can keep up with a driver's delivery rate of frames. 42472d3dbb9SYuri PankovThe rest of the networking stack will handle issues related to keeping up 42552d2369aSRobert Mustacchiappropriately and ensure that kernel memory is not exhausted by packets 42652d2369aSRobert Mustacchithat are not being processed. 42752d2369aSRobert Mustacchi.Pp 4282c0ebdeeSRobert MustacchiIf the device driver has negotiated the 4292c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 4302c0ebdeeSRobert Mustacchicapability 4312c0ebdeeSRobert Mustacchi.Pq discussed in Xr mac_capab_rings 9E 4322c0ebdeeSRobert Mustacchithen it should call 4332c0ebdeeSRobert Mustacchi.Xr mac_rx_ring 9F 4342c0ebdeeSRobert Mustacchiand not 4352c0ebdeeSRobert Mustacchi.Xr mac_rx 9F . 4362c0ebdeeSRobert MustacchiA given interrupt may correspond to more than one ring that needs to be 4372c0ebdeeSRobert Mustacchichecked. 4382c0ebdeeSRobert MustacchiThe set of rings is likely to span different groups that were registered 4392c0ebdeeSRobert Mustacchiwith MAC through the 4402c0ebdeeSRobert Mustacchi.Xr mr_gget 9E 4412c0ebdeeSRobert Mustacchiinterface. 4422c0ebdeeSRobert MustacchiIn those cases, the driver should follow the above procedure 4432c0ebdeeSRobert Mustacchiindependently for each ring. 4442c0ebdeeSRobert MustacchiThat means it will call 4452c0ebdeeSRobert Mustacchi.Xr mac_rx_ring 9F 4462c0ebdeeSRobert Mustacchionce for each ring using the handle that it received from when MAC 4472c0ebdeeSRobert Mustacchicalled the driver's 4482c0ebdeeSRobert Mustacchi.Xr mr_rget 9E 4492c0ebdeeSRobert Mustacchientry point. 4502c0ebdeeSRobert MustacchiWhen it is looking at the rings, the driver will need to make sure that 4512c0ebdeeSRobert Mustacchithe ring has not had interrupts disabled 4522c0ebdeeSRobert Mustacchi.Pq due to a pending change to polling mode . 4532c0ebdeeSRobert MustacchiThis is discussed in greater detail in the 4542c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E 4552c0ebdeeSRobert Mustacchiand 4562c0ebdeeSRobert Mustacchi.Xr mri_poll 9E 4572c0ebdeeSRobert Mustacchimanual pages. 4582c0ebdeeSRobert Mustacchi.Pp 45952d2369aSRobert MustacchiFinally, the device driver should make sure that any other housekeeping 46052d2369aSRobert Mustacchiactivities required for the ring are taken care of such that more data 46152d2369aSRobert Mustacchican be received. 46252d2369aSRobert Mustacchi.Ss Transmitting Data and Back Pressure 46352d2369aSRobert MustacchiA device driver will be asked to transmit a message block chain by 46452d2369aSRobert Mustacchihaving it's 46552d2369aSRobert Mustacchi.Xr mc_tx 9E 46672d3dbb9SYuri Pankoventry point called. 46772d3dbb9SYuri PankovWhile the driver is processing the message blocks, it may run out of resources. 46872d3dbb9SYuri PankovFor example, a transmit descriptor ring may become full. 46972d3dbb9SYuri PankovAt that point, the device driver should return the remaining unprocessed frames. 47072d3dbb9SYuri PankovThe act of returning frames indicates that the device has asserted flow control. 47152d2369aSRobert MustacchiOnce this has been done, no additional calls will be made to the 47252d2369aSRobert Mustacchidriver's transmit entry point and the back pressure will be propagated 47352d2369aSRobert Mustacchithroughout the rest of the networking stack. 47452d2369aSRobert Mustacchi.Pp 47552d2369aSRobert MustacchiAt some point in the future when resources have become available again, 47652d2369aSRobert Mustacchifor example after an interrupt indicating that some portion of the 47752d2369aSRobert Mustacchitransmit ring has been sent, then the device driver must notify the 47872d3dbb9SYuri Pankovsystem that it can continue transmission. 47972d3dbb9SYuri PankovTo do this, the driver should call 48052d2369aSRobert Mustacchi.Xr mac_tx_update 9F . 48152d2369aSRobert MustacchiAfter that point, the driver will receive calls to its 48252d2369aSRobert Mustacchi.Xr mc_tx 9E 48372d3dbb9SYuri Pankoventry point again. 48472d3dbb9SYuri PankovAs mentioned in the section on callbacks, the device driver should avoid holding 48572d3dbb9SYuri Pankovany particular locks across the call to 48652d2369aSRobert Mustacchi.Xr mac_tx_update 9F . 48752d2369aSRobert Mustacchi.Ss Interrupt Coalescing 48852d2369aSRobert MustacchiFor devices operating at higher data rates, interrupt coalescing is an 48952d2369aSRobert Mustacchiimportant part of a well functioning device and may impact the 49072d3dbb9SYuri Pankovperformance of the device. 49172d3dbb9SYuri PankovNot all devices support interrupt coalescing. 49272d3dbb9SYuri PankovIf interrupt coalescing is supported on the device, it is recommended that 49372d3dbb9SYuri Pankovdevice driver writers provide private properties for their device to control the 49472d3dbb9SYuri Pankovinterrupt coalescing rate. 49572d3dbb9SYuri PankovThis will make it much easier to perform experiments and observe the impact of 49672d3dbb9SYuri Pankovdifferent interrupt rates on the rest of the system. 4972c0ebdeeSRobert Mustacchi.Ss Polling 4982c0ebdeeSRobert MustacchiEven with interrupt coalescing, when there is a certain incoming packet rate it 4992c0ebdeeSRobert Mustacchican make more sense to just actively poll the device, asking for more packets 5002c0ebdeeSRobert Mustacchirather than constantly taking an interrupt. 5012c0ebdeeSRobert MustacchiWhen a device driver supports the 5022c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E 5032c0ebdeeSRobert Mustacchicapability and therefore polling on receive rings, the MAC framework will ask 5042c0ebdeeSRobert Mustacchithe driver to disable interrupts, with its 5052c0ebdeeSRobert Mustacchi.Xr mi_disable 9E 5062c0ebdeeSRobert Mustacchientry point, and then subsequently call its polling entry point, 5072c0ebdeeSRobert Mustacchi.Xr mri_poll 9E . 5082c0ebdeeSRobert Mustacchi.Pp 5092c0ebdeeSRobert MustacchiAs long as a device driver implements the needed entry points, then there is 5102c0ebdeeSRobert Mustacchinothing else that it needs to do to take advantage of polling. 5112c0ebdeeSRobert MustacchiA driver should not attempt to spin up its own threads, task queues, or 5122c0ebdeeSRobert Mustacchicreatively use timeouts, to try to simulate polling for received packets. 51352d2369aSRobert Mustacchi.Ss MAC Address Filter Management 51452d2369aSRobert MustacchiThe MAC framework will attempt to use as many MAC address filters as a 51572d3dbb9SYuri Pankovdevice has. 51672d3dbb9SYuri PankovTo program a multicast address filter, the driver's 51752d2369aSRobert Mustacchi.Xr mc_multicst 9E 51872d3dbb9SYuri Pankoventry point will be called. 51972d3dbb9SYuri PankovIf the device driver runs out of filters, it should not take any special action 52072d3dbb9SYuri Pankovand just return the appropriate error as documented in the corresponding manual 52172d3dbb9SYuri Pankovpages for the entry points. 52252d2369aSRobert MustacchiThe framework will ensure that the device is placed in promiscuous mode 52352d2369aSRobert Mustacchiif it needs to. 5242c0ebdeeSRobert Mustacchi.Pp 5252c0ebdeeSRobert MustacchiIf the hardware supports more than one unicast filter then the device 5262c0ebdeeSRobert Mustacchidriver should consider implementing the 5272c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 5282c0ebdeeSRobert Mustacchicapability, which exposes a means for multiple unicast MAC address filters to be 5292c0ebdeeSRobert Mustacchiused by the broader system. 5302c0ebdeeSRobert MustacchiIt is still useful to implement this on hardware which only has a single ring. 5312c0ebdeeSRobert MustacchiSee 5322c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E 5332c0ebdeeSRobert Mustacchifor more information. 5342c0ebdeeSRobert Mustacchi.Ss Receive Side Scaling 5352c0ebdeeSRobert MustacchiReceive side scaling is where a hardware device supports multiple, 5362c0ebdeeSRobert Mustacchiindependent queues of frames that can be received. 5372c0ebdeeSRobert MustacchiEach of these queues is generally associated with an independent 5382c0ebdeeSRobert Mustacchiinterrupt and the hardware usually performs some form of hash across the 5392c0ebdeeSRobert Mustacchiqueues. 5402c0ebdeeSRobert MustacchiHardware which supports this should look at implementing the 5412c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 5422c0ebdeeSRobert Mustacchicapability and see 5432c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E 5442c0ebdeeSRobert Mustacchifor more information. 54552d2369aSRobert Mustacchi.Ss Link Updates 54652d2369aSRobert MustacchiIt is the responsibility of the device driver to keep track of the 54772d3dbb9SYuri Pankovdata link's state. 54872d3dbb9SYuri PankovMany devices provide a means of receiving an interrupt when the state of the 54972d3dbb9SYuri Pankovlink changes. 55072d3dbb9SYuri PankovWhen such a change happens, the driver should update its internal data 55172d3dbb9SYuri Pankovstructures and then call 55252d2369aSRobert Mustacchi.Xr mac_link_update 9F 55372d3dbb9SYuri Pankovto inform the MAC layer that this has occurred. 55472d3dbb9SYuri PankovIf the device driver does not properly inform the system about link changes, 55572d3dbb9SYuri Pankovthen various features like link aggregations and other mechanisms that leverage 55672d3dbb9SYuri Pankovthe link state will not work correctly. 55752d2369aSRobert Mustacchi.Ss Link Speed and Auto-negotiation 55852d2369aSRobert MustacchiMany networking devices support more than one possible speed that they 55972d3dbb9SYuri Pankovcan operate at. 56072d3dbb9SYuri PankovThe selection of a speed is often performed through 56152d2369aSRobert Mustacchi.Em auto-negotiation , 56252d2369aSRobert Mustacchithough some devices allow the user to control what speeds are advertised 56352d2369aSRobert Mustacchiand used. 56452d2369aSRobert Mustacchi.Pp 56552d2369aSRobert MustacchiLogically, there are two different sets of things that the device driver 56652d2369aSRobert Mustacchineeds to keep track of while it's operating: 56752d2369aSRobert Mustacchi.Bl -enum 56852d2369aSRobert Mustacchi.It 56952d2369aSRobert MustacchiThe supported speeds in hardware. 57052d2369aSRobert Mustacchi.It 57152d2369aSRobert MustacchiThe enabled speeds from the user. 57252d2369aSRobert Mustacchi.El 57352d2369aSRobert Mustacchi.Pp 57452d2369aSRobert MustacchiBy default, when a link first comes up, the device driver should 57552d2369aSRobert Mustacchigenerally configure the link to support the common set of speeds and 57652d2369aSRobert Mustacchiperform auto-negotiation. 57752d2369aSRobert Mustacchi.Pp 57852d2369aSRobert MustacchiA user can control what speeds a device advertises via auto-negotiation 57952d2369aSRobert Mustacchiand whether or not it performs auto-negotiation at all by using a series 58052d2369aSRobert Mustacchiof properties that have 58152d2369aSRobert Mustacchi.Sy _EN_ 58272d3dbb9SYuri Pankovin the name. 58372d3dbb9SYuri PankovThese are read/write properties and there is one for each speed supported in the 58472d3dbb9SYuri Pankovoperating system. 58572d3dbb9SYuri PankovFor a full list of them, see the 58652d2369aSRobert Mustacchi.Sx PROPERTIES 58752d2369aSRobert Mustacchisection. 58852d2369aSRobert Mustacchi.Pp 58952d2369aSRobert MustacchiIn addition to these properties, there is a corresponding set of 59052d2369aSRobert Mustacchiproperties with 59152d2369aSRobert Mustacchi.Sy _ADV_ 59272d3dbb9SYuri Pankovin the name. 59372d3dbb9SYuri PankovThese are similar to the 59452d2369aSRobert Mustacchi.Sy _EN_ 59552d2369aSRobert Mustacchifamily of properties, but they are read-only and indicate what the 59672d3dbb9SYuri Pankovdevice has actually negotiated. 59772d3dbb9SYuri PankovWhile they are generally similar to the 59852d2369aSRobert Mustacchi.Sy _EN_ 59972d3dbb9SYuri Pankovfamily of properties, they may change depending on power settings. 60072d3dbb9SYuri PankovSee the 60152d2369aSRobert Mustacchi.Sy Ethernet Link Properties 60252d2369aSRobert Mustacchisection in 603bbf21555SRichard Lowe.Xr dladm 8 60452d2369aSRobert Mustacchifor more information. 60552d2369aSRobert Mustacchi.Pp 60652d2369aSRobert MustacchiIt's worth discussing how these different values get used throughout the 60772d3dbb9SYuri Pankovdifferent entry points. 60872d3dbb9SYuri PankovThe first entry point to consider is the 60952d2369aSRobert Mustacchi.Xr mc_propinfo 9E 61072d3dbb9SYuri Pankoventry point. 61172d3dbb9SYuri PankovFor a given speed, the driver should consult whether or not the hardware 61272d3dbb9SYuri Pankovsupports this speed. 61372d3dbb9SYuri PankovIf it does, it should fill in the default value that the hardware takes and 61472d3dbb9SYuri Pankovwhether or not the property is writable. 61572d3dbb9SYuri PankovThe properties should also be updated to indicate whether or not it is writable. 61672d3dbb9SYuri PankovThis holds for both the 61752d2369aSRobert Mustacchi.Sy _EN_ 61852d2369aSRobert Mustacchiand 61952d2369aSRobert Mustacchi.Sy _ADV_ 62052d2369aSRobert Mustacchifamily of properties. 62152d2369aSRobert Mustacchi.Pp 62252d2369aSRobert MustacchiThe next entry point is 62352d2369aSRobert Mustacchi.Xr mc_getprop 9E . 62452d2369aSRobert MustacchiHere, the device should first consult whether the given speed is 62572d3dbb9SYuri Pankovsupported. 62672d3dbb9SYuri PankovIf it is not, then the driver should return 62752d2369aSRobert Mustacchi.Er ENOTSUP . 62852d2369aSRobert MustacchiIf it does, then it should return the current value of the property. 62952d2369aSRobert Mustacchi.Pp 63052d2369aSRobert MustacchiThe last property endpoint is the 63152d2369aSRobert Mustacchi.Xr mc_setprop 9E 63272d3dbb9SYuri Pankoventry point. 63372d3dbb9SYuri PankovHere, the same logic applies. 63472d3dbb9SYuri PankovBefore the driver considers whether or not the property is writable, it should 63572d3dbb9SYuri Pankovfirst check whether or not it's a supported property. 63672d3dbb9SYuri PankovIf it's not, then it should return 63752d2369aSRobert Mustacchi.Er ENOTSUP . 63852d2369aSRobert MustacchiOtherwise, it should proceed to check whether the property is writable, 63952d2369aSRobert Mustacchiand if it is and a valid value, then it should update the property and 64052d2369aSRobert Mustacchirestart the link's negotiation. 64152d2369aSRobert Mustacchi.Pp 64252d2369aSRobert MustacchiFinally, there is the 64352d2369aSRobert Mustacchi.Xr mc_getstat 9E 64472d3dbb9SYuri Pankoventry point. 64572d3dbb9SYuri PankovSeveral of the statistics that are queried relate to auto-negotiation and 64672d3dbb9SYuri Pankovhardware capabilities. 64772d3dbb9SYuri PankovWhen a statistic relates to the hardware supporting a given speed, the 64852d2369aSRobert Mustacchi.Sy _EN_ 64972d3dbb9SYuri Pankovproperties should be ignored. 65072d3dbb9SYuri PankovThe only thing that should be consulted is what the hardware itself supports. 65172d3dbb9SYuri PankovOtherwise, the statistics should look at what is currently being advertised by 65272d3dbb9SYuri Pankovthe device. 65352d2369aSRobert Mustacchi.Ss Unregistering from MAC 65452d2369aSRobert MustacchiDuring a driver's 65552d2369aSRobert Mustacchi.Xr detach 9E 65652d2369aSRobert Mustacchiroutine, it should unregister the device instance from MAC by calling 65752d2369aSRobert Mustacchi.Xr mac_unregister 9F 65872d3dbb9SYuri Pankovon the handle that it originally called it on. 65972d3dbb9SYuri PankovIf the call to 66052d2369aSRobert Mustacchi.Xr mac_unregister 9F 66152d2369aSRobert Mustacchifailed, then the device is likely still in use and the driver should 66252d2369aSRobert Mustacchifail the call to 66352d2369aSRobert Mustacchi.Xr detach 9E . 66452d2369aSRobert Mustacchi.Ss Interacting with Devices 66552d2369aSRobert MustacchiAdministrators always interact with devices through the 666bbf21555SRichard Lowe.Xr dladm 8 66772d3dbb9SYuri Pankovcommand line interface. 6682c0ebdeeSRobert MustacchiThe state of devices such as whether the link is considered up or down, 6692c0ebdeeSRobert Mustacchivarious link properties such as the MTU, auto-negotiation state, and 6702c0ebdeeSRobert Mustacchiflow control state, are all exposed. 67172d3dbb9SYuri PankovIt is also the preferred way that these properties are set and configured. 67252d2369aSRobert Mustacchi.Pp 67352d2369aSRobert MustacchiWhile device tunables may be presented in a 674bbf21555SRichard Lowe.Xr driver.conf 5 67552d2369aSRobert Mustacchifile, it is recommended instead to expose such things through 676bbf21555SRichard Lowe.Xr dladm 8 67752d2369aSRobert Mustacchiprivate properties, whether explicitly documented or not. 67852d2369aSRobert Mustacchi.Sh CAPABILITIES 67952d2369aSRobert MustacchiCapabilities in the MAC Framework are optional features that a device 68052d2369aSRobert Mustacchisupports which indicate various hardware features that the device 68172d3dbb9SYuri Pankovsupports. 68272d3dbb9SYuri PankovThe two current capabilities that the system supports are related to being able 68372d3dbb9SYuri Pankovto hardware perform large send offloads (LSO), often also known as TCP 68472d3dbb9SYuri Pankovsegmentation and the ability for hardware to calculate and verify the checksums 68572d3dbb9SYuri Pankovpresent in IPv4, IPV6, and protocol headers such as TCP and UDP. 68652d2369aSRobert Mustacchi.Pp 68752d2369aSRobert MustacchiThe MAC framework will query a device for support of a capability 68852d2369aSRobert Mustacchithrough the 68952d2369aSRobert Mustacchi.Xr mc_getcapab 9E 69072d3dbb9SYuri Pankovfunction. 69172d3dbb9SYuri PankovEach capability has its own constant and may have corresponding data that goes 69272d3dbb9SYuri Pankovalong with it and a specific structure that the device is required to fill in. 69372d3dbb9SYuri PankovNote, the set of capabilities changes over time and there are also private 69472d3dbb9SYuri Pankovcapabilities in the system. 69572d3dbb9SYuri PankovSeveral of the capabilities are used in the implementation of the MAC framework. 69652d2369aSRobert MustacchiOthers, like 6972c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS , 69872d3dbb9SYuri Pankovrepresent feature that have not been stabilized and thus both API and binary 69972d3dbb9SYuri Pankovcompatibility for them is not guaranteed. 70072d3dbb9SYuri PankovIt is important that the device driver handles unknown capabilities correctly. 70172d3dbb9SYuri PankovFor more information, see 70252d2369aSRobert Mustacchi.Xr mc_getcapab 9E . 70352d2369aSRobert Mustacchi.Pp 70452d2369aSRobert MustacchiThe following capabilities are 70552d2369aSRobert Mustacchistable and defined in the system: 7062c0ebdeeSRobert Mustacchi.Ss Dv MAC_CAPAB_HCKSUM 70752d2369aSRobert MustacchiThe 7082c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_HCKSUM 70952d2369aSRobert Mustacchicapability indicates to the system that the device driver supports some 71072d3dbb9SYuri Pankovamount of checksumming. 71172d3dbb9SYuri PankovThe specific data for this capability is a pointer to a 7122c0ebdeeSRobert Mustacchi.Vt uint32_t . 71352d2369aSRobert MustacchiTo indicate no support for any kind of checksumming, the driver should 71452d2369aSRobert Mustacchieither set this value to zero or simply return that it doesn't support 71552d2369aSRobert Mustacchithe capability. 71652d2369aSRobert Mustacchi.Pp 71752d2369aSRobert MustacchiNote, the values that the driver declares in this capability indicate 71872d3dbb9SYuri Pankovwhat it can do when it transmits data. 71972d3dbb9SYuri PankovIf the driver can only verify checksums when receiving data, then it should not 72072d3dbb9SYuri Pankovindicate that it supports this capability. 72172d3dbb9SYuri PankovThe following set of flags may be combined through a bitwise inclusive OR: 72252d2369aSRobert Mustacchi.Bl -tag -width Ds 7232c0ebdeeSRobert Mustacchi.It Dv HCKSUM_INET_PARTIAL 72452d2369aSRobert MustacchiThis indicates that the hardware can calculate a partial checksum for 725b22a70abSPatrick Mooneyboth IPv4 and IPv6 UDP and TCP packets; however, it requires the pseudo-header 726b22a70abSPatrick Mooneychecksum be calculated for it. 72772d3dbb9SYuri PankovThe pseudo-header checksum will be available for the mblk_t when calling 72852d2369aSRobert Mustacchi.Xr mac_hcksum_get 9F . 729b22a70abSPatrick MooneyNote this does not imply that the hardware is capable of calculating 730b22a70abSPatrick Mooneythe partial checksum for other L4 protocols or the IPv4 header checksum. 73172d3dbb9SYuri PankovThat should be indicated with the 7322c0ebdeeSRobert Mustacchi.Dv HCKSUM_IPHDRCKSUM flag . 7332c0ebdeeSRobert Mustacchi.It Dv HCKSUM_INET_FULL_V4 734b22a70abSPatrick MooneyThis indicates that the hardware will fully calculate the L4 checksum for 735b22a70abSPatrick Mooneyoutgoing IPv4 UDP or TCP packets only, and does not require a pseudo-header 736b22a70abSPatrick Mooneychecksum. 73752d2369aSRobert MustacchiNote this does not imply that the hardware is capable of calculating the 738b22a70abSPatrick Mooneychecksum for other L4 protocols or the IPv4 header checksum. 73972d3dbb9SYuri PankovThat should be indicated with the 7402c0ebdeeSRobert Mustacchi.Dv HCKSUM_IPHDRCKSUM . 7412c0ebdeeSRobert Mustacchi.It Dv HCKSUM_INET_FULL_V6 742b22a70abSPatrick MooneyThis indicates that the hardware will fully calculate the L4 checksum for 743b22a70abSPatrick Mooneyoutgoing IPv6 UDP or TCP packets only, and does not require a pseudo-header 744b22a70abSPatrick Mooneychecksum. 745b22a70abSPatrick MooneyNote this does not imply that the hardware is capable of calculating the 746b22a70abSPatrick Mooneychecksum for any other L4 protocols. 7472c0ebdeeSRobert Mustacchi.It Dv HCKSUM_IPHDRCKSUM 74852d2369aSRobert MustacchiThis indicates that the hardware supports calculating the checksum for 74952d2369aSRobert Mustacchithe IPv4 header itself. 75052d2369aSRobert Mustacchi.El 75152d2369aSRobert Mustacchi.Pp 75252d2369aSRobert MustacchiWhen in a driver's transmit function, the driver will be processing a 75372d3dbb9SYuri Pankovsingle frame. 75472d3dbb9SYuri PankovIt should call 75552d2369aSRobert Mustacchi.Xr mac_hcksum_get 9F 75672d3dbb9SYuri Pankovto see what checksum flags are set on it. 75772d3dbb9SYuri PankovNote that the flags that are set on it are different from the ones described 75872d3dbb9SYuri Pankovabove and are documented in its manual page. 75972d3dbb9SYuri PankovThese flags indicate how the driver is expected to program the hardware and what 76072d3dbb9SYuri Pankovchecksumming is required. 76172d3dbb9SYuri PankovNot all frames will require hardware checksumming or will ask the hardware to 76272d3dbb9SYuri Pankovchecksum it. 76352d2369aSRobert Mustacchi.Pp 76452d2369aSRobert MustacchiIf a driver supports offloading the receive checksum and verification, 76572d3dbb9SYuri Pankovit should check to see what the hardware indicated was verified. 76672d3dbb9SYuri PankovThe driver should then call 76752d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F . 76852d2369aSRobert MustacchiThe flags used are different from the ones above and are discussed in 76952d2369aSRobert Mustacchidetail in the 77052d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F 77172d3dbb9SYuri Pankovmanual page. 77272d3dbb9SYuri PankovIf there is no checksum information available or the driver does not support 77372d3dbb9SYuri Pankovchecksumming, then it should simply not call 77452d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F . 77552d2369aSRobert Mustacchi.Pp 77652d2369aSRobert MustacchiNote that the checksum flags should be set on the first 77772d3dbb9SYuri Pankovmblk_t that makes up a given message. 77872d3dbb9SYuri PankovIn other words, if multiple mblk_t structures are linked together by the 7792c0ebdeeSRobert Mustacchi.Fa b_cont 78052d2369aSRobert Mustacchimember to describe a single frame, then it should only be called on the 78172d3dbb9SYuri Pankovfirst mblk_t of that set. 78272d3dbb9SYuri PankovHowever, each distinct message should have the checksum bits set on it, if 78372d3dbb9SYuri Pankovapplicable. 78472d3dbb9SYuri PankovIn other words, each mblk_t that is linked together by the 7852c0ebdeeSRobert Mustacchi.Fa b_next 78652d2369aSRobert Mustacchipointer may have checksum flags set. 78752d2369aSRobert Mustacchi.Pp 78852d2369aSRobert MustacchiIt is recommended that device drivers provide a private property or 789bbf21555SRichard Lowe.Xr driver.conf 5 79052d2369aSRobert Mustacchiproperty to control whether or not checksumming is enabled for both rx 79152d2369aSRobert Mustacchiand tx; however, the default disposition is recommended to be enabled 79272d3dbb9SYuri Pankovfor both. 79372d3dbb9SYuri PankovThis way if hardware bugs are found in the checksumming implementation, they can 79472d3dbb9SYuri Pankovbe disabled without requiring software updates. 79552d2369aSRobert MustacchiThe transmit property should be checked when determining how to reply to 79652d2369aSRobert Mustacchi.Xr mc_getcapab 9E 79752d2369aSRobert Mustacchiand the receive property should be checked in the context of the receive 79852d2369aSRobert Mustacchifunction. 7992c0ebdeeSRobert Mustacchi.Ss Dv MAC_CAPAB_LSO 80052d2369aSRobert MustacchiThe 8012c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_LSO 80252d2369aSRobert Mustacchicapability indicates that the driver supports various forms of large 80372d3dbb9SYuri Pankovsend offload (LSO). 80472d3dbb9SYuri PankovThe private data is a pointer to a 805942d4fcaSRobert Mustacchi.Ft mac_capab_lso_t 80672d3dbb9SYuri Pankovstructure. 807942d4fcaSRobert MustacchiThe system currently supports offloading TCP packets over both IPv4 and 808942d4fcaSRobert MustacchiIPv6. 80952d2369aSRobert MustacchiThis structure has the following members which are used to indicate 81052d2369aSRobert Mustacchivarious types of LSO support. 81152d2369aSRobert Mustacchi.Bd -literal -offset indent 81252d2369aSRobert Mustacchit_uscalar_t lso_flags; 81352d2369aSRobert Mustacchilso_basic_tcp_ivr4_t lso_basic_tcp_ipv4; 814942d4fcaSRobert Mustacchilso_basic_tcp_ipv6_t lso_basic_tcp_ipv6; 81552d2369aSRobert Mustacchi.Ed 81652d2369aSRobert Mustacchi.Pp 81752d2369aSRobert MustacchiThe 818942d4fcaSRobert Mustacchi.Fa lso_flags 81952d2369aSRobert Mustacchimember is used to indicate which members are valid and should be 82072d3dbb9SYuri Pankovconsidered. 82172d3dbb9SYuri PankovEach flag represents a different form of LSO. 82272d3dbb9SYuri PankovThe member should be set to the bitwise inclusive OR of the following values: 82352d2369aSRobert Mustacchi.Bl -tag -width Dv -offset indent 824942d4fcaSRobert Mustacchi.It Dv LSO_TX_BASIC_TCP_IPV4 82552d2369aSRobert MustacchiThis indicates hardware support for performing TCP segmentation 82672d3dbb9SYuri Pankovoffloading over IPv4. 82772d3dbb9SYuri PankovWhen this flag is set, the 828942d4fcaSRobert Mustacchi.Fa lso_basic_tcp_ipv4 829942d4fcaSRobert Mustacchimember must be filled in. 830942d4fcaSRobert Mustacchi.It Dv LSO_TX_BASIC_TCP_IPV6 831942d4fcaSRobert MustacchiThis indicates hardware support for performing TCP segmentation 832942d4fcaSRobert Mustacchioffloading over IPv6. 833942d4fcaSRobert MustacchiThe IPv6 packet will have no extension headers present. 834942d4fcaSRobert MustacchiWhen this flag is set, the 835942d4fcaSRobert Mustacchi.Fa lso_basic_tcp_ipv6 83652d2369aSRobert Mustacchimember must be filled in. 83752d2369aSRobert Mustacchi.El 83852d2369aSRobert Mustacchi.Pp 83952d2369aSRobert MustacchiThe 840942d4fcaSRobert Mustacchi.Fa lso_basic_tcp_ipv4 84152d2369aSRobert Mustacchimember is a structure with the following members: 84252d2369aSRobert Mustacchi.Bd -literal -offset indent 84352d2369aSRobert Mustacchit_uscalar_t lso_max 84452d2369aSRobert Mustacchi.Ed 84552d2369aSRobert Mustacchi.Bd -filled -offset indent 84652d2369aSRobert MustacchiThe 847942d4fcaSRobert Mustacchi.Fa lso_max 848942d4fcaSRobert Mustacchimember should be set to the maximum size of the TCP data 849942d4fcaSRobert Mustacchipayload that can be offloaded to the hardware. 850942d4fcaSRobert Mustacchi.Ed 851942d4fcaSRobert Mustacchi.Pp 852942d4fcaSRobert MustacchiThe 853942d4fcaSRobert Mustacchi.Fa lso_basic_tcp_ipv6 854942d4fcaSRobert Mustacchimember is a structure with the following members: 855942d4fcaSRobert Mustacchi.Bd -literal -offset indent 856942d4fcaSRobert Mustacchit_uscalar_t lso_max 857942d4fcaSRobert Mustacchi.Ed 858942d4fcaSRobert Mustacchi.Bd -filled -offset indent 859942d4fcaSRobert MustacchiThe 860942d4fcaSRobert Mustacchi.Fa lso_max 86152d2369aSRobert Mustacchimember should be set to the maximum size of the TCP data 86252d2369aSRobert Mustacchipayload that can be offloaded to the hardware. 86352d2369aSRobert Mustacchi.Ed 86452d2369aSRobert Mustacchi.Pp 86552d2369aSRobert MustacchiLike with checksumming, it is recommended that driver writers provide a 86652d2369aSRobert Mustacchimeans for disabling the support of LSO even if it is enabled by default. 86752d2369aSRobert MustacchiThis deals with the case where issues that pop up for LSO may be worked 86852d2369aSRobert Mustacchiaround without requiring additional driver work. 8692c0ebdeeSRobert Mustacchi.Sh EVOLVING CAPABILITIES 8702c0ebdeeSRobert MustacchiThe following capabilities are still evolving in the operating system. 8712c0ebdeeSRobert MustacchiThey are documented such that device driver writers may experiment with 8722c0ebdeeSRobert Mustacchithem. 8732c0ebdeeSRobert MustacchiHowever, if such drivers are not present inside the core operating 8742c0ebdeeSRobert Mustacchisystem repository, they may be subject to API and ABI breakage. 8752c0ebdeeSRobert Mustacchi.Ss Dv MAC_CAPAB_RINGS 8762c0ebdeeSRobert MustacchiThe 8772c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 8782c0ebdeeSRobert Mustacchicapability is very important for implementing a high-performing device 8792c0ebdeeSRobert Mustacchidriver. 8802c0ebdeeSRobert MustacchiNetworking hardware structures the queues of packets to be sent 8812c0ebdeeSRobert Mustacchiand received into a ring. 8822c0ebdeeSRobert MustacchiEach entry in this ring has a descriptor, which describes the address 8832c0ebdeeSRobert Mustacchiand options for a packet which is going to 8842c0ebdeeSRobert Mustacchibe transmitted or received. 8852c0ebdeeSRobert MustacchiWhile simple networking devices only have a single ring, most high-speed 8862c0ebdeeSRobert Mustacchinetworking devices have support for many rings. 8872c0ebdeeSRobert Mustacchi.Pp 8882c0ebdeeSRobert MustacchiRings are used for two important purposes. 8892c0ebdeeSRobert MustacchiThe first is receive side scaling (RSS), which is the ability to have 8902c0ebdeeSRobert Mustacchithe hardware hash the contents of a packet based on some of the protocol 8912c0ebdeeSRobert Mustacchiheaders, and send it to one of several rings. 8922c0ebdeeSRobert MustacchiThese different rings may each have their own interrupt associated with 8932c0ebdeeSRobert Mustacchithem, allowing the card to receive traffic in parallel. 8942c0ebdeeSRobert MustacchiSimilar logic can be performed when sending traffic, to leverage 8952c0ebdeeSRobert Mustacchimultiple hardware resources, thus increasing capacity. 8962c0ebdeeSRobert Mustacchi.Pp 8972c0ebdeeSRobert MustacchiThe second use of rings is to group them together and apply filtering 8982c0ebdeeSRobert Mustacchirules. 8992c0ebdeeSRobert MustacchiFor example, if a packet matches a specific VLAN or MAC address, 9002c0ebdeeSRobert Mustacchithen it can be sent to a specific ring or a specific group of rings. 9012c0ebdeeSRobert MustacchiThis is especially useful when there are multiple different virtual NICs 9022c0ebdeeSRobert Mustacchior zones in play as the operating system will be able to use the 903496cffd8SPeter Tribblehardware classification features to already know where a given packet 9042c0ebdeeSRobert Mustacchineeds to be delivered internally rather than having to determine that 9052c0ebdeeSRobert Mustacchifor each packet. 9062c0ebdeeSRobert Mustacchi.Pp 9072c0ebdeeSRobert MustacchiFrom the MAC framework's perspective, a driver can have one or more 9082c0ebdeeSRobert Mustacchigroups. 9092c0ebdeeSRobert MustacchiA group consists of the following: 9102c0ebdeeSRobert Mustacchi.Bl -bullet -offset -indent 9112c0ebdeeSRobert Mustacchi.It 9122c0ebdeeSRobert MustacchiOne or more hardware rings. 9132c0ebdeeSRobert Mustacchi.It 9142c0ebdeeSRobert MustacchiOne or more MAC address or VLAN filters. 9152c0ebdeeSRobert Mustacchi.El 9162c0ebdeeSRobert Mustacchi.Pp 9172c0ebdeeSRobert MustacchiThe details around how a device driver changes when rings are employed, 9182c0ebdeeSRobert Mustacchithe data structures that a driver must implement, and more are available 9192c0ebdeeSRobert Mustacchiin 9202c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E . 9212c0ebdeeSRobert Mustacchi.Ss Dv MAC_CAPAB_TRANSCEIVER 9222c0ebdeeSRobert MustacchiMany networking devices leverage external transceivers that adhere to 9232c0ebdeeSRobert Mustacchistandards such as SFP, QSFP, QSFP-DD, etc., which often contain 9242c0ebdeeSRobert Mustacchistandardized information in a EEPROM on the device. 9252c0ebdeeSRobert MustacchiThe 9262c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_TRANSCEIVER 9272c0ebdeeSRobert Mustacchicapability provides a means of discovering the number of transceivers, 9282c0ebdeeSRobert Mustacchitheir types, and reading the data from a transceiver. 9292c0ebdeeSRobert MustacchiThis allows administrators and users to determine if devices are 9302c0ebdeeSRobert Mustacchipresent, if the hardware can use them, and in many cases, detailed 9312c0ebdeeSRobert Mustacchiinformation about the device ranging from its manufacturer and 9322c0ebdeeSRobert Mustacchiserial numbers to specific information about its health. 9332c0ebdeeSRobert MustacchiImplementing this capability will lead to the operating system being 9342c0ebdeeSRobert Mustacchiable to discover and display transceivers as part of its fault 9352c0ebdeeSRobert Mustacchimanagement topology. 9362c0ebdeeSRobert Mustacchi.Pp 9372c0ebdeeSRobert MustacchiSee 9382c0ebdeeSRobert Mustacchi.Xr mac_capab_transceiver 9E 9392c0ebdeeSRobert Mustacchifor more details on the capability structure and the various function 9402c0ebdeeSRobert Mustacchientry points that come along with it. 9412c0ebdeeSRobert Mustacchi.Ss Dv MAC_CAPAB_LED 9422c0ebdeeSRobert MustacchiThe 9432c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_LED 9442c0ebdeeSRobert Mustacchicapability provides a means to access and control the LEDs on a network 9452c0ebdeeSRobert Mustacchiinterface card. 9462c0ebdeeSRobert MustacchiThis is then made available to the broader operating system and consumed 9472c0ebdeeSRobert Mustacchiby facilities such as the Fault Management Architecture. 9482c0ebdeeSRobert MustacchiSee 9492c0ebdeeSRobert Mustacchi.Xr mac_capab_led 9E 9502c0ebdeeSRobert Mustacchifor more details on the structure and requirements of the capability. 95152d2369aSRobert Mustacchi.Sh PROPERTIES 95272d3dbb9SYuri PankovProperties in the MAC framework represent aspects of a link. 95372d3dbb9SYuri PankovThese include things like the link's current state and MTU. 95472d3dbb9SYuri PankovMany of the properties in the system are focused around auto-negotiation and 95572d3dbb9SYuri Pankovcontrolling what link speeds are advertised. 95672d3dbb9SYuri PankovInformation about properties is covered by three different device entry points. 95772d3dbb9SYuri PankovThe 95852d2369aSRobert Mustacchi.Xr mc_propinfo 9E 95972d3dbb9SYuri Pankoventry point obtains metadata about the property. 96072d3dbb9SYuri PankovThe 96152d2369aSRobert Mustacchi.Xr mc_getprop 9E 96272d3dbb9SYuri Pankoventry point obtains the property. 96372d3dbb9SYuri PankovThe 96452d2369aSRobert Mustacchi.Xr mc_setprop 9E 96552d2369aSRobert Mustacchientry point updates the property to a new value. 96652d2369aSRobert Mustacchi.Pp 96772d3dbb9SYuri PankovMany of the properties listed below are read-only. 96872d3dbb9SYuri PankovEach property indicates whether it's read-only or it's read/write. 96972d3dbb9SYuri PankovHowever, driver writers may not implement the ability to set all writable 97072d3dbb9SYuri Pankovproperties. 97172d3dbb9SYuri PankovMany of these depend on the card itself. 97272d3dbb9SYuri PankovIn particular, all properties that relate to auto-negotiation and are read/write 97372d3dbb9SYuri Pankovmay not be updated if the hardware in question does not support toggling what 97472d3dbb9SYuri Pankovlink speeds are auto-negotiated. 97572d3dbb9SYuri PankovWhile copper Ethernet often does not have this restriction, it often exists with 97672d3dbb9SYuri Pankovvarious fiber standards and phys. 97752d2369aSRobert Mustacchi.Pp 97852d2369aSRobert MustacchiThe following properties are the subset of MAC framework properties that 97972d3dbb9SYuri Pankovdriver writers should be aware of and handle. 98072d3dbb9SYuri PankovWhile other properties exist in the system, driver writers should always return 98172d3dbb9SYuri Pankovan error when a property not listed below is encountered. 98272d3dbb9SYuri PankovSee 98352d2369aSRobert Mustacchi.Xr mc_getprop 9E 98452d2369aSRobert Mustacchiand 98552d2369aSRobert Mustacchi.Xr mc_setprop 9E 98652d2369aSRobert Mustacchifor more information on how to handle them. 98752d2369aSRobert Mustacchi.Bl -hang -width Ds 9882c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_DUPLEX 98952d2369aSRobert Mustacchi.Bd -filled -compact 99052d2369aSRobert MustacchiType: 9912c0ebdeeSRobert Mustacchi.Vt link_duplex_t | 99252d2369aSRobert MustacchiPermissions: 99352d2369aSRobert Mustacchi.Sy Read-Only 99452d2369aSRobert Mustacchi.Ed 99552d2369aSRobert Mustacchi.Pp 99652d2369aSRobert MustacchiThe 9972c0ebdeeSRobert Mustacchi.Dv MAC_PROP_DUPLEX 99872d3dbb9SYuri Pankovproperty is used to indicate whether or not the link is duplex. 99972d3dbb9SYuri PankovA duplex link may have traffic flowing in both directions at the same time. 100072d3dbb9SYuri PankovThe 10012c0ebdeeSRobert Mustacchi.Vt link_duplex_t 100252d2369aSRobert Mustacchiis an enumeration which may be set to any of the following values: 100352d2369aSRobert Mustacchi.Bl -tag -width Ds 10042c0ebdeeSRobert Mustacchi.It Dv LINK_DUPLEX_UNKNOWN 100572d3dbb9SYuri PankovThe current state of the link is unknown. 100672d3dbb9SYuri PankovThis may be because the link has not negotiated to a specific speed or it is 100772d3dbb9SYuri Pankovdown. 10082c0ebdeeSRobert Mustacchi.It Dv LINK_DUPLEX_HALF 100972d3dbb9SYuri PankovThe link is running at half duplex. 101072d3dbb9SYuri PankovCommunication may travel in only one direction on the link at a given time. 10112c0ebdeeSRobert Mustacchi.It Dv LINK_DUPLEX_FULL 101272d3dbb9SYuri PankovThe link is running at full duplex. 101372d3dbb9SYuri PankovCommunication may travel in both directions on the link simultaneously. 101452d2369aSRobert Mustacchi.El 10152c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_SPEED 101652d2369aSRobert Mustacchi.Bd -filled -compact 101752d2369aSRobert MustacchiType: 10182c0ebdeeSRobert Mustacchi.Vt uint64_t | 101952d2369aSRobert MustacchiPermissions: 102052d2369aSRobert Mustacchi.Sy Read-Only 102152d2369aSRobert Mustacchi.Ed 102252d2369aSRobert Mustacchi.Pp 102352d2369aSRobert MustacchiThe 10242c0ebdeeSRobert Mustacchi.Dv MAC_PROP_SPEED 102572d3dbb9SYuri Pankovproperty stores the current link speed in bits per second. 102672d3dbb9SYuri PankovA link that is running at 100 MBit/s would store the value 100000000ULL. 102772d3dbb9SYuri PankovA link that is running at 40 Gbit/s would store the value 40000000000ULL. 10282c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_STATUS 102952d2369aSRobert Mustacchi.Bd -filled -compact 103052d2369aSRobert MustacchiType: 10312c0ebdeeSRobert Mustacchi.Vt link_state_t | 103252d2369aSRobert MustacchiPermissions: 103352d2369aSRobert Mustacchi.Sy Read-Only 103452d2369aSRobert Mustacchi.Ed 103552d2369aSRobert Mustacchi.Pp 103652d2369aSRobert MustacchiThe 10372c0ebdeeSRobert Mustacchi.Dv MAC_PROP_STATUS 103872d3dbb9SYuri Pankovproperty is used to indicate the current state of the link. 103972d3dbb9SYuri PankovIt indicates whether the link is up or down. 104072d3dbb9SYuri PankovThe 10412c0ebdeeSRobert Mustacchi.Vt link_state_t 104252d2369aSRobert Mustacchiis an enumeration which may be set to any of the following values: 104352d2369aSRobert Mustacchi.Bl -tag -width Ds 10442c0ebdeeSRobert Mustacchi.It Dv LINK_STATE_UNKNOWN 104572d3dbb9SYuri PankovThe current state of the link is unknown. 104672d3dbb9SYuri PankovThis may be because the driver's 104752d2369aSRobert Mustacchi.Xr mc_start 9E 104852d2369aSRobert Mustacchiendpoint has not been called so it has not attempted to start the link. 10492c0ebdeeSRobert Mustacchi.It Dv LINK_STATE_DOWN 105072d3dbb9SYuri PankovThe link is down. 105172d3dbb9SYuri PankovThis may be because of a negotiation problem, a cable problem, or some other 105272d3dbb9SYuri Pankovdevice specific issue. 10532c0ebdeeSRobert Mustacchi.It Dv LINK_STATE_UP 105472d3dbb9SYuri PankovThe link is up. 105572d3dbb9SYuri PankovIf auto-negotiation is in use, it should have completed. 105652d2369aSRobert MustacchiTraffic should be able to flow over the link, barring other issues. 105752d2369aSRobert Mustacchi.El 1058dd72704bSRobert Mustacchi.It Dv MAC_PROP_MEDIA 1059dd72704bSRobert Mustacchi.Bd -filled -compact 1060dd72704bSRobert MustacchiType: 1061dd72704bSRobert Mustacchi.Vt uint32_t No (Varies) | 1062dd72704bSRobert MustacchiPermissions: 1063dd72704bSRobert Mustacchi.Sy Read-Only 1064dd72704bSRobert Mustacchi.Ed 1065dd72704bSRobert Mustacchi.Pp 1066dd72704bSRobert MustacchiThe 1067dd72704bSRobert Mustacchi.Dv MAC_PROP_MEDIA 1068dd72704bSRobert Mustacchiproperty indicates the current type of media on the link. 1069dd72704bSRobert MustacchiThe type of media is class-specific and determined based on the 1070dd72704bSRobert Mustacchi.Fa m_type_ident 1071dd72704bSRobert Mustacchifield in the 1072dd72704bSRobert Mustacchi.Vt mac_register_t 1073dd72704bSRobert Mustacchistructure used when calling 1074dd72704bSRobert Mustacchi.Xr mac_register 9F . 1075dd72704bSRobert MustacchiThe media is always read-only. 1076dd72704bSRobert MustacchiThis property is not used to control how auto-negotiation should be 1077dd72704bSRobert Mustacchiperformed, instead the existing speed-based properties are used instead. 1078dd72704bSRobert MustacchiThis property should be updated after auto-negotiation has completed. 1079dd72704bSRobert MustacchiIf device hardware and firmware do not provide a way to accurately 1080dd72704bSRobert Mustacchidetermine this, then it is much better to return that the media is 1081dd72704bSRobert Mustacchiunknown rather than to lie or guess. 1082dd72704bSRobert MustacchiA common case where this comes up is when a network card uses an 1083dd72704bSRobert MustacchiSFP-based device. 1084dd72704bSRobert MustacchiIf the underlying negotiated type of the link isn't made available and 1085dd72704bSRobert Mustacchitherefore the driver can't distinguish between say 40GBASE-SR4 and 1086dd72704bSRobert Mustacchi40GBASE-LR4, then drivers should return that the media is unknown. 1087dd72704bSRobert Mustacchi.Pp 1088dd72704bSRobert MustacchiSimilarly many types here represent an electrical interface that is 1089dd72704bSRobert Mustacchioften used between a MAC and a PHY, but also for chip-to-chip 1090dd72704bSRobert Mustacchiconnectivity or on a backplane. 1091dd72704bSRobert MustacchiWhen connecting to a PHY these shouldn't generally be used as the user 1092dd72704bSRobert Mustacchiis concerned with what is actually on the link they plug in, not the 1093dd72704bSRobert Mustacchiinternals of the device. 1094dd72704bSRobert Mustacchi.Pp 1095dd72704bSRobert MustacchiCurrently media values are defined for Ethernet-based devices and use 1096dd72704bSRobert Mustacchithe enumeration 1097dd72704bSRobert Mustacchi.Vt mac_ether_media_t . 1098dd72704bSRobert MustacchiThese are defined in 1099dd72704bSRobert Mustacchi.In sys/mac_ether.h 1100dd72704bSRobert Mustacchiand generally follow the IEEE standardized physical medium dependent 1101dd72704bSRobert Mustacchi.Pq PMD 1102dd72704bSRobert Mustacchilayer in 802.3. 1103dd72704bSRobert Mustacchi.Bl -tag -width Ds 1104dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_UNKNOWN 1105dd72704bSRobert MustacchiThis indicates that the type of the link media is unknown to the driver. 1106dd72704bSRobert MustacchiThis may be because the link is in a state where this information is 1107dd72704bSRobert Mustacchiunknown or the hardware, firmware, and device driver cannot figure it 1108dd72704bSRobert Mustacchiout. 1109dd72704bSRobert MustacchiIf there is no media present and the link is down, use 1110dd72704bSRobert Mustacchi.Dv ETHER_MEDIA_NONE 1111dd72704bSRobert Mustacchiinstead. 1112dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_NONE 1113dd72704bSRobert MustacchiRepresents the case that there is no specific media in use. 1114dd72704bSRobert MustacchiThis should generally be used when the link is down. 1115dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10BASE_T 1116dd72704bSRobert MustacchiTraditional 10 Mbit/s Ethernet based utilizing CAT-3 cabling. 1117dd72704bSRobert MustacchiDefined in 802.3i. 1118dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10BASE_T1 1119dd72704bSRobert MustacchiA more recent variant of 10 Mbit/s Ethernet that uses a single twisted 1120dd72704bSRobert Mustacchipair. 1121dd72704bSRobert MustacchiDefined in 802.3cg. 1122dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_TX 1123dd72704bSRobert MustacchiThe most common form of 100 Mbit/s Ethernet that utilizes two twisted 1124dd72704bSRobert Mustacchipairs over a CAT-5 cable. 1125dd72704bSRobert MustacchiDefined in 802.3u. 1126dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_FX 1127dd72704bSRobert Mustacchi100 Mbit/s Ethernet operating over multi-mode fiber. 1128dd72704bSRobert MustacchiDefined in 802.3u. 1129dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_X 1130dd72704bSRobert MustacchiThis is a general term that covers operating in one of the 100BASE-?X 1131dd72704bSRobert Mustacchivariants. 1132dd72704bSRobert MustacchiThis is here because some PHYs do not distinguish between operating in 1133dd72704bSRobert Mustacchi100BASE-TX and 100BASE-FX. 1134dd72704bSRobert MustacchiIf the driver can determine if it is operating with a BASE-T or fiber 1135dd72704bSRobert Mustacchibased PHY, prefer the more specific types instead. 1136dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_T4 1137dd72704bSRobert MustacchiThis is an uncommon half-duplex variant of 100 Mbit/s Ethernet that 1138dd72704bSRobert Mustacchioperates over CAT-3 cable using four twisted pairs. 1139dd72704bSRobert MustacchiDefined in 802.3u. 1140dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_T2 1141dd72704bSRobert MustacchiThis is another uncommon variant of 100 Mbit/s Ethernet that only 1142dd72704bSRobert Mustacchirequires two twisted pairs, but unlike 100BASE-TX requires CAT-3 cables. 1143dd72704bSRobert MustacchiDefined in 802.3y. 1144dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100BASE_T1 1145dd72704bSRobert MustacchiA more recent form of 100 Mbit/s Ethernet that requires only a single 1146dd72704bSRobert Mustacchitwisted pair. 1147dd72704bSRobert MustacchiDefined in 802.3bw. 1148dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100_SGMII 1149dd72704bSRobert MustacchiThis form of 100 Mbit/s Ethernet is generally used for chip-to-chip 1150dd72704bSRobert Mustacchiconnectivity and utilizes the SGMII 1151dd72704bSRobert Mustacchi.Pq Serial gigabit media-independent interface 1152dd72704bSRobert Mustacchispecification. 1153dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_X 1154dd72704bSRobert MustacchiThis is a general catch-all for all 1 Gbit/s fiber-based operation. 1155dd72704bSRobert MustacchiThis is here for compatibility with the generic information returned by 1156dd72704bSRobert Mustacchitraditional 802.3-compatible PHYs. 1157dd72704bSRobert MustacchiWhen more specific information is available, that should be used 1158dd72704bSRobert Mustacchiinstead. 1159dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_T 1160dd72704bSRobert MustacchiTraditional 1 Gbit/s Ethernet that utilizes a CAT-5 cable with four 1161dd72704bSRobert Mustacchitwisted pairs. 1162dd72704bSRobert MustacchiDefined in 802.3ab. 1163dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_T1 1164dd72704bSRobert MustacchiA more recent form of 1 Gbit/s Ethernet that only requires a single 1165dd72704bSRobert Mustacchitwisted pair. 1166dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_KX 1167dd72704bSRobert MustacchiThis form of 1 Gbit/s Ethernet is designed for operating over a backplane. 1168dd72704bSRobert MustacchiDefined in 802.3ap. 1169dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_CX 1170dd72704bSRobert MustacchiAn older form of 1 Gbit/s Ethernet that operates over balanced copper 1171dd72704bSRobert Mustacchicables. 1172dd72704bSRobert MustacchiDefined in 802.3z. 1173dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_SX 1174dd72704bSRobert Mustacchi1 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1175dd72704bSRobert Mustacchieach direction. 1176dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_LX 1177dd72704bSRobert Mustacchi1 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1178dd72704bSRobert Mustacchieach direction. 1179dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000BASE_BX 1180dd72704bSRobert Mustacchi1 Gbit/s Ethernet operating over a single piece of single-mode fiber. 1181dd72704bSRobert MustacchiThis media operates bi-directionally as opposed to how 1000BASE-LX and 1182dd72704bSRobert Mustacchi1000BASE-SX operate. 1183dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_1000_SGMII 1184dd72704bSRobert MustacchiA form of 1 Gbit/s Ethernet defined by Cisco that is used for 1185dd72704bSRobert Mustacchichip-to-chip connectivity. 1186dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_2500BASE_T 1187dd72704bSRobert Mustacchi2.5 Gbit/s Ethernet based on four copper twisted-pairs. 1188dd72704bSRobert MustacchiDefined in 802.3bz. 1189dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_2500BASE_KX 1190dd72704bSRobert Mustacchi2.5 Gbit/s Ethernet that is designed for operating over a backplane 1191dd72704bSRobert Mustacchiinterconnect. 1192dd72704bSRobert MustacchiDefined in 802.3cb. 1193dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_2500BASE_X 1194dd72704bSRobert MustacchiThis is a variant of 2.5 Gbit/s Ethernet that took the 1000BASE-X IEEE 1195dd72704bSRobert Mustacchistandard and ran it with a 2.5x faster clock. 1196dd72704bSRobert MustacchiIt is a defacto standard. 1197dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_5000BASE_T 1198dd72704bSRobert Mustacchi5.0 Gbit/s Ethernet based on four copper twisted-pairs. 1199dd72704bSRobert MustacchiDefined in 802.3bz. 1200dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_5000BASE_KR 1201dd72704bSRobert Mustacchi5.0 Gbit/s Ethernet that is designed for operating over a backplane 1202dd72704bSRobert Mustacchiinterconnect. 1203dd72704bSRobert MustacchiDefined in 802.3cb. 1204dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_T 1205dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over four copper twisted pairs utilizing 1206dd72704bSRobert MustacchiCAT-6a cables. 1207dd72704bSRobert MustacchiDefined in 802.3an. 1208dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_SR 1209dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1210dd72704bSRobert Mustacchieach direction. 1211dd72704bSRobert MustacchiDefined in 802.3ae. 1212dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_LR 1213dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1214dd72704bSRobert Mustacchieach direction. 1215dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1216dd72704bSRobert MustacchiDefined in 802.3ae. 1217dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_ER 1218dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1219dd72704bSRobert Mustacchieach direction. 1220dd72704bSRobert MustacchiThe maximum fiber length is 30km. 1221dd72704bSRobert MustacchiDefined in 802.3ae. 1222dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_LRM 1223dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1224dd72704bSRobert Mustacchieach direction. 1225dd72704bSRobert MustacchiThis has a longer reach of up to 220m and is a longer distance than 1226dd72704bSRobert Mustacchi10GBASE-SR. 1227dd72704bSRobert MustacchiDefined in 802.3aq. 1228dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_KR 1229dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a single lane backplane. 1230dd72704bSRobert MustacchiDefined n 802.3ap. 1231dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_CX4 1232dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a group of four shielded copper cables. 1233dd72704bSRobert MustacchiDefined in 802.3ak. 1234dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_KX4 1235dd72704bSRobert Mustacchi10 Gbit/s Ethernet operating over a four lane backplane. 1236dd72704bSRobert MustacchiDefined n 802.3ap. 1237dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_CR 1238dd72704bSRobert Mustacchi10 Gbit/s Ethernet that is built using a passive copper 1239dd72704bSRobert MustacchiSFP-compatible cable. 1240dd72704bSRobert MustacchiThis is sometimes called 10GSFP+Cu passive. 1241dd72704bSRobert MustacchiDefined in SFF-8431. 1242dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_AOC 1243dd72704bSRobert Mustacchi10 Gbit/s Ethernet that is built using a short-range active 1244dd72704bSRobert Mustacchioptical cable that is SFP+-compatible. 1245dd72704bSRobert MustacchiDefined in SFF-8431. 1246dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10GBASE_ACC 1247dd72704bSRobert Mustacchi10 Gbit/s Ethernet based upon a single lane of copper cable with an 1248dd72704bSRobert Mustacchiactive component that allows it go longer distances than 10GBASE-CR. 1249dd72704bSRobert MustacchiDefined in SFF-8431. 1250dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10G_XAUI 1251dd72704bSRobert Mustacchi10 Gbit/s signalling that is defined for use between a MAC and PHY. 1252dd72704bSRobert MustacchiThis is the roman numeral X and attachment unit interface. 1253dd72704bSRobert MustacchiSometimes used for chip-to-chip interconnects. 1254dd72704bSRobert MustacchiDefined in 802.3ae. 1255dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10G_SFI 1256dd72704bSRobert Mustacchi10 Gbit/s signalling that is defined for use between a MAC and an 1257dd72704bSRobert MustacchiSFP-based transceiver. 1258dd72704bSRobert MustacchiDefined in SFF-8431. 1259dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_10G_XFI 1260dd72704bSRobert Mustacchi10 Gbit/s signalling that is defined for use between a MAC and an 1261dd72704bSRobert MustacchiXFP-based transceiver. 1262dd72704bSRobert MustacchiDefined in INF-8077i 1263dd72704bSRobert Mustacchi.Pq XFP MSA . 1264dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_T 1265dd72704bSRobert Mustacchi25 Gbit/s Ethernet based upon four twisted pair cables using CAT-8 1266dd72704bSRobert Mustacchicable. 1267dd72704bSRobert MustacchiDefined in 802.3bq. 1268dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_SR 1269dd72704bSRobert Mustacchi25 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1270dd72704bSRobert Mustacchieach direction. 1271dd72704bSRobert MustacchiDefined in 802.3by. 1272dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_LR 1273dd72704bSRobert Mustacchi25 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1274dd72704bSRobert Mustacchieach direction. 1275dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1276dd72704bSRobert MustacchiDefined in 802.3cc. 1277dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_ER 1278dd72704bSRobert Mustacchi25 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1279dd72704bSRobert Mustacchieach direction. 1280dd72704bSRobert MustacchiThe maximum fiber length is 30km. 1281dd72704bSRobert MustacchiDefined in 802.3cc. 1282dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_KR 1283dd72704bSRobert Mustacchi25 Gbit/s Ethernet operating over a backplane with a single lane. 1284dd72704bSRobert MustacchiDefined in 802.3by. 1285dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_CR 1286dd72704bSRobert Mustacchi25 Gbit/s Ethernet operating over a single lane of copper cable. 1287dd72704bSRobert MustacchiGenerally used with an SFP28 style connector. 1288dd72704bSRobert MustacchiDefined in 802.3by. 1289dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_AOC 1290dd72704bSRobert Mustacchi25 Gbit/s Ethernet based that is built using a short-range active 1291dd72704bSRobert Mustacchioptical cable that is SFP28-compatible. 1292dd72704bSRobert MustacchiDefined loosely by SFF-8402 and often utilizes 25GBASE-SR. 1293dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25GBASE_ACC 1294dd72704bSRobert Mustacchi25 Gbit/s Ethernet based upon a single lane of copper cable with an 1295dd72704bSRobert Mustacchiactive component that allows it go longer distances than 25GBASE-CR. 1296dd72704bSRobert MustacchiDefined loosely by SFF-8402. 1297dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_25G_AUI 1298dd72704bSRobert Mustacchi25 Gbit/s signalling that is defined for use between a MAC and PHY and 1299dd72704bSRobert Mustacchifor chip-to-chip connectivity. 1300dd72704bSRobert MustacchiDefined by 802.3by. 1301dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_T 1302dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon four twisted-pairs of CAT-8 cables. 1303dd72704bSRobert MustacchiDefined in 802.3bq. 1304dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_CR4 1305dd72704bSRobert Mustacchi40 Gbit/s Ethernet utilizing four lanes of twinaxial copper cabling 1306dd72704bSRobert Mustacchieach operating at 10 Gbit/s. 1307dd72704bSRobert MustacchiThis is generally used with a QSFP+ connector defined in SFF-8635. 1308dd72704bSRobert MustacchiDefined in 802.3ba. 1309dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_KR4 1310dd72704bSRobert Mustacchi40 Gbit/s Ethernet utilizing four lanes over a copper backplane each 1311dd72704bSRobert Mustacchioperating at 10 Gbit/s. 1312dd72704bSRobert MustacchiDefined in 802.3ba. 1313dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_SR4 1314dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon using four pairs of multi-mode fiber, each 1315dd72704bSRobert Mustacchioperating at 10 Gbit/s, with one fiber in the pair being used for 1316dd72704bSRobert Mustacchitransmit and the other for receive. 1317dd72704bSRobert MustacchiGenerally utilizes a QSFP+ connector. 1318dd72704bSRobert MustacchiDefined in 802.3ba. 1319dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_LR4 1320dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1321dd72704bSRobert Mustacchifor each direction. 1322dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 10 1323dd72704bSRobert MustacchiGbit/s signals. 1324dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1325dd72704bSRobert MustacchiDefined in 802.3ba. 1326dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_ER4 1327dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1328dd72704bSRobert Mustacchifor each direction. 1329dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 10 1330dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP+ connector. 1331dd72704bSRobert MustacchiThe maximum fiber length is 40km. 1332dd72704bSRobert MustacchiDefined in 802.3bm. 1333dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_LM4 1334dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon using one pair of multi-mode fibers, one 1335dd72704bSRobert Mustacchifor each direction. 1336dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 10 1337dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP+ connector. 1338dd72704bSRobert MustacchiDefined by a specific MSA. 1339dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_AOC4 1340dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon a QSFP+ based cable with built-in 1341dd72704bSRobert Mustacchioptical transceivers. 1342dd72704bSRobert MustacchiThe electrical interface is four lanes running at 10 Gbit/s. 1343dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40GBASE_ACC4 1344dd72704bSRobert Mustacchi40 Gbit/s Ethernet based upon four copper lanes each running at 10 1345dd72704bSRobert MustacchiGbit/s with some additional component compared to 40GBASE-CR4. 1346dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40G_XLAUI 1347dd72704bSRobert Mustacchi40 Gbit/s signalling operating across four lanes that is defined for use 1348dd72704bSRobert Mustacchibetween a MAC and a PHY or for chip-to-chip connectivity. 1349dd72704bSRobert MustacchiDefined by 802.3ba. 1350dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_40G_XLPPI 1351dd72704bSRobert Mustacchi40 Gbit/s signalling operating across four lanes that is designed to 1352dd72704bSRobert Mustacchiconnect between a chip and a module, generally a QSFP+ based device. 1353dd72704bSRobert MustacchiDefined in 802.3ba. 1354dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_KR2 1355dd72704bSRobert Mustacchi50 Gbit/s Ethernet which operates over a two lane copper backplane. 1356dd72704bSRobert MustacchiEach lane operates at 25 Gbit/s. 1357dd72704bSRobert MustacchiDefined by the 25G and 50G Ethernet consortium. 1358dd72704bSRobert MustacchiThis did not become an IEEE standard. 1359dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_CR2 1360dd72704bSRobert Mustacchi50 Gbit/s Ethernet which operates over two lane copper twinaxial cable, 1361dd72704bSRobert Mustacchigenerally with a QSFP+ connector. 1362dd72704bSRobert MustacchiEach lane operates at 25 Gbit/s. 1363dd72704bSRobert MustacchiDefined by the 25G and 50G Ethernet consortium. 1364dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_SR2 1365dd72704bSRobert Mustacchi50 Gbit/s Ethernet based upon using four pairs of multi-mode fiber, each 1366dd72704bSRobert Mustacchioperating at 25 Gbit/s, with one fiber in the pair being used for 1367dd72704bSRobert Mustacchitransmit and the other for receive. 1368dd72704bSRobert MustacchiGenerally utilizes a QSFP+ connector. 1369dd72704bSRobert MustacchiDefined by the 25G and 50G Ethernet consortium. 1370dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_LR2 1371dd72704bSRobert Mustacchi50 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1372dd72704bSRobert Mustacchifor each direction. 1373dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is two 25 1374dd72704bSRobert MustacchiGbit/s signals. 1375dd72704bSRobert MustacchiDefined by the 25G and 50G Ethernet consortium. 1376dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_AOC2 1377dd72704bSRobert Mustacchi50 Gbit/s Ethernet generally based upon a QSFP+ based cable with built-in 1378dd72704bSRobert Mustacchioptical transceivers. 1379dd72704bSRobert MustacchiThe electrical interface is two lanes running at 25 Gbit/s. 1380dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_ACC2 1381dd72704bSRobert Mustacchi50 Gbit/s Ethernet based upon two copper twinaxial lanes each running at 1382dd72704bSRobert Mustacchi25 Gbit/s with some additional component compared to 50GBASE-CR2. 1383dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_KR 1384dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a single lane backplane. 1385dd72704bSRobert MustacchiDefined by 802.3cd. 1386dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_CR 1387dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a single lane twinaxial copper cable 1388dd72704bSRobert Mustacchigenerally utilizing an SFP56 interface. 1389dd72704bSRobert MustacchiDefined by 802.3cd. 1390dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_SR 1391dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1392dd72704bSRobert Mustacchieach direction. 1393dd72704bSRobert MustacchiDefined by 802.3cd. 1394dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_LR 1395dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1396dd72704bSRobert Mustacchieach direction. 1397dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1398dd72704bSRobert MustacchiDefined in 802.3cd. 1399dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_ER 1400dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1401dd72704bSRobert Mustacchieach direction. 1402dd72704bSRobert MustacchiThe maximum fiber length is 40km. 1403dd72704bSRobert MustacchiDefined in 802.3cd. 1404dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_FR 1405dd72704bSRobert Mustacchi50 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1406dd72704bSRobert Mustacchieach direction. 1407dd72704bSRobert MustacchiThe maximum fiber length is 2km. 1408dd72704bSRobert MustacchiDefined in 802.3cd. 1409dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_AOC 1410dd72704bSRobert Mustacchi50 Gbit/s Ethernet that is built using a short-range active optical 1411dd72704bSRobert Mustacchicable that is generally SFP56 compatible. 1412dd72704bSRobert MustacchiThe electrical interface operates at 25 Gbit/s PAM4 signaling. 1413dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_50GBASE_ACC 1414dd72704bSRobert Mustacchi50 Gbit/s Ethernet that is built using a single lane twinaxial 1415dd72704bSRobert Mustacchicable that is generally SFP56 compatible but uses an active component 1416dd72704bSRobert Mustacchisuch as a retimer or redriver when compared to 50GBASE-CR. 1417dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_CR10 1418dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over ten lanes of shielded twinaxial 1419dd72704bSRobert Mustacchicopper cable, each operating at 10 Gbit/s. 1420dd72704bSRobert MustacchiDefined in 802.3ba. 1421dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_SR10 1422dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using ten pairs of multi-mode fiber, each 1423dd72704bSRobert Mustacchioperating at 10 Gbit/s, with one fiber in the pair being used for 1424dd72704bSRobert Mustacchitransmit and the other for receive. 1425dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_SR4 1426dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using four pairs of multi-mode fiber, 1427dd72704bSRobert Mustacchieach operating at 25 Gbit/s, with one fiber in the pair being used for 1428dd72704bSRobert Mustacchitransmit and the other for receive. 1429dd72704bSRobert MustacchiDefined by 802.3bm. 1430dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_LR4 1431dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1432dd72704bSRobert Mustacchifor each direction. 1433dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 25 1434dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP28 connector. 1435dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1436dd72704bSRobert MustacchiDefined by 802.3ba. 1437dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_ER4 1438dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1439dd72704bSRobert Mustacchifor each direction. 1440dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 25 1441dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP28 connector. 1442dd72704bSRobert MustacchiThe maximum fiber length is 40km. 1443dd72704bSRobert MustacchiDefined by 802.3ba. 1444dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_KR4 1445dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using a four lane copper backplane. 1446dd72704bSRobert MustacchiEach lane operates at 25 Gbit/s. 1447dd72704bSRobert MustacchiDefined in 802.3bj. 1448dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_CAUI4 1449dd72704bSRobert Mustacchi100 Gbit/s signalling used for chip-to-chip and chip-to-module 1450dd72704bSRobert Mustacchiconnectivity. 1451dd72704bSRobert MustacchiDefined in 802.3bm. 1452dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_CR4 1453dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using a four lane copper twinaxial cable. 1454dd72704bSRobert MustacchiEach lane operates at 25 Gbit/s and generally utilizes a QSFP28 1455dd72704bSRobert Mustacchiconnector. 1456dd72704bSRobert MustacchiDefined in 802.3bj. 1457dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_AOC4 1458dd72704bSRobert Mustacchi100 Gbit/s Ethernet that utilizes an active optical cable with 1459dd72704bSRobert Mustacchishort-range optical transceivers. 1460dd72704bSRobert MustacchiElectrically operates as four lanes of 25 Gbit/s and most commonly uses 1461dd72704bSRobert Mustacchia QSFP28 connector. 1462dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_ACC4 1463dd72704bSRobert Mustacchi100 Gbit/s Ethernet that utilizes a four lane copper twinaxial cable 1464dd72704bSRobert Mustacchithat unlike 100GBASE-CR4 has an active component such as a retimer or 1465dd72704bSRobert Mustacchiredriver. 1466dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_KR2 1467dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using a two lane copper backplane. 1468dd72704bSRobert MustacchiEach lane operates at 50 Gbit/s. 1469dd72704bSRobert MustacchiDefined in 802.3cd. 1470dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_CR2 1471dd72704bSRobert Mustacchi100 Gbit/s Ethernet that utilizes a two lane copper twinaxial cable. 1472dd72704bSRobert MustacchiEach lane operates at 50 Gbit/s. 1473dd72704bSRobert MustacchiDefined by 802.3cd. 1474dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_SR2 1475dd72704bSRobert Mustacchi100 Gbit/s Ethernet based upon using two pairs of multi-mode fiber, 1476dd72704bSRobert Mustacchieach operating at 50 Gbit/s, with one fiber in the pair being used for 1477dd72704bSRobert Mustacchitransmit and the other for receive. 1478dd72704bSRobert MustacchiDefined by 802.3cd. 1479dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_KR 1480dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a single lane copper backplane. 1481dd72704bSRobert MustacchiDefined by 802.3ck. 1482dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_CR 1483dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a single lane copper twinaxial cable. 1484dd72704bSRobert MustacchiGenerally uses an SFP112 connector. 1485dd72704bSRobert MustacchiDefined by 802.3ck. 1486dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_SR 1487dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a pair of multi-mode fibers, one for 1488dd72704bSRobert Mustacchitransmitting and one for receiving. 1489dd72704bSRobert MustacchiThe maximum fiber length is 60-100m depending on the fiber type 1490dd72704bSRobert Mustacchi.Pq OM3, OM4 . 1491dd72704bSRobert MustacchiDefined by 802.3db. 1492dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_DR 1493dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1494dd72704bSRobert Mustacchitransmitting and one for receiving. 1495dd72704bSRobert MustacchiDesigned to be used with a parallel DR4/DR8 interface. 1496dd72704bSRobert MustacchiThe maximum fiber length is 500m. 1497dd72704bSRobert MustacchiDefined by 802.3cd. 1498dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_LR 1499dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1500dd72704bSRobert Mustacchitransmitting and one for receiving. 1501dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1502dd72704bSRobert MustacchiDefined by 802.3cu. 1503dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_100GBASE_FR 1504dd72704bSRobert Mustacchi100 Gbit/s Ethernet operating over a pair of single-mode fibers, one for 1505dd72704bSRobert Mustacchitransmitting and one for receiving. 1506dd72704bSRobert MustacchiThe maximum fiber length is 2km. 1507dd72704bSRobert MustacchiDefined by 802.3cu. 1508dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_CR4 1509dd72704bSRobert Mustacchi200 Gbit/s Ethernet utilizing a four lane passive copper twinaxial 1510dd72704bSRobert Mustacchicable. 1511dd72704bSRobert MustacchiEach lane operates at 50 Gbit/s and the connector is generally based on 1512dd72704bSRobert MustacchiQSFP56. 1513dd72704bSRobert MustacchiDefined by 802.3cd. 1514dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_KR4 1515dd72704bSRobert Mustacchi200 Gbit/s Ethernet utilizing four lanes over a copper backplane each 1516dd72704bSRobert Mustacchioperating at 50 Gbit/s. 1517dd72704bSRobert MustacchiDefined by 802.3cd. 1518dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_SR4 1519dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using four pairs of multi-mode fiber, 1520dd72704bSRobert Mustacchieach operating at 50 Gbit/s, with one fiber in the pair being used for 1521dd72704bSRobert Mustacchitransmit and the other for receive. 1522dd72704bSRobert MustacchiDefined by 802.3cd. 1523dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_DR4 1524dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using four pairs of single-mode fiber, 1525dd72704bSRobert Mustacchieach operating at 50 Gbit/s, with one fiber in the pair being used for 1526dd72704bSRobert Mustacchitransmit and the other for receive. 1527dd72704bSRobert MustacchiDefined by 802.3bs. 1528dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_FR4 1529dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1530dd72704bSRobert Mustacchifor transmitting and one for receiving. 1531dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 50 1532dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP56 connector. 1533dd72704bSRobert MustacchiThe maximum fiber length is 2km. 1534dd72704bSRobert MustacchiDefined by 802.3bs. 1535dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_LR4 1536dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1537dd72704bSRobert Mustacchifor transmitting and one for receiving. 1538dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 50 1539dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP56 connector. 1540dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1541dd72704bSRobert MustacchiDefined by 802.3bs. 1542dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_ER4 1543dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1544dd72704bSRobert Mustacchifor transmitting and one for receiving. 1545dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 50 1546dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP56 connector. 1547dd72704bSRobert MustacchiThe maximum fiber length is 40km. 1548dd72704bSRobert MustacchiDefined by 802.3bs. 1549dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GAUI_4 1550dd72704bSRobert Mustacchi200 Gbit/s signalling utilizing four lanes each operating at 50 Gbit/s. 1551dd72704bSRobert MustacchiUsed for chip-to-chip and chip-to-module connections. 1552dd72704bSRobert MustacchiDefined by 802.3bs. 1553dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_KR2 1554dd72704bSRobert Mustacchi200 Gbit/s Ethernet utilizing two lanes over a copper backplane each 1555dd72704bSRobert Mustacchioperating at 100 Gbit/s. 1556dd72704bSRobert MustacchiDefined by 802.3ck. 1557dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_CR2 1558dd72704bSRobert Mustacchi200 Gbit/s Ethernet utilizing a two lane passive copper twinaxial 1559dd72704bSRobert Mustacchicable. 1560dd72704bSRobert MustacchiEach lane operates at 100 Gbit/s. 1561dd72704bSRobert MustacchiDefined by 802.3ck. 1562dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GBASE_SR2 1563dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using two pairs of multi-mode fiber, 1564dd72704bSRobert Mustacchieach operating at 100 Gbit/s, with one fiber in the pair being used for 1565dd72704bSRobert Mustacchitransmit and the other for receive. 1566dd72704bSRobert MustacchiDefined by 802.3db. 1567dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_200GAUI_2 1568dd72704bSRobert Mustacchi200 Gbit/s signalling utilizing two lanes each operating at 100 Gbit/s. 1569dd72704bSRobert MustacchiUsed for chip-to-chip and chip-to-module connections. 1570dd72704bSRobert MustacchiDefined by 802.3ck. 1571dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_KR8 1572dd72704bSRobert Mustacchi400 Gbit/s Ethernet utilizing eight lanes over a copper backplane each 1573dd72704bSRobert Mustacchioperating at 50 Gbit/s. 1574dd72704bSRobert MustacchiDefined by the 25/50 Gigabit Ethernet Consortium. 1575dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_FR8 1576dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1577dd72704bSRobert Mustacchifor transmitting and one for receiving. 1578dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is eight 50 1579dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP-DD connector. 1580dd72704bSRobert MustacchiThe maximum fiber length is 2km. 1581dd72704bSRobert MustacchiDefined by 802.3bs. 1582dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_LR8 1583dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1584dd72704bSRobert Mustacchifor transmitting and one for receiving. 1585dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is eight 50 1586dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP-DD connector. 1587dd72704bSRobert MustacchiThe maximum fiber length is 10km. 1588dd72704bSRobert MustacchiDefined by 802.3bs. 1589dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_ER8 1590dd72704bSRobert Mustacchi200 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1591dd72704bSRobert Mustacchifor transmitting and one for receiving. 1592dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is eight 50 1593dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP-DD connector. 1594dd72704bSRobert MustacchiThe maximum fiber length is 40km. 1595dd72704bSRobert MustacchiDefined by 802.3cn. 1596dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GAUI_8 1597dd72704bSRobert Mustacchi400 Gbit/s signalling utilizing eight lanes each operating at 50 Gbit/s. 1598dd72704bSRobert MustacchiUsed for chip-to-chip and chip-to-module connections. 1599dd72704bSRobert MustacchiDefined by 802.3bs. 1600dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_KR4 1601dd72704bSRobert Mustacchi400 Gbit/s Ethernet utilizing four lanes over a copper backplane each 1602dd72704bSRobert Mustacchioperating at 100 Gbit/s. 1603dd72704bSRobert MustacchiDefined by 802.3ck. 1604dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_CR4 1605dd72704bSRobert Mustacchi200 Gbit/s Ethernet utilizing a two lane passive copper twinaxial 1606dd72704bSRobert Mustacchicable. 1607dd72704bSRobert MustacchiEach lane operates at 100 Gbit/s and generally uses a QSFP112 connector. 1608dd72704bSRobert MustacchiDefined by 802.3ck. 1609dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_SR4 1610dd72704bSRobert Mustacchi400 Gbit/s Ethernet based upon using four pairs of multi-mode fiber, 1611dd72704bSRobert Mustacchieach operating at 100 Gbit/s, with one fiber in the pair being used for 1612dd72704bSRobert Mustacchitransmit and the other for receive. 1613dd72704bSRobert MustacchiDefined by 802.3db. 1614dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_DR4 1615dd72704bSRobert Mustacchi400 Gbit/s Ethernet based upon using four pairs of single-mode fiber, 1616dd72704bSRobert Mustacchieach operating at 100 Gbit/s, with one fiber in the pair being used for 1617dd72704bSRobert Mustacchitransmit and the other for receive. 1618dd72704bSRobert MustacchiThe maximum fiber length is 500m. 1619dd72704bSRobert MustacchiDefined by 802.3bs. 1620dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GBASE_FR4 1621dd72704bSRobert Mustacchi400 Gbit/s Ethernet based upon using one pair of single-mode fibers, one 1622dd72704bSRobert Mustacchifor transmitting and one for receiving. 1623dd72704bSRobert MustacchiUtilizes wavelength multiplexing as the electrical interface is four 100 1624dd72704bSRobert MustacchiGbit/s signals and generally based upon a QSFP112 connector. 1625dd72704bSRobert MustacchiThe maximum fiber length is 2km. 1626dd72704bSRobert MustacchiDefined by 802.3cu. 1627dd72704bSRobert Mustacchi.It Dv ETHER_MEDIA_400GAUI_4 1628dd72704bSRobert Mustacchi400 Gbit/s signalling utilizing four lanes each operating at 100 Gbit/s. 1629dd72704bSRobert MustacchiUsed for chip-to-chip and chip-to-module connections. 1630dd72704bSRobert MustacchiDefined by 802.3ck. 1631dd72704bSRobert Mustacchi.El 16322c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_AUTONEG 163352d2369aSRobert Mustacchi.Bd -filled -compact 163452d2369aSRobert MustacchiType: 16352c0ebdeeSRobert Mustacchi.Vt uint8_t | 163652d2369aSRobert MustacchiPermissions: 163752d2369aSRobert Mustacchi.Sy Read/Write 163852d2369aSRobert Mustacchi.Ed 163952d2369aSRobert Mustacchi.Pp 164052d2369aSRobert MustacchiThe 16412c0ebdeeSRobert Mustacchi.Dv MAC_PROP_AUTONEG 164252d2369aSRobert Mustacchiproperty indicates whether or not the device is currently configured to 164372d3dbb9SYuri Pankovperform auto-negotiation. 164472d3dbb9SYuri PankovA value of 164552d2369aSRobert Mustacchi.Sy 0 164672d3dbb9SYuri Pankovindicates that auto-negotiation is disabled. 164772d3dbb9SYuri PankovA 164852d2369aSRobert Mustacchi.Sy non-zero 164972d3dbb9SYuri Pankovvalue indicates that auto-negotiation is enabled. 165072d3dbb9SYuri PankovDevices should generally default to enabling auto-negotiation. 165152d2369aSRobert Mustacchi.Pp 165252d2369aSRobert MustacchiWhen getting this property, the device driver should return the current 165372d3dbb9SYuri Pankovstate. 165472d3dbb9SYuri PankovWhen setting this property, if the device supports operating in the requested 165572d3dbb9SYuri Pankovmode, then the device driver should reset the link to negotiate to the new speed 165672d3dbb9SYuri Pankovafter updating any internal registers. 16572c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_MTU 165852d2369aSRobert Mustacchi.Bd -filled -compact 165952d2369aSRobert MustacchiType: 16602c0ebdeeSRobert Mustacchi.Vt uint32_t | 166152d2369aSRobert MustacchiPermissions: 166252d2369aSRobert Mustacchi.Sy Read/Write 166352d2369aSRobert Mustacchi.Ed 166452d2369aSRobert Mustacchi.Pp 166552d2369aSRobert MustacchiThe 16662c0ebdeeSRobert Mustacchi.Dv MAC_PROP_MTU 166772d3dbb9SYuri Pankovproperty determines the maximum transmission unit (MTU). 166872d3dbb9SYuri PankovThis indicates the maximum size packet that the device can transmit, ignoring 166972d3dbb9SYuri Pankovits own headers. 167072d3dbb9SYuri PankovFor an Ethernet device, this would exclude the size of the Ethernet header and 167172d3dbb9SYuri Pankovany VLAN headers that would be placed. 167272d3dbb9SYuri PankovIt is up to the driver to ensure that any MTU values that it accepts when adding 167372d3dbb9SYuri Pankovin its margin and header sizes does not exceed its maximum frame size. 167452d2369aSRobert Mustacchi.Pp 167552d2369aSRobert MustacchiBy default, drivers for Ethernet should initialize this value and the 167652d2369aSRobert MustacchiMTU to 167752d2369aSRobert Mustacchi.Sy 1500 . 167852d2369aSRobert MustacchiWhen getting this property, the driver should return its current 167972d3dbb9SYuri Pankovrecorded MTU. 168072d3dbb9SYuri PankovWhen setting this property, the driver should first validate that it is within 168172d3dbb9SYuri Pankovthe device's valid range and then it must call 168252d2369aSRobert Mustacchi.Xr mac_maxsdu_update 9F . 168372d3dbb9SYuri PankovNote that the call may fail. 168472d3dbb9SYuri PankovIf the call completes successfully, the driver should update the hardware with 168572d3dbb9SYuri Pankovthe new value of the MTU and perform any other work needed to handle it. 168652d2369aSRobert Mustacchi.Pp 168752d2369aSRobert MustacchiIf the device does not support changing the MTU after the device's 168852d2369aSRobert Mustacchi.Xr mc_start 9E 168952d2369aSRobert Mustacchientry point has been called, then driver writers should return 169052d2369aSRobert Mustacchi.Er EBUSY . 16912c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_FLOWCTRL 169252d2369aSRobert Mustacchi.Bd -filled -compact 169352d2369aSRobert MustacchiType: 16942c0ebdeeSRobert Mustacchi.Vt link_flowctrl_t | 169552d2369aSRobert MustacchiPermissions: 169652d2369aSRobert Mustacchi.Sy Read/Write 169752d2369aSRobert Mustacchi.Ed 169852d2369aSRobert Mustacchi.Pp 169952d2369aSRobert MustacchiThe 17002c0ebdeeSRobert Mustacchi.Dv MAC_PROP_FLOWCTRL 170152d2369aSRobert Mustacchiproperty manages the configuration of pause frames as part of Ethernet 170272d3dbb9SYuri Pankovflow control. 170372d3dbb9SYuri PankovNote, this only describes what this device will advertise. 170452d2369aSRobert MustacchiWhat is actually enabled may be different and is subject to the rules of 170572d3dbb9SYuri Pankovauto-negotiation. 170672d3dbb9SYuri PankovThe 17072c0ebdeeSRobert Mustacchi.Vt link_flowctrl_t 170852d2369aSRobert Mustacchiis an enumeration that may be set to one of the following values: 170952d2369aSRobert Mustacchi.Bl -tag -width Ds 17102c0ebdeeSRobert Mustacchi.It Dv LINK_FLOWCTRL_NONE 171172d3dbb9SYuri PankovFlow control is disabled. 171272d3dbb9SYuri PankovNo pause frames should be generated or honored. 17132c0ebdeeSRobert Mustacchi.It Dv LINK_FLOWCTRL_RX 171452d2369aSRobert MustacchiThe device can receive pause frames; however, it should not generate 171552d2369aSRobert Mustacchithem. 17162c0ebdeeSRobert Mustacchi.It Dv LINK_FLOWCTRL_TX 171752d2369aSRobert MustacchiThe device can generate pause frames; however, it does not support 171852d2369aSRobert Mustacchireceiving them. 17192c0ebdeeSRobert Mustacchi.It Dv LINK_FLOWCTRL_BI 172052d2369aSRobert MustacchiThe device supports both sending and receiving pause frames. 172152d2369aSRobert Mustacchi.El 172252d2369aSRobert Mustacchi.Pp 172352d2369aSRobert MustacchiWhen getting this property, the device driver should return the way that 172452d2369aSRobert Mustacchiit has configured the device, not what the device has actually 172572d3dbb9SYuri Pankovnegotiated. 172672d3dbb9SYuri PankovWhen setting the property, it should update the hardware and allow the link to 172772d3dbb9SYuri Pankovpotentially perform auto-negotiation again. 17282c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_FEC_CAP 1729d77e6e0fSPaul Winder.Bd -filled -compact 1730d77e6e0fSPaul WinderType: 17312c0ebdeeSRobert Mustacchi.Vt link_fec_t | 1732d77e6e0fSPaul WinderPermissions: 1733d77e6e0fSPaul Winder.Sy Read/Write 1734d77e6e0fSPaul Winder.Ed 1735d77e6e0fSPaul Winder.Pp 1736d77e6e0fSPaul WinderThe 17372c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_FEC_CAP 1738d77e6e0fSPaul Winderproperty indicates which Forward Error Correction (FEC) code is advertised 1739d77e6e0fSPaul Winderby the device. 1740d77e6e0fSPaul Winder.Pp 1741d77e6e0fSPaul WinderThe 17422c0ebdeeSRobert Mustacchi.Vt link_fec_t 1743d77e6e0fSPaul Winderis an enumeration that may be a combination of the following bit values: 1744d77e6e0fSPaul Winder.Bl -tag -width Ds 17452c0ebdeeSRobert Mustacchi.It Dv LINK_FEC_NONE 1746d77e6e0fSPaul WinderNo FEC over the link. 17472c0ebdeeSRobert Mustacchi.It Dv LINK_FEC_AUTO 1748d77e6e0fSPaul WinderThe FEC coding to use is auto-negotiated, 17492c0ebdeeSRobert Mustacchi.Dv LINK_FEC_AUTO 1750d77e6e0fSPaul Windercannot be set along with any of the other values. 1751d77e6e0fSPaul WinderThis is the default setting the device driver should use. 17522c0ebdeeSRobert Mustacchi.It Dv LINK_FEC_RS 1753d77e6e0fSPaul WinderThe link may use Reed-Solomon FEC coding. 17542c0ebdeeSRobert Mustacchi.It Dv LINK_FEC_BASE_R 1755d77e6e0fSPaul WinderThe link may use Base-R coding, also common referred to as FireCode. 1756d77e6e0fSPaul Winder.El 1757d77e6e0fSPaul Winder.Pp 1758d77e6e0fSPaul WinderWhen setting the property, it should update the hardware with the requested, or 1759d77e6e0fSPaul Windercombination of requested codings. 1760d77e6e0fSPaul WinderIf a particular combination of codings is not supported by the hardware, 1761d77e6e0fSPaul Winderthe device driver should return 1762d77e6e0fSPaul Winder.Er EINVAL . 1763d77e6e0fSPaul WinderWhen retrieving this property, the device driver should return the current 1764d77e6e0fSPaul Windervalue of the property. 17652c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_FEC_CAP 1766d77e6e0fSPaul Winder.Bd -filled -compact 1767d77e6e0fSPaul WinderType: 17682c0ebdeeSRobert Mustacchi.Vt link_fec_t | 1769d77e6e0fSPaul WinderPermissions: 1770d77e6e0fSPaul Winder.Sy Read-Only 1771d77e6e0fSPaul Winder.Ed 1772d77e6e0fSPaul Winder.Pp 1773d77e6e0fSPaul WinderThe 17742c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_FEC_CAP 1775d77e6e0fSPaul Winderhas the same values as 17762c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_FEC_CAP . 1777d77e6e0fSPaul WinderThe property indicates which Forward Error Correction (FEC) code has been 1778d77e6e0fSPaul Windernegotiated over the link. 177952d2369aSRobert Mustacchi.El 178052d2369aSRobert Mustacchi.Pp 178152d2369aSRobert MustacchiThe remaining properties are all about various auto-negotiation link 178272d3dbb9SYuri Pankovspeeds. 178372d3dbb9SYuri PankovThey fall into two different buckets: properties with 178452d2369aSRobert Mustacchi.Sy _ADV_ 178552d2369aSRobert Mustacchiin the name and properties with 178652d2369aSRobert Mustacchi.Sy _EN_ 178772d3dbb9SYuri Pankovin the name. 178872d3dbb9SYuri PankovFor any given supported speed, there is one of each. 178972d3dbb9SYuri PankovThe 179052d2369aSRobert Mustacchi.Sy _EN_ 179152d2369aSRobert Mustacchiset of properties are read/write properties that control what should be 179272d3dbb9SYuri Pankovadvertised by the device. 179372d3dbb9SYuri PankovWhen these are retrieved, they should return the current value of the property. 179472d3dbb9SYuri PankovWhen they are set, they should change how the hardware advertises the specific 179572d3dbb9SYuri Pankovspeed and trigger any kind of link reset and auto-negotiation, if enabled, to 179672d3dbb9SYuri Pankovoccur. 179752d2369aSRobert Mustacchi.Pp 179852d2369aSRobert MustacchiThe 179952d2369aSRobert Mustacchi.Sy _ADV_ 180072d3dbb9SYuri Pankovset of properties are read-only properties. 180172d3dbb9SYuri PankovThey are meant to reflect what has actually been negotiated. 180272d3dbb9SYuri PankovThese may be different from the 180352d2369aSRobert Mustacchi.Sy _EN_ 180452d2369aSRobert Mustacchifamily of properties, especially when different power management 180552d2369aSRobert Mustacchisettings are at play. 180652d2369aSRobert Mustacchi.Pp 180752d2369aSRobert MustacchiSee the 180852d2369aSRobert Mustacchi.Sx Link Speed and Auto-negotiation 180952d2369aSRobert Mustacchisection for more information. 181052d2369aSRobert Mustacchi.Pp 181152d2369aSRobert MustacchiThe properties are ordered in increasing link speed: 181252d2369aSRobert Mustacchi.Bl -hang -width Ds 18132c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_10HDX_CAP 181452d2369aSRobert Mustacchi.Bd -filled -compact 181552d2369aSRobert MustacchiType: 18162c0ebdeeSRobert Mustacchi.Vt uint8_t | 181752d2369aSRobert MustacchiPermissions: 181852d2369aSRobert Mustacchi.Sy Read-Only 181952d2369aSRobert Mustacchi.Ed 182052d2369aSRobert Mustacchi.Pp 182152d2369aSRobert MustacchiThe 18222c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_10HDX_CAP 182352d2369aSRobert Mustacchiproperty describes whether or not 10 Mbit/s half-duplex support is 182452d2369aSRobert Mustacchiadvertised. 18252c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_10HDX_CAP 182652d2369aSRobert Mustacchi.Bd -filled -compact 182752d2369aSRobert MustacchiType: 18282c0ebdeeSRobert Mustacchi.Vt uint8_t | 182952d2369aSRobert MustacchiPermissions: 183052d2369aSRobert Mustacchi.Sy Read/Write 183152d2369aSRobert Mustacchi.Ed 183252d2369aSRobert Mustacchi.Pp 183352d2369aSRobert MustacchiThe 18342c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_10HDX_CAP 183552d2369aSRobert Mustacchiproperty describes whether or not 10 Mbit/s half-duplex support is 183652d2369aSRobert Mustacchienabled. 18372c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_10FDX_CAP 183852d2369aSRobert Mustacchi.Bd -filled -compact 183952d2369aSRobert MustacchiType: 18402c0ebdeeSRobert Mustacchi.Vt uint8_t | 184152d2369aSRobert MustacchiPermissions: 184252d2369aSRobert Mustacchi.Sy Read-Only 184352d2369aSRobert Mustacchi.Ed 184452d2369aSRobert Mustacchi.Pp 184552d2369aSRobert MustacchiThe 18462c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_10FDX_CAP 184752d2369aSRobert Mustacchiproperty describes whether or not 10 Mbit/s full-duplex support is 184852d2369aSRobert Mustacchiadvertised. 18492c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_10FDX_CAP 185052d2369aSRobert Mustacchi.Bd -filled -compact 185152d2369aSRobert MustacchiType: 18522c0ebdeeSRobert Mustacchi.Vt uint8_t | 185352d2369aSRobert MustacchiPermissions: 185452d2369aSRobert Mustacchi.Sy Read/Write 185552d2369aSRobert Mustacchi.Ed 185652d2369aSRobert Mustacchi.Pp 185752d2369aSRobert MustacchiThe 18582c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_10FDX_CAP 185952d2369aSRobert Mustacchiproperty describes whether or not 10 Mbit/s full-duplex support is 186052d2369aSRobert Mustacchienabled. 18612c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_100HDX_CAP 186252d2369aSRobert Mustacchi.Bd -filled -compact 186352d2369aSRobert MustacchiType: 18642c0ebdeeSRobert Mustacchi.Vt uint8_t | 186552d2369aSRobert MustacchiPermissions: 186652d2369aSRobert Mustacchi.Sy Read-Only 186752d2369aSRobert Mustacchi.Ed 186852d2369aSRobert Mustacchi.Pp 186952d2369aSRobert MustacchiThe 18702c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_100HDX_CAP 187152d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s half-duplex support is 187252d2369aSRobert Mustacchiadvertised. 18732c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_100HDX_CAP 187452d2369aSRobert Mustacchi.Bd -filled -compact 187552d2369aSRobert MustacchiType: 18762c0ebdeeSRobert Mustacchi.Vt uint8_t | 187752d2369aSRobert MustacchiPermissions: 187852d2369aSRobert Mustacchi.Sy Read/Write 187952d2369aSRobert Mustacchi.Ed 188052d2369aSRobert Mustacchi.Pp 188152d2369aSRobert MustacchiThe 18822c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_100HDX_CAP 188352d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s half-duplex support is 188452d2369aSRobert Mustacchienabled. 18852c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_100FDX_CAP 188652d2369aSRobert Mustacchi.Bd -filled -compact 188752d2369aSRobert MustacchiType: 18882c0ebdeeSRobert Mustacchi.Vt uint8_t | 188952d2369aSRobert MustacchiPermissions: 189052d2369aSRobert Mustacchi.Sy Read-Only 189152d2369aSRobert Mustacchi.Ed 189252d2369aSRobert Mustacchi.Pp 189352d2369aSRobert MustacchiThe 18942c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_100FDX_CAP 189552d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s full-duplex support is 189652d2369aSRobert Mustacchiadvertised. 18972c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_100FDX_CAP 189852d2369aSRobert Mustacchi.Bd -filled -compact 189952d2369aSRobert MustacchiType: 19002c0ebdeeSRobert Mustacchi.Vt uint8_t | 190152d2369aSRobert MustacchiPermissions: 190252d2369aSRobert Mustacchi.Sy Read/Write 190352d2369aSRobert Mustacchi.Ed 190452d2369aSRobert Mustacchi.Pp 190552d2369aSRobert MustacchiThe 19062c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_100FDX_CAP 190752d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s full-duplex support is 190852d2369aSRobert Mustacchienabled. 19092c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_100T4_CAP 191052d2369aSRobert Mustacchi.Bd -filled -compact 191152d2369aSRobert MustacchiType: 19122c0ebdeeSRobert Mustacchi.Vt uint8_t | 191352d2369aSRobert MustacchiPermissions: 191452d2369aSRobert Mustacchi.Sy Read-Only 191552d2369aSRobert Mustacchi.Ed 191652d2369aSRobert Mustacchi.Pp 191752d2369aSRobert MustacchiThe 19182c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_100T4_CAP 191952d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s Ethernet using the 192052d2369aSRobert Mustacchi100BASE-T4 standard is 192152d2369aSRobert Mustacchiadvertised. 19222c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_100T4_CAP 192352d2369aSRobert Mustacchi.Bd -filled -compact 192452d2369aSRobert MustacchiType: 19252c0ebdeeSRobert Mustacchi.Vt uint8_t | 192652d2369aSRobert MustacchiPermissions: 192752d2369aSRobert Mustacchi.Sy Read/Write 192852d2369aSRobert Mustacchi.Ed 192952d2369aSRobert Mustacchi.Pp 193052d2369aSRobert MustacchiThe 1931b632e9f0SJason King.Dv MAC_PROP_EN_100T4_CAP 193252d2369aSRobert Mustacchiproperty describes whether or not 100 Mbit/s Ethernet using the 193352d2369aSRobert Mustacchi100BASE-T4 standard is 193452d2369aSRobert Mustacchienabled. 1935b632e9f0SJason King.It Dv MAC_PROP_ADV_1000HDX_CAP 193652d2369aSRobert Mustacchi.Bd -filled -compact 193752d2369aSRobert MustacchiType: 19382c0ebdeeSRobert Mustacchi.Vt uint8_t | 193952d2369aSRobert MustacchiPermissions: 194052d2369aSRobert Mustacchi.Sy Read-Only 194152d2369aSRobert Mustacchi.Ed 194252d2369aSRobert Mustacchi.Pp 194352d2369aSRobert MustacchiThe 19442c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_1000HDX_CAP 194552d2369aSRobert Mustacchiproperty describes whether or not 1 Gbit/s half-duplex support is 194652d2369aSRobert Mustacchiadvertised. 19472c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_1000HDX_CAP 194852d2369aSRobert Mustacchi.Bd -filled -compact 194952d2369aSRobert MustacchiType: 19502c0ebdeeSRobert Mustacchi.Vt uint8_t | 195152d2369aSRobert MustacchiPermissions: 195252d2369aSRobert Mustacchi.Sy Read/Write 195352d2369aSRobert Mustacchi.Ed 195452d2369aSRobert Mustacchi.Pp 195552d2369aSRobert MustacchiThe 19562c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_1000HDX_CAP 195752d2369aSRobert Mustacchiproperty describes whether or not 1 Gbit/s half-duplex support is 195852d2369aSRobert Mustacchienabled. 19592c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_1000FDX_CAP 196052d2369aSRobert Mustacchi.Bd -filled -compact 196152d2369aSRobert MustacchiType: 19622c0ebdeeSRobert Mustacchi.Vt uint8_t | 196352d2369aSRobert MustacchiPermissions: 196452d2369aSRobert Mustacchi.Sy Read-Only 196552d2369aSRobert Mustacchi.Ed 196652d2369aSRobert Mustacchi.Pp 196752d2369aSRobert MustacchiThe 19682c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_1000FDX_CAP 196952d2369aSRobert Mustacchiproperty describes whether or not 1 Gbit/s full-duplex support is 197052d2369aSRobert Mustacchiadvertised. 19712c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_1000FDX_CAP 197252d2369aSRobert Mustacchi.Bd -filled -compact 197352d2369aSRobert MustacchiType: 19742c0ebdeeSRobert Mustacchi.Vt uint8_t | 197552d2369aSRobert MustacchiPermissions: 197652d2369aSRobert Mustacchi.Sy Read/Write 197752d2369aSRobert Mustacchi.Ed 197852d2369aSRobert Mustacchi.Pp 197952d2369aSRobert MustacchiThe 19802c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_1000FDX_CAP 198152d2369aSRobert Mustacchiproperty describes whether or not 1 Gbit/s full-duplex support is 198252d2369aSRobert Mustacchienabled. 19832c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_2500FDX_CAP 198452d2369aSRobert Mustacchi.Bd -filled -compact 198552d2369aSRobert MustacchiType: 19862c0ebdeeSRobert Mustacchi.Vt uint8_t | 198752d2369aSRobert MustacchiPermissions: 198852d2369aSRobert Mustacchi.Sy Read-Only 198952d2369aSRobert Mustacchi.Ed 199052d2369aSRobert Mustacchi.Pp 199152d2369aSRobert MustacchiThe 19922c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_2500FDX_CAP 199352d2369aSRobert Mustacchiproperty describes whether or not 2.5 Gbit/s full-duplex support is 199452d2369aSRobert Mustacchiadvertised. 19952c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_2500FDX_CAP 199652d2369aSRobert Mustacchi.Bd -filled -compact 199752d2369aSRobert MustacchiType: 19982c0ebdeeSRobert Mustacchi.Vt uint8_t | 199952d2369aSRobert MustacchiPermissions: 200052d2369aSRobert Mustacchi.Sy Read/Write 200152d2369aSRobert Mustacchi.Ed 200252d2369aSRobert Mustacchi.Pp 200352d2369aSRobert MustacchiThe 20042c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_2500FDX_CAP 200552d2369aSRobert Mustacchiproperty describes whether or not 2.5 Gbit/s full-duplex support is 200652d2369aSRobert Mustacchienabled. 20072c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_5000FDX_CAP 200852d2369aSRobert Mustacchi.Bd -filled -compact 200952d2369aSRobert MustacchiType: 20102c0ebdeeSRobert Mustacchi.Vt uint8_t | 201152d2369aSRobert MustacchiPermissions: 201252d2369aSRobert Mustacchi.Sy Read-Only 201352d2369aSRobert Mustacchi.Ed 201452d2369aSRobert Mustacchi.Pp 201552d2369aSRobert MustacchiThe 20162c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_5000FDX_CAP 201752d2369aSRobert Mustacchiproperty describes whether or not 5.0 Gbit/s full-duplex support is 201852d2369aSRobert Mustacchiadvertised. 20192c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_5000FDX_CAP 202052d2369aSRobert Mustacchi.Bd -filled -compact 202152d2369aSRobert MustacchiType: 20222c0ebdeeSRobert Mustacchi.Vt uint8_t | 202352d2369aSRobert MustacchiPermissions: 202452d2369aSRobert Mustacchi.Sy Read/Write 202552d2369aSRobert Mustacchi.Ed 202652d2369aSRobert Mustacchi.Pp 202752d2369aSRobert MustacchiThe 20282c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_5000FDX_CAP 202952d2369aSRobert Mustacchiproperty describes whether or not 5.0 Gbit/s full-duplex support is 203052d2369aSRobert Mustacchienabled. 20312c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_10GFDX_CAP 203252d2369aSRobert Mustacchi.Bd -filled -compact 203352d2369aSRobert MustacchiType: 20342c0ebdeeSRobert Mustacchi.Vt uint8_t | 203552d2369aSRobert MustacchiPermissions: 203652d2369aSRobert Mustacchi.Sy Read-Only 203752d2369aSRobert Mustacchi.Ed 203852d2369aSRobert Mustacchi.Pp 203952d2369aSRobert MustacchiThe 20402c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_10GFDX_CAP 204152d2369aSRobert Mustacchiproperty describes whether or not 10 Gbit/s full-duplex support is 204252d2369aSRobert Mustacchiadvertised. 20432c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_10GFDX_CAP 204452d2369aSRobert Mustacchi.Bd -filled -compact 204552d2369aSRobert MustacchiType: 20462c0ebdeeSRobert Mustacchi.Vt uint8_t | 204752d2369aSRobert MustacchiPermissions: 204852d2369aSRobert Mustacchi.Sy Read/Write 204952d2369aSRobert Mustacchi.Ed 205052d2369aSRobert Mustacchi.Pp 205152d2369aSRobert MustacchiThe 20522c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_10GFDX_CAP 205352d2369aSRobert Mustacchiproperty describes whether or not 10 Gbit/s full-duplex support is 205452d2369aSRobert Mustacchienabled. 20552c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_40GFDX_CAP 205652d2369aSRobert Mustacchi.Bd -filled -compact 205752d2369aSRobert MustacchiType: 20582c0ebdeeSRobert Mustacchi.Vt uint8_t | 205952d2369aSRobert MustacchiPermissions: 206052d2369aSRobert Mustacchi.Sy Read-Only 206152d2369aSRobert Mustacchi.Ed 206252d2369aSRobert Mustacchi.Pp 206352d2369aSRobert MustacchiThe 20642c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_40GFDX_CAP 206552d2369aSRobert Mustacchiproperty describes whether or not 40 Gbit/s full-duplex support is 206652d2369aSRobert Mustacchiadvertised. 20672c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_40GFDX_CAP 206852d2369aSRobert Mustacchi.Bd -filled -compact 206952d2369aSRobert MustacchiType: 20702c0ebdeeSRobert Mustacchi.Vt uint8_t | 207152d2369aSRobert MustacchiPermissions: 207252d2369aSRobert Mustacchi.Sy Read/Write 207352d2369aSRobert Mustacchi.Ed 207452d2369aSRobert Mustacchi.Pp 207552d2369aSRobert MustacchiThe 20762c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_40GFDX_CAP 207752d2369aSRobert Mustacchiproperty describes whether or not 40 Gbit/s full-duplex support is 207852d2369aSRobert Mustacchienabled. 20792c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_ADV_100GFDX_CAP 208052d2369aSRobert Mustacchi.Bd -filled -compact 208152d2369aSRobert MustacchiType: 20822c0ebdeeSRobert Mustacchi.Vt uint8_t | 208352d2369aSRobert MustacchiPermissions: 208452d2369aSRobert Mustacchi.Sy Read-Only 208552d2369aSRobert Mustacchi.Ed 208652d2369aSRobert Mustacchi.Pp 208752d2369aSRobert MustacchiThe 20882c0ebdeeSRobert Mustacchi.Dv MAC_PROP_ADV_100GFDX_CAP 208952d2369aSRobert Mustacchiproperty describes whether or not 100 Gbit/s full-duplex support is 209052d2369aSRobert Mustacchiadvertised. 20912c0ebdeeSRobert Mustacchi.It Dv MAC_PROP_EN_100GFDX_CAP 209252d2369aSRobert Mustacchi.Bd -filled -compact 209352d2369aSRobert MustacchiType: 20942c0ebdeeSRobert Mustacchi.Vt uint8_t | 209552d2369aSRobert MustacchiPermissions: 209652d2369aSRobert Mustacchi.Sy Read/Write 209752d2369aSRobert Mustacchi.Ed 209852d2369aSRobert Mustacchi.Pp 209952d2369aSRobert MustacchiThe 21002c0ebdeeSRobert Mustacchi.Dv MAC_PROP_EN_100GFDX_CAP 210152d2369aSRobert Mustacchiproperty describes whether or not 100 Gbit/s full-duplex support is 210252d2369aSRobert Mustacchienabled. 2103*2aaafd60SRobert Mustacchi.It Dv MAC_PROP_ADV_200GFDX_CAP 2104*2aaafd60SRobert Mustacchi.Bd -filled -compact 2105*2aaafd60SRobert MustacchiType: 2106*2aaafd60SRobert Mustacchi.Vt uint8_t | 2107*2aaafd60SRobert MustacchiPermissions: 2108*2aaafd60SRobert Mustacchi.Sy Read-Only 2109*2aaafd60SRobert Mustacchi.Ed 2110*2aaafd60SRobert Mustacchi.Pp 2111*2aaafd60SRobert MustacchiThe 2112*2aaafd60SRobert Mustacchi.Dv MAC_PROP_ADV_200GFDX_CAP 2113*2aaafd60SRobert Mustacchiproperty describes whether or not 200 Gbit/s full-duplex support is 2114*2aaafd60SRobert Mustacchiadvertised. 2115*2aaafd60SRobert Mustacchi.It Dv MAC_PROP_EN_200GFDX_CAP 2116*2aaafd60SRobert Mustacchi.Bd -filled -compact 2117*2aaafd60SRobert MustacchiType: 2118*2aaafd60SRobert Mustacchi.Vt uint8_t | 2119*2aaafd60SRobert MustacchiPermissions: 2120*2aaafd60SRobert Mustacchi.Sy Read/Write 2121*2aaafd60SRobert Mustacchi.Ed 2122*2aaafd60SRobert Mustacchi.Pp 2123*2aaafd60SRobert MustacchiThe 2124*2aaafd60SRobert Mustacchi.Dv MAC_PROP_EN_200GFDX_CAP 2125*2aaafd60SRobert Mustacchiproperty describes whether or not 200 Gbit/s full-duplex support is 2126*2aaafd60SRobert Mustacchienabled. 2127*2aaafd60SRobert Mustacchi.It Dv MAC_PROP_ADV_400GFDX_CAP 2128*2aaafd60SRobert Mustacchi.Bd -filled -compact 2129*2aaafd60SRobert MustacchiType: 2130*2aaafd60SRobert Mustacchi.Vt uint8_t | 2131*2aaafd60SRobert MustacchiPermissions: 2132*2aaafd60SRobert Mustacchi.Sy Read-Only 2133*2aaafd60SRobert Mustacchi.Ed 2134*2aaafd60SRobert Mustacchi.Pp 2135*2aaafd60SRobert MustacchiThe 2136*2aaafd60SRobert Mustacchi.Dv MAC_PROP_ADV_400GFDX_CAP 2137*2aaafd60SRobert Mustacchiproperty describes whether or not 400 Gbit/s full-duplex support is 2138*2aaafd60SRobert Mustacchiadvertised. 2139*2aaafd60SRobert Mustacchi.It Dv MAC_PROP_EN_400GFDX_CAP 2140*2aaafd60SRobert Mustacchi.Bd -filled -compact 2141*2aaafd60SRobert MustacchiType: 2142*2aaafd60SRobert Mustacchi.Vt uint8_t | 2143*2aaafd60SRobert MustacchiPermissions: 2144*2aaafd60SRobert Mustacchi.Sy Read/Write 2145*2aaafd60SRobert Mustacchi.Ed 2146*2aaafd60SRobert Mustacchi.Pp 2147*2aaafd60SRobert MustacchiThe 2148*2aaafd60SRobert Mustacchi.Dv MAC_PROP_EN_400GFDX_CAP 2149*2aaafd60SRobert Mustacchiproperty describes whether or not 400 Gbit/s full-duplex support is 2150*2aaafd60SRobert Mustacchienabled. 215152d2369aSRobert Mustacchi.El 215252d2369aSRobert Mustacchi.Ss Private Properties 215352d2369aSRobert MustacchiIn addition to the defined properties above, drivers are allowed to 215472d3dbb9SYuri Pankovdefine private properties. 215572d3dbb9SYuri PankovThese private properties are device-specific properties. 215672d3dbb9SYuri PankovAll private properties share the same constant, 21572c0ebdeeSRobert Mustacchi.Dv MAC_PROP_PRIVATE . 215872d3dbb9SYuri PankovProperties are distinguished by a name, which is a character string. 215972d3dbb9SYuri PankovThe list of such private properties is defined when registering with mac in the 21602c0ebdeeSRobert Mustacchi.Fa m_priv_props 216152d2369aSRobert Mustacchimember of the 216252d2369aSRobert Mustacchi.Xr mac_register 9S 216352d2369aSRobert Mustacchistructure. 216452d2369aSRobert Mustacchi.Pp 216552d2369aSRobert MustacchiThe driver may define whatever semantics it wants for these private 216672d3dbb9SYuri Pankovproperties. 216772d3dbb9SYuri PankovThey will not be listed when running 2168bbf21555SRichard Lowe.Xr dladm 8 , 216972d3dbb9SYuri Pankovunless explicitly requested by name. 217072d3dbb9SYuri PankovAll such properties should start with a leading underscore character and then 217172d3dbb9SYuri Pankovconsist of alphanumeric ASCII characters and additional underscores or hyphens. 217252d2369aSRobert Mustacchi.Pp 217352d2369aSRobert MustacchiProperties of type 21742c0ebdeeSRobert Mustacchi.Dv MAC_PROP_PRIVATE 217552d2369aSRobert Mustacchimay show up in all three property related entry points: 217652d2369aSRobert Mustacchi.Xr mc_propinfo 9E , 217752d2369aSRobert Mustacchi.Xr mc_getprop 9E , 217852d2369aSRobert Mustacchiand 217952d2369aSRobert Mustacchi.Xr mc_setprop 9E . 218052d2369aSRobert MustacchiDevice drivers should tell the different properties apart by using the 218152d2369aSRobert Mustacchi.Xr strcmp 9F 218252d2369aSRobert Mustacchifunction to compare it to the set of properties that it knows about. 218352d2369aSRobert MustacchiWhen encountering properties that it doesn't know, it should treat them 218452d2369aSRobert Mustacchilike all other unknown properties. 218552d2369aSRobert Mustacchi.Sh STATISTICS 218652d2369aSRobert MustacchiThe MAC framework defines a couple different sets of statistics which 218772d3dbb9SYuri Pankovare based on various standards for devices to implement. 218872d3dbb9SYuri PankovStatistics are retrieved through the 218952d2369aSRobert Mustacchi.Xr mc_getstat 9E 219072d3dbb9SYuri Pankoventry point. 219172d3dbb9SYuri PankovThere are both statistics that are required for all devices and then there is a 219272d3dbb9SYuri Pankovseparate set of Ethernet specific statistics. 219372d3dbb9SYuri PankovNot all devices will support every statistic. 219472d3dbb9SYuri PankovIn many cases, several device registers will need to be combined to create the 219572d3dbb9SYuri Pankovproper stat. 219652d2369aSRobert Mustacchi.Pp 219752d2369aSRobert MustacchiIn general, if the device is not keeping track of these statistics, then 219852d2369aSRobert Mustacchiit is recommended that the driver store these values as a 21992c0ebdeeSRobert Mustacchi.Vt uint64_t 220052d2369aSRobert Mustacchito ensure that overflow does not occur. 220152d2369aSRobert Mustacchi.Pp 220252d2369aSRobert MustacchiIf a device does not support a specific statistic, then it is fine to 220372d3dbb9SYuri Pankovreturn that it is not supported. 220472d3dbb9SYuri PankovThe same should be used for unrecognized statistics. 220572d3dbb9SYuri PankovSee 220652d2369aSRobert Mustacchi.Xr mc_getstat 9E 220752d2369aSRobert Mustacchifor more information on the proper way to handle these. 220852d2369aSRobert Mustacchi.Ss General Device Statistics 220952d2369aSRobert MustacchiThe following statistics are based on MIB-II statistics from both RFC 221052d2369aSRobert Mustacchi1213 and RFC 1573. 221152d2369aSRobert Mustacchi.Bl -tag -width Ds 22122c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_IFSPEED 221352d2369aSRobert MustacchiThe device's current speed in bits per second. 22142c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_MULTIRCV 221552d2369aSRobert MustacchiThe total number of received multicast packets. 22162c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_BRDCSTRCV 221752d2369aSRobert MustacchiThe total number of received broadcast packets. 22182c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_MULTIXMT 221952d2369aSRobert MustacchiThe total number of transmitted multicast packets. 22202c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_BRDCSTXMT 222152d2369aSRobert MustacchiThe total number of received broadcast packets. 22222c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_NORCVBUF 222352d2369aSRobert MustacchiThe total number of packets discarded by the hardware due to a lack of 222452d2369aSRobert Mustacchireceive buffers. 22252c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_IERRORS 222652d2369aSRobert MustacchiThe total number of errors detected on input. 22272c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_UNKNOWNS 222852d2369aSRobert MustacchiThe total number of received packets that were discarded because they 222952d2369aSRobert Mustacchiwere of an unknown protocol. 22302c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_NOXMTBUF 223152d2369aSRobert MustacchiThe total number of outgoing packets dropped due to a lack of transmit 223252d2369aSRobert Mustacchibuffers. 22332c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_OERRORS 223452d2369aSRobert MustacchiThe total number of outgoing packets that resulted in errors. 22352c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_COLLISIONS 223652d2369aSRobert MustacchiTotal number of collisions encountered by the transmitter. 22372c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_RBYTES 22382c0ebdeeSRobert MustacchiThe total number of bytes received by the device, regardless of packet 22392c0ebdeeSRobert Mustacchitype. 22402c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_IPACKETS 22412c0ebdeeSRobert MustacchiThe total number of packets received by the device, regardless of packet type. 22422c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_OBYTES 22432c0ebdeeSRobert MustacchiThe total number of bytes transmitted by the device, regardless of packet type. 22442c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_OPACKETS 22452c0ebdeeSRobert MustacchiThe total number of packets sent by the device, regardless of packet type. 22462c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_UNDERFLOWS 224752d2369aSRobert MustacchiThe total number of packets that were smaller than the minimum sized 224852d2369aSRobert Mustacchipacket for the device and were therefore dropped. 22492c0ebdeeSRobert Mustacchi.It Dv MAC_STAT_OVERFLOWS 225052d2369aSRobert MustacchiThe total number of packets that were larger than the maximum sized 225152d2369aSRobert Mustacchipacket for the device and were therefore dropped. 225252d2369aSRobert Mustacchi.El 225352d2369aSRobert Mustacchi.Ss Ethernet Specific Statistics 225472d3dbb9SYuri PankovThe following statistics are specific to Ethernet devices. 225572d3dbb9SYuri PankovThey refer to values from RFC 1643 and include various MII/GMII specific stats. 225672d3dbb9SYuri PankovMany of these are also defined in IEEE 802.3. 225752d2369aSRobert Mustacchi.Bl -tag -width Ds 22582c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_1000FDX 225952d2369aSRobert MustacchiIndicates that the device is advertising support for 1 Gbit/s 226052d2369aSRobert Mustacchifull-duplex operation. 22612c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_1000HDX 226252d2369aSRobert MustacchiIndicates that the device is advertising support for 1 Gbit/s 226352d2369aSRobert Mustacchihalf-duplex operation. 22642c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_100FDX 226552d2369aSRobert MustacchiIndicates that the device is advertising support for 100 Mbit/s 226652d2369aSRobert Mustacchifull-duplex operation. 22672c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_100GFDX 226852d2369aSRobert MustacchiIndicates that the device is advertising support for 100 Gbit/s 226952d2369aSRobert Mustacchifull-duplex operation. 22702c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_100HDX 227152d2369aSRobert MustacchiIndicates that the device is advertising support for 100 Mbit/s 227252d2369aSRobert Mustacchihalf-duplex operation. 22732c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_100T4 227452d2369aSRobert MustacchiIndicates that the device is advertising support for 100 Mbit/s 227552d2369aSRobert Mustacchi100BASE-T4 operation. 22762c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_10FDX 227752d2369aSRobert MustacchiIndicates that the device is advertising support for 10 Mbit/s 227852d2369aSRobert Mustacchifull-duplex operation. 22792c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_10GFDX 228052d2369aSRobert MustacchiIndicates that the device is advertising support for 10 Gbit/s 228152d2369aSRobert Mustacchifull-duplex operation. 22822c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_10HDX 228352d2369aSRobert MustacchiIndicates that the device is advertising support for 10 Mbit/s 228452d2369aSRobert Mustacchihalf-duplex operation. 22852c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_2500FDX 228652d2369aSRobert MustacchiIndicates that the device is advertising support for 2.5 Gbit/s 228752d2369aSRobert Mustacchifull-duplex operation. 22882c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_40GFDX 228952d2369aSRobert MustacchiIndicates that the device is advertising support for 40 Gbit/s 229052d2369aSRobert Mustacchifull-duplex operation. 22912c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_5000FDX 229252d2369aSRobert MustacchiIndicates that the device is advertising support for 5.0 Gbit/s 229352d2369aSRobert Mustacchifull-duplex operation. 22942c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_ASMPAUSE 229552d2369aSRobert MustacchiIndicates that the device is advertising support for receiving pause 229652d2369aSRobert Mustacchiframes. 22972c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_AUTONEG 229852d2369aSRobert MustacchiIndicates that the device is advertising support for auto-negotiation. 22992c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_CAP_PAUSE 230052d2369aSRobert MustacchiIndicates that the device is advertising support for generating pause 230152d2369aSRobert Mustacchiframes. 23022c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ADV_REMFAULT 230352d2369aSRobert MustacchiIndicates that the device is advertising support for detecting faults in 230452d2369aSRobert Mustacchithe remote link peer. 23052c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_ALIGN_ERRORS 230652d2369aSRobert MustacchiIndicates the number of times an alignment error was generated by the 230772d3dbb9SYuri PankovEthernet device. 230872d3dbb9SYuri PankovThis is a count of packets that were not an integral number of octets and failed 230972d3dbb9SYuri Pankovthe FCS check. 23102c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_1000FDX 231152d2369aSRobert MustacchiIndicates the device supports 1 Gbit/s full-duplex operation. 23122c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_1000HDX 231352d2369aSRobert MustacchiIndicates the device supports 1 Gbit/s half-duplex operation. 23142c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_100FDX 231552d2369aSRobert MustacchiIndicates the device supports 100 Mbit/s full-duplex operation. 23162c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_100GFDX 231752d2369aSRobert MustacchiIndicates the device supports 100 Gbit/s full-duplex operation. 23182c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_100HDX 231952d2369aSRobert MustacchiIndicates the device supports 100 Mbit/s half-duplex operation. 23202c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_100T4 232152d2369aSRobert MustacchiIndicates the device supports 100 Mbit/s 100BASE-T4 operation. 23222c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_10FDX 232352d2369aSRobert MustacchiIndicates the device supports 10 Mbit/s full-duplex operation. 23242c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_10GFDX 232552d2369aSRobert MustacchiIndicates the device supports 10 Gbit/s full-duplex operation. 23262c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_10HDX 232752d2369aSRobert MustacchiIndicates the device supports 10 Mbit/s half-duplex operation. 23282c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_2500FDX 232952d2369aSRobert MustacchiIndicates the device supports 2.5 Gbit/s full-duplex operation. 23302c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_40GFDX 233152d2369aSRobert MustacchiIndicates the device supports 40 Gbit/s full-duplex operation. 23322c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_5000FDX 233352d2369aSRobert MustacchiIndicates the device supports 5.0 Gbit/s full-duplex operation. 23342c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_ASMPAUSE 233552d2369aSRobert MustacchiIndicates that the device supports the ability to receive pause frames. 23362c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_AUTONEG 233752d2369aSRobert MustacchiIndicates that the device supports the ability to perform link 233852d2369aSRobert Mustacchiauto-negotiation. 23392c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_PAUSE 234052d2369aSRobert MustacchiIndicates that the device supports the ability to transmit pause frames. 23412c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CAP_REMFAULT 234252d2369aSRobert MustacchiIndicates that the device supports the ability of detecting a remote 234352d2369aSRobert Mustacchifault in a link peer. 23442c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_CARRIER_ERRORS 234552d2369aSRobert MustacchiIndicates the number of times that the Ethernet carrier sense condition 234652d2369aSRobert Mustacchiwas lost or not asserted. 23472c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_DEFER_XMTS 234852d2369aSRobert MustacchiIndicates the number of frames for which the device was unable to 234952d2369aSRobert Mustacchitransmit the frame due to being busy and had to try again. 23502c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_EX_COLLISIONS 235152d2369aSRobert MustacchiIndicates the number of frames that failed to send due to an excessive 235252d2369aSRobert Mustacchinumber of collisions. 23532c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_FCS_ERRORS 235452d2369aSRobert MustacchiIndicates the number of times that a frame check sequence failed. 23552c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_FIRST_COLLISIONS 235652d2369aSRobert MustacchiIndicates the number of times that a frame was eventually transmitted 235752d2369aSRobert Mustacchisuccessfully, but only after a single collision. 23582c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_JABBER_ERRORS 235952d2369aSRobert MustacchiIndicates the number of frames that were received that were both larger 236052d2369aSRobert Mustacchithan the maximum packet size and failed the frame check sequence. 23612c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LINK_ASMPAUSE 236252d2369aSRobert MustacchiIndicates whether the link is currently configured to accept pause 236352d2369aSRobert Mustacchiframes. 23642c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LINK_AUTONEG 236552d2369aSRobert MustacchiIndicates whether the current link state is a result of 236652d2369aSRobert Mustacchiauto-negotiation. 23672c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LINK_DUPLEX 236872d3dbb9SYuri PankovIndicates the current duplex state of the link. 236972d3dbb9SYuri PankovThe values used here should be the same as documented for 23702c0ebdeeSRobert Mustacchi.Dv MAC_PROP_DUPLEX . 23712c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LINK_PAUSE 237252d2369aSRobert MustacchiIndicates whether the link is currently configured to generate pause 237352d2369aSRobert Mustacchiframes. 23742c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_1000FDX 237552d2369aSRobert MustacchiIndicates the remote device supports 1 Gbit/s full-duplex operation. 23762c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_1000HDX 237752d2369aSRobert MustacchiIndicates the remote device supports 1 Gbit/s half-duplex operation. 23782c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_100FDX 237952d2369aSRobert MustacchiIndicates the remote device supports 100 Mbit/s full-duplex operation. 23802c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_100GFDX 238152d2369aSRobert MustacchiIndicates the remote device supports 100 Gbit/s full-duplex operation. 23822c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_100HDX 238352d2369aSRobert MustacchiIndicates the remote device supports 100 Mbit/s half-duplex operation. 23842c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_100T4 238552d2369aSRobert MustacchiIndicates the remote device supports 100 Mbit/s 100BASE-T4 operation. 23862c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_10FDX 238752d2369aSRobert MustacchiIndicates the remote device supports 10 Mbit/s full-duplex operation. 23882c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_10GFDX 238952d2369aSRobert MustacchiIndicates the remote device supports 10 Gbit/s full-duplex operation. 23902c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_10HDX 239152d2369aSRobert MustacchiIndicates the remote device supports 10 Mbit/s half-duplex operation. 23922c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_2500FDX 239352d2369aSRobert MustacchiIndicates the remote device supports 2.5 Gbit/s full-duplex operation. 23942c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_40GFDX 239552d2369aSRobert MustacchiIndicates the remote device supports 40 Gbit/s full-duplex operation. 23962c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_5000FDX 239752d2369aSRobert MustacchiIndicates the remote device supports 5.0 Gbit/s full-duplex operation. 23982c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_ASMPAUSE 239952d2369aSRobert MustacchiIndicates that the remote device supports the ability to receive pause 240052d2369aSRobert Mustacchiframes. 24012c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_AUTONEG 240252d2369aSRobert MustacchiIndicates that the remote device supports the ability to perform link 240352d2369aSRobert Mustacchiauto-negotiation. 24042c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_PAUSE 240552d2369aSRobert MustacchiIndicates that the remote device supports the ability to transmit pause 240652d2369aSRobert Mustacchiframes. 24072c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_LP_CAP_REMFAULT 240852d2369aSRobert MustacchiIndicates that the remote device supports the ability of detecting a 240952d2369aSRobert Mustacchiremote fault in a link peer. 24102c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_MACRCV_ERRORS 241152d2369aSRobert MustacchiIndicates the number of times that the internal MAC layer encountered an 241252d2369aSRobert Mustacchierror when attempting to receive and process a frame. 24132c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_MACXMT_ERRORS 241452d2369aSRobert MustacchiIndicates the number of times that the internal MAC layer encountered an 241552d2369aSRobert Mustacchierror when attempting to process and transmit a frame. 24162c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_MULTI_COLLISIONS 241752d2369aSRobert MustacchiIndicates the number of times that a frame was eventually transmitted 241852d2369aSRobert Mustacchisuccessfully, but only after more than one collision. 24192c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_SQE_ERRORS 242072d3dbb9SYuri PankovIndicates the number of times that an SQE error occurred. 242172d3dbb9SYuri PankovThe specific conditions for this error are documented in IEEE 802.3. 24222c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_TOOLONG_ERRORS 242352d2369aSRobert MustacchiIndicates the number of frames that were received that were longer than 242452d2369aSRobert Mustacchithe maximum frame size supported by the device. 24252c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_TOOSHORT_ERRORS 242652d2369aSRobert MustacchiIndicates the number of frames that were received that were shorter than 242752d2369aSRobert Mustacchithe minimum frame size supported by the device. 24282c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_TX_LATE_COLLISIONS 242952d2369aSRobert MustacchiIndicates the number of times a collision was detected late on the 243052d2369aSRobert Mustacchidevice. 24312c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_XCVR_ADDR 243252d2369aSRobert MustacchiIndicates the address of the MII/GMII receiver address. 24332c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_XCVR_ID 243452d2369aSRobert MustacchiIndicates the id of the MII/GMII receiver address. 24352c0ebdeeSRobert Mustacchi.It Dv ETHER_STAT_XCVR_INUSE 2436dd72704bSRobert MustacchiIndicates what kind of transceiver is in use. 2437dd72704bSRobert MustacchiUse the 2438dd72704bSRobert Mustacchi.Vt mac_ether_media_t 2439dd72704bSRobert Mustacchienumeration values described in the discussion of 2440dd72704bSRobert Mustacchi.Dv MAC_PROP_MEDIA 2441dd72704bSRobert Mustacchiabove. 2442dd72704bSRobert MustacchiThese definitions are compatible with the older subset of 2443dd72704bSRobert MustacchiXCVR_* macros. 244452d2369aSRobert Mustacchi.El 244552d2369aSRobert Mustacchi.Ss Device Specific kstats 244652d2369aSRobert MustacchiIn addition to the defined statistics above, if the device driver 244752d2369aSRobert Mustacchimaintains additional statistics or the device provides additional 244852d2369aSRobert Mustacchistatistics, it should create its own kstats through the 244952d2369aSRobert Mustacchi.Xr kstat_create 9F 245052d2369aSRobert Mustacchifunction to allow operators to observe them. 24518c732929SRobert Mustacchi.Sh RECEIVE DESCRIPTOR LAYOUT 24528c732929SRobert MustacchiOne of the important things that a device driver must do is lay out DMA 24538c732929SRobert Mustacchimemory, generally in a ring of descriptors, into which received Ethernet 24548c732929SRobert Mustacchiframes will be placed. 24558c732929SRobert MustacchiWhen performing this, there are a few things that drivers should 24568c732929SRobert Mustacchigenerally do: 24578c732929SRobert Mustacchi.Bl -enum -offset indent 24588c732929SRobert Mustacchi.It 24598c732929SRobert MustacchiDrivers should lay out memory so that the IP header will be 4-byte 24608c732929SRobert Mustacchialigned. 24618c732929SRobert MustacchiThe IP stack expects that the beginning of an IP header will be at a 24628c732929SRobert Mustacchi4-byte aligned address; however, a DMA allocation will be at a 4- 24638c732929SRobert Mustacchior 8-byte aligned address by default. 2464496cffd8SPeter TribbleThe IP header is at a 14 byte offset from the beginning of the Ethernet 24658c732929SRobert Mustacchiframe, leaving the IP header at a 2-byte alignment if the Ethernet frame 24668c732929SRobert Mustacchistarts at the beginning of the DMA buffer. 24678c732929SRobert MustacchiIf VLAN tagging is in place, then each VLAN tag adds 4 bytes, which 24688c732929SRobert Mustacchidoesn't change the alignment the IP header is found at. 24698c732929SRobert Mustacchi.Pp 24708c732929SRobert MustacchiAs a solution to this, the driver should program the device to start 24718c732929SRobert Mustacchiplacing the received Ethernet frame at two bytes off of the start of the 24728c732929SRobert MustacchiDMA buffer. 24738c732929SRobert MustacchiThis will make sure that no matter whether or not VLAN tags are present, 24748c732929SRobert Mustacchithat the IP header will be 4-byte aligned. 24758c732929SRobert Mustacchi.It 24768c732929SRobert MustacchiDrivers should try to allocate the DMA memory used for receiving frames 24778c732929SRobert Mustacchias a continuous buffer. 24788c732929SRobert MustacchiIf for some reason that would not be possible, the driver should try to 24798c732929SRobert Mustacchiensure that there is enough space for all of the initial Ethernet and 24808c732929SRobert Mustacchiany possible layer three and layer four headers 24818c732929SRobert Mustacchi.Pq such as IP, TCP, or UDP 24828c732929SRobert Mustacchiin the initial descriptor. 24838c732929SRobert Mustacchi.It 24848c732929SRobert MustacchiAs discussed in the 24858c732929SRobert Mustacchi.Sx MBLKS AND DMA 24868c732929SRobert Mustacchisection, there are multiple strategies for managing the relationship 24878c732929SRobert Mustacchibetween DMA data, receive descriptors, and the operating system 24888c732929SRobert Mustacchirepresentation of a packet in the 24898c732929SRobert Mustacchi.Xr mblk 9S 24908c732929SRobert Mustacchistructure. 24918c732929SRobert MustacchiDrivers must limit their resource consumption. 24928c732929SRobert MustacchiSee the 24938c732929SRobert Mustacchi.Sy Considerations 24948c732929SRobert Mustacchisection of 24958c732929SRobert Mustacchi.Sx MBLKS AND DMA 24968c732929SRobert Mustacchifor more on this. 24978c732929SRobert Mustacchi.El 249852d2369aSRobert Mustacchi.Sh TX STALL DETECTION, DEVICE RESETS, AND FAULT MANAGEMENT 249952d2369aSRobert MustacchiDevice drivers are the first line of defense for dealing with broken 250072d3dbb9SYuri Pankovdevices and bugs in their firmware. 250172d3dbb9SYuri PankovWhile most devices will rarely fail, it is important that when designing and 250272d3dbb9SYuri Pankovimplementing the device driver that particular attention is paid in the design 250372d3dbb9SYuri Pankovwith respect to RAS (Reliability, Availability, and Serviceability). 250472d3dbb9SYuri PankovWhile everything described in this section is optional, it is highly recommended 250572d3dbb9SYuri Pankovthat all new device drivers follow these guidelines. 250652d2369aSRobert Mustacchi.Pp 250752d2369aSRobert MustacchiThe Fault Management Architecture (FMA) provides facilities for 250852d2369aSRobert Mustacchidetecting and reporting various classes of defects and faults. 250952d2369aSRobert MustacchiSpecifically for networking device drivers, issues that should be 251052d2369aSRobert Mustacchidetected and reported include: 251152d2369aSRobert Mustacchi.Bl -bullet -offset indent 251252d2369aSRobert Mustacchi.It 251352d2369aSRobert MustacchiDevice internal uncorrectable errors 251452d2369aSRobert Mustacchi.It 251552d2369aSRobert MustacchiDevice internal correctable errors 251652d2369aSRobert Mustacchi.It 251752d2369aSRobert MustacchiPCI and PCI Express transport errors 251852d2369aSRobert Mustacchi.It 251952d2369aSRobert MustacchiDevice temperature alarms 252052d2369aSRobert Mustacchi.It 252152d2369aSRobert MustacchiDevice transmission stalls 252252d2369aSRobert Mustacchi.It 252352d2369aSRobert MustacchiDevice communication timeouts 252452d2369aSRobert Mustacchi.It 252552d2369aSRobert MustacchiHigh invalid interrupts 252652d2369aSRobert Mustacchi.El 252752d2369aSRobert Mustacchi.Pp 252852d2369aSRobert MustacchiAll such errors fall into three primary categories: 252952d2369aSRobert Mustacchi.Bl -enum -offset indent 253052d2369aSRobert Mustacchi.It 253152d2369aSRobert MustacchiErrors detected by the Fault Management Architecture 253252d2369aSRobert Mustacchi.It 253352d2369aSRobert MustacchiErrors detected by the device and indicated to the device driver 253452d2369aSRobert Mustacchi.It 253552d2369aSRobert MustacchiErrors detected by the device driver 253652d2369aSRobert Mustacchi.El 253752d2369aSRobert Mustacchi.Ss Fault Management Setup and Teardown 253852d2369aSRobert MustacchiDrivers should initialize support for the fault management framework by 253952d2369aSRobert Mustacchicalling 254052d2369aSRobert Mustacchi.Xr ddi_fm_init 9F 254152d2369aSRobert Mustacchifrom their 254252d2369aSRobert Mustacchi.Xr attach 9E 254372d3dbb9SYuri Pankovroutine. 254472d3dbb9SYuri PankovBy registering with the fault management framework, a device driver is given the 254572d3dbb9SYuri Pankovchance to detect and notice transport errors as well as report other errors that 254672d3dbb9SYuri Pankovexist. 254772d3dbb9SYuri PankovWhile a device driver does not need to indicate that it is capable of all such 254872d3dbb9SYuri Pankovcapabilities described in 254952d2369aSRobert Mustacchi.Xr ddi_fm_init 9F , 255052d2369aSRobert Mustacchiwe suggest that device drivers at least register the 25512c0ebdeeSRobert Mustacchi.Dv DDI_FM_EREPORT_CAPABLE 255252d2369aSRobert Mustacchiso as to allow the driver to report issues that it detects. 255352d2369aSRobert Mustacchi.Pp 255452d2369aSRobert MustacchiIf the driver registers with the fault management framework during its 255552d2369aSRobert Mustacchi.Xr attach 9E 255652d2369aSRobert Mustacchientry point, it must call 2557b31ca922SChris Fraire.Xr ddi_fm_fini 9F 255852d2369aSRobert Mustacchiduring its 255952d2369aSRobert Mustacchi.Xr detach 9E 256052d2369aSRobert Mustacchientry point. 256152d2369aSRobert Mustacchi.Ss Transport Errors 256272d3dbb9SYuri PankovMany modern networking devices leverage PCI or PCI Express. 256372d3dbb9SYuri PankovAs such, there are two primary ways that device drivers access data: they either 256452d2369aSRobert Mustacchimemory map device registers and use routines like 256552d2369aSRobert Mustacchi.Xr ddi_get8 9F 256652d2369aSRobert Mustacchiand 256752d2369aSRobert Mustacchi.Xr ddi_put8 9F 256872d3dbb9SYuri Pankovor they use direct memory access (DMA). 256972d3dbb9SYuri PankovNew device drivers should always enable checking of the transport layer by 257072d3dbb9SYuri Pankovmarking their support in the 2571b31ca922SChris Fraire.Xr ddi_device_acc_attr 9S 257252d2369aSRobert Mustacchistructure and using routines like 257352d2369aSRobert Mustacchi.Xr ddi_fm_acc_err_get 9F 257452d2369aSRobert Mustacchiand 257552d2369aSRobert Mustacchi.Xr ddi_fm_dma_err_get 9F 257652d2369aSRobert Mustacchito detect if errors have occurred. 257752d2369aSRobert Mustacchi.Ss Device Indicated Errors 257852d2369aSRobert MustacchiMany devices have capabilities to announce to a device driver that a 257972d3dbb9SYuri Pankovfatal correctable error or uncorrectable error has occurred. 258072d3dbb9SYuri PankovOther devices have the ability to indicate that various physical issues have 258152d2369aSRobert Mustacchioccurred such as a fan failing or a temperature sensor having fired. 258252d2369aSRobert Mustacchi.Pp 258352d2369aSRobert MustacchiDrivers should wire themselves to receive notifications when these 258472d3dbb9SYuri Pankovevents occur. 258572d3dbb9SYuri PankovThe means and capabilities will vary from device to device. 258672d3dbb9SYuri PankovFor example, some devices will generate information about these notifications 258772d3dbb9SYuri Pankovthrough special interrupts. 258872d3dbb9SYuri PankovOther devices may have a register that software can poll. 258972d3dbb9SYuri PankovIn the cases where polling is required, driver writers should try not to poll 259072d3dbb9SYuri Pankovtoo frequently and should generally only poll when the device is actively being 259172d3dbb9SYuri Pankovused, e.g. between calls to the 259252d2369aSRobert Mustacchi.Xr mc_start 9E 259352d2369aSRobert Mustacchiand 259452d2369aSRobert Mustacchi.Xr mc_stop 9E 259552d2369aSRobert Mustacchientry points. 259652d2369aSRobert Mustacchi.Ss Driver Transmit Stall Detection 259752d2369aSRobert MustacchiOne of the primary responsibilities of a hardened device driver is to 259872d3dbb9SYuri Pankovperform transmit stall detection. 259972d3dbb9SYuri PankovThe core idea behind tx stall detection is that the driver should record when 260072d3dbb9SYuri Pankovit's getting activity related to when data has been successfully transmitted. 260172d3dbb9SYuri PankovMost devices should be transmitting data on a regular basis as long as the link 260272d3dbb9SYuri Pankovis up. 260372d3dbb9SYuri PankovIf it is not, then this may indicate that the device is stuck and needs to be 260472d3dbb9SYuri Pankovreset. 260572d3dbb9SYuri PankovAt this time, the MAC framework does not provide any resources for performing 260672d3dbb9SYuri Pankovthese checks; however, polling on each individual transmit ring for the last 260772d3dbb9SYuri Pankovcompletion time while something is actively being transmitted through the use of 260872d3dbb9SYuri Pankovroutines such as 260952d2369aSRobert Mustacchi.Xr timeout 9F 261052d2369aSRobert Mustacchimay be a reasonable starting point. 261152d2369aSRobert Mustacchi.Ss Driver Command Timeout Detection 261272d3dbb9SYuri PankovEach device is programmed in different ways. 261372d3dbb9SYuri PankovSome devices are programmed through asynchronous commands while others are 261472d3dbb9SYuri Pankovprogrammed by writing directly to memory mapped registers. 261572d3dbb9SYuri PankovIf a device receives asynchronous replies to commands, then the device driver 261672d3dbb9SYuri Pankovshould set reasonable timeouts for all such commands and plan on detecting them. 261772d3dbb9SYuri PankovIf a timeout occurs, the driver should presume that there is an issue with the 261852d2369aSRobert Mustacchihardware and proceed to abort the command or reset the device. 261952d2369aSRobert Mustacchi.Pp 262072d3dbb9SYuri PankovMany devices do not have such a communication mechanism. 262172d3dbb9SYuri PankovHowever, whenever there is some activity where the device driver must wait, then 262252d2369aSRobert Mustacchiit should be prepared for the fact that the device may never get back to 262352d2369aSRobert Mustacchiit and react appropriately by performing some kind of device reset. 262452d2369aSRobert Mustacchi.Ss Reacting to Errors 262552d2369aSRobert MustacchiWhen any of the above categories of errors has been triggered, the 262652d2369aSRobert Mustacchibehavior that the device driver should take depends on the kind of 262772d3dbb9SYuri Pankoverror. 262872d3dbb9SYuri PankovIf a fatal error, for example, a transport error, a transmit stall was detected, 262972d3dbb9SYuri Pankovor the device indicated an uncorrectable error was detected, then it is 263052d2369aSRobert Mustacchiimportant that the driver take the following steps: 263152d2369aSRobert Mustacchi.Bl -enum -offset indent 263252d2369aSRobert Mustacchi.It 263352d2369aSRobert MustacchiSet a flag in the device driver's state that indicates that it has hit 263472d3dbb9SYuri Pankovan error condition. 263572d3dbb9SYuri PankovWhen this error condition flag is asserted, transmitted packets should be 263672d3dbb9SYuri Pankovaccepted and dropped and actions that would require writing to the device state 263772d3dbb9SYuri Pankovshould fail with an error. 263872d3dbb9SYuri PankovThis flag should remain until the device has been successfully restarted. 263952d2369aSRobert Mustacchi.It 264052d2369aSRobert MustacchiIf the error was not a transport error that was indicated by the fault 264152d2369aSRobert Mustacchimanagement architecture, e.g. a transport error that was detected, then 264252d2369aSRobert Mustacchithe device driver should post an 264352d2369aSRobert Mustacchi.Sy ereport 264452d2369aSRobert Mustacchiindicating what has occurred with the 264552d2369aSRobert Mustacchi.Xr ddi_fm_ereport_post 9F 264652d2369aSRobert Mustacchifunction. 264752d2369aSRobert Mustacchi.It 264852d2369aSRobert MustacchiThe device driver should indicate that the device's service was lost 264952d2369aSRobert Mustacchiwith a call to 265052d2369aSRobert Mustacchi.Xr ddi_fm_service_impact 9F 265152d2369aSRobert Mustacchiusing the symbol 26522c0ebdeeSRobert Mustacchi.Dv DDI_SERVICE_LOST . 265352d2369aSRobert Mustacchi.It 265452d2369aSRobert MustacchiAt this point the device driver should issue a device reset through some 265552d2369aSRobert Mustacchidevice-specific means. 265652d2369aSRobert Mustacchi.It 265752d2369aSRobert MustacchiWhen the device reset has been completed, then the device driver should 265872d3dbb9SYuri Pankovrestore all of the programmed state to the device. 265972d3dbb9SYuri PankovThis includes things like the current MTU, advertised auto-negotiation speeds, 266072d3dbb9SYuri PankovMAC address filters, and more. 266152d2369aSRobert Mustacchi.It 266252d2369aSRobert MustacchiFinally, when service has been restored, the device driver should call 266352d2369aSRobert Mustacchi.Xr ddi_fm_service_impact 9F 266452d2369aSRobert Mustacchiusing the symbol 26652c0ebdeeSRobert Mustacchi.Dv DDI_SERVICE_RESTORED . 266652d2369aSRobert Mustacchi.El 266752d2369aSRobert Mustacchi.Pp 266852d2369aSRobert MustacchiWhen a non-fatal error occurs, then the device driver should submit an 266952d2369aSRobert Mustacchiereport and should optionally mark the device degraded using 267052d2369aSRobert Mustacchi.Xr ddi_fm_service_impact 9F 267152d2369aSRobert Mustacchiwith the 26722c0ebdeeSRobert Mustacchi.Dv DDI_SERVICE_DEGRADED 267352d2369aSRobert Mustacchivalue depending on the nature of the problem that has occurred. 267452d2369aSRobert Mustacchi.Pp 267552d2369aSRobert MustacchiDevice drivers should never make the decision to remove a device from 267652d2369aSRobert Mustacchiservice based on errors that have occurred nor should they panic the 267772d3dbb9SYuri Pankovsystem. 267872d3dbb9SYuri PankovRather, the device driver should always try to notify the operating system with 267972d3dbb9SYuri Pankovvarious ereports and allow its policy decisions to occur. 268072d3dbb9SYuri PankovThe decision to retire a device lies in the hands of the fault management 268172d3dbb9SYuri Pankovarchitecture. 268272d3dbb9SYuri PankovIt knows more about the operator's intent and the surrounding system's state 268372d3dbb9SYuri Pankovthan the device driver itself does and it will make the call to offline and 268472d3dbb9SYuri Pankovretire the device if it is required. 268552d2369aSRobert Mustacchi.Ss Device Resets 268672d3dbb9SYuri PankovWhen resetting a device, a device driver must exercise caution. 268772d3dbb9SYuri PankovIf a device driver has not been written to plan for a device reset, then it 268872d3dbb9SYuri Pankovmay not correctly restore the device's state after such a reset. 268972d3dbb9SYuri PankovSuch state should be stored in the instance's private state data as the MAC 269052d2369aSRobert Mustacchiframework does not know about device resets and will not inform the 269152d2369aSRobert Mustacchidevice again about the expected, programmed state. 269252d2369aSRobert Mustacchi.Pp 269352d2369aSRobert MustacchiOne wrinkle with device resets is that many networking cards show up as 269452d2369aSRobert Mustacchimultiple PCI functions on a single device, for example, each port may 269552d2369aSRobert Mustacchishow up as a separate function and thus have a separate instance of the 269672d3dbb9SYuri Pankovdevice driver attached. 269772d3dbb9SYuri PankovWhen resetting a function, device driver writers should carefully read the 269872d3dbb9SYuri Pankovdevice programming manuals and verify whether or not a reset impacts only the 269972d3dbb9SYuri Pankovstalled function or if it impacts all function across the device. 270052d2369aSRobert Mustacchi.Pp 270152d2369aSRobert MustacchiIf the only way to reset a given function is through the device, then 270252d2369aSRobert Mustacchithis may require more coordination and work on the part of the device 270352d2369aSRobert Mustacchidriver to ensure that all the other instances are correctly restored. 270452d2369aSRobert MustacchiIn cases where this occurs, some devices offer ways of injecting 270552d2369aSRobert Mustacchiinterrupts onto those other functions to notify them that this is 270652d2369aSRobert Mustacchioccurring. 270752d2369aSRobert Mustacchi.Sh MBLKS AND DMA 270852d2369aSRobert MustacchiThe networking stack manages framed data through the use of the 270952d2369aSRobert Mustacchi.Xr mblk 9S 271072d3dbb9SYuri Pankovstructure. 271172d3dbb9SYuri PankovThe mblk allows for a single message to be made up of individual blocks. 271272d3dbb9SYuri PankovEach part is linked together through its 27132c0ebdeeSRobert Mustacchi.Fa b_cont 271472d3dbb9SYuri Pankovmember. 271572d3dbb9SYuri PankovHowever, it also allows for multiple messages to be chained together through the 271672d3dbb9SYuri Pankovuse of the 27172c0ebdeeSRobert Mustacchi.Fa b_next 271872d3dbb9SYuri Pankovmember. 271972d3dbb9SYuri PankovWhile the networking stack works with these structures, device drivers generally 272072d3dbb9SYuri Pankovwork with DMA regions. 272172d3dbb9SYuri PankovThere are two different strategies that device drivers use for handling these 272272d3dbb9SYuri Pankovtwo different cases: copying and binding. 272352d2369aSRobert Mustacchi.Ss Copying Data 272452d2369aSRobert MustacchiThe first way that device drivers handle interfacing between the two is 272572d3dbb9SYuri Pankovby having two separate regions of memory. 272672d3dbb9SYuri PankovOne part is memory which has been allocated for DMA through a call to 2727b31ca922SChris Fraire.Xr ddi_dma_mem_alloc 9F 272852d2369aSRobert Mustacchiand the other is memory associated with the memory block. 272952d2369aSRobert Mustacchi.Pp 273052d2369aSRobert MustacchiIn this case, a driver will use 273152d2369aSRobert Mustacchi.Xr bcopy 9F 273272d3dbb9SYuri Pankovto copy memory between the two distinct regions. 273372d3dbb9SYuri PankovWhen transmitting a packet, it will copy the memory from the mblk_t to the DMA 273472d3dbb9SYuri Pankovregion. 273572d3dbb9SYuri PankovWhen receiving memory, it will allocate a mblk_t through the 273652d2369aSRobert Mustacchi.Xr allocb 9F 273752d2369aSRobert Mustacchiroutine, copy the memory across with 273852d2369aSRobert Mustacchi.Xr bcopy 9F , 273952d2369aSRobert Mustacchiand then increment the mblk_t's 27402c0ebdeeSRobert Mustacchi.Fa b_wptr 274152d2369aSRobert Mustacchistructure. 274252d2369aSRobert Mustacchi.Pp 274352d2369aSRobert MustacchiIf, when receiving, memory is not available for a new message block, 274472d3dbb9SYuri Pankovthen the frame should be skipped and effectively dropped. 274572d3dbb9SYuri PankovA kstat should be bumped when such an occasion occurs. 274652d2369aSRobert Mustacchi.Ss Binding Data 274772d3dbb9SYuri PankovAn alternative approach to copying data is to use DMA binding. 274872d3dbb9SYuri PankovWhen using DMA binding, the OS takes care of mapping between DMA memory and 274972d3dbb9SYuri Pankovnormal device memory. 275072d3dbb9SYuri PankovThe exact process is a bit different between transmit and receive. 275152d2369aSRobert Mustacchi.Pp 275252d2369aSRobert MustacchiWhen transmitting a device driver has an mblk_t and needs to call the 275352d2369aSRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 275472d3dbb9SYuri Pankovfunction to bind it to an already existing DMA handle. 275572d3dbb9SYuri PankovAt that point, it will receive various DMA cookies that it can use to obtain the 275672d3dbb9SYuri Pankovaddresses to program the device with for transmitting data. 275772d3dbb9SYuri PankovOnce the transmit is done, the driver must then make sure to call 275852d2369aSRobert Mustacchi.Xr freemsg 9F 275972d3dbb9SYuri Pankovto release the data. 276072d3dbb9SYuri PankovIt must not call 276152d2369aSRobert Mustacchi.Xr freemsg 9F 276252d2369aSRobert Mustacchibefore it receives an interrupt from the device indicating that the data 276352d2369aSRobert Mustacchihas been transmitted, otherwise it risks sending arbitrary kernel 276452d2369aSRobert Mustacchimemory. 276552d2369aSRobert Mustacchi.Pp 276672d3dbb9SYuri PankovWhen receiving data, the device can perform a similar operation. 276772d3dbb9SYuri PankovFirst, it must bind the DMA memory into the kernel's virtual memory address 276852d2369aSRobert Mustacchispace through a call to the 276952d2369aSRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 277072d3dbb9SYuri Pankovfunction if it has not already. 277172d3dbb9SYuri PankovOnce it has, it must then call 277252d2369aSRobert Mustacchi.Xr desballoc 9F 277372d3dbb9SYuri Pankovto try and create a new mblk_t which leverages the associated memory. 277472d3dbb9SYuri PankovIt can then pass that mblk_t up to the stack. 277552d2369aSRobert Mustacchi.Ss Considerations 277652d2369aSRobert MustacchiWhen deciding which of these options to use, there are many different 277772d3dbb9SYuri Pankovconsiderations that must be made. 277872d3dbb9SYuri PankovThe answer as to whether to bind memory or to copy data is not always simpler. 277952d2369aSRobert Mustacchi.Pp 278052d2369aSRobert MustacchiThe first thing to remember is that DMA resources may be finite on a 278172d3dbb9SYuri Pankovgiven platform. 278272d3dbb9SYuri PankovConsider the case of receiving data. 278372d3dbb9SYuri PankovA device driver that binds one of its receive descriptors may not get it back 278472d3dbb9SYuri Pankovfor quite some time as it may be used by the kernel until an application 278572d3dbb9SYuri Pankovactually consumes it. 278672d3dbb9SYuri PankovDevice drivers that try to bind memory for receive, often work with the 278772d3dbb9SYuri Pankovconstraint that they must be able to replace that DMA memory with another DMA 278872d3dbb9SYuri Pankovdescriptor. 278972d3dbb9SYuri PankovIf they were not replaced, then eventually the device would not be able to 279072d3dbb9SYuri Pankovreceive additional data into the ring. 279152d2369aSRobert Mustacchi.Pp 279252d2369aSRobert MustacchiOn the other hand, particularly for larger frames, copying every packet 279352d2369aSRobert Mustacchifrom one buffer to another can be a source of additional latency and 279472d3dbb9SYuri Pankovmemory waste in the system. 279572d3dbb9SYuri PankovFor larger copies, the cost of copying may dwarf any potential cost of 279672d3dbb9SYuri Pankovperforming DMA binding. 279752d2369aSRobert Mustacchi.Pp 279852d2369aSRobert MustacchiFor device driver authors that are unsure of what to do, they should 279952d2369aSRobert Mustacchifirst employ the copying method to simplify the act of writing the 280072d3dbb9SYuri Pankovdevice driver. 280172d3dbb9SYuri PankovThe copying method is simpler and also allows the device driver author not to 280272d3dbb9SYuri Pankovworry about allocated DMA memory that is still outstanding when it is asked to 280372d3dbb9SYuri Pankovunload. 280452d2369aSRobert Mustacchi.Pp 280552d2369aSRobert MustacchiIf device driver writers are worried about the cost, it is recommended 280652d2369aSRobert Mustacchito make the decision as to whether or not to copy or bind DMA data 280772d3dbb9SYuri Pankova separate private property for both transmitting and receiving. 280872d3dbb9SYuri PankovThat private property should indicate the size of the received frame at which 280972d3dbb9SYuri Pankovto switch from one format to the other. 281072d3dbb9SYuri PankovThis way, data can be gathered to determine what the impact of each method is on 281172d3dbb9SYuri Pankova given platform. 281252d2369aSRobert Mustacchi.Sh SEE ALSO 2813bbf21555SRichard Lowe.Xr dlpi 4P , 2814bbf21555SRichard Lowe.Xr driver.conf 5 , 2815bbf21555SRichard Lowe.Xr ieee802.3 7 , 2816bbf21555SRichard Lowe.Xr dladm 8 , 281752d2369aSRobert Mustacchi.Xr _fini 9E , 281852d2369aSRobert Mustacchi.Xr _info 9E , 281952d2369aSRobert Mustacchi.Xr _init 9E , 282052d2369aSRobert Mustacchi.Xr attach 9E , 282152d2369aSRobert Mustacchi.Xr close 9E , 282252d2369aSRobert Mustacchi.Xr detach 9E , 28232c0ebdeeSRobert Mustacchi.Xr mac_capab_led 9E , 28242c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E , 28252c0ebdeeSRobert Mustacchi.Xr mac_capab_transceiver 9E , 282652d2369aSRobert Mustacchi.Xr mc_close 9E , 282752d2369aSRobert Mustacchi.Xr mc_getcapab 9E , 282852d2369aSRobert Mustacchi.Xr mc_getprop 9E , 282952d2369aSRobert Mustacchi.Xr mc_getstat 9E , 283052d2369aSRobert Mustacchi.Xr mc_multicst 9E , 283152d2369aSRobert Mustacchi.Xr mc_open 9E , 283252d2369aSRobert Mustacchi.Xr mc_propinfo 9E , 283352d2369aSRobert Mustacchi.Xr mc_setpromisc 9E , 283452d2369aSRobert Mustacchi.Xr mc_setprop 9E , 283552d2369aSRobert Mustacchi.Xr mc_start 9E , 283652d2369aSRobert Mustacchi.Xr mc_stop 9E , 283752d2369aSRobert Mustacchi.Xr mc_tx 9E , 283852d2369aSRobert Mustacchi.Xr mc_unicst 9E , 283952d2369aSRobert Mustacchi.Xr open 9E , 284052d2369aSRobert Mustacchi.Xr allocb 9F , 284152d2369aSRobert Mustacchi.Xr bcopy 9F , 284252d2369aSRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F , 2843b31ca922SChris Fraire.Xr ddi_dma_mem_alloc 9F , 284452d2369aSRobert Mustacchi.Xr ddi_fm_acc_err_get 9F , 284552d2369aSRobert Mustacchi.Xr ddi_fm_dma_err_get 9F , 284652d2369aSRobert Mustacchi.Xr ddi_fm_ereport_post 9F , 284752d2369aSRobert Mustacchi.Xr ddi_fm_fini 9F , 284852d2369aSRobert Mustacchi.Xr ddi_fm_init 9F , 284952d2369aSRobert Mustacchi.Xr ddi_fm_service_impact 9F , 285052d2369aSRobert Mustacchi.Xr ddi_get8 9F , 285152d2369aSRobert Mustacchi.Xr ddi_put8 9F , 285252d2369aSRobert Mustacchi.Xr desballoc 9F , 285352d2369aSRobert Mustacchi.Xr freemsg 9F , 285452d2369aSRobert Mustacchi.Xr kstat_create 9F , 285552d2369aSRobert Mustacchi.Xr mac_alloc 9F , 285686e5bb79SLuqman Aden.Xr mac_devt_to_instance 9F , 285752d2369aSRobert Mustacchi.Xr mac_fini_ops 9F , 28588c732929SRobert Mustacchi.Xr mac_free 9F , 285986e5bb79SLuqman Aden.Xr mac_getinfo 9F , 286052d2369aSRobert Mustacchi.Xr mac_hcksum_get 9F , 286152d2369aSRobert Mustacchi.Xr mac_hcksum_set 9F , 286252d2369aSRobert Mustacchi.Xr mac_init_ops 9F , 286352d2369aSRobert Mustacchi.Xr mac_link_update 9F , 286452d2369aSRobert Mustacchi.Xr mac_lso_get 9F , 286552d2369aSRobert Mustacchi.Xr mac_maxsdu_update 9F , 286686e5bb79SLuqman Aden.Xr mac_private_minor 9F , 286752d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_link_flowctrl 9F , 286852d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_str 9F , 286952d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint32 9F , 287052d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint64 9F , 287152d2369aSRobert Mustacchi.Xr mac_prop_info_set_default_uint8 9F , 287252d2369aSRobert Mustacchi.Xr mac_prop_info_set_perm 9F , 287352d2369aSRobert Mustacchi.Xr mac_prop_info_set_range_uint32 9F , 287452d2369aSRobert Mustacchi.Xr mac_register 9F , 287552d2369aSRobert Mustacchi.Xr mac_rx 9F , 287652d2369aSRobert Mustacchi.Xr mac_unregister 9F , 287752d2369aSRobert Mustacchi.Xr mod_install 9F , 287852d2369aSRobert Mustacchi.Xr mod_remove 9F , 287952d2369aSRobert Mustacchi.Xr strcmp 9F , 288052d2369aSRobert Mustacchi.Xr timeout 9F , 288152d2369aSRobert Mustacchi.Xr cb_ops 9S , 2882b31ca922SChris Fraire.Xr ddi_device_acc_attr 9S , 288352d2369aSRobert Mustacchi.Xr dev_ops 9S , 288452d2369aSRobert Mustacchi.Xr mac_callbacks 9S , 288552d2369aSRobert Mustacchi.Xr mac_register 9S , 288652d2369aSRobert Mustacchi.Xr mblk 9S , 288752d2369aSRobert Mustacchi.Xr modldrv 9S , 288852d2369aSRobert Mustacchi.Xr modlinkage 9S 288952d2369aSRobert Mustacchi.Rs 289052d2369aSRobert Mustacchi.%A McCloghrie, K. 289152d2369aSRobert Mustacchi.%A Rose, M. 289252d2369aSRobert Mustacchi.%T RFC 1213 Management Information Base for Network Management of 289352d2369aSRobert Mustacchi.%T TCP/IP-based internets: MIB-II 289452d2369aSRobert Mustacchi.%D March 1991 289552d2369aSRobert Mustacchi.Re 289652d2369aSRobert Mustacchi.Rs 289752d2369aSRobert Mustacchi.%A McCloghrie, K. 289852d2369aSRobert Mustacchi.%A Kastenholz, F. 289952d2369aSRobert Mustacchi.%T RFC 1573 Evolution of the Interfaces Group of MIB-II 290052d2369aSRobert Mustacchi.%D January 1994 290152d2369aSRobert Mustacchi.Re 290252d2369aSRobert Mustacchi.Rs 290352d2369aSRobert Mustacchi.%A Kastenholz, F. 290452d2369aSRobert Mustacchi.%T RFC 1643 Definitions of Managed Objects for the Ethernet-like 290552d2369aSRobert Mustacchi.%T Interface Types 290652d2369aSRobert Mustacchi.Re 2907dd72704bSRobert Mustacchi.Rs 2908dd72704bSRobert Mustacchi.%A IEEE Computer Standard 2909dd72704bSRobert Mustacchi.%T IEEE 802.3 2910dd72704bSRobert Mustacchi.%T IEEE Standard for Ethernet 2911dd72704bSRobert Mustacchi.%D 2022 2912dd72704bSRobert Mustacchi.Re 2913