9e-gate Sdiff usr/src/man/man9e/mac_capab

Print this page

12309 errors in section 9e of the manual

   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"

 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

 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.

   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"

 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_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
 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 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

 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 Otherwise, 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.