path: root/sbin/sconfig/sconfig.8

.\" $FreeBSD$
.Dd November 21, 2003
.Dt SCONFIG 8
.Os FreeBSD
.Sh NAME
.Nm sconfig
.Nd channel configuration utility for Cronyx adapters
.Sh SYNOPSIS
.Nm
.Op Fl aimsxeftuc
.Op Ar device name
.Op Ar data rate options
.Op Ar protocol options ...
.Op Ar interface options ...
.Sh DESCRIPTION
The
.Nm
utility is used for configuring the channel options of the Cronyx
adapters. In asynchronous mode all the parameters should be set by standard
.Xr stty 1
utility, with
.Nm
you could set only few of them (see below).
.Pp
Some of the options could be set only on free channels, that is the
corresponding network interface in 
.Ar down
state in the synchronous mode, and in the asynchronous mode the asynchronous
terminal device
.Pa /dev/tty*
closed.
.Pp
Other channel options could be changed
.Do on the fly
.Dc .
Generally, the channel options are set up during the operating system startup,
for example from the
.Pa /etc/rc
file.
.Pp
Note, that not all options have a sense for every particular
case, and an attempt to set some of them can hang up the channel or
the whole adapter.
.\"--------------------------------------------------------------
.Ss "Information options"
You can specify only one of these options. If information option is specified,
sconfig will show corresponding information and will ignore all other options,
except
.Ar device name.
See also description of the 
.Ar device name.
.Bl -tag -width 10n
.It <none>
This will show settings of the channel.
.It Fl a
Print all settings of the channel.
.It Fl i
Print interface settings, equal to the output of
.Xr ifconfig 1
command.
.It Fl m
Print modem signal status. The description of all signals can be found in
any document related to the modems. Only LE signal should be described. If
this signal is On, than some what use channel. If it is Off, than channel is
free.
.It Fl s
Print brief channel statistics. This is general statistics. See also
.Fl x
,
.Fl e
,
.Fl f
,
.Fl t
and
.Fl u
options. For the description of output, see below.
.Pp
This statistics is very useful if something goes wrong. For example, if you
have no any interrupts, than you use interrupt that is not registered in BIOS
for use with ISA bus.
.It Fl x
Print full channel statistics. This options allows to see some more counters,
but with less precision than with
.Pa -s
option.
.It Fl e
Print brief E1/G703 statistics. If you select this option, you will get
statistics accumulated for period of time equal to 15 minutes. For the
description of output, see below.
.It Fl f
Print full E1/G703 statistics. This option shows all E1/G703 statistics that
shows previous option(
.Fl e
), but also total statistics for whole period of time and statistics for 24
hours (if available). For the description of output, see below.
.It Fl t
Print brief E3/T3/STS-1 statistics. If you select this option, you will
get statistics accumulated for period of time equal to 15 minutes. For
the description of output, see below.
.It Fl u
Print full E3/T3/STS-1 statistics. This option shows all E3/T3/STS-1
statistics that shows previous option(
.Fl t
), but also total statistics for whole period of time and statistics for 24
hours (if available). For the description of output, see below.
.It Fl c
Cleans all kind of statistics. 
.El
.\"--------------------------------------------------------------
.Ss "Device selection"
Device is equal to the name of the interface that is used for a name of
the interface that is sees
.Nm ifconfig.
The channel number depends on the order of loading drivers by the system.
Some times people confuse channel number and adapter number because of the
same spelling. Adapter number appears in kernel context, channel number
in configuration context.
.Bl -tag -width 10n
.It <none>
You can omit device name only if you want to get information. This will cause
printing information about all available channels of Cronyx adapters. In the
case you want to make some settings you MUST specify device name.
.It cx##
This is the channel name for the Sigma family of Cronyx adapters. (ISA bus)
.It ct##
This is the channel name for the Tau family of Cronyx adapters. (ISA bus)
.It cp##
This is the channel name for the Tau-PCI family of Cronyx adapters. (PCI bus)
.It ce##
This is the channel name for the Tau32-PCI family of Cronyx adapters. (PCI bus)
.El
.\"--------------------------------------------------------------
.Ss "Data rate options"
.Bl -tag -width 10n
.It value
If case of nonzero value it will cause setting data rate to given value and
setting the internal clock source of the synchronization (in synchronous mode).
Zero value is equal to the
.Ar extclock.
The transmitted data (TXD) are synchronized using the internal on-board timing
generator, the internally generated timing signal is driven on the TXCOUT pin,
and the signal on the TXCIN pin is ignored. This mode is used for direct
terminal-to-terminal communication, e.g. for connecting two computers together
in a synchronous mode via relatively short cable.  This method should also be
used for testing channels with an external loopback connector.
.It extclock
Set the external timing clock source of synchronous channels. External clock
mode is the most common method for connecting external modem hardware. In this
mode the external timing signal is received on TXCIN pin of the connector,
and it is used as a synchronization clock for transmitting data (TXD).
.El
.\"--------------------------------------------------------------
.Ss "Protocol options"
Note. These option could be set only if channel is free and they requires
specifying of the device name.
.Bl -tag -width 10n
.It async
Set asynchronous protocol (or mode). In this mode Cronyx adapters behave as a
usual serial devices and you may work with them using usual serial utilities.
All asynchronous settings are performed via serial configuration utilities. With
.Nm sconfig
you may set only a few of them. See also
.Xr stty 1 .
(Only for Sigma family)
.It cisco
Set the Cisco HDLC synchronous protocol.
.It fr
Set the Frame Relay synchronous protocol (ANSI T1.617 Annex D).
.It ppp
Set the PPP synchronous protocol. Parameters to the PPP could be set by the
command
.Xr spppcontrol 1 .
.It keepalive=on, keepalive=off
Turns on/off sending keepalive messages. This option is used only for
synchronous PPP. If this option is on, than PPP will periodically send
echo-request messages. If it would not receive any echo-reply messages for
some (definite) period of time it will break connection. It is used for
tracking line state.
.It idle
You are using NETGRAPH. Protocol depends on connected module.
.El
.\"--------------------------------------------------------------
.Ss "Interface options"
Not all of these options could be set on running channel and not all of them
are suits to all kind of adapters/channels. In all dual state options off is
default value. All this options is not applicable in asynchronous mode, except
debug option.
.Bl -tag -width 10n
.It port=rs232, port=v35, port=rs449
Set port type for old Sigma models. 
.It cfg=A, cfg=B, cfg=C
Set configuration for the adapter. This option could be set only for Tau/E1
and Tau/G703 and only if all channels are not running.
.Ar cfg=A
- Two independent E1/G703 channels. This is default setting.
.Ar cfg=B (Only for ISA models)
- For Tau/G703 this mean one G703 channel and one digital channel.
For Tau/E1 first physical channel divides on to subchannels. One of them
goes to the first logical channel and another one goes to the second physical
channel. Second (logical) channel is digital channel.
.Ar cfg=C
- This configuration is used only for E1 models. In this case first
physical channel consists of three data flows. Two of them go to two
(logical) channels. The last one goes to the second physical channel. On new
models (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1) this configuration means single source
of synchronization and passing all unused (in both channels) timeslots from
one channel to other. For the detailed description of the configuration see
your documentation to the adapter. This option could not be set on running
channel.
.It loop=on, loop=off
Turn on/off internal loopback. This mode is useful for testing. Switch on this
option and try to send something. If you have no any interrupt, than, probably,
you forgot to switch using IRQ for PCI to ISA bus. Check your BIOS settings.
.It rloop=on, rloop=off (Only for Tau32-PCI and Tau-PCI/E3)
Turn on/off remote loopback. This mode is also useful for testing.
.It dpll=on, dpll=off
Turn on/off digital phase locked loop mode (DPLL). When enabled, the receiver
timing clock signal is derived from the received data. Must be used with NRZI
encoding, to avoid the synchronization loss.
.It nrzi=on, nrzi=off
Turn on/off nrzi encoding. In off state nrz encoding is used. NRZ - the zero
bit is transmitted by the zero signal level, the one bit - by the positive
signal level. NRZI - the bit number zero is transmitted by the change of the
signal level, the one bit - by the constant signal level. Commonly is used with
dpll=on option.
.It invclk=on, invclk=off
Invert the both transmit and receive clock signals (Tau and Tau-PCI only).
.It invrclk=on, invrclk=off
Invert the receive clock signals (Tau-PCI only).
.It invtclk=on, invtclk=off
Invert the transmit clock signals (Tau-PCI only).
.It higain=on, higain=off
Turn on/off increasing the E1 receiver non linear sensitivity to -30 dB (E1
only). In of state the sensitivity is -12 dB. This allows increasing line
distance.
.It cablen=on, cablen=off (Only for Tau-PCI/T3 and Tau-PCI/STS-1)
Turn on/off adjusting transmit signal for long cable T3/STS-1.
.It monitor=on, monitor=off
Turn on/off increasing the E1 receiver lines sensitivity to -30 dB
(Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only). This could be used for interception
purposes.
.It phony=on, phony=off
Turn on/off the so-called phony mode (Tau32-PCI and Tau-PCI E1 family only). This mode allows
receiving raw CEPT frames from E1 line. Raw frames could be accessed, for
example, via raw protocol. Packets would come at rate of 500 frames per second
with length 16xN (for Tau-PCI/E1 model), where N is the number of timeslots. For
Tau-PCI/2E1 and Tau-PCI/4E1 N should be equal to 32 independently from number of
used timeslots.
.It unfram=on, unfram=off
Turn on/off unframed mode (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only).
.Ar unfram=on
switches channel to unframed G.703 mode.
.Ar unfram=off
switches channel to framed E1 (G.704 mode). 
.It scrambler=on, scrambler=off
Turn on/off the scrambling of G.703 data (Tau32-PCI, Tau-PCI/G.703 and Tau-PCI/2E1,
Tau-PCI/4E1 in unframed mode only).
.It use16=on, use16=off
Turn on/off the usage of 16-th timeslot for data transmission (Tau32-PCI and Tau-PCI E1 family only).
Normally 16-th timeslot is used for signaling information (multiframing CAS).
.It crc4=on, crc4=off
Turn on/off CRC4 superframe mode (E1 only). 
.It syn=int, syn=rcv, syn=rcv0, syn=rcv1, syn=rcv2, sync=rcv3
.Ar int
- use an internal clock generator for G703 transmitter
(clock master). 
.Ar rcv
- use the G703 receiver data clock as the transmit clock
(clock slave). 
.Ar rcv0, rcv1, rcv2, rcv3
- use the G703 receiver clock of the other channel
(E1 models only). 
.It dir=<number>
Binds logical channel to the physical channel (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1
only). Using this parameter you could, for example, split E1 physical channel
into several channels.
.It ts=interval
Set up the list of timeslots to use by the channel (E1 only). The
timeslots are numbered from 1 to 31, and are separated by comma or minus sign,
giving an interval. For example: "ts=1-3,5,17". 
.It pass=interval
Set up the list of timeslots, translated to the E1 subchannel in cfg=B and
cfg=C configurations (Tau/E1 only). 
.It debug=0, debug=1, debug=2
Turn on/off debug messages.
.Ar 0
- turn off debug messages.
.Ar 1
- turn on debug
messages, equal to the
.Ar debug
option to the
.Xr ifconfig 8
utility.
.Ar 2
- high intensive debug message, developers only.
.El
.\"--------------------------------------------------------------
.Sh EXAMPLES
Set up the channel 1 for use with the HDSL modem or any other
synchronous leased-line modem, and PPP/HDLC protocol (for Sigma):
.Bd -literal -offset indent
sconfig cx1 ppp extclock
ifconfig cx1 158.250.244.2 158.250.244.1 up
.Ed
.Pp
Set up the channel 0 of Tau/E1 for use with the Cisco protocol
over E1 link, with the single virtual connection.
The DLCI number is detected automatically.
Use timeslots 1-10:
.Bd -literal -offset indent
sconfig ct0 cisco ts=1-10
ifconfig ct0 158.250.244.2 158.250.244.1 up
.Ed
.Pp
Set up the channel 0 for the synchronous null-modem link to the nearby computer,
internal clock source, 256000 bits/sec, protocol Cisco/HDLC (for Tau):
.Bd -literal -offset indent
sconfig ct0 cisco 256000
ifconfig ct0 200.1.1.1 200.1.1.2 up
.Ed
.Pp
Set up the channel 1 for the leased line link using data-only
null-modem cable (or modems like Zelax+ M115). Synchronous DPLL mode, 128000
bits/sec, protocol PPP/HDLC, NRZI encoding (for Sigma):
.Bd -literal -offset indent
sconfig cx1 ppp 128000 nrzi=on dpll=on
ifconfig cx1 158.250.244.2 158.250.244.1 up
.Ed
.\"--------------------------------------------------------------
.Sh DIAGNOSTICS
This section contains description of abbreviations used by
.Nm sconfig
while displaying various statistics. For description of options connected with
statistics see above.
.\"--------------------------------------------------------------
.Ss Statistics
When running, the driver gathers the statistics about the channels, which
could be accessed via sconfig utility or by
.Xr ioctl 2
call
.Ar SERIAL_GETSTAT.
.Bl -tag -width 10n
.It Rintr
The total number of receive interrupts. 
.It Tintr
The total number of transmit interrupts. 
.It Mintr
The total number of modem interrupts. 
.It Ibytes
The total bytes received. 
.It Ipkts
The total packets received (for HDLC mode). 
.It Ierrs
The number of receive errors. 
.It Obytes
The total bytes transmitted. 
.It Opkts
The total packets transmitted (for HDLC mode). 
.It Oerrs The number of transmit errors.
.El
.\"--------------------------------------------------------------
.Ss E1/G.703 Statistics
For E1 and G.703 channels the SNMP-compatible statistics data are gathered
(see RFC 1406). It could be accessed via sconfig utility or by ioctl(2) call
.Ar SERIAL_GETESTAT .
.Bl -tag -width 10n 
.It Unav (uas)
Unavailable seconds - receiving all ones, or loss of carrier, or loss of
signal.
.It Degr (dm)
Degraded minutes - having error rate more than 10e-6, not counting unavailable
and severely errored seconds.
.It Bpv (bpv)
HDB3 bipolar violation errors. 
.It Fsyn (fse)
Frame synchronization errors (E1 only). 
.It CRC (crce)
CRC4 errors (E1). 
.It RCRC (rcrce)
Remote CRC4 errors: E-bit counter (E1). 
.It Err (es)
Errored seconds - any framing errors, or out of frame sync, or any slip events.
.It Lerr (les)
Line errored seconds - any BPV. 
.It Sev (ses)
Severely errored seconds - 832 or more framing errors, or 2048 or more bipolar
violations. 
.It Bur (bes)
Bursty errored seconds - more than 1 framing error, but not severely errored. 
.It Oof (oofs)
Severely errored framing seconds - out of frame sync. 
.It Slp (css)
Controlled slip second -- any slip buffer overflow or underflow.
.El
.\"--------------------------------------------------------------
.Ss E1/G.703 Status
.Nm sconfig
utility also prints the E1/G.703 channel status. The status could have the
following values (nonexclusive):
.Bl -tag -width 10n 
.It Ok
The channel is in valid state, synchronized. 
.It LOS
Loss of sync. 
.It AIS
Receiving unframed all ones (E1 only). 
.It LOF
Loss of framing (E1 only). 
.It LOMF
Loss of multiframing (E1 only). 
.It FARLOF
Receiving remote alarm (E1 only). 
.It AIS16
Receiving all ones in timeslot 16 (E1 only). 
.It FARLOMF
Receiving distant multiframe alarm (E1 only). 
.It TSTREQ
Receiving test request code (G.703 only). 
.It TSTERR
Test error (G.703 only).
.El
.\"--------------------------------------------------------------
.Sh SEE ALSO
.Xr stty 1
.Xr ioctl 2
.Xr sppp 4
.Xr spppconrol 8
.Xr ifconfig 8
.Xr route 8
.\"--------------------------------------------------------------
.Sh HISTORY
This utility is a replacement of utilities
.Nm cxconfig
and
.Nm ctconfig
that was used in past with FreeBSD drivers. Those two utilities and the present
utility are not compatible. And therefore all scripts should be rewritten. More
over, Linux and FreeBSD version of present utility not fully compatible.
.\"--------------------------------------------------------------
.Sh BUGS
All software produced by Cronyx Engineering is thoroughly tested. But
as created by the man it can contain some
.So
BUGS
.Sc .
If you have caught one, try to localize it and send a letter with description
of this bug and all operation that you have done. We will try to reproduce
an error and fix it.
.\"--------------------------------------------------------------
.Sh CONTACT
E-mail: info@cronyx.ru
.Pp
http://www.cronyx.ru