Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UTOPIA(9)		 BSD Kernel Developer's	Manual		     UTOPIA(9)

NAME
     utopia -- driver module for ATM PHY chips

SYNOPSIS
     #include <dev/utopia/utopia.h>

     int
     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);

     void
     utopia_detach(struct utopia *utp);

     int
     utopia_start(struct utopia	*utp);

     void
     utopia_stop(struct	utopia *utp);

     void
     utopia_init_media(struct utopia *utp);

     void
     utopia_reset_media(struct utopia *utp);

     int
     utopia_reset(struct utopia	*utp);

     int
     utopia_set_sdh(struct utopia *utp,	int sdh);

     int
     utopia_set_unass(struct utopia *utp, int unass);

     int
     utopia_set_noscramb(struct	utopia *utp, int noscramb);

     int
     utopia_update_carrier(struct utopia *utp);

     int
     utopia_set_loopback(struct	utopia *utp, u_int mode);

     void
     utopia_intr(struct	utopia *utp);

     void
     utopia_update_stats(struct	utopia *utp);

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 han-
     dling and application access to PHY registers.

     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:

	   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);
	   };

     The readregs() function should read PHY registers starting	at register
     reg.  The maximum number of registers to read is given by the integer
     pointed to	by n.  The function should either return 0 on success, or an
     error code.  In the first case, *n	should be set to the actual number of
     registers read.  The writereg() function should write one register.  It
     must change all bits for which the	corresponding bit in mask is 1 to the
     value of the corresponding	bit in val.  It	returns	either 0 on success,
     or	an error code.

     The ATM driver's private state block (softc) must begin with a struct
     ifatm.

     The struct	utopia holds the current state of the PHY chip and contains
     the following fields:

	   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 */
		   struct utopia_stats1	stats;	   /* statistics */
	   };
     The public	accessible fields have the following functions:

     ifatm   Pointer to	the driver's private data (softc).

     media   Pointer to	the driver's media structure.

     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:

		   1.	In utopia_detach() the mutex is	locked to sleep	and
			wait for the kernel thread to remove the struct	utopia
			from the list of all utopia devices.  Before returning
			to the caller the mutex	is unlocked.

		   2.	In the utopia kernel thread the	mutex is locked, and
			the utopia_carrier_update() function is	called with
			this mutex locked.  This will result in	the driver's
			readregs() function being called with the mutex
			locked.

		   3.	In the sysctl handlers the mutex will be locked	before
			calling	into the driver's readreg() or writereg()
			functions.

     flags   Flags set by either the driver or the utopia module.  The follow-
	     ing flags are defined:

	     UTP_FL_NORESET
		     If	this flag is set, the module will not try to write the
		     SUNI master reset register.  (Set by the driver.)

	     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.)

     state   Flags describing the current state	of the PHY chip.  These	are
	     managed by	the module:

	     UTP_ST_ACTIVE
		     The driver	is active and the PHY registers	can be ac-
		     cessed.  This is set by calling 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).

	     UTP_ST_SDH
		     Interface is in SDH mode as opposed to SONET mode.

	     UTP_ST_UNASS
		     Interface is producing unassigned cells instead of	idle
		     cells.

	     UTP_ST_NOSCRAMB
		     Cell scrambling is	switched off.

	     UTP_ST_DETACH
		     (Internal use.)  Interface	is currently detaching.

	     UTP_ST_ATTACHED
		     The attach	routine	has been run successfully.

     carrier
	     The carrier state of the interface.  This field can have one of
	     three values:

	     UTP_CARR_UNKNOWN
		     Carrier state is still unknown.

	     UTP_CARR_OK
		     Carrier has been detected.

	     UTP_CARR_LOST
		     Carrier has been lost.

     loopback
	     This is the current loopback mode of the interface.  Note that
	     not all chips support all loopback	modes.	Refer to the chip doc-
	     umentation.  The following	modes may be supported:

	     UTP_LOOP_NONE
		     No	loopback, normal operation.

	     UTP_LOOP_TIME
		     Timing source loopback.  The transmitter clock is driven
		     by	the receive clock.

	     UTP_LOOP_DIAG
		     Diagnostic	loopback.

	     UTP_LOOP_LINE
		     Serial line loopback.

	     UTP_LOOP_PARAL
		     Parallel diagnostic loopback.

	     UTP_LOOP_TWIST
		     Twisted pair diagnostic loopback.

	     UTP_LOOP_PATH
		     Diagnostic	path loopback.

     chip    This points to a function vector for chip specific	functions.
	     Two fields	in this	vector are publicly available:

	     type    This is the type of the detected PHY chip.	 One of:

		     UTP_TYPE_UNKNOWN (0)
		     UTP_TYPE_SUNI_LITE	(1)
		     UTP_TYPE_SUNI_ULTRA (2)
		     UTP_TYPE_SUNI_622 (3)
		     UTP_TYPE_IDT77105 (4)

	     name    This is a string with the name of the PHY chip.

     The following functions are used by the driver during attach/detach
     and/or initialisation/stopping the	interface:

     utopia_attach()
	     Attach the	PHY chip.  This	is called with a preallocated 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
	     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 UTP_ST_ATTACHED flag is set.

     utopia_detach()
	     Remove the	utopia attachment from the system.  This cancels all
	     outstanding polling timeouts.

     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.

     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.

     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	con-
	     tain the same information as the ATM MIB.

     utopia_reset_media()
	     This may be called	to remove all media information	from the ifme-
	     dia field.

     The following functions can be used to modify the PHY state while the in-
     terface is	running:

     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.

     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 suc-
	     cess, an error code otherwise, leaving the	previous state.

     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 unas-
	     signed cells.  Returns 0 on success, an error code	otherwise,
	     leaving the previous state.

     utopia_set_noscramb()
	     If	the argument is	zero enables scrambling, if it is non-zero
	     disables scrambling.  Returns 0 on	success, an error code other-
	     wise, leaving the previous	state.

     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.

     utopia_set_loopback()
	     Set the loopback mode of the chip.	 Returns 0 on success, an er-
	     ror code otherwise, leaving the previous state.

     utopia_intr()
	     Called when an interrupt from the PHY chip	is detected.  This re-
	     sets the interrupt	state by reading all registers and, if the in-
	     terrupt was from the RSOP,	checks the carrier state.

     utopia_update_stats()
	     Update the	statistics with	counters read from the chip.

SEE ALSO
     utopia(4)

AUTHORS
     Harti Brandt <harti@FreeBSD.org>

BSD				  May 8, 2003				   BSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=utopia&sektion=9&manpath=FreeBSD+9.0-RELEASE>

home | help