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