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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
UTOPIA(9)	       FreeBSD 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 red.  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.  Pointer to a mutex pro-
	  vided	by the driver. This mutex is used to synchronize with the ker-
	  nel 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 beeing	called with the	mutex locked.

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

     flags
	  Flags	set by either the driver or the	utopia module. The following
	  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 car-
	       rier 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	man-
	  aged by the module:

	  UTP_ST_ACTIVE
	       The driver is active and	the phy	registers can be accessed.
	       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 reg-
	       isters 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 documenta-
	  tion.	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 the a function vector for	chip specific functions. Two
	  fields in this vector	a publically 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	ini-
	  tializes 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 out-
	  standing 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 contain the same
	  information as the ATM MIB.

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

     The following functions can be used to modify the PHY state while the
     interface is running:

     utopia_reset()
	  Reset	the operational	parameters to the default state	(SONET,	idle
	  cells, scrambling enabled). Returns 0	on success, an error code oth-
	  erwise 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 success, 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 unassigned 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	dis-
	  ables	scrambling. Returns 0 on success, an error code	otherwise
	  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 error
	  code otherwise leaving the previous state.

     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.

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

SEE ALSO
     utopia(4)

AUTHOR
     Harti Brandt <harti@freebsd.org>.

FreeBSD				  May 8, 2003			       FreeBSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR

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

home | help