| utopia.9 (131681) | utopia.9 (131736) |
|---|---|
| 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 --- 9 unchanged lines hidden (view full) --- 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 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.\" | 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 --- 9 unchanged lines hidden (view full) --- 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 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> | 26.\" Author: Hartmut Brandt <harti@FreeBSD.org> |
| 27.\" | 27.\" |
| 28.\" $FreeBSD: head/share/man/man9/utopia.9 131681 2004-07-06 07:02:31Z ru $ | 28.\" $FreeBSD: head/share/man/man9/utopia.9 131736 2004-07-07 07:56:58Z ru $ 29.\" |
| 29.Dd May 8, 2003 30.Dt UTOPIA 9 31.Os 32.Sh NAME 33.Nm utopia | 30.Dd May 8, 2003 31.Dt UTOPIA 9 32.Os 33.Sh NAME 34.Nm utopia |
| 34.Nd Driver module for ATM PHY chips | 35.Nd "driver module for ATM PHY chips" |
| 35.Sh SYNOPSIS 36.In dev/utopia/utopia.h 37.Ft int | 36.Sh SYNOPSIS 37.In dev/utopia/utopia.h 38.Ft int |
| 38.Fn 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" | 39.Fo utopia_attach 40.Fa "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media" 41.Fa "struct mtx *lock" "struct sysctl_ctx_list *ctx" 42.Fa "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab" 43.Fc |
| 39.Ft void 40.Fn utopia_detach "struct utopia *utp" 41.Ft int 42.Fn utopia_start "struct utopia *utp" 43.Ft void 44.Fn utopia_stop "struct utopia *utp" 45.Ft void 46.Fn utopia_init_media "struct utopia *utp" --- 16 unchanged lines hidden (view full) --- 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, 69media option handling and application access to PHY registers. 70.Pp | 44.Ft void 45.Fn utopia_detach "struct utopia *utp" 46.Ft int 47.Fn utopia_start "struct utopia *utp" 48.Ft void 49.Fn utopia_stop "struct utopia *utp" 50.Ft void 51.Fn utopia_init_media "struct utopia *utp" --- 16 unchanged lines hidden (view full) --- 68.Ft void 69.Fn utopia_update_stats "struct utopia *utp" 70.Sh DESCRIPTION 71This module is used by all ATM drivers for cards that use a number of known 72PHY chips to provide uniform functionality. 73The module implements status monitoring in either interrupt or polling mode, 74media option handling and application access to PHY registers. 75.Pp |
| 71To use this interface a driver must implement two functions for reading and 72writing PHY registers and initialize the following structure with pointers | 76To use this interface, a driver must implement two functions for reading and 77writing PHY registers, and initialize the following structure with pointers |
| 73to these functions: 74.Bd -literal -offset indent 75struct utopia_methods { 76 int (*readregs)(struct ifatm *, u_int reg, 77 uint8_t *val, u_int *n); 78 int (*writereg)(struct ifatm *, u_int reg, 79 u_int mask, u_int val); 80}; 81.Ed 82.Pp 83The 84.Fn readregs 85function should read PHY registers starting at register 86.Fa reg . 87The maximum number of registers to read is given by the integer pointed 88to by 89.Fa n . | 78to these functions: 79.Bd -literal -offset indent 80struct utopia_methods { 81 int (*readregs)(struct ifatm *, u_int reg, 82 uint8_t *val, u_int *n); 83 int (*writereg)(struct ifatm *, u_int reg, 84 u_int mask, u_int val); 85}; 86.Ed 87.Pp 88The 89.Fn readregs 90function should read PHY registers starting at register 91.Fa reg . 92The maximum number of registers to read is given by the integer pointed 93to by 94.Fa n . |
| 90The function should either return 0 on success or an error code. 91In the first case | 95The function should either return 0 on success, or an error code. 96In the first case, |
| 92.Fa *n | 97.Fa *n |
| 93should be set to the actual number of registers red. | 98should be set to the actual number of registers read. |
| 94The 95.Fn writereg 96function should write one register. 97It must change all bits for which the corresponding bit in 98.Fa mask 99is 1 to the value of the corresponding bit in 100.Fa val . | 99The 100.Fn writereg 101function should write one register. 102It must change all bits for which the corresponding bit in 103.Fa mask 104is 1 to the value of the corresponding bit in 105.Fa val . |
| 101It returns either 0 on success or an error code. | 106It returns either 0 on success, or an error code. |
| 102.Pp | 107.Pp |
| 103The ATM driver's private state block (softc) must begin with a | 108The ATM driver's private state block 109.Pq Va softc 110must begin with a |
| 104.Vt "struct ifatm" . 105.Pp 106The 107.Vt "struct utopia" 108holds the current state of the PHY chip and contains the following fields: 109.Bd -literal -offset indent 110struct utopia { 111 struct ifatm *ifatm; /* driver data */ --- 5 unchanged lines hidden (view full) --- 117 u_int state; /* current state */ 118 u_int carrier; /* carrier state */ 119 u_int loopback; /* loopback mode */ 120 const struct utopia_chip *chip; /* chip operations */ 121 struct utopia_stats1 stats; /* statistics */ 122}; 123.Ed 124The public accessible fields have the following functions: | 111.Vt "struct ifatm" . 112.Pp 113The 114.Vt "struct utopia" 115holds the current state of the PHY chip and contains the following fields: 116.Bd -literal -offset indent 117struct utopia { 118 struct ifatm *ifatm; /* driver data */ --- 5 unchanged lines hidden (view full) --- 124 u_int state; /* current state */ 125 u_int carrier; /* carrier state */ 126 u_int loopback; /* loopback mode */ 127 const struct utopia_chip *chip; /* chip operations */ 128 struct utopia_stats1 stats; /* statistics */ 129}; 130.Ed 131The public accessible fields have the following functions: |
| 125.Bl -tag -width XXX | 132.Bl -tag -width indent |
| 126.It Va ifatm | 133.It Va ifatm |
| 127Pointer to the driver's private data (softc). | 134Pointer to the driver's private data 135.Pq Va softc . |
| 128.It Va media 129Pointer to the driver's media structure. | 136.It Va media 137Pointer to the driver's media structure. |
| 130.Ir Va lock | 138.It Va lock |
| 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 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" | 139Pointer to a mutex provided by the driver. 140This mutex is used to synchronize 141with the kernel thread that handles device polling. 142It is locked in several 143places: 144.Bl -enum -offset indent 145.It 146In 147.Fn utopia_detach 148the mutex is locked to sleep and wait for the kernel thread to remove the 149.Vt "struct utopia" |
| 142from the list of all utopia devices. | 150from the list of all 151.Nm 152devices. |
| 143Before returning to the caller the mutex is unlocked. 144.It 145In the 146.Nm | 153Before returning to the caller the mutex is unlocked. 154.It 155In the 156.Nm |
| 147kernel thread the mutex is locked and the | 157kernel 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 151.Fn readregs 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 | 158.Fn utopia_carrier_update 159function is called with this mutex locked. 160This will result in the driver's 161.Fn readregs 162function being called with the mutex locked. 163.It 164In the sysctl handlers the mutex will be locked before calling into the driver's 165.Fn readreg 166or 167.Fn writereg 168functions. 169.El 170.It Va flags |
| 161Flags set by either the driver or the utopia module. | 171Flags set by either the driver or the 172.Nm 173module. |
| 162The following flags are 163defined: | 174The following flags are 175defined: |
| 164.Bl -tag -width XXX | 176.Bl -tag -width indent |
| 165.It Dv UTP_FL_NORESET | 177.It Dv UTP_FL_NORESET |
| 166If this flag is set the module will not try to write the | 178If this flag is set, the module will not try to write the |
| 167SUNI master reset register. | 179SUNI master reset register. |
| 168(set by the driver) | 180(Set by the driver.) |
| 169.It Dv UTP_FL_POLL_CARRIER | 181.It Dv UTP_FL_POLL_CARRIER |
| 170If this flag is set the module will periodically poll the carrier state | 182If this flag is set, the module will periodically poll the carrier state |
| 171(as opposed to interrupt driven carrier state changes). | 183(as opposed to interrupt driven carrier state changes). |
| 172(set by the driver) | 184(Set by the driver.) |
| 173.El 174.It Va state | 185.El 186.It Va state |
| 175Flags describing the current state of the phy chip. | 187Flags describing the current state of the PHY chip. |
| 176These are managed 177by the module: | 188These are managed 189by the module: |
| 178.Bl -tag -width XXX | 190.Bl -tag -width indent |
| 179.It Dv UTP_ST_ACTIVE | 191.It Dv UTP_ST_ACTIVE |
| 180The driver is active and the phy registers can be accessed. | 192The 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 185registers are accessible all the time or only when the interface is up). 186.It Dv UTP_ST_SDH 187Interface is in SDH mode as opposed to SONET mode. 188.It Dv UTP_ST_UNASS 189Interface is producing unassigned cells instead of idle cells. 190.It Dv UTP_ST_NOSCRAMB 191Cell scrambling is switched off. 192.It Dv UTP_ST_DETACH | 193This is set by calling 194.Fn utopia_start , 195which should be called either in the attach routine of the driver or 196in the network interface initialisation routine (depending on whether the 197registers are accessible all the time or only when the interface is up). 198.It Dv UTP_ST_SDH 199Interface is in SDH mode as opposed to SONET mode. 200.It Dv UTP_ST_UNASS 201Interface is producing unassigned cells instead of idle cells. 202.It Dv UTP_ST_NOSCRAMB 203Cell scrambling is switched off. 204.It Dv UTP_ST_DETACH |
| 193(internal use) interface is currently detaching. | 205(Internal use.) 206Interface is currently detaching. |
| 194.It Dv UTP_ST_ATTACHED 195The attach routine has been run successfully. 196.El 197.It Va carrier 198The carrier state of the interface. 199This field can have one of three values: | 207.It Dv UTP_ST_ATTACHED 208The attach routine has been run successfully. 209.El 210.It Va carrier 211The carrier state of the interface. 212This field can have one of three values: |
| 200.Bl -tag -width XXX | 213.Bl -tag -width indent |
| 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 209This is the current loopback mode of the interface. | 214.It Dv UTP_CARR_UNKNOWN 215Carrier state is still unknown. 216.It Dv UTP_CARR_OK 217Carrier has been detected. 218.It Dv UTP_CARR_LOST 219Carrier has been lost. 220.El 221.It Va loopback 222This is the current loopback mode of the interface. |
| 210Note, that not all | 223Note that not all |
| 211chips support all loopback modes. 212Refer to the chip documentation. 213The 214following modes may be supported: | 224chips support all loopback modes. 225Refer to the chip documentation. 226The 227following modes may be supported: |
| 215.Bl -tag -width XXX | 228.Bl -tag -width indent |
| 216.It Dv UTP_LOOP_NONE 217No loopback, normal operation. 218.It Dv UTP_LOOP_TIME 219Timing source loopback. 220The transmitter clock is driven by the receive clock. 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 | 229.It Dv UTP_LOOP_NONE 230No loopback, normal operation. 231.It Dv UTP_LOOP_TIME 232Timing source loopback. 233The transmitter clock is driven by the receive clock. 234.It Dv UTP_LOOP_DIAG 235Diagnostic loopback. 236.It Dv UTP_LOOP_LINE 237Serial line loopback. 238.It Dv UTP_LOOP_PARAL 239Parallel diagnostic loopback. 240.It Dv UTP_LOOP_TWIST 241Twisted pair diagnostic loopback. 242.It Dv UTP_LOOP_PATH 243Diagnostic path loopback. 244.El 245.It Va chip |
| 233This points the a function vector for chip specific functions. | 246This points to a function vector for chip specific functions. |
| 234Two fields 235in this vector are publically available: | 247Two fields 248in this vector are publically available: |
| 236.Bl -tag -width XXX | 249.Bl -tag -width indent |
| 237.It Va type 238This is the type of the detected PHY chip. 239One of: | 250.It Va type 251This is the type of the detected PHY chip. 252One of: |
| 240.Bl -tag -width XXX 241.It Dv UTP_TYPE_UNKNOWN (0) 242.It Dv UTP_TYPE_SUNI_LITE (1) 243.It Dv UTP_TYPE_SUNI_ULTRA (2) 244.It Dv UTP_TYPE_SUNI_622 (3) 245.It Dv UTP_TYPE_IDT77105 (4) | 253.Pp 254.Bl -tag -width indent -compact 255.It Dv UTP_TYPE_UNKNOWN Pq No 0 256.It Dv UTP_TYPE_SUNI_LITE Pq No 1 257.It Dv UTP_TYPE_SUNI_ULTRA Pq No 2 258.It Dv UTP_TYPE_SUNI_622 Pq No 3 259.It Dv UTP_TYPE_IDT77105 Pq No 4 |
| 246.El 247.It Va name 248This is a string with the name of the PHY chip. 249.El 250.El 251.Pp 252The following functions are used by the driver during attach/detach and/or 253initialisation/stopping the interface: | 260.El 261.It Va name 262This is a string with the name of the PHY chip. 263.El 264.El 265.Pp 266The following functions are used by the driver during attach/detach and/or 267initialisation/stopping the interface: |
| 254.Bl -tag -width XXX | 268.Bl -tag -width indent |
| 255.It Fn utopia_attach 256Attach the PHY chip. 257This is called with a preallocated 258.Vt "struct utopia" | 269.It Fn utopia_attach 270Attach the PHY chip. 271This is called with a preallocated 272.Vt "struct utopia" |
| 259(which may be part of the driver's softc). 260The module initializes all fields of the utopia state and the media field. | 273(which may be part of the driver's 274.Va softc ) . 275The module initializes all fields of the 276.Nm 277state and the media field. |
| 261User settable flags should be set after the call to 262.Fn utopia_attach . 263This function may fail due to the inability to install the sysctl handlers. | 278User settable flags should be set after the call to 279.Fn utopia_attach . 280This function may fail due to the inability to install the sysctl handlers. |
| 264In this case it will return -1. 265On success 0 is returned and the | 281In this case it will return \-1. 282On success, 0 is returned and the |
| 266.Dv UTP_ST_ATTACHED 267flag is set. 268.It Fn utopia_detach | 283.Dv UTP_ST_ATTACHED 284flag is set. 285.It Fn utopia_detach |
| 269Remove the utopia attachment from the system. | 286Remove the 287.Nm 288attachment from the system. |
| 270This cancels all outstanding polling 271timeouts. 272.It Fn utopia_start 273Start operation of that PHY. 274This should be called at a time 275when the PHY registers are known to be accessible. 276This may be either in 277the driver's attach function or when the interface is set running. --- 7 unchanged lines hidden (view full) --- 285makes sure, that the ifmedia fields contain the same information as the 286ATM MIB. 287.It Fn utopia_reset_media 288This may be called to remove all media information from the ifmedia field. 289.El 290.Pp 291The following functions can be used to modify the PHY state while the interface 292is running: | 289This cancels all outstanding polling 290timeouts. 291.It Fn utopia_start 292Start operation of that PHY. 293This should be called at a time 294when the PHY registers are known to be accessible. 295This may be either in 296the driver's attach function or when the interface is set running. --- 7 unchanged lines hidden (view full) --- 304makes sure, that the ifmedia fields contain the same information as the 305ATM MIB. 306.It Fn utopia_reset_media 307This may be called to remove all media information from the ifmedia field. 308.El 309.Pp 310The following functions can be used to modify the PHY state while the interface 311is running: |
| 293.Bl -tag -width XXX | 312.Bl -tag -width indent |
| 294.It Fn utopia_reset 295Reset the operational parameters to the default state (SONET, idle cells, 296scrambling enabled). | 313.It Fn utopia_reset 314Reset the operational parameters to the default state (SONET, idle cells, 315scrambling enabled). |
| 297Returns 0 on success, an error code otherwise leaving | 316Returns 0 on success, an error code otherwise, leaving |
| 298the state undefined. 299.It Fn utopia_set_sdh 300If the argument is zero the chip is switched to Sonet mode, if it is non-zero 301the chip is switched to SDH mode. | 317the state undefined. 318.It Fn utopia_set_sdh 319If the argument is zero the chip is switched to Sonet mode, if it is non-zero 320the chip is switched to SDH mode. |
| 302Returns 0 on success, an error code otherwise | 321Returns 0 on success, an error code otherwise, |
| 303leaving the previous state. 304.It Fn utopia_set_unass 305If the argument is zero the chip is switched to produce idle cells, if it is 306non-zero the chip is switched to produce unassigned cells. 307Returns 0 on success, | 322leaving the previous state. 323.It Fn utopia_set_unass 324If the argument is zero the chip is switched to produce idle cells, if it is 325non-zero the chip is switched to produce unassigned cells. 326Returns 0 on success, |
| 308an error code otherwise leaving the previous state. | 327an error code otherwise, leaving the previous state. |
| 309.It Fn utopia_set_noscramb 310If the argument is zero enables scrambling, if it is 311non-zero disables scrambling. 312Returns 0 on success, | 328.It Fn utopia_set_noscramb 329If the argument is zero enables scrambling, if it is 330non-zero disables scrambling. 331Returns 0 on success, |
| 313an error code otherwise leaving the previous state. | 332an error code otherwise, leaving the previous state. |
| 314.It Fn utopia_update_carrier 315Check the carrier state and update the carrier field in the state structure. | 333.It Fn utopia_update_carrier 334Check the carrier state and update the carrier field in the state structure. |
| 316This will generate a message to the netgraph stack if the carrier state changes. | 335This will generate a message to the Netgraph stack if the carrier state changes. |
| 317For chips that are polled this is called automatically, for interrupt 318driven attachments this must be called on interrupts from the PHY chip. 319.It Fn utopia_set_loopback 320Set the loopback mode of the chip. 321Returns 0 on success, an error code | 336For chips that are polled this is called automatically, for interrupt 337driven attachments this must be called on interrupts from the PHY chip. 338.It Fn utopia_set_loopback 339Set the loopback mode of the chip. 340Returns 0 on success, an error code |
| 322otherwise leaving the previous state. | 341otherwise, leaving the previous state. |
| 323.It Fn utopia_intr 324Called when an interrupt from the PHY chip is detected. 325This resets the 326interrupt state by reading all registers and, if the interrupt was from the 327RSOP, checks the carrier state. 328.It Fn utopia_update_stats | 342.It Fn utopia_intr 343Called when an interrupt from the PHY chip is detected. 344This resets the 345interrupt state by reading all registers and, if the interrupt was from the 346RSOP, checks the carrier state. 347.It Fn utopia_update_stats |
| 329Update the statistics with counters red from the chip. | 348Update the statistics with counters read from the chip. |
| 330.El 331.Sh SEE ALSO 332.Xr utopia 4 | 349.El 350.Sh SEE ALSO 351.Xr utopia 4 |
| 333.Sh AUTHOR 334.An Harti Brandt Aq harti@freebsd.org . | 352.Sh AUTHORS 353.An Harti Brandt Aq harti@FreeBSD.org |