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 71This module is used by all ATM drivers for cards that use a number of known 72PHY chips to provide uniform functionality. 73The module implements status monitoring in either interrupt or polling mode, 74media option handling and application access to PHY registers. 75.Pp 76To use this interface, a driver must implement two functions for reading and 77writing PHY registers, and initialize the following structure with pointers 78to these functions: 79.Bd -literal -offset indent 80struct 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 88The 89.Fn readregs 90function should read PHY registers starting at register 91.Fa reg . 92The maximum number of registers to read is given by the integer pointed 93to by 94.Fa n . 95The function should either return 0 on success, or an error code. 96In the first case, 97.Fa *n 98should be set to the actual number of registers read. 99The 100.Fn writereg 101function should write one register. 102It must change all bits for which the corresponding bit in 103.Fa mask 104is 1 to the value of the corresponding bit in 105.Fa val . 106It returns either 0 on success, or an error code. 107.Pp 108The ATM driver's private state block 109.Pq Va softc 110must begin with a 111.Vt "struct ifatm" . 112.Pp 113The 114.Vt "struct utopia" 115holds the current state of the PHY chip and contains the following fields: 116.Bd -literal -offset indent 117struct 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 131The public accessible fields have the following functions: 132.Bl -tag -width indent 133.It Va ifatm 134Pointer to the driver's private data 135.Pq Va softc . 136.It Va media 137Pointer to the driver's media structure. 138.It Va lock 139Pointer to a mutex provided by the driver. 140This mutex is used to synchronize 141with the kernel thread that handles device polling. 142It is locked in several 143places: 144.Bl -enum -offset indent 145.It 146In 147.Fn utopia_detach 148the mutex is locked to sleep and wait for the kernel thread to remove the 149.Vt "struct utopia" 150from the list of all 151.Nm 152devices. 153Before returning to the caller the mutex is unlocked. 154.It 155In the 156.Nm 157kernel thread the mutex is locked, and the 158.Fn utopia_carrier_update 159function is called with this mutex locked. 160This will result in the driver's 161.Fn readregs 162function being called with the mutex locked. 163.It 164In the sysctl handlers the mutex will be locked before calling into the driver's 165.Fn readreg 166or 167.Fn writereg 168functions. 169.El 170.It Va flags 171Flags set by either the driver or the 172.Nm 173module. 174The following flags are 175defined: 176.Bl -tag -width indent 177.It Dv UTP_FL_NORESET 178If this flag is set, the module will not try to write the 179SUNI master reset register. 180(Set by the driver.) 181.It Dv UTP_FL_POLL_CARRIER 182If 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 187Flags describing the current state of the PHY chip. 188These are managed 189by the module: 190.Bl -tag -width indent 191.It Dv UTP_ST_ACTIVE 192The driver is active and the PHY registers can be accessed. 193This is set by calling 194.Fn utopia_start , 195which should be called either in the attach routine of the driver or 196in the network interface initialisation routine (depending on whether the 197registers are accessible all the time or only when the interface is up). 198.It Dv UTP_ST_SDH 199Interface is in SDH mode as opposed to SONET mode. 200.It Dv UTP_ST_UNASS 201Interface is producing unassigned cells instead of idle cells. 202.It Dv UTP_ST_NOSCRAMB 203Cell scrambling is switched off. 204.It Dv UTP_ST_DETACH 205(Internal use.) 206Interface is currently detaching. 207.It Dv UTP_ST_ATTACHED 208The attach routine has been run successfully. 209.El 210.It Va carrier 211The carrier state of the interface. 212This field can have one of three values: 213.Bl -tag -width indent 214.It Dv UTP_CARR_UNKNOWN 215Carrier state is still unknown. 216.It Dv UTP_CARR_OK 217Carrier has been detected. 218.It Dv UTP_CARR_LOST 219Carrier has been lost. 220.El 221.It Va loopback 222This is the current loopback mode of the interface. 223Note that not all 224chips support all loopback modes. 225Refer to the chip documentation. 226The 227following modes may be supported: 228.Bl -tag -width indent 229.It Dv UTP_LOOP_NONE 230No loopback, normal operation. 231.It Dv UTP_LOOP_TIME 232Timing source loopback. 233The transmitter clock is driven by the receive clock. 234.It Dv UTP_LOOP_DIAG 235Diagnostic loopback. 236.It Dv UTP_LOOP_LINE 237Serial line loopback. 238.It Dv UTP_LOOP_PARAL 239Parallel diagnostic loopback. 240.It Dv UTP_LOOP_TWIST 241Twisted pair diagnostic loopback. 242.It Dv UTP_LOOP_PATH 243Diagnostic path loopback. 244.El 245.It Va chip 246This points to a function vector for chip specific functions. 247Two fields 248in this vector are publicly available: 249.Bl -tag -width indent 250.It Va type 251This is the type of the detected PHY chip. 252One 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 262This is a string with the name of the PHY chip. 263.El 264.El 265.Pp 266The following functions are used by the driver during attach/detach and/or 267initialisation/stopping the interface: 268.Bl -tag -width indent 269.It Fn utopia_attach 270Attach the PHY chip. 271This is called with a preallocated 272.Vt "struct utopia" 273(which may be part of the driver's 274.Va softc ) . 275The module initializes all fields of the 276.Nm 277state and the media field. 278User settable flags should be set after the call to 279.Fn utopia_attach . 280This function may fail due to the inability to install the sysctl handlers. 281In this case it will return \-1. 282On success, 0 is returned and the 283.Dv UTP_ST_ATTACHED 284flag is set. 285.It Fn utopia_detach 286Remove the 287.Nm 288attachment from the system. 289This cancels all outstanding polling 290timeouts. 291.It Fn utopia_start 292Start operation of that PHY. 293This should be called at a time 294when the PHY registers are known to be accessible. 295This may be either in 296the driver's attach function or when the interface is set running. 297.It Fn utopia_stop 298Stop operation of the PHY attachment. 299This may be called either in the detach 300function of the driver or when the interface is brought down. 301.It Fn utopia_init_media 302This must be called if the media field in the ATM MIB was changed. 303The function 304makes sure, that the ifmedia fields contain the same information as the 305ATM MIB. 306.It Fn utopia_reset_media 307This may be called to remove all media information from the ifmedia field. 308.El 309.Pp 310The following functions can be used to modify the PHY state while the interface 311is running: 312.Bl -tag -width indent 313.It Fn utopia_reset 314Reset the operational parameters to the default state (SONET, idle cells, 315scrambling enabled). 316Returns 0 on success, an error code otherwise, leaving 317the state undefined. 318.It Fn utopia_set_sdh 319If the argument is zero the chip is switched to Sonet mode, if it is non-zero 320the chip is switched to SDH mode. 321Returns 0 on success, an error code otherwise, 322leaving the previous state. 323.It Fn utopia_set_unass 324If the argument is zero the chip is switched to produce idle cells, if it is 325non-zero the chip is switched to produce unassigned cells. 326Returns 0 on success, 327an error code otherwise, leaving the previous state. 328.It Fn utopia_set_noscramb 329If the argument is zero enables scrambling, if it is 330non-zero disables scrambling. 331Returns 0 on success, 332an error code otherwise, leaving the previous state. 333.It Fn utopia_update_carrier 334Check the carrier state and update the carrier field in the state structure. 335This will generate a message to the Netgraph stack if the carrier state changes. 336For chips that are polled this is called automatically, for interrupt 337driven attachments this must be called on interrupts from the PHY chip. 338.It Fn utopia_set_loopback 339Set the loopback mode of the chip. 340Returns 0 on success, an error code 341otherwise, leaving the previous state. 342.It Fn utopia_intr 343Called when an interrupt from the PHY chip is detected. 344This resets the 345interrupt state by reading all registers and, if the interrupt was from the 346RSOP, checks the carrier state. 347.It Fn utopia_update_stats 348Update 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 Mt harti@FreeBSD.org 354