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 Nov 26, 2017
  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 -
  43 This interface is still evolving in illumos.
  44 API and ABI stability is
  45 not guaranteed.
  46 .Sh PARAMETERS
  47 .Bl -tag -width Fa
  48 .It Fa driver
  49 A pointer to the driver's private data that was passed in via the
  50 .Sy m_pdata
  51 member of the
  52 .Xr mac_register 9S
  53 structure to the
  54 .Xr mac_register 9F
  55 function.
  56 .It Fa id
  57 An integer value indicating which transceiver is being inquired about.
  58 .It Fa infop
  59 An opaque structure which is used to set information about the
  60 transceiver.
  61 .It Fa page
  62 A value that indicates which page from the i2c bus is being requested.
  63 .It Fa buf
  64 A pointer to which data should be written to when reading from the
  65 device.
  66 .It Fa nbytes
  67 A value indicating the number of bytes being asked to read into
  68 .Fa buf .
  69 .It Fa offset
  70 A value indicating the offset into the page to start reading data.
  71 .It Fa nread
  72 A value to be updated by the driver with the number of successfully read
  73 bytes.
  74 .El
  75 .Sh DESCRIPTION
  76 The
  77 .Sy MAC_CAPAB_TRANSCEIVER
  78 capability allows for GLDv3 networking device drivers to provide
  79 information to the system about their transceiver.
  80 Implementing this capability is optional.
  81 For more information on how to handle capabilities and how to indicate
  82 that a capability is not supported, see
  83 .Xr mc_getcapab 9E .
  84 .Pp
  85 This capability should be implemented if the device in question supports
  86 a Small Form Factor (SFF) transceiver.
  87 These are more commonly known by names such as SFP, SFP+, SFP28, QSFP+,
  88 and QSFP28.
  89 This interface does not apply to traditional copper Ethernet phys.
  90 These transceivers provide standardized information over the i2c bus at
  91 specific pages.
  92 .Ss Supported Standards
  93 .Bl -tag -width Sy
  94 .It Sy INF-8074
  95 The
  96 .Sy INF-8084
  97 standard was the original multiple source agreement (MSA) for SFP
  98 devices.
  99 It proposed the original series of management pages at i2c page 0xa0.
 100 This page contained up to 512 bytes, however, only the first
 101 96 bytes are standardized.
 102 Bytes 97 to 127 are reserved for the vendor.
 103 The remaining bytes are reserved by the specification.
 104 The management page was subsequently adopted by SFP+ devices.
 105 .It Sy SFF-8472
 106 The
 107 .Sy SFF-8472
 108 standard extended the original SFP MSA.
 109 This standard added a second i2c page at 0xa2, while maintaining the
 110 original page at 0xa0.
 111 The page at 0xa0 is now explicitly 256 bytes.
 112 The page at 0xa2 is also 256 bytes.
 113 This standard was also adopted for all SFP28 parts, which are commonly
 114 used in transceivers for 25 Gb/s Ethernet.
 115 .It Sy SFF-8436
 116 The
 117 .Sy SFF-8436
 118 standard was developed for QSFP+ transceivers, which involve the
 119 bonding of 4 SFP+ links.
 120 QSFP+ is commonly used in the transceivers for 40 Gb/s Ethernet.
 121 This standard uses i2c page 0xa0 for read-only identification purposes.
 122 The lower half of the page is used for control, while the upper 128
 123 bytes is similar to the
 124 .Sy INF-8084
 125 and
 126 .Sy SFF-8472
 127 standards.
 128 .It Sy SFF-8636
 129 The
 130 .Sy SFF-8636
 131 standard is a common management standard which is shared between both
 132 SAS and QSFP+ 28 Gb/s transceivers.
 133 The latter transceiver is commonly found in 100 Gb/s Ethernet.
 134 The transceiver's memory map is similar to that found in the
 135 .Sy SFF-8436
 136 specification.
 137 The identification information is found in the upper 128
 138 bytes of page 0xa0, while the lower part of the page is used for
 139 control, among other purposes.
 140 .El
 141 .Pp
 142 The 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
 151 When the device driver's
 152 .Xr mc_getcapab 9E
 153 function entry point is called with the capability requested set to
 154 .Sy MAC_CAPAB_TRANSCEIVER ,
 155 then the value of the capability structure is the following structure:
 156 .Bd -literal -offset indent
 157 typedef struct mac_capab_transceiver {
 158         uint_t  mct_flags;
 159         uint_t  mct_ntransceiveres;
 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
 168 If the device driver supports the
 169 .Sy MAC_CAPAB_TRANSCEIVER
 170 capability, it should fill in this structure, based on the following
 171 rules:
 172 .Bl -tag -width Sy
 173 .It Sy mct_flags
 174 The
 175 .Vt mct_flags
 176 member is used to negotiate extensions with the driver.
 177 MAC will set the value of
 178 .Vt mct_flags
 179 to include all of the currently known extensions.
 180 The driver should intersect this list with the set that they actually
 181 support.
 182 At this time, no such features are defined and the driver should set the
 183 member to
 184 .Sy 0 .
 185 .It Sy mct_ntransceivers
 186 The value of
 187 .Sy mct_ntransceivers
 188 indicates that the number of transceivers present in the device.
 189 For most devices, it is expected that this value will be set to one.
 190 However, some devices do support multiple transceivers and PHYs that
 191 show up behind a single logical MAC.
 192 .Pp
 193 It is expected that this value will not change across the lifetime of
 194 the device being attached.
 195 It is important to remember that this represents the total possible
 196 number of transceivers in the device, not how many are currently present
 197 and powered on.
 198 .Pp
 199 The number of transceivers will influence the
 200 .Fa id
 201 argument used in the
 202 .Fn mct_info
 203 and
 204 .Fn mct_read
 205 entry points.
 206 The transceiver IDs will start at zero and go to the value of
 207 .Fa mct_ntransceivers - 1 .
 208 It is up to the driver to keep the mapping between actual transceivers
 209 and the transceiver identifiers consistent.
 210 .It Sy mct_info
 211 The
 212 .Fn mct_info
 213 entry point is used to set basic information about the transceiver.
 214 This entry point is
 215 .Em required .
 216 If the device driver cannot implement this entry point, then it should
 217 not indicate that it supports the capability.
 218 .Pp
 219 The
 220 .Fn mct_info
 221 entry point should fill in information about the transceiver with an
 222 identifier of
 223 .Fa id .
 224 See the description above of
 225 .Sy mct_ntransceivers
 226 for more information on how the IDs are determined.
 227 .Pp
 228 The driver should then proceed to fill in basic information by calling
 229 the functions described in the section
 230 .Sx Information Functions .
 231 After successfully calling all of the functions, the driver should
 232 return
 233 .Sy 0 .
 234 Othewrise, it should return the appropriate error number.
 235 For a full list of error numbers, see
 236 .Xr Intro 2 .
 237 Common values are:
 238 .Bl -tag -width Er -offset width
 239 .It Er EINVAL
 240 The transceiver identifier
 241 .Fa id
 242 was invalid.
 243 .It Er ENOTSUP
 244 This instance of the devices does not support a transceiver.
 245 For example, a device which sometimes has copper PHYs and therefore this
 246 instance does not have any PHYs.
 247 .It Er EIO
 248 An error occurred while trying to read device registers.
 249 For example, an FM-aware device had an error.
 250 .El
 251 .It Sy mct_read
 252 The
 253 .Fn mct_read
 254 function is used to read information from a transceiver's i2c bus.
 255 The
 256 .Fn mct_read
 257 entry point is an
 258 .Em optional
 259 entry point.
 260 .Pp
 261 The transceiver should first check the value of
 262 .Fa id ,
 263 which indicates which transceiver information is being requested.
 264 See the description above of
 265 .Sy mct_ntransceivers
 266 for more information on how the IDs are determined.
 267 .Pp
 268 The driver should try to read up to
 269 .Fa nbytes
 270 of data from the i2c bus at page
 271 .Fa page .
 272 The driver should start reading at offset
 273 .Fa offset .
 274 Finally, it should update the value in
 275 .Fa nread
 276 with the number of bytes written to the buffer
 277 .Fa buf .
 278 .Pp
 279 If for some reason the driver cannot read all of the requested bytes,
 280 that is acceptable.
 281 Instead it should perform a short read.
 282 This may occur because the transceiver does not allow reads at a
 283 requested region or the region is shorter than is common for most
 284 devices.
 285 .Pp
 286 Upon successful completion, the driver should ensure that
 287 .Fa nread
 288 has been updated and then return
 289 .Sy 0 .
 290 Otherwise, the driver should return the appropriate error number.
 291 For
 292 a full list of error numbers, see
 293 .Xr Intro 2 .
 294 Common values are:
 295 .Bl -tag -width Er -offset width
 296 .It Er EINVAL
 297 The value of
 298 .Fa id
 299 represented an invalid transceiver identifier.
 300 The transceiver i2c page
 301 .Fa page
 302 is not valid for this type of device.
 303 The value of
 304 .Fa offset
 305 is beyond the range supported for this
 306 .Fa page .
 307 .It Er EIO
 308 An error occurred while trying to read the device i2c pages.
 309 .El
 310 .El
 311 .Ss Transceiver Information Functions
 312 The
 313 .Fn mct_info
 314 entry point is the primary required entry point for a device driver
 315 which supports this capability.
 316 The information structure is opaque to the device driver.
 317 Instead, a series of informational functions is
 318 available to the device driver to call on the transceiver.
 319 The device drivers should try to call and fill in as many of these as
 320 possible.
 321 There are two different properties that a driver can set:
 322 .Bl -enum -offset indent
 323 .It
 324 Whether the transceiver is present.
 325 .It
 326 Whether the transceiver is usable.
 327 .El
 328 .Pp
 329 To set whether or not the transceiver is present, the driver should call
 330 .Xr mac_transceiver_info_set_present 9F .
 331 This is used to indicate whether the transceiver is plugged in or not.
 332 If the transceiver is a part of the NIC, then this function should
 333 always be called with the value set to
 334 .Dv B_TRUE .
 335 .Pp
 336 Finally, the driver has the ability to provide information about whether
 337 or not the transceiver is usable or not.
 338 A transceiver may be present, but not usable, if the hardware and
 339 firmware support a limited number of transceivers.
 340 To set this information, the driver should call
 341 .Xr mac_transceiver_info_set_usable 9F .
 342 If the transceiver is not present, then the driver should not call this
 343 function.
 344 .Ss Opaque Transceivers
 345 Some devices abstract the nature of the transceiver and do not allow
 346 direct access to the transceiver.
 347 In this case, if the device driver still has access to enough
 348 information to know if the transceiver is at least present, then it
 349 should still implement the
 350 .Fn mct_info
 351 entry point.
 352 .Ss Locking and Data Access
 353 Calls to get information about the transceivers may come at the same
 354 time as general I/O requests to the device to send or receive data.
 355 The driver should make sure that reading data from the i2c bus of the
 356 transceiver does not interfere with the device's functionality in this
 357 regard.
 358 Different locks should be used.
 359 .Pp
 360 On some devices, reading from the transceiver's i2c bus might cause a
 361 disruption of service to the device.
 362 For example, on some devices a phy reset may be required or come about
 363 as a side effect of trying to read the device.
 364 If any kind of disruption would be caused, then the driver
 365 must not implement the
 366 .Ft mct_read
 367 entry point.
 368 .Sh CONTEXT
 369 The various callback functions will be called from
 370 .Sy kernel
 371 context.
 372 These functions will never be called from
 373 .Sy interrupt
 374 context.
 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