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 mod
ule 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 ac
tual 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 sup
plied */
struct mtx *lock; /* driver sup
plied */
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 opera
tions */
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 mu
tex is used to
synchronize with the kernel thread that handles de
vice 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. Be
fore 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 period
ically 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 rou
tine of the
driver or in the network interface initiali
sation routine
(depending on whether the registers are ac
cessible 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 in
stead of idle
cells.
UTP_ST_NOSCRAMB
Cell scrambling is switched off.
UTP_ST_DETACH
(Internal use.) Interface is currently de
taching.
UTP_ST_ATTACHED
The attach routine has been run successful
ly.
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 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 at
tach/detach
and/or initialisation/stopping the interface:
utopia_attach()
Attach the PHY chip. This is called with a preallo
cated 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 in
terface 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 suc
cess, 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. Re
turns 0 on success, an error code otherwise, leaving the previous
state.
utopia_set_unass()
If the argument is zero the chip is switched to pro
duce 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 Net
graph stack if
the carrier state changes. For chips that are
polled this is
called automatically, for interrupt driven attach
ments 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 de
tected. 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>
BSD May 8, 2003
Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout