This is a driver for the physical layer chips used in ATM interfaces.

It currently supports the PMC Sierra Lite, Ultra and 622 chips and
the IDT 77105. The driver handles media options and state in a consistent
manner for ATM drivers. The next commit to the midway driver will make
it use utopia.

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 .