2 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
35 .Nd "driver module for ATM PHY chips"
37 .In dev/utopia/utopia.h
40 .Fa "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media"
41 .Fa "struct mtx *lock" "struct sysctl_ctx_list *ctx"
42 .Fa "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab"
45 .Fn utopia_detach "struct utopia *utp"
47 .Fn utopia_start "struct utopia *utp"
49 .Fn utopia_stop "struct utopia *utp"
51 .Fn utopia_init_media "struct utopia *utp"
53 .Fn utopia_reset_media "struct utopia *utp"
55 .Fn utopia_reset "struct utopia *utp"
57 .Fn utopia_set_sdh "struct utopia *utp" "int sdh"
59 .Fn utopia_set_unass "struct utopia *utp" "int unass"
61 .Fn utopia_set_noscramb "struct utopia *utp" "int noscramb"
63 .Fn utopia_update_carrier "struct utopia *utp"
65 .Fn utopia_set_loopback "struct utopia *utp" "u_int mode"
67 .Fn utopia_intr "struct utopia *utp"
69 .Fn utopia_update_stats "struct utopia *utp"
71 This module is used by all ATM drivers for cards that use a number of known
72 PHY chips to provide uniform functionality.
73 The module implements status monitoring in either interrupt or polling mode,
74 media option handling and application access to PHY registers.
76 To use this interface, a driver must implement two functions for reading and
77 writing PHY registers, and initialize the following structure with pointers
79 .Bd -literal -offset indent
80 struct utopia_methods {
81 int (*readregs)(struct ifatm *, u_int reg,
82 uint8_t *val, u_int *n);
83 int (*writereg)(struct ifatm *, u_int reg,
84 u_int mask, u_int val);
90 function should read PHY registers starting at register
92 The maximum number of registers to read is given by the integer pointed
95 The function should either return 0 on success, or an error code.
98 should be set to the actual number of registers read.
101 function should write one register.
102 It must change all bits for which the corresponding bit in
104 is 1 to the value of the corresponding bit in
106 It returns either 0 on success, or an error code.
108 The ATM driver's private state block
115 holds the current state of the PHY chip and contains the following fields:
116 .Bd -literal -offset indent
118 struct ifatm *ifatm; /* driver data */
119 struct ifmedia *media; /* driver supplied */
120 struct mtx *lock; /* driver supplied */
121 const struct utopia_methods *methods;
122 LIST_ENTRY(utopia) link; /* list of these structures */
123 u_int flags; /* flags set by the driver */
124 u_int state; /* current state */
125 u_int carrier; /* carrier state */
126 u_int loopback; /* loopback mode */
127 const struct utopia_chip *chip; /* chip operations */
128 struct utopia_stats1 stats; /* statistics */
131 The public accessible fields have the following functions:
132 .Bl -tag -width indent
134 Pointer to the driver's private data
137 Pointer to the driver's media structure.
139 Pointer to a mutex provided by the driver.
140 This mutex is used to synchronize
141 with the kernel thread that handles device polling.
142 It is locked in several
144 .Bl -enum -offset indent
148 the mutex is locked to sleep and wait for the kernel thread to remove the
153 Before returning to the caller the mutex is unlocked.
157 kernel thread the mutex is locked, and the
158 .Fn utopia_carrier_update
159 function is called with this mutex locked.
160 This will result in the driver's
162 function being called with the mutex locked.
164 In the sysctl handlers the mutex will be locked before calling into the driver's
171 Flags set by either the driver or the
174 The following flags are
176 .Bl -tag -width indent
177 .It Dv UTP_FL_NORESET
178 If this flag is set, the module will not try to write the
179 SUNI master reset register.
181 .It Dv UTP_FL_POLL_CARRIER
182 If this flag is set, the module will periodically poll the carrier state
183 (as opposed to interrupt driven carrier state changes).
187 Flags describing the current state of the PHY chip.
190 .Bl -tag -width indent
192 The driver is active and the PHY registers can be accessed.
193 This is set by calling
195 which should be called either in the attach routine of the driver or
196 in the network interface initialisation routine (depending on whether the
197 registers are accessible all the time or only when the interface is up).
199 Interface is in SDH mode as opposed to SONET mode.
201 Interface is producing unassigned cells instead of idle cells.
202 .It Dv UTP_ST_NOSCRAMB
203 Cell scrambling is switched off.
206 Interface is currently detaching.
207 .It Dv UTP_ST_ATTACHED
208 The attach routine has been run successfully.
211 The carrier state of the interface.
212 This field can have one of three values:
213 .Bl -tag -width indent
214 .It Dv UTP_CARR_UNKNOWN
215 Carrier state is still unknown.
217 Carrier has been detected.
219 Carrier has been lost.
222 This is the current loopback mode of the interface.
224 chips support all loopback modes.
225 Refer to the chip documentation.
227 following modes may be supported:
228 .Bl -tag -width indent
230 No loopback, normal operation.
232 Timing source loopback.
233 The transmitter clock is driven by the receive clock.
237 Serial line loopback.
238 .It Dv UTP_LOOP_PARAL
239 Parallel diagnostic loopback.
240 .It Dv UTP_LOOP_TWIST
241 Twisted pair diagnostic loopback.
243 Diagnostic path loopback.
246 This points to a function vector for chip specific functions.
248 in this vector are publicly available:
249 .Bl -tag -width indent
251 This is the type of the detected PHY chip.
254 .Bl -tag -width indent -compact
255 .It Dv UTP_TYPE_UNKNOWN Pq No 0
256 .It Dv UTP_TYPE_SUNI_LITE Pq No 1
257 .It Dv UTP_TYPE_SUNI_ULTRA Pq No 2
258 .It Dv UTP_TYPE_SUNI_622 Pq No 3
259 .It Dv UTP_TYPE_IDT77105 Pq No 4
262 This is a string with the name of the PHY chip.
266 The following functions are used by the driver during attach/detach and/or
267 initialisation/stopping the interface:
268 .Bl -tag -width indent
271 This is called with a preallocated
273 (which may be part of the driver's
275 The module initializes all fields of the
277 state and the media field.
278 User settable flags should be set after the call to
280 This function may fail due to the inability to install the sysctl handlers.
281 In this case it will return \-1.
282 On success, 0 is returned and the
288 attachment from the system.
289 This cancels all outstanding polling
292 Start operation of that PHY.
293 This should be called at a time
294 when the PHY registers are known to be accessible.
295 This may be either in
296 the driver's attach function or when the interface is set running.
298 Stop operation of the PHY attachment.
299 This may be called either in the detach
300 function of the driver or when the interface is brought down.
301 .It Fn utopia_init_media
302 This must be called if the media field in the ATM MIB was changed.
304 makes sure, that the ifmedia fields contain the same information as the
306 .It Fn utopia_reset_media
307 This may be called to remove all media information from the ifmedia field.
310 The following functions can be used to modify the PHY state while the interface
312 .Bl -tag -width indent
314 Reset the operational parameters to the default state (SONET, idle cells,
316 Returns 0 on success, an error code otherwise, leaving
318 .It Fn utopia_set_sdh
319 If the argument is zero the chip is switched to Sonet mode, if it is non-zero
320 the chip is switched to SDH mode.
321 Returns 0 on success, an error code otherwise,
322 leaving the previous state.
323 .It Fn utopia_set_unass
324 If the argument is zero the chip is switched to produce idle cells, if it is
325 non-zero the chip is switched to produce unassigned cells.
326 Returns 0 on success,
327 an error code otherwise, leaving the previous state.
328 .It Fn utopia_set_noscramb
329 If the argument is zero enables scrambling, if it is
330 non-zero disables scrambling.
331 Returns 0 on success,
332 an error code otherwise, leaving the previous state.
333 .It Fn utopia_update_carrier
334 Check the carrier state and update the carrier field in the state structure.
335 This will generate a message to the Netgraph stack if the carrier state changes.
336 For chips that are polled this is called automatically, for interrupt
337 driven attachments this must be called on interrupts from the PHY chip.
338 .It Fn utopia_set_loopback
339 Set the loopback mode of the chip.
340 Returns 0 on success, an error code
341 otherwise, leaving the previous state.
343 Called when an interrupt from the PHY chip is detected.
345 interrupt state by reading all registers and, if the interrupt was from the
346 RSOP, checks the carrier state.
347 .It Fn utopia_update_stats
348 Update the statistics with counters read from the chip.
353 .An Harti Brandt Aq harti@FreeBSD.org