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
     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 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
          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 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()
                     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 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
          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 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:
<https://www.freebsd.org/cgi/man.cgi?query=utopia&sektion=9&manpath=FreeBSD+5.2-RELEASE>

home | help