share/man/man9/utopia.9

   1 .\" Copyright (c) 2003
   2 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   3 .\"     All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd May 8, 2003
  31 .Dt UTOPIA 9
  32 .Os
  33 .Sh NAME
  34 .Nm utopia
  35 .Nd "driver module for ATM PHY chips"
  36 .Sh SYNOPSIS
  37 .In dev/utopia/utopia.h
  38 .Ft int
  39 .Fo utopia_attach
  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"
  43 .Fc
  44 .Ft void
  45 .Fn utopia_detach "struct utopia *utp"
  46 .Ft int
  47 .Fn utopia_start "struct utopia *utp"
  48 .Ft void
  49 .Fn utopia_stop "struct utopia *utp"
  50 .Ft void
  51 .Fn utopia_init_media "struct utopia *utp"
  52 .Ft void
  53 .Fn utopia_reset_media "struct utopia *utp"
  54 .Ft int
  55 .Fn utopia_reset "struct utopia *utp"
  56 .Ft int
  57 .Fn utopia_set_sdh "struct utopia *utp" "int sdh"
  58 .Ft int
  59 .Fn utopia_set_unass "struct utopia *utp" "int unass"
  60 .Ft int
  61 .Fn utopia_set_noscramb "struct utopia *utp" "int noscramb"
  62 .Ft int
  63 .Fn utopia_update_carrier "struct utopia *utp"
  64 .Ft int
  65 .Fn utopia_set_loopback "struct utopia *utp" "u_int mode"
  66 .Ft void
  67 .Fn utopia_intr "struct utopia *utp"
  68 .Ft void
  69 .Fn utopia_update_stats "struct utopia *utp"
  70 .Sh DESCRIPTION
  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.
  75 .Pp
  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
  78 to these functions:
  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);
  85 };
  86 .Ed
  87 .Pp
  88 The
  89 .Fn readregs
  90 function should read PHY registers starting at register
  91 .Fa reg .
  92 The maximum number of registers to read is given by the integer pointed
  93 to by
  94 .Fa n .
  95 The function should either return 0 on success, or an error code.
  96 In the first case,
  97 .Fa *n
  98 should be set to the actual number of registers read.
  99 The
 100 .Fn writereg
 101 function should write one register.
 102 It must change all bits for which the corresponding bit in
 103 .Fa mask
 104 is 1 to the value of the corresponding bit in
 105 .Fa val .
 106 It returns either 0 on success, or an error code.
 107 .Pp
 108 The ATM driver's private state block
 109 .Pq Va softc
 110 must begin with a
 111 .Vt "struct ifatm" .
 112 .Pp
 113 The
 114 .Vt "struct utopia"
 115 holds the current state of the PHY chip and contains the following fields:
 116 .Bd -literal -offset indent
 117 struct utopia {
 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 */
 129 };
 130 .Ed
 131 The public accessible fields have the following functions:
 132 .Bl -tag -width indent
 133 .It Va ifatm
 134 Pointer to the driver's private data
 135 .Pq Va softc .
 136 .It Va media
 137 Pointer to the driver's media structure.
 138 .It Va lock
 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
 143 places:
 144 .Bl -enum -offset indent
 145 .It
 146 In
 147 .Fn utopia_detach
 148 the mutex is locked to sleep and wait for the kernel thread to remove the
 149 .Vt "struct utopia"
 150 from the list of all
 151 .Nm
 152 devices.
 153 Before returning to the caller the mutex is unlocked.
 154 .It
 155 In the
 156 .Nm
 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
 161 .Fn readregs
 162 function being called with the mutex locked.
 163 .It
 164 In the sysctl handlers the mutex will be locked before calling into the driver's
 165 .Fn readreg
 166 or
 167 .Fn writereg
 168 functions.
 169 .El
 170 .It Va flags
 171 Flags set by either the driver or the
 172 .Nm
 173 module.
 174 The following flags are
 175 defined:
 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.
 180 (Set by the driver.)
 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).
 184 (Set by the driver.)
 185 .El
 186 .It Va state
 187 Flags describing the current state of the PHY chip.
 188 These are managed
 189 by the module:
 190 .Bl -tag -width indent
 191 .It Dv UTP_ST_ACTIVE
 192 The driver is active and the PHY registers can be accessed.
 193 This is set by calling
 194 .Fn utopia_start ,
 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).
 198 .It Dv UTP_ST_SDH
 199 Interface is in SDH mode as opposed to SONET mode.
 200 .It Dv UTP_ST_UNASS
 201 Interface is producing unassigned cells instead of idle cells.
 202 .It Dv UTP_ST_NOSCRAMB
 203 Cell scrambling is switched off.
 204 .It Dv UTP_ST_DETACH
 205 (Internal use.)
 206 Interface is currently detaching.
 207 .It Dv UTP_ST_ATTACHED
 208 The attach routine has been run successfully.
 209 .El
 210 .It Va carrier
 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.
 216 .It Dv UTP_CARR_OK
 217 Carrier has been detected.
 218 .It Dv UTP_CARR_LOST
 219 Carrier has been lost.
 220 .El
 221 .It Va loopback
 222 This is the current loopback mode of the interface.
 223 Note that not all
 224 chips support all loopback modes.
 225 Refer to the chip documentation.
 226 The
 227 following modes may be supported:
 228 .Bl -tag -width indent
 229 .It Dv UTP_LOOP_NONE
 230 No loopback, normal operation.
 231 .It Dv UTP_LOOP_TIME
 232 Timing source loopback.
 233 The transmitter clock is driven by the receive clock.
 234 .It Dv UTP_LOOP_DIAG
 235 Diagnostic loopback.
 236 .It Dv UTP_LOOP_LINE
 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.
 242 .It Dv UTP_LOOP_PATH
 243 Diagnostic path loopback.
 244 .El
 245 .It Va chip
 246 This points to a function vector for chip specific functions.
 247 Two fields
 248 in this vector are publicly available:
 249 .Bl -tag -width indent
 250 .It Va type
 251 This is the type of the detected PHY chip.
 252 One of:
 253 .Pp
 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
 260 .El
 261 .It Va name
 262 This is a string with the name of the PHY chip.
 263 .El
 264 .El
 265 .Pp
 266 The following functions are used by the driver during attach/detach and/or
 267 initialisation/stopping the interface:
 268 .Bl -tag -width indent
 269 .It Fn utopia_attach
 270 Attach the PHY chip.
 271 This is called with a preallocated
 272 .Vt "struct utopia"
 273 (which may be part of the driver's
 274 .Va softc ) .
 275 The module initializes all fields of the
 276 .Nm
 277 state and the media field.
 278 User settable flags should be set after the call to
 279 .Fn utopia_attach .
 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
 283 .Dv UTP_ST_ATTACHED
 284 flag is set.
 285 .It Fn utopia_detach
 286 Remove the
 287 .Nm
 288 attachment from the system.
 289 This cancels all outstanding polling
 290 timeouts.
 291 .It Fn utopia_start
 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.
 297 .It Fn utopia_stop
 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.
 303 The function
 304 makes sure, that the ifmedia fields contain the same information as the
 305 ATM MIB.
 306 .It Fn utopia_reset_media
 307 This may be called to remove all media information from the ifmedia field.
 308 .El
 309 .Pp
 310 The following functions can be used to modify the PHY state while the interface
 311 is running:
 312 .Bl -tag -width indent
 313 .It Fn utopia_reset
 314 Reset the operational parameters to the default state (SONET, idle cells,
 315 scrambling enabled).
 316 Returns 0 on success, an error code otherwise, leaving
 317 the state undefined.
 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.
 342 .It Fn utopia_intr
 343 Called when an interrupt from the PHY chip is detected.
 344 This resets the
 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.
 349 .El
 350 .Sh SEE ALSO
 351 .Xr utopia 4
 352 .Sh AUTHORS
 353 .An Harti Brandt Aq harti@FreeBSD.org