3 NAME
   4      mac_capab_transceiver, mct_info, mct_read - MAC capability for networking
   5      transceivers
   8      #include <sys/mac_provider.h>
  10      typedef struct mac_capab_transceiver mac_capab_transceiver_t;
  12      int
  13      mct_info(void *driver, uint_t id, mac_transceiver_info_t *infop);
  15      int
  16      mct_read(void *driver, uint_t id, uint_t page, void *buf, size_t nbytes,
  17          off_t offset, size_t *nread);
  20      Volatile - This interface is still evolving in illumos.  API and ABI
  21      stability is not guaranteed.
  24      driver        A pointer to the driver's private data that was passed in
  25                    via the m_pdata member of the mac_register(9S) structure to
  26                    the mac_register(9F) function.
  28      id            An integer value indicating which transceiver is being
  29                    inquired about.
  31      infop         An opaque structure which is used to set information about
  32                    the transceiver.
  34      page          A value that indicates which page from the i2c bus is being
  35                    requested.
  37      buf           A pointer to which data should be written to when reading
  38                    from the device.
  40      nbytes        A value indicating the number of bytes being asked to read
  41                    into buf.
  43      offset        A value indicating the offset into the page to start
  44                    reading data.
  46      nread         A value to be updated by the driver with the number of
  47                    successfully read bytes.
  50      The MAC_CAPAB_TRANSCEIVER capability allows for GLDv3 networking device
  51      drivers to provide information to the system about their transceiver.
  52      Implementing this capability is optional.  For more information on how to
  53      handle capabilities and how to indicate that a capability is not
  54      supported, see mc_getcapab(9E).
  56      This capability should be implemented if the device in question supports
  57      a Small Form Factor (SFF) transceiver.  These are more commonly known by
  58      names such as SFP, SFP+, SFP28, QSFP+, and QSFP28.  This interface does
  59      not apply to traditional copper Ethernet phys.  These transceivers
  60      provide standardized information over the i2c bus at specific pages.
  62    Supported Standards
  63      INF-8074
  64              The INF-8084 standard was the original multiple source agreement
  65              (MSA) for SFP devices.  It proposed the original series of
  66              management pages at i2c page 0xa0.  This page contained up to 512
  67              bytes, however, only the first 96 bytes are standardized.  Bytes
  68              97 to 127 are reserved for the vendor.  The remaining bytes are
  69              reserved by the specification.  The management page was
  70              subsequently adopted by SFP+ devices.
  72      SFF-8472
  73              The SFF-8472 standard extended the original SFP MSA.  This
  74              standard added a second i2c page at 0xa2, while maintaining the
  75              original page at 0xa0.  The page at 0xa0 is now explicitly 256
  76              bytes.  The page at 0xa2 is also 256 bytes.  This standard was
  77              also adopted for all SFP28 parts, which are commonly used in
  78              transceivers for 25 Gb/s Ethernet.
  80      SFF-8436
  81              The SFF-8436 standard was developed for QSFP+ transceivers, which
  82              involve the bonding of 4 SFP+ links.  QSFP+ is commonly used in
  83              the transceivers for 40 Gb/s Ethernet.  This standard uses i2c
  84              page 0xa0 for read-only identification purposes.  The lower half
  85              of the page is used for control, while the upper 128 bytes is
  86              similar to the INF-8084 and SFF-8472 standards.
  88      SFF-8636
  89              The SFF-8636 standard is a common management standard which is
  90              shared between both SAS and QSFP+ 28 Gb/s transceivers.  The
  91              latter transceiver is commonly found in 100 Gb/s Ethernet.  The
  92              transceiver's memory map is similar to that found in the SFF-8436
  93              specification.  The identification information is found in the
  94              upper 128 bytes of page 0xa0, while the lower part of the page is
  95              used for control, among other purposes.
  97      The following table summarizes the above information.
  99            Standard       Speeds                      Size         i2c pages
 100            INF-8074       1 Gb/s, 10 Gb/s             128 bytes    0xa0
 101            SFF-8472       1 Gb/s, 10 Gb/s, 25 GB/s    512 bytes    0xa0, 0xa2
 102            SFF-8436       40 Gb/s                     256 bytes    0xa0
 103            SFF-8636       100 Gb/s                    256 bytes    0xa0
 105    MAC Capability Structure
 106      When the device driver's mc_getcapab(9E) function entry point is called
 107      with the capability requested set to MAC_CAPAB_TRANSCEIVER, then the
 108      value of the capability structure is the following structure:
 110            typedef struct mac_capab_transceiver {
 111                    uint_t  mct_flags;
 112                    uint_t  mct_ntransceivers;
 113                    int     (*mct_info)(void *driver, uint_t id,
 114                                mac_transceiver_info_t *infop),
 115                    int     (*mct_read)(void *driver, uint_t id, uint_t page,
 116                                void *buf, size_t nbytes, off_t offset,
 117                                size_t *nread)
 118            } mac_capab_transceiver_t;
 120      If the device driver supports the MAC_CAPAB_TRANSCEIVER capability, it
 121      should fill in this structure, based on the following rules:
 123      mct_flags
 124              The mct_flags member is used to negotiate extensions with the
 125              driver.  MAC will set the value of mct_flags to include all of
 126              the currently known extensions.  The driver should intersect this
 127              list with the set that they actually support.  At this time, no
 128              such features are defined and the driver should set the member to
 129              0.
 131      mct_ntransceivers
 132              The value of mct_ntransceivers indicates the number of
 133              transceivers present in the device.  For most devices, it is
 134              expected that this value will be set to one.  However, some
 135              devices do support multiple transceivers and PHYs that show up
 136              behind a single logical MAC.
 138              It is expected that this value will not change across the
 139              lifetime of the device being attached.  It is important to
 140              remember that this represents the total possible number of
 141              transceivers in the device, not how many are currently present
 142              and powered on.
 144              The number of transceivers will influence the id argument used in
 145              the mct_info() and mct_read() entry points.  The transceiver IDs
 146              will start at zero and go to the value of mct_ntransceivers - 1.
 147              It is up to the driver to keep the mapping between actual
 148              transceivers and the transceiver identifiers consistent.
 150      mct_info
 151              The mct_info() entry point is used to set basic information about
 152              the transceiver.  This entry point is required.  If the device
 153              driver cannot implement this entry point, then it should not
 154              indicate that it supports the capability.
 156              The mct_info() entry point should fill in information about the
 157              transceiver with an identifier of id.  See the description above
 158              of mct_ntransceivers for more information on how the IDs are
 159              determined.
 161              The driver should then proceed to fill in basic information by
 162              calling the functions described in the section Information
 163              Functions.  After successfully calling all of the functions, the
 164              driver should return 0.  Otherwise, it should return the
 165              appropriate error number.  For a full list of error numbers, see
 166              Intro(2).  Common values are:
 168                   EINVAL             The transceiver identifier id was
 169                                      invalid.
 171                   ENOTSUP            This instance of the devices does not
 172                                      support a transceiver.  For example, a
 173                                      device which sometimes has copper PHYs
 174                                      and therefore this instance does not have
 175                                      any PHYs.
 177                   EIO                An error occurred while trying to read
 178                                      device registers.  For example, an FM-
 179                                      aware device had an error.
 181      mct_read
 182              The mct_read() function is used to read information from a
 183              transceiver's i2c bus.  The mct_read() entry point is an optional
 184              entry point.
 186              The transceiver should first check the value of id, which
 187              indicates which transceiver information is being requested.  See
 188              the description above of mct_ntransceivers for more information
 189              on how the IDs are determined.
 191              The driver should try to read up to nbytes of data from the i2c
 192              bus at page page.  The driver should start reading at offset
 193              offset.  Finally, it should update the value in nread with the
 194              number of bytes written to the buffer buf.
 196              If for some reason the driver cannot read all of the requested
 197              bytes, that is acceptable.  Instead it should perform a short
 198              read.  This may occur because the transceiver does not allow
 199              reads at a requested region or the region is shorter than is
 200              common for most devices.
 202              Upon successful completion, the driver should ensure that nread
 203              has been updated and then return 0.  Otherwise, the driver should
 204              return the appropriate error number.  For a full list of error
 205              numbers, see Intro(2).  Common values are:
 207                   EINVAL             The value of id represented an invalid
 208                                      transceiver identifier.  The transceiver
 209                                      i2c page page is not valid for this type
 210                                      of device.  The value of offset is beyond
 211                                      the range supported for this page.
 213                   EIO                An error occurred while trying to read
 214                                      the device i2c pages.
 216    Transceiver Information Functions
 217      The mct_info() entry point is the primary required entry point for a
 218      device driver which supports this capability.  The information structure
 219      is opaque to the device driver.  Instead, a series of informational
 220      functions is available to the device driver to call on the transceiver.
 221      The device drivers should try to call and fill in as many of these as
 222      possible.  There are two different properties that a driver can set:
 224            1.   Whether the transceiver is present.
 226            2.   Whether the transceiver is usable.
 228      To set whether or not the transceiver is present, the driver should call
 229      mac_transceiver_info_set_present(9F).  This is used to indicate whether
 230      the transceiver is plugged in or not.  If the transceiver is a part of
 231      the NIC, then this function should always be called with the value set to
 232      B_TRUE.
 234      Finally, the driver has the ability to provide information about whether
 235      or not the transceiver is usable or not.  A transceiver may be present,
 236      but not usable, if the hardware and firmware support a limited number of
 237      transceivers.  To set this information, the driver should call
 238      mac_transceiver_info_set_usable(9F).  If the transceiver is not present,
 239      then the driver should not call this function.
 241    Opaque Transceivers
 242      Some devices abstract the nature of the transceiver and do not allow
 243      direct access to the transceiver.  In this case, if the device driver
 244      still has access to enough information to know if the transceiver is at
 245      least present, then it should still implement the mct_info() entry point.
 247    Locking and Data Access
 248      Calls to get information about the transceivers may come at the same time
 249      as general I/O requests to the device to send or receive data.  The
 250      driver should make sure that reading data from the i2c bus of the
 251      transceiver does not interfere with the device's functionality in this
 252      regard.  Different locks should be used.
 254      On some devices, reading from the transceiver's i2c bus might cause a
 255      disruption of service to the device.  For example, on some devices a phy
 256      reset may be required or come about as a side effect of trying to read
 257      the device.  If any kind of disruption would be caused, then the driver
 258      must not implement the mct_read entry point.
 261      The various callback functions will be called from kernel context.  These
 262      functions will never be called from interrupt context.
 265      Intro(2), mac(9E), mc_getcapab(9E), mac_register(9F),
 266      mac_transceiver_info_set_present(9F),
 267      mac_transceiver_info_set_usable(9F), mac_register(9S)
 269      SFP (Small Formfactor Pluggable) Interface, INF-8074i, SFF Committee, May
 270      12, 2001, Revision 1.0.
 272      Diagnostic Monitoring Interface for Optical Transceivers, SFF-8472,
 273      November 21, 2014, Revision 12.2.
 275      QSFP+ 10 Gbs 4X PLUGGABLE TRANSCEIVER, SFF-8436, October 31, 2013,
 276      Revision 4.8.
 278      Management Interface for Cabled Environments, SFF-8636, January 26, 2016,
 279      Revision 2.7.
 281 illumos                        February 15, 2020                       illumos