diff options
Diffstat (limited to 'share/man/man9/utopia.9')
| -rw-r--r-- | share/man/man9/utopia.9 | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/share/man/man9/utopia.9 b/share/man/man9/utopia.9 new file mode 100644 index 0000000..8716bd6 --- /dev/null +++ b/share/man/man9/utopia.9 @@ -0,0 +1,305 @@ +.\" Copyright (c) 2003 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Author: Hartmut Brandt <harti@freebsd.org> +.\" +.\" $FreeBSD$ +.Dd May 8, 2003 +.Dt UTOPIA 9 +.Os FreeBSD +.Sh NAME +.Nm utopia +.Nd Driver module for ATM PHY chips +.Sh SYNOPSIS +.In dev/utopia/utopia.h +.Ft int +.Fn utopia_attach "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media" "struct mtx *lock" "struct sysctl_ctx_list *ctx" "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab" +.Ft void +.Fn utopia_detach "struct utopia *utp" +.Ft int +.Fn utopia_start "struct utopia *utp" +.Ft void +.Fn utopia_stop "struct utopia *utp" +.Ft void +.Fn utopia_init_media "struct utopia *utp" +.Ft void +.Fn utopia_reset_media "struct utopia *utp" +.Ft int +.Fn utopia_reset "struct utopia *utp" +.Ft int +.Fn utopia_set_sdh "struct utopia *utp" "int sdh" +.Ft int +.Fn utopia_set_unass "struct utopia *utp" "int unass" +.Ft int +.Fn utopia_set_noscramb "struct utopia *utp" "int noscramb" +.Ft int +.Fn utopia_update_carrier "struct utopia *utp" +.Ft int +.Fn utopia_set_loopback "struct utopia *utp" "u_int mode" +.Ft void +.Fn utopia_intr "struct utopia *utp" +.Sh DESCRIPTION +This module is used by all ATM drivers for cards that use a number of known +PHY chips to provide uniform functionality. +The module implements status monitoring in either interrupt or polling mode, +media option handling and application access to PHY registers. +.Pp +To use this interface a driver must implement two functions for reading and +writing PHY registers and initialize the following structure with pointers +to these functions: +.Bd -literal -offset indent +struct utopia_methods { + int (*readregs)(struct ifatm *, u_int reg, + uint8_t *val, u_int *n); + int (*writereg)(struct ifatm *, u_int reg, + u_int mask, u_int val); +}; +.Ed +.Pp +The +.Fn readregs +function should read PHY registers starting at register +.Fa reg . +The maximum number of registers to read is given by the integer pointed +to by +.Fa n . +The function should either return 0 on success or an error code. +In the first case +.Fa *n +should be set to the actual number of registers red. +The +.Fn writereg +function should write one register. +It must change all bits for which the corresponding bit in +.Fa mask +is 1 to the value of the corresponding bit in +.Fa val . +It returns either 0 on success or an error code. +.Pp +The ATM driver's private state block (softc) must begin with a +.Vt "struct ifatm" . +.Pp +The +.Vt "struct utopia" +holds the current state of the PHY chip and contains the following fields: +.Bd -literal -offset indent +struct utopia { + struct ifatm *ifatm; /* driver data */ + struct ifmedia *media; /* driver supplied */ + struct mtx *lock; /* driver supplied */ + const struct utopia_methods *methods; + LIST_ENTRY(utopia) link; /* list of these structures */ + u_int flags; /* flags set by the driver */ + u_int state; /* current state */ + u_int carrier; /* carrier state */ + u_int loopback; /* loopback mode */ + const struct utopia_chip *chip; /* chip operations */ +}; +.Ed +The public accessible fields have the following functions: +.Bl -tag -width XXX +.It Va ifatm +Pointer to the driver's private data (softc). +.It Va media +Pointer to the driver's media structure. +.Ir Va lock +Pointer to a mutex provided by the driver. This mutex is used to synchronize +with the kernel thread that handles device polling. It is locked in several +places: +.Bl -enum -offset indent +.It +In +.Fn utopia_detach +the mutex is locked to sleep and wait for the kernel thread to remove the +.Vt "struct utopia" +from the list of all utopia devices. +Before returning to the caller the mutex is unlocked. +.It +In the +.Nm +kernel thread the mutex is locked and the +.Fn utopia_carrier_update +function is called with this mutex locked. +This will result in the driver's +.Fn readregs +function beeing called with the mutex locked. +.It +In the sysctl handlers the mutex will be locked before calling into the driver's +.Fn readreg +or +.Fn writereg +functions. +.El +.It Va flags +Flags set by either the driver or the utopia module. The following flags are +defined: +.Bl -tag -width XXX +.It Dv UTP_FL_NORESET +If this flag is set the module will not try to write the +SUNI master reset register. (set by the driver) +.It Dv UTP_FL_POLL_CARRIER +If this flag is set the module will periodically poll the carrier state +(as opposed to interrupt driven carrier state changes). (set by the driver) +.El +.It Va state +Flags describing the current state of the phy chip. These are managed +by the module: +.Bl -tag -width XXX +.It Dv UTP_ST_ACTIVE +The driver is active and the phy registers can be accessed. +This is set by calling +.Fn utopia_start , +which should be called either in the attach routine of the driver or +in the network interface initialisation routine (depending on whether the +registers are accessible all the time or only when the interface is up). +.It Dv UTP_ST_SDH +Interface is in SDH mode as opposed to SONET mode. +.It Dv UTP_ST_UNASS +Interface is producing unassigned cells instead of idle cells. +.It Dv UTP_ST_NOSCRAMB +Cell scrambling is switched off. +.It Dv UTP_ST_DETACH +(internal use) interface is currently detaching. +.It Dv UTP_ST_ATTACHED +The attach routine has been run successfully. +.El +.It Va carrier +The carrier state of the interface. This field can have one of three values: +.Bl -tag -width XXX +.It Dv UTP_CARR_UNKNOWN +Carrier state is still unknown. +.It Dv UTP_CARR_OK +Carrier has been detected. +.It Dv UTP_CARR_LOST +Carrier has been lost. +.El +.It Va loopback +This is the current loopback mode of the interface. Note, that not all +chips support all loopback modes. Refer to the chip documentation. The +following modes may be supported: +.Bl -tag -width XXX +.It Dv UTP_LOOP_NONE +No loopback, normal operation. +.It Dv UTP_LOOP_TIME +Timing source loopback. The transmitter clock is driven by the receive clock. +.It Dv UTP_LOOP_DIAG +Diagnostic loopback. +.It Dv UTP_LOOP_LINE +Serial line loopback. +.It Dv UTP_LOOP_PARAL +Parallel diagnostic loopback. +.It Dv UTP_LOOP_TWIST +Twisted pair diagnostic loopback. +.It Dv UTP_LOOP_PATH +Diagnostic path loopback. +.El +.It Va chip +This points the a function vector for chip specific functions. Two fields +in this vector a publically available: +.Bl -tag -width XXX +.It Va type +This is the type of the detected PHY chip. +One of: +.Bl -tag -width XXX +.It Dv UTP_TYPE_UNKNOWN (0) +.It Dv UTP_TYPE_SUNI_LITE (1) +.It Dv UTP_TYPE_SUNI_ULTRA (2) +.It Dv UTP_TYPE_SUNI_622 (3) +.It Dv UTP_TYPE_IDT77105 (4) +.El +.It Va name +This is a string with the name of the PHY chip. +.El +.El +.Pp +The following functions are used by the driver during attach/detach and/or +initialisation/stopping the interface: +.Bl -tag -width XXX +.It Fn utopia_attach +Attach the PHY chip. This is called with a preallocated +.Vt "struct utopia" +(which may be part of the driver's softc). +The module initializes all fields of the utopia state and the media field. +User settable flags should be set after the call to +.Fn utopia_attach . +This function may fail due to the inability to install the sysctl handlers. +In this case it will return -1. +On success 0 is returned and the +.Dv UTP_ST_ATTACHED +flag is set. +.It Fn utopia_detach +Remove the utopia attachment from the system. This cancels all outstanding polling +timeouts. +.It Fn utopia_start +Start operation of that PHY. This should be called at a time +when the PHY registers are known to be accessible. This may be either in +the driver's attach function or when the interface is set running. +.It Fn utopia_stop +Stop operation of the PHY attachment. This may be called either in the detach +function of the driver or when the interface is brought down. +.It Fn utopia_init_media +This must be called if the media field in the ATM MIB was changed. The function +makes sure, that the ifmedia fields contain the same information as the +ATM MIB. +.It Fn utopia_reset_media +This may be called to remove all media information from the ifmedia field. +.El +.Pp +The following functions can be used to modify the PHY state while the interface +is running: +.Bl -tag -width XXX +.It Fn utopia_reset +Reset the operational parameters to the default state (SONET, idle cells, +scrambling enabled). Returns 0 on success, an error code otherwise leaving +the state undefined. +.It Fn utopia_set_sdh +If the argument is zero the chip is switched to Sonet mode, if it is non-zero +the chip is switched to SDH mode. Returns 0 on success, an error code otherwise +leaving the previous state. +.It Fn utopia_set_unass +If the argument is zero the chip is switched to produce idle cells, if it is +non-zero the chip is switched to produce unassigned cells. Returns 0 on success, +an error code otherwise leaving the previous state. +.It Fn utopia_set_noscramb +If the argument is zero enables scrambling, if it is +non-zero disables scrambling. Returns 0 on success, +an error code otherwise leaving the previous state. +.It Fn utopia_update_carrier +Check the carrier state and update the carrier field in the state structure. +This will generate a message to the netgraph stack if the carrier state changes. +For chips that are polled this is called automatically, for interrupt +driven attachments this must be called on interrupts from the PHY chip. +.It Fn utopia_set_loopback +Set the loopback mode of the chip. Returns 0 on success, an error code +otherwise leaving the previous state. +.It Fn utopia_intr +Called when an interrupt from the PHY chip is detected. This resets the +interrupt state by reading all registers and, if the interrupt was from the +RSOP, checks the carrier state. +.El +.Sh SEE ALSO +.Xr utopia 4 +.Sh AUTHOR +.An Harti Brandt Aq harti@freebsd.org . |
