1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2017, Joyent, Inc. 13.\" 14.Dd February 15, 2020 15.Dt MAC_CAPAB_TRANSCEIVER 9E 16.Os 17.Sh NAME 18.Nm mac_capab_transceiver , 19.Nm mct_info , 20.Nm mct_read 21.Nd MAC capability for networking transceivers 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Vt typedef struct mac_capab_transceiver mac_capab_transceiver_t; 25.Ft int 26.Fo "mct_info" 27.Fa "void *driver" 28.Fa "uint_t id" 29.Fa "mac_transceiver_info_t *infop" 30.Fc 31.Ft int 32.Fo mct_read 33.Fa "void *driver" 34.Fa "uint_t id" 35.Fa "uint_t page" 36.Fa "void *buf" 37.Fa "size_t nbytes" 38.Fa "off_t offset" 39.Fa "size_t *nread" 40.Fc 41.Sh INTERFACE LEVEL 42.Sy Volatile - 43This interface is still evolving in illumos. 44API and ABI stability is 45not guaranteed. 46.Sh PARAMETERS 47.Bl -tag -width Fa 48.It Fa driver 49A pointer to the driver's private data that was passed in via the 50.Sy m_pdata 51member of the 52.Xr mac_register 9S 53structure to the 54.Xr mac_register 9F 55function. 56.It Fa id 57An integer value indicating which transceiver is being inquired about. 58.It Fa infop 59An opaque structure which is used to set information about the 60transceiver. 61.It Fa page 62A value that indicates which page from the i2c bus is being requested. 63.It Fa buf 64A pointer to which data should be written to when reading from the 65device. 66.It Fa nbytes 67A value indicating the number of bytes being asked to read into 68.Fa buf . 69.It Fa offset 70A value indicating the offset into the page to start reading data. 71.It Fa nread 72A value to be updated by the driver with the number of successfully read 73bytes. 74.El 75.Sh DESCRIPTION 76The 77.Sy MAC_CAPAB_TRANSCEIVER 78capability allows for GLDv3 networking device drivers to provide 79information to the system about their transceiver. 80Implementing this capability is optional. 81For more information on how to handle capabilities and how to indicate 82that a capability is not supported, see 83.Xr mc_getcapab 9E . 84.Pp 85This capability should be implemented if the device in question supports 86a Small Form Factor (SFF) transceiver. 87These are more commonly known by names such as SFP, SFP+, SFP28, QSFP+, 88and QSFP28. 89This interface does not apply to traditional copper Ethernet phys. 90These transceivers provide standardized information over the i2c bus at 91specific pages. 92.Ss Supported Standards 93.Bl -tag -width Sy 94.It Sy INF-8074 95The 96.Sy INF-8084 97standard was the original multiple source agreement (MSA) for SFP 98devices. 99It proposed the original series of management pages at i2c page 0xa0. 100This page contained up to 512 bytes, however, only the first 10196 bytes are standardized. 102Bytes 97 to 127 are reserved for the vendor. 103The remaining bytes are reserved by the specification. 104The management page was subsequently adopted by SFP+ devices. 105.It Sy SFF-8472 106The 107.Sy SFF-8472 108standard extended the original SFP MSA. 109This standard added a second i2c page at 0xa2, while maintaining the 110original page at 0xa0. 111The page at 0xa0 is now explicitly 256 bytes. 112The page at 0xa2 is also 256 bytes. 113This standard was also adopted for all SFP28 parts, which are commonly 114used in transceivers for 25 Gb/s Ethernet. 115.It Sy SFF-8436 116The 117.Sy SFF-8436 118standard was developed for QSFP+ transceivers, which involve the 119bonding of 4 SFP+ links. 120QSFP+ is commonly used in the transceivers for 40 Gb/s Ethernet. 121This standard uses i2c page 0xa0 for read-only identification purposes. 122The lower half of the page is used for control, while the upper 128 123bytes is similar to the 124.Sy INF-8084 125and 126.Sy SFF-8472 127standards. 128.It Sy SFF-8636 129The 130.Sy SFF-8636 131standard is a common management standard which is shared between both 132SAS and QSFP+ 28 Gb/s transceivers. 133The latter transceiver is commonly found in 100 Gb/s Ethernet. 134The transceiver's memory map is similar to that found in the 135.Sy SFF-8436 136specification. 137The identification information is found in the upper 128 138bytes of page 0xa0, while the lower part of the page is used for 139control, among other purposes. 140.El 141.Pp 142The following table summarizes the above information. 143.Bl -column "Sy SFF-8636" "1 Gb/s, 10 Gb/s, 25 Gb/s" "256 bytes" "0xa0, 0xa2" -offset indent 144.Em "Standard" Ta Em Speeds Ta Em Size Ta Em i2c pages 145.It INF-8074 Ta 1 Gb/s, 10 Gb/s Ta 128 bytes Ta 0xa0 146.It SFF-8472 Ta 1 Gb/s, 10 Gb/s, 25 GB/s Ta 512 bytes Ta 0xa0, 0xa2 147.It SFF-8436 Ta 40 Gb/s Ta 256 bytes Ta 0xa0 148.It SFF-8636 Ta 100 Gb/s Ta 256 bytes Ta 0xa0 149.El 150.Ss MAC Capability Structure 151When the device driver's 152.Xr mc_getcapab 9E 153function entry point is called with the capability requested set to 154.Sy MAC_CAPAB_TRANSCEIVER , 155then the value of the capability structure is the following structure: 156.Bd -literal -offset indent 157typedef struct mac_capab_transceiver { 158 uint_t mct_flags; 159 uint_t mct_ntransceivers; 160 int (*mct_info)(void *driver, uint_t id, 161 mac_transceiver_info_t *infop), 162 int (*mct_read)(void *driver, uint_t id, uint_t page, 163 void *buf, size_t nbytes, off_t offset, 164 size_t *nread) 165} mac_capab_transceiver_t; 166.Ed 167.Pp 168If the device driver supports the 169.Sy MAC_CAPAB_TRANSCEIVER 170capability, it should fill in this structure, based on the following 171rules: 172.Bl -tag -width Sy 173.It Sy mct_flags 174The 175.Vt mct_flags 176member is used to negotiate extensions with the driver. 177MAC will set the value of 178.Vt mct_flags 179to include all of the currently known extensions. 180The driver should intersect this list with the set that they actually 181support. 182At this time, no such features are defined and the driver should set the 183member to 184.Sy 0 . 185.It Sy mct_ntransceivers 186The value of 187.Sy mct_ntransceivers 188indicates the number of transceivers present in the device. 189For most devices, it is expected that this value will be set to one. 190However, some devices do support multiple transceivers and PHYs that 191show up behind a single logical MAC. 192.Pp 193It is expected that this value will not change across the lifetime of 194the device being attached. 195It is important to remember that this represents the total possible 196number of transceivers in the device, not how many are currently present 197and powered on. 198.Pp 199The number of transceivers will influence the 200.Fa id 201argument used in the 202.Fn mct_info 203and 204.Fn mct_read 205entry points. 206The transceiver IDs will start at zero and go to the value of 207.Fa mct_ntransceivers - 1 . 208It is up to the driver to keep the mapping between actual transceivers 209and the transceiver identifiers consistent. 210.It Sy mct_info 211The 212.Fn mct_info 213entry point is used to set basic information about the transceiver. 214This entry point is 215.Em required . 216If the device driver cannot implement this entry point, then it should 217not indicate that it supports the capability. 218.Pp 219The 220.Fn mct_info 221entry point should fill in information about the transceiver with an 222identifier of 223.Fa id . 224See the description above of 225.Sy mct_ntransceivers 226for more information on how the IDs are determined. 227.Pp 228The driver should then proceed to fill in basic information by calling 229the functions described in the section 230.Sx Information Functions . 231After successfully calling all of the functions, the driver should 232return 233.Sy 0 . 234Otherwise, it should return the appropriate error number. 235For a full list of error numbers, see 236.Xr Intro 2 . 237Common values are: 238.Bl -tag -width Er -offset width 239.It Er EINVAL 240The transceiver identifier 241.Fa id 242was invalid. 243.It Er ENOTSUP 244This instance of the devices does not support a transceiver. 245For example, a device which sometimes has copper PHYs and therefore this 246instance does not have any PHYs. 247.It Er EIO 248An error occurred while trying to read device registers. 249For example, an FM-aware device had an error. 250.El 251.It Sy mct_read 252The 253.Fn mct_read 254function is used to read information from a transceiver's i2c bus. 255The 256.Fn mct_read 257entry point is an 258.Em optional 259entry point. 260.Pp 261The transceiver should first check the value of 262.Fa id , 263which indicates which transceiver information is being requested. 264See the description above of 265.Sy mct_ntransceivers 266for more information on how the IDs are determined. 267.Pp 268The driver should try to read up to 269.Fa nbytes 270of data from the i2c bus at page 271.Fa page . 272The driver should start reading at offset 273.Fa offset . 274Finally, it should update the value in 275.Fa nread 276with the number of bytes written to the buffer 277.Fa buf . 278.Pp 279If for some reason the driver cannot read all of the requested bytes, 280that is acceptable. 281Instead it should perform a short read. 282This may occur because the transceiver does not allow reads at a 283requested region or the region is shorter than is common for most 284devices. 285.Pp 286Upon successful completion, the driver should ensure that 287.Fa nread 288has been updated and then return 289.Sy 0 . 290Otherwise, the driver should return the appropriate error number. 291For 292a full list of error numbers, see 293.Xr Intro 2 . 294Common values are: 295.Bl -tag -width Er -offset width 296.It Er EINVAL 297The value of 298.Fa id 299represented an invalid transceiver identifier. 300The transceiver i2c page 301.Fa page 302is not valid for this type of device. 303The value of 304.Fa offset 305is beyond the range supported for this 306.Fa page . 307.It Er EIO 308An error occurred while trying to read the device i2c pages. 309.El 310.El 311.Ss Transceiver Information Functions 312The 313.Fn mct_info 314entry point is the primary required entry point for a device driver 315which supports this capability. 316The information structure is opaque to the device driver. 317Instead, a series of informational functions is 318available to the device driver to call on the transceiver. 319The device drivers should try to call and fill in as many of these as 320possible. 321There are two different properties that a driver can set: 322.Bl -enum -offset indent 323.It 324Whether the transceiver is present. 325.It 326Whether the transceiver is usable. 327.El 328.Pp 329To set whether or not the transceiver is present, the driver should call 330.Xr mac_transceiver_info_set_present 9F . 331This is used to indicate whether the transceiver is plugged in or not. 332If the transceiver is a part of the NIC, then this function should 333always be called with the value set to 334.Dv B_TRUE . 335.Pp 336Finally, the driver has the ability to provide information about whether 337or not the transceiver is usable or not. 338A transceiver may be present, but not usable, if the hardware and 339firmware support a limited number of transceivers. 340To set this information, the driver should call 341.Xr mac_transceiver_info_set_usable 9F . 342If the transceiver is not present, then the driver should not call this 343function. 344.Ss Opaque Transceivers 345Some devices abstract the nature of the transceiver and do not allow 346direct access to the transceiver. 347In this case, if the device driver still has access to enough 348information to know if the transceiver is at least present, then it 349should still implement the 350.Fn mct_info 351entry point. 352.Ss Locking and Data Access 353Calls to get information about the transceivers may come at the same 354time as general I/O requests to the device to send or receive data. 355The driver should make sure that reading data from the i2c bus of the 356transceiver does not interfere with the device's functionality in this 357regard. 358Different locks should be used. 359.Pp 360On some devices, reading from the transceiver's i2c bus might cause a 361disruption of service to the device. 362For example, on some devices a phy reset may be required or come about 363as a side effect of trying to read the device. 364If any kind of disruption would be caused, then the driver 365must not implement the 366.Ft mct_read 367entry point. 368.Sh CONTEXT 369The various callback functions will be called from 370.Sy kernel 371context. 372These functions will never be called from 373.Sy interrupt 374context. 375.Sh SEE ALSO 376.Xr Intro 2 , 377.Xr mac 9E , 378.Xr mc_getcapab 9E , 379.Xr mac_register 9F , 380.Xr mac_transceiver_info_set_present 9F , 381.Xr mac_transceiver_info_set_usable 9F , 382.Xr mac_register 9S 383.Rs 384.%N INF-8074i 385.%T SFP (Small Formfactor Pluggable) Interface 386.%Q SFF Committee 387.%O Revision 1.0 388.%D May 12, 2001 389.Re 390.Rs 391.%N SFF-8472 392.%T Diagnostic Monitoring Interface for Optical Transceivers 393.%O Revision 12.2 394.%D November 21, 2014 395.Re 396.Rs 397.%N SFF-8436 398.%T QSFP+ 10 Gbs 4X PLUGGABLE TRANSCEIVER 399.%O Revision 4.8 400.%D October 31, 2013 401.Re 402.Rs 403.%N SFF-8636 404.%T Management Interface for Cabled Environments 405.%O Revision 2.7 406.%D January 26, 2016 407.Re 408