5 files changed, 442 insertions, 1 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 8171ba2..a7b0d57 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -256,6 +256,7 @@ MAN=	aac.4 \
 	urio.4 \
 	usb.4 \
 	uscanner.4 \
+	utopia.4 \
 	uvisor.4 \
 	uvscom.4 \
 	vga.4 \
diff --git a/share/man/man4/utopia.4 b/share/man/man4/utopia.4
new file mode 100644
index 0000000..ff93994
--- /dev/null
+++ b/share/man/man4/utopia.4
@@ -0,0 +1,131 @@
+.\" 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 4
+.Os FreeBSD
+.Sh NAME
+.Nm utopia
+.Nd Driver module for ATM PHY chips
+.Sh SYNOPSIS
+.Cd device utopia
+.Sh DESCRIPTION
+This module is used by all ATM drivers for cards that use S/Uni and IDT77105
+chips to provide uniform functionality.
+The module implements status monitoring
+in either interrupt or polling mode, media option handling and application
+access to chip registers.
+.Pp
+The driver implements several sysctls that accessible under the
+.Cm hw.atm.XXX
+tree, where
+.Cm XXX
+is the name of the ATM interface:
+.Bl -tag -width XXX
+.It Cm phy_regs
+When reading this sysctl an array of 8-bit unsigned integers is returned
+containing all accessible chip registers starting at register 0.
+A register can be written by writing three 8-bit unsigned integers to the
+sysctl: the register number, the new value and a bit mask.
+This changes all bits in the register for which the corresponding bit in the
+mask is one to the bit values from value.
+Note, that not all registers may
+be writeable.
+.It Cm phy_loopback
+allows to put the interface in one of several loopback modes.
+Not all modes and all combinations of modes are supported on all chips.
+The possible modes are:
+.Bl -tag -width XXX
+.It Dv UTP_LOOP_NONE (0x00)
+No loopback, normal operation.
+.It Dv UTP_LOOP_TIME (0x01)
+Timing source loopback. When this is set the transmitter's clock is
+derived from the receiver's clock.
+.It Dv UTP_LOOP_DIAG (0x02)
+Diagnostic loopback. In this mode the receiver's input is connected to the
+transmitter's output. The receiver gets back everything that is sent. The
+transmitter operates normally.
+.It Dv UTP_LOOP_LINE (0x04)
+Serial line loopback. This connects the line receiver to the line transmitter.
+The chip transmits all cells back that it receives. The receiver operates
+normally.
+.It Dv UTP_LOOP_PARAL (0x08)
+Parallel diagnostic loopback. This feeds back all transmitted cells into the
+receiver between the parallel/serial converters. The transmitter
+operates normally.
+.It Dv UTP_LOOP_TWIST (0x10)
+Twisted pair diagnostic loopback. Connects the high speed receive data to the
+high speed transmit data. All received data is sent back. The receiver
+operates normally.
+.It Dv UTP_LOOP_PATH (0x20)
+Diagnostic path loopback. This connectes the receiver input to the transmitter
+output just between the path overhead processor and the byte mux. The
+transmitter operates normally.
+.El
+.It Cm phy_type
+This is the detected type of the phy chip. Currently the following chips are
+supported:
+.Bl -tag -width XXX
+.It Dv UTP_TYPE_UNKNOWN (0)
+The module could not determine the type of the PHY chip.
+.It Dv UTP_TYPE_SUNI_LITE (1)
+PMC-5346 (S/Uni-Lite)
+.It Dv UTP_TYPE_SUNI_ULTRA (2)
+PMC-5350 (S/Uni-Ultra)
+.It Dv UTP_TYPE_SUNI_622 (3)
+PMC-5355 (S/Uni-622)
+.It Dv UTP_TYPE_IDT77105 (4)
+IDT77105 (25.6MBit UTP interface)
+.El
+.It Cm phy_name
+This is a string describing the type of the PHY chip.
+.El
+.Pp
+The
+.Nm
+module also interfaces with the ifmedia system.
+The module reports the current state of the carrier and will issue a
+warning message when the carrier state changes.
+While the physical media itself cannot be changed, several media options can:
+.Bl -tag -width XXX
+.It Cm SDH
+If the PHY is a S/Uni this flag switches the interface into SDH mode.
+If this option is not set (the default) the interface is in Sonet mode.
+.It Cm noscramb
+If the PHY is a S/Uni disable scrambling.
+This may be useful for debugging purposes.
+.It Cm unassigned
+Normally the interface emits idle cells when there are no other cells to
+transmit. This changes the default cell type to unassigned cells. This
+may be needed for interworking with public networks. Works only for S/Unis.
+.El
+.Sh SEE ALSO
+.Xr en 4,
+.Xr utopia 9
+.Sh AUTHOR
+.An Harti Brandt Aq harti@freebsd.org .
diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7
index de7c2f3..1c08fe8 100644
--- a/share/man/man7/hier.7
+++ b/share/man/man7/hier.7
@@ -189,6 +189,10 @@ see
 .Xr ppbus 4
 .It Pa usb/
 The USB subsystem
+.It Pa utopia/
+Physical chip driver for ATM interfaces;
+see
+.Xr utopia 4
 .It Pa wi/
 The
 .Xr wi 4
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index a511017..85c2bc4 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -66,7 +66,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	spl.9 store.9 style.9 suser.9 swi.9 sx.9 \
 	sysctl_add_oid.9 sysctl_ctx_init.9 \
 	taskqueue.9 thread_exit.9 time.9 timeout.9 tvtohz.9 \
-	ucred.9 uidinfo.9 uio.9 \
+	ucred.9 uidinfo.9 uio.9 utopia.9 \
 	vaccess.9 vaccess_acl_posix1e.9 vcount.9 \
 	vfs_busy.9 vfs_getnewfsid.9 vfs_getvfs.9 \
 	vfs_mount.9 vfs_mountedon.9 vfs_rootmountalloc.9 \
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 .