utopia (9)

Leading comments

 Copyright (c) 2003
	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
 	All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions an...

(The comments found at the beginning of the groff file "man9/utopia.9freebsd".)

NAME

utopia - driver module for ATM PHY chips

SYNOPSIS

In dev/utopia/utopia.h Ft int Fo utopia_attach Fa struct utopia *utp struct ifatm *ifatm struct ifmedia *media Fa struct mtx *lock struct sysctl_ctx_list *ctx Fa struct sysctl_oid_list *tree const struct utopia_methods *vtab Fc Ft void Fn utopia_detach struct utopia *utp Ft int Fn utopia_start struct utopia *utp Ft void Fn utopia_stop struct utopia *utp Ft void Fn utopia_init_media struct utopia *utp Ft void Fn utopia_reset_media struct utopia *utp Ft int Fn utopia_reset struct utopia *utp Ft int Fn utopia_set_sdh struct utopia *utp int sdh Ft int Fn utopia_set_unass struct utopia *utp int unass Ft int Fn utopia_set_noscramb struct utopia *utp int noscramb Ft int Fn utopia_update_carrier struct utopia *utp Ft int Fn utopia_set_loopback struct utopia *utp u_int mode Ft void Fn utopia_intr struct utopia *utp Ft void Fn 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 Fn readregs function should read PHY registers starting at register Fa reg . The maximum number of registers to read is given by the integer pointed to by Fa n . The function should either return 0 on success, or an error code. In the first case, Fa *n should be set to the actual number of registers read. The Fn writereg function should write one register. It must change all bits for which the corresponding bit in Fa mask is 1 to the value of the corresponding bit in Fa val . It returns either 0 on success, or an error code.

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

The Vt 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 Fn utopia_detach the mutex is locked to sleep and wait for the kernel thread to remove the Vt struct utopia from the list of all ifconfig devices. Before returning to the caller the mutex is unlocked.
2. In the ifconfig kernel thread the mutex is locked, and the Fn utopia_carrier_update function is called with this mutex locked. This will result in the driver's Fn readregs function being called with the mutex locked.
3. In the sysctl handlers the mutex will be locked before calling into the driver's Fn readreg or Fn writereg functions.

flags

Flags set by either the driver or the ifconfig 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 Fn 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:

Fn utopia_attach

Attach the PHY chip. This is called with a preallocated Vt struct utopia (which may be part of the driver's softc ) The module initializes all fields of the ifconfig state and the media field. User settable flags should be set after the call to Fn 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.

Fn utopia_detach

Remove the ifconfig attachment from the system. This cancels all outstanding polling timeouts.

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

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

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

Fn 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:

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

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

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

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

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

Fn utopia_set_loopback

Set the loopback mode of the chip. Returns 0 on success, an error code otherwise, leaving the previous state.

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

Fn utopia_update_stats

Update the statistics with counters read from the chip.

SEE ALSO

utopia(4)

AUTHORS

An Harti Brandt Aq harti@FreeBSD.org