| utopia.9 (130843) | utopia.9 (131530) |
|---|---|
| 1.\" Copyright (c) 2003 2.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 11 unchanged lines hidden (view full) --- 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" Author: Hartmut Brandt <harti@freebsd.org> 27.\" | 1.\" Copyright (c) 2003 2.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 11 unchanged lines hidden (view full) --- 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" Author: Hartmut Brandt <harti@freebsd.org> 27.\" |
| 28.\" $FreeBSD: head/share/man/man9/utopia.9 130843 2004-06-21 14:11:45Z mpp $ | 28.\" $FreeBSD: head/share/man/man9/utopia.9 131530 2004-07-03 18:29:24Z ru $ |
| 29.Dd May 8, 2003 30.Dt UTOPIA 9 31.Os FreeBSD 32.Sh NAME 33.Nm utopia 34.Nd Driver module for ATM PHY chips 35.Sh SYNOPSIS 36.In dev/utopia/utopia.h --- 15 unchanged lines hidden (view full) --- 52.Fn utopia_set_sdh "struct utopia *utp" "int sdh" 53.Ft int 54.Fn utopia_set_unass "struct utopia *utp" "int unass" 55.Ft int 56.Fn utopia_set_noscramb "struct utopia *utp" "int noscramb" 57.Ft int 58.Fn utopia_update_carrier "struct utopia *utp" 59.Ft int | 29.Dd May 8, 2003 30.Dt UTOPIA 9 31.Os FreeBSD 32.Sh NAME 33.Nm utopia 34.Nd Driver module for ATM PHY chips 35.Sh SYNOPSIS 36.In dev/utopia/utopia.h --- 15 unchanged lines hidden (view full) --- 52.Fn utopia_set_sdh "struct utopia *utp" "int sdh" 53.Ft int 54.Fn utopia_set_unass "struct utopia *utp" "int unass" 55.Ft int 56.Fn utopia_set_noscramb "struct utopia *utp" "int noscramb" 57.Ft int 58.Fn utopia_update_carrier "struct utopia *utp" 59.Ft int |
| 60.Fn utopia_set_loopback "struct utopia *utp" "u_int mode" | 60.Fn utopia_set_loopback "struct utopia *utp" "u_int mode" |
| 61.Ft void 62.Fn utopia_intr "struct utopia *utp" 63.Ft void 64.Fn utopia_update_stats "struct utopia *utp" 65.Sh DESCRIPTION 66This module is used by all ATM drivers for cards that use a number of known 67PHY chips to provide uniform functionality. 68The module implements status monitoring in either interrupt or polling mode, --- 54 unchanged lines hidden (view full) --- 123.Ed 124The public accessible fields have the following functions: 125.Bl -tag -width XXX 126.It Va ifatm 127Pointer to the driver's private data (softc). 128.It Va media 129Pointer to the driver's media structure. 130.Ir Va lock | 61.Ft void 62.Fn utopia_intr "struct utopia *utp" 63.Ft void 64.Fn utopia_update_stats "struct utopia *utp" 65.Sh DESCRIPTION 66This module is used by all ATM drivers for cards that use a number of known 67PHY chips to provide uniform functionality. 68The module implements status monitoring in either interrupt or polling mode, --- 54 unchanged lines hidden (view full) --- 123.Ed 124The public accessible fields have the following functions: 125.Bl -tag -width XXX 126.It Va ifatm 127Pointer to the driver's private data (softc). 128.It Va media 129Pointer to the driver's media structure. 130.Ir Va lock |
| 131Pointer to a mutex provided by the driver. This mutex is used to synchronize 132with the kernel thread that handles device polling. It is locked in several | 131Pointer to a mutex provided by the driver. 132This mutex is used to synchronize 133with the kernel thread that handles device polling. 134It is locked in several |
| 133places: 134.Bl -enum -offset indent 135.It 136In 137.Fn utopia_detach 138the mutex is locked to sleep and wait for the kernel thread to remove the 139.Vt "struct utopia" 140from the list of all utopia devices. 141Before returning to the caller the mutex is unlocked. 142.It 143In the 144.Nm 145kernel thread the mutex is locked and the 146.Fn utopia_carrier_update 147function is called with this mutex locked. 148This will result in the driver's | 135places: 136.Bl -enum -offset indent 137.It 138In 139.Fn utopia_detach 140the mutex is locked to sleep and wait for the kernel thread to remove the 141.Vt "struct utopia" 142from the list of all utopia devices. 143Before returning to the caller the mutex is unlocked. 144.It 145In the 146.Nm 147kernel thread the mutex is locked and the 148.Fn utopia_carrier_update 149function is called with this mutex locked. 150This will result in the driver's |
| 149.Fn readregs | 151.Fn readregs |
| 150function being called with the mutex locked. 151.It 152In the sysctl handlers the mutex will be locked before calling into the driver's 153.Fn readreg 154or 155.Fn writereg 156functions. 157.El 158.It Va flags | 152function being called with the mutex locked. 153.It 154In the sysctl handlers the mutex will be locked before calling into the driver's 155.Fn readreg 156or 157.Fn writereg 158functions. 159.El 160.It Va flags |
| 159Flags set by either the driver or the utopia module. The following flags are | 161Flags set by either the driver or the utopia module. 162The following flags are |
| 160defined: 161.Bl -tag -width XXX 162.It Dv UTP_FL_NORESET 163If this flag is set the module will not try to write the | 163defined: 164.Bl -tag -width XXX 165.It Dv UTP_FL_NORESET 166If this flag is set the module will not try to write the |
| 164SUNI master reset register. (set by the driver) | 167SUNI master reset register. 168(set by the driver) |
| 165.It Dv UTP_FL_POLL_CARRIER 166If this flag is set the module will periodically poll the carrier state | 169.It Dv UTP_FL_POLL_CARRIER 170If this flag is set the module will periodically poll the carrier state |
| 167(as opposed to interrupt driven carrier state changes). (set by the driver) | 171(as opposed to interrupt driven carrier state changes). 172(set by the driver) |
| 168.El 169.It Va state | 173.El 174.It Va state |
| 170Flags describing the current state of the phy chip. These are managed | 175Flags describing the current state of the phy chip. 176These are managed |
| 171by the module: 172.Bl -tag -width XXX 173.It Dv UTP_ST_ACTIVE 174The driver is active and the phy registers can be accessed. 175This is set by calling 176.Fn utopia_start , 177which should be called either in the attach routine of the driver or 178in the network interface initialisation routine (depending on whether the --- 5 unchanged lines hidden (view full) --- 184.It Dv UTP_ST_NOSCRAMB 185Cell scrambling is switched off. 186.It Dv UTP_ST_DETACH 187(internal use) interface is currently detaching. 188.It Dv UTP_ST_ATTACHED 189The attach routine has been run successfully. 190.El 191.It Va carrier | 177by the module: 178.Bl -tag -width XXX 179.It Dv UTP_ST_ACTIVE 180The driver is active and the phy registers can be accessed. 181This is set by calling 182.Fn utopia_start , 183which should be called either in the attach routine of the driver or 184in the network interface initialisation routine (depending on whether the --- 5 unchanged lines hidden (view full) --- 190.It Dv UTP_ST_NOSCRAMB 191Cell scrambling is switched off. 192.It Dv UTP_ST_DETACH 193(internal use) interface is currently detaching. 194.It Dv UTP_ST_ATTACHED 195The attach routine has been run successfully. 196.El 197.It Va carrier |
| 192The carrier state of the interface. This field can have one of three values: | 198The carrier state of the interface. 199This field can have one of three values: |
| 193.Bl -tag -width XXX 194.It Dv UTP_CARR_UNKNOWN 195Carrier state is still unknown. 196.It Dv UTP_CARR_OK 197Carrier has been detected. 198.It Dv UTP_CARR_LOST 199Carrier has been lost. 200.El 201.It Va loopback | 200.Bl -tag -width XXX 201.It Dv UTP_CARR_UNKNOWN 202Carrier state is still unknown. 203.It Dv UTP_CARR_OK 204Carrier has been detected. 205.It Dv UTP_CARR_LOST 206Carrier has been lost. 207.El 208.It Va loopback |
| 202This is the current loopback mode of the interface. Note, that not all 203chips support all loopback modes. Refer to the chip documentation. The | 209This is the current loopback mode of the interface. 210Note, that not all 211chips support all loopback modes. 212Refer to the chip documentation. 213The |
| 204following modes may be supported: 205.Bl -tag -width XXX 206.It Dv UTP_LOOP_NONE 207No loopback, normal operation. 208.It Dv UTP_LOOP_TIME | 214following modes may be supported: 215.Bl -tag -width XXX 216.It Dv UTP_LOOP_NONE 217No loopback, normal operation. 218.It Dv UTP_LOOP_TIME |
| 209Timing source loopback. The transmitter clock is driven by the receive clock. | 219Timing source loopback. 220The transmitter clock is driven by the receive clock. |
| 210.It Dv UTP_LOOP_DIAG 211Diagnostic loopback. 212.It Dv UTP_LOOP_LINE 213Serial line loopback. 214.It Dv UTP_LOOP_PARAL 215Parallel diagnostic loopback. 216.It Dv UTP_LOOP_TWIST 217Twisted pair diagnostic loopback. 218.It Dv UTP_LOOP_PATH 219Diagnostic path loopback. 220.El 221.It Va chip | 221.It Dv UTP_LOOP_DIAG 222Diagnostic loopback. 223.It Dv UTP_LOOP_LINE 224Serial line loopback. 225.It Dv UTP_LOOP_PARAL 226Parallel diagnostic loopback. 227.It Dv UTP_LOOP_TWIST 228Twisted pair diagnostic loopback. 229.It Dv UTP_LOOP_PATH 230Diagnostic path loopback. 231.El 232.It Va chip |
| 233<<<<<<< utopia.9 234This points the a function vector for chip specific functions. 235Two fields 236in this vector a publically available: 237======= |
|
| 222This points the a function vector for chip specific functions. Two fields 223in this vector are publicly available: | 238This points the a function vector for chip specific functions. Two fields 239in this vector are publicly available: |
| 240>>>>>>> 1.3 |
|
| 224.Bl -tag -width XXX 225.It Va type 226This is the type of the detected PHY chip. 227One of: 228.Bl -tag -width XXX 229.It Dv UTP_TYPE_UNKNOWN (0) 230.It Dv UTP_TYPE_SUNI_LITE (1) 231.It Dv UTP_TYPE_SUNI_ULTRA (2) --- 4 unchanged lines hidden (view full) --- 236This is a string with the name of the PHY chip. 237.El 238.El 239.Pp 240The following functions are used by the driver during attach/detach and/or 241initialisation/stopping the interface: 242.Bl -tag -width XXX 243.It Fn utopia_attach | 241.Bl -tag -width XXX 242.It Va type 243This is the type of the detected PHY chip. 244One of: 245.Bl -tag -width XXX 246.It Dv UTP_TYPE_UNKNOWN (0) 247.It Dv UTP_TYPE_SUNI_LITE (1) 248.It Dv UTP_TYPE_SUNI_ULTRA (2) --- 4 unchanged lines hidden (view full) --- 253This is a string with the name of the PHY chip. 254.El 255.El 256.Pp 257The following functions are used by the driver during attach/detach and/or 258initialisation/stopping the interface: 259.Bl -tag -width XXX 260.It Fn utopia_attach |
| 244Attach the PHY chip. This is called with a preallocated | 261Attach the PHY chip. 262This is called with a preallocated |
| 245.Vt "struct utopia" 246(which may be part of the driver's softc). 247The module initializes all fields of the utopia state and the media field. 248User settable flags should be set after the call to 249.Fn utopia_attach . 250This function may fail due to the inability to install the sysctl handlers. 251In this case it will return -1. 252On success 0 is returned and the 253.Dv UTP_ST_ATTACHED 254flag is set. 255.It Fn utopia_detach | 263.Vt "struct utopia" 264(which may be part of the driver's softc). 265The module initializes all fields of the utopia state and the media field. 266User settable flags should be set after the call to 267.Fn utopia_attach . 268This function may fail due to the inability to install the sysctl handlers. 269In this case it will return -1. 270On success 0 is returned and the 271.Dv UTP_ST_ATTACHED 272flag is set. 273.It Fn utopia_detach |
| 256Remove the utopia attachment from the system. This cancels all outstanding polling | 274Remove the utopia attachment from the system. 275This cancels all outstanding polling |
| 257timeouts. 258.It Fn utopia_start | 276timeouts. 277.It Fn utopia_start |
| 259Start operation of that PHY. This should be called at a time 260when the PHY registers are known to be accessible. This may be either in | 278Start operation of that PHY. 279This should be called at a time 280when the PHY registers are known to be accessible. 281This may be either in |
| 261the driver's attach function or when the interface is set running. 262.It Fn utopia_stop | 282the driver's attach function or when the interface is set running. 283.It Fn utopia_stop |
| 263Stop operation of the PHY attachment. This may be called either in the detach | 284Stop operation of the PHY attachment. 285This may be called either in the detach |
| 264function of the driver or when the interface is brought down. 265.It Fn utopia_init_media | 286function of the driver or when the interface is brought down. 287.It Fn utopia_init_media |
| 266This must be called if the media field in the ATM MIB was changed. The function | 288This must be called if the media field in the ATM MIB was changed. 289The function |
| 267makes sure, that the ifmedia fields contain the same information as the 268ATM MIB. 269.It Fn utopia_reset_media 270This may be called to remove all media information from the ifmedia field. 271.El 272.Pp 273The following functions can be used to modify the PHY state while the interface 274is running: 275.Bl -tag -width XXX 276.It Fn utopia_reset 277Reset the operational parameters to the default state (SONET, idle cells, | 290makes sure, that the ifmedia fields contain the same information as the 291ATM MIB. 292.It Fn utopia_reset_media 293This may be called to remove all media information from the ifmedia field. 294.El 295.Pp 296The following functions can be used to modify the PHY state while the interface 297is running: 298.Bl -tag -width XXX 299.It Fn utopia_reset 300Reset the operational parameters to the default state (SONET, idle cells, |
| 278scrambling enabled). Returns 0 on success, an error code otherwise leaving | 301scrambling enabled). 302Returns 0 on success, an error code otherwise leaving |
| 279the state undefined. 280.It Fn utopia_set_sdh 281If the argument is zero the chip is switched to Sonet mode, if it is non-zero | 303the state undefined. 304.It Fn utopia_set_sdh 305If the argument is zero the chip is switched to Sonet mode, if it is non-zero |
| 282the chip is switched to SDH mode. Returns 0 on success, an error code otherwise | 306the chip is switched to SDH mode. 307Returns 0 on success, an error code otherwise |
| 283leaving the previous state. 284.It Fn utopia_set_unass 285If the argument is zero the chip is switched to produce idle cells, if it is | 308leaving the previous state. 309.It Fn utopia_set_unass 310If the argument is zero the chip is switched to produce idle cells, if it is |
| 286non-zero the chip is switched to produce unassigned cells. Returns 0 on success, | 311non-zero the chip is switched to produce unassigned cells. 312Returns 0 on success, |
| 287an error code otherwise leaving the previous state. 288.It Fn utopia_set_noscramb 289If the argument is zero enables scrambling, if it is | 313an error code otherwise leaving the previous state. 314.It Fn utopia_set_noscramb 315If the argument is zero enables scrambling, if it is |
| 290non-zero disables scrambling. Returns 0 on success, | 316non-zero disables scrambling. 317Returns 0 on success, |
| 291an error code otherwise leaving the previous state. 292.It Fn utopia_update_carrier 293Check the carrier state and update the carrier field in the state structure. 294This will generate a message to the netgraph stack if the carrier state changes. 295For chips that are polled this is called automatically, for interrupt 296driven attachments this must be called on interrupts from the PHY chip. 297.It Fn utopia_set_loopback | 318an error code otherwise leaving the previous state. 319.It Fn utopia_update_carrier 320Check the carrier state and update the carrier field in the state structure. 321This will generate a message to the netgraph stack if the carrier state changes. 322For chips that are polled this is called automatically, for interrupt 323driven attachments this must be called on interrupts from the PHY chip. 324.It Fn utopia_set_loopback |
| 298Set the loopback mode of the chip. Returns 0 on success, an error code | 325Set the loopback mode of the chip. 326Returns 0 on success, an error code |
| 299otherwise leaving the previous state. 300.It Fn utopia_intr | 327otherwise leaving the previous state. 328.It Fn utopia_intr |
| 301Called when an interrupt from the PHY chip is detected. This resets the | 329Called when an interrupt from the PHY chip is detected. 330This resets the |
| 302interrupt state by reading all registers and, if the interrupt was from the 303RSOP, checks the carrier state. 304.It Fn utopia_update_stats 305Update the statistics with counters red from the chip. 306.El 307.Sh SEE ALSO 308.Xr utopia 4 309.Sh AUTHOR 310.An Harti Brandt Aq harti@freebsd.org . | 331interrupt state by reading all registers and, if the interrupt was from the 332RSOP, checks the carrier state. 333.It Fn utopia_update_stats 334Update the statistics with counters red from the chip. 335.El 336.Sh SEE ALSO 337.Xr utopia 4 338.Sh AUTHOR 339.An Harti Brandt Aq harti@freebsd.org . |