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