Provided by: freebsd-manpages_9.2+1-1_all bug

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 handling 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 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 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 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 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 documentation.  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 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 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 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 disables 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 read from the chip.

SEE ALSO

     utopia(4)

AUTHORS

     Harti Brandt <harti@FreeBSD.org>