sbin/sconfig/sconfig.8

   1 .\" Copyright (c) 2002-2004 Roman Kurakin <rik@cronyx.ru>
   2 .\" Copyright (c) 2002-2004 Cronyx Engineering
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software is distributed with NO WARRANTIES, not even the implied
   6 .\" warranties for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7 .\"
   8 .\" Authors grant any other persons or organisations a permission to use,
   9 .\" modify and redistribute this software in source and binary forms,
  10 .\" as long as this message is kept with the software, all derivative
  11 .\" works or modified versions.
  12 .\"
  13 .\" $FreeBSD$
  14 .Dd October 3, 2016
  15 .Dt SCONFIG 8 i386
  16 .Os
  17 .Sh NAME
  18 .Nm sconfig
  19 .Nd "channel configuration utility for Cronyx adapters"
  20 .Sh SYNOPSIS
  21 .Nm
  22 .Op Fl aimsxeftuc
  23 .Op Ar device
  24 .Op Ar data_rate_options
  25 .Op Ar protocol_options ...
  26 .Op Ar interface_options ...
  27 .Sh DESCRIPTION
  28 The
  29 .Nm
  30 utility is used for configuring the channel options of the Cronyx
  31 adapters.
  32 In asynchronous mode, all parameters should be set using the standard
  33 .Xr stty 1
  34 utility.
  35 With
  36 .Nm ,
  37 it is only possible to set some of them (see below).
  38 .Pp
  39 Some of the options can be set only on free channels,
  40 that is when the corresponding network interface is in the
  41 .Cm down
  42 state in the synchronous mode,
  43 and the terminal device
  44 .Pa /dev/tty*
  45 is closed in asynchronous mode.
  46 .Pp
  47 Other channel options can be changed
  48 .Dq "on the fly" .
  49 Generally, the channel options are set up during the operating system startup,
  50 for example, from the
  51 .Pa /etc/rc
  52 script.
  53 .Pp
  54 Note that not all options make sense in every particular case,
  55 and an attempt to set some of them may hung up the channel
  56 or the whole adapter.
  57 .\"--------------------------------------------------------------
  58 .Ss "Information Options"
  59 Only one of these options can be specified.
  60 If information option is specified,
  61 .Nm
  62 will show the corresponding information and will ignore all other options,
  63 except
  64 .Ar device .
  65 See also the description of the
  66 .Ar device
  67 argument.
  68 .Bl -tag -width indent
  69 .It <none>
  70 This will show settings of the channel.
  71 .It Fl a
  72 Print all settings of the channel.
  73 .It Fl i
  74 Print interface settings, equal to the output of the
  75 .Xr ifconfig 8
  76 utility.
  77 .It Fl m
  78 Print modem signal status.
  79 The description of all signals can be found in any modem documentation.
  80 Only LE signal should be described.
  81 If this signal is ON then the channel is busy.
  82 If it is OFF then the channel is free.
  83 .It Fl s
  84 Print brief channel statistics.
  85 This is the generic statistics,
  86 see also the
  87 .Fl x , e , f , t ,
  88 and
  89 .Fl u
  90 options.
  91 For a description of the output, see below.
  92 .Pp
  93 This statistics is very useful if something goes wrong.
  94 For example, if all interrupt counters are zero then the device
  95 was configured to use an interrupt that was not registered in the
  96 BIOS for use with the ISA bus.
  97 .It Fl x
  98 Print full channel statistics.
  99 This options prints additional counters,
 100 but with less precision than with the
 101 .Fl s
 102 option.
 103 .It Fl e
 104 Print brief E1/G703 statistics.
 105 If this option is selected, the
 106 statistics accumulated over the last 15 minutes is printed.
 107 For a description of the output, see below.
 108 .It Fl f
 109 Print full E1/G703 statistics.
 110 This option shows all E1/G703 statistics that the
 111 .Fl e
 112 option shows,
 113 plus total statistics for the whole period of time and statistics for
 114 last 24 hours (if available).
 115 For a description of the output, see below.
 116 .It Fl t
 117 Print brief E3/T3/STS-1 statistics.
 118 If this option is selected, the
 119 statistics accumulated over the last 15 minutes is printed.
 120 For a description of the output, see below.
 121 .It Fl u
 122 Print full E3/T3/STS-1 statistics.
 123 This option shows all E3/T3/STS-1 statistics that the
 124 .Fl t
 125 option shows,
 126 plus total statistics for the whole period of time and statistics for
 127 last 24 hours (if available).
 128 For a description of the output, see below.
 129 .It Fl c
 130 Cleans all kind of statistics.
 131 .El
 132 .\"--------------------------------------------------------------
 133 .Ss "Device Selection"
 134 The device is selected using the name of the network interface,
 135 as shown by
 136 .Xr ifconfig 8 .
 137 The channel number depends on the order the drivers were loaded into the system.
 138 Sometimes people confuse channel number and adapter number because of the
 139 same spelling.
 140 The adapter number appears in the kernel context, while the channel number
 141 is in the configuration context.
 142 .Bl -tag -width indent
 143 .It <none>
 144 If the device name is omitted,
 145 .Nm
 146 will print information about all channels of all Cronyx adapters
 147 available in the system.
 148 If some settings need to be made, the device name must be specified.
 149 .It Li cx Ns Ar ##
 150 This is the channel name for the Sigma family of Cronyx adapters.
 151 (ISA bus.)
 152 .It Li ct Ns Ar ##
 153 This is the channel name for the Tau family of Cronyx adapters.
 154 (ISA bus.)
 155 .It Li cp Ns Ar ##
 156 This is the channel name for the Tau-PCI family of Cronyx adapters.
 157 (PCI bus.)
 158 .It Li ce Ns Ar ##
 159 This is the channel name for the Tau32-PCI family of Cronyx adapters.
 160 (PCI bus.)
 161 .El
 162 .\"--------------------------------------------------------------
 163 .Ss "Data Rate Options"
 164 .Bl -tag -width indent
 165 .It Ar value
 166 A non-zero value will set the data rate to a given value
 167 in asynchronous mode,
 168 and will set the data rate and internal clock source of synchronization
 169 in synchronous mode.
 170 A zero value is equivalent to specifying the
 171 .Cm extclock
 172 option.
 173 The transmitted data (TxD) are synchronized using the internal on-board timing
 174 generator, the internally generated timing signal is driven on the TXCOUT pin,
 175 and the signal on the TXCIN pin is ignored.
 176 This mode is used for direct
 177 terminal-to-terminal communication, e.g., when connecting two computers together
 178 in synchronous mode with a relatively short cable.
 179 This method should also be
 180 used for testing channels with an external loopback connector.
 181 .It Cm extclock
 182 Set the external timing clock source for synchronous channels.
 183 External clock mode is the most commonly used method for connecting
 184 external modem hardware.
 185 In this mode,
 186 the external timing signal is received on the TXCIN pin of the connector,
 187 and it is used as a synchronization clock for transmitting data (TxD).
 188 .Pp
 189 Note: in
 190 .Cm extclock
 191 mode, the device cannot determine the value of the external timing clock
 192 since it does not have the built-in clock gauge.
 193 .El
 194 .\"--------------------------------------------------------------
 195 .Ss "Protocol Options"
 196 Note: these option can only be used on a free channel, and they require
 197 specifying the device name.
 198 .Bl -tag -width indent
 199 .It Cm async
 200 (Only for Sigma family.)
 201 Select the asynchronous protocol (or mode).
 202 In this mode, Cronyx adapters behave as normal serial devices,
 203 and standard serial communications utilities can be used to
 204 work with them.
 205 All asynchronous settings should be set using the standard
 206 serial communications configuration utilities, e.g.,
 207 .Xr stty 1 .
 208 With
 209 .Nm ,
 210 it is only possible to set some of them.
 211 .It Cm cisco
 212 Select the Cisco HDLC synchronous protocol.
 213 .It Cm fr
 214 Select the Frame Relay synchronous protocol
 215 .Tn ( ANSI
 216 T1.617 Annex D).
 217 .It Cm ppp
 218 Select the synchronous PPP protocol.
 219 PPP parameters can be configured using the
 220 .Xr spppcontrol 8
 221 utility.
 222 .It Sm Cm keepalive No = Bro Cm on , off Brc Sm
 223 Turn on/off transmission of keepalive messages.
 224 This option is used only for synchronous PPP.
 225 If this option is
 226 .Cm on ,
 227 PPP will periodically send ECHO-REQUEST messages.
 228 If it will not receive any ECHO-REPLY messages for
 229 some (definite) period of time it will break the connection.
 230 It is used for tracking the line state.
 231 .It Cm idle
 232 This mode is reported when using Netgraph.
 233 An actual protocol depends on the type of a connected Netgraph node,
 234 and it cannot be changed with
 235 .Nm .
 236 .El
 237 .\"--------------------------------------------------------------
 238 .Ss "Interface Options"
 239 Not all of these options can be set on a busy channel, and not all of them
 240 are applicable to all kinds of adapters/channels.
 241 For all dual-state options,
 242 .Cm off
 243 is the default value.
 244 None of these options can be used in the asynchronous mode,
 245 except for the
 246 .Cm debug
 247 option.
 248 .Bl -tag -width indent
 249 .It Sm Cm port No = Bro Cm rs232 , v35 , rs449 Brc Sm
 250 Set the port type for old Sigma models.
 251 .It Sm Cm cfg No = Bro Cm A , B , C Brc Sm
 252 Set the configuration for the adapter.
 253 This option can be used only with Tau/E1
 254 and Tau/G703 adapters, and only if all channels are free.
 255 .Bl -tag -width ".Cm cfg Ns = Ns Cm A"
 256 .It Cm cfg Ns = Ns Cm A
 257 Two independent E1/G703 channels.
 258 This is the default setting.
 259 .It Cm cfg Ns = Ns Cm B
 260 (Only for ISA models.)
 261 For Tau/G703 this means one G703 channel and one digital channel.
 262 For Tau/E1, the first physical channel is divided into two subchannels.
 263 One of them goes to the first logical channel, another one goes to the
 264 second physical channel.
 265 Second (logical) channel is the digital channel.
 266 .It Cm cfg Ns = Ns Cm C
 267 (Only for E1 models.)
 268 In this mode, first
 269 physical channel consists of three data flows.
 270 Two of them go to the two (logical) channels.
 271 The last one goes to the second physical channel.
 272 On newer models (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1),
 273 this programs the hardware to use a single source of synchronization
 274 and pass all unused (in both channels) timeslots from
 275 one channel to another.
 276 .El
 277 .Pp
 278 For a detailed description of available configuration modes,
 279 see the adapter documentation.
 280 This option cannot be set on a busy channel.
 281 .It Sm Cm loop No = Bro Cm on , off Brc Sm
 282 Turn on/off internal loopback.
 283 This mode is useful for debugging.
 284 When this mode is
 285 .Cm on ,
 286 some data should be sent.
 287 If no interrupts are generated, chances are that
 288 the corresponding IRQ configuration entry in the BIOS
 289 was not switched from
 290 .Dq Li "PCI/ISA PNP"
 291 to
 292 .Dq Li "Legacy ISA" .
 293 .It Sm Cm rloop No = Bro Cm on , off Brc Sm
 294 (Only for Tau32-PCI and Tau-PCI/E3.)
 295 Turn on/off remote loopback feature.
 296 This mode is also useful for debugging.
 297 .It Sm Cm dpll No = Bro Cm on , off Brc Sm
 298 Turn on/off digital phase locked loop mode (DPLL).
 299 When enabled, the receiver
 300 timing clock signal is derived from the received data.
 301 Must be used with the NRZI
 302 encoding to avoid the synchronization loss.
 303 .It Sm Cm nrzi No = Bro Cm on , off Brc Sm
 304 Turn on/off NRZI encoding.
 305 If
 306 .Cm off ,
 307 NRZ encoding is used.
 308 .Bl -tag -width "NRZI"
 309 .It NRZ
 310 The zero bit is transmitted by the zero signal level,
 311 the one bit is transmitted by the positive signal level.
 312 .It NRZI
 313 The zero bit is transmitted by the change of the signal
 314 level, the one bit is by the constant signal level.
 315 Commonly used with the
 316 .Cm dpll Ns = Ns Cm on
 317 option.
 318 .El
 319 .It Sm Cm invclk No = Bro Cm on , off Brc Sm
 320 (Tau and Tau-PCI only.)
 321 Invert both the transmit and receive clock signals.
 322 .It Sm Cm invrclk No = Bro Cm on , off Brc Sm
 323 (Tau-PCI only.)
 324 Invert the receive clock signals.
 325 .It Sm Cm invtclk No = Bro Cm on , off Brc Sm
 326 (Tau-PCI only.)
 327 Invert the transmit clock signals.
 328 .It Sm Cm higain No = Bro Cm on , off Brc Sm
 329 (E1 only.)
 330 In off state the sensitivity is -12 dB.
 331 Turn on/off increasing the E1 receiver's non-linear sensitivity to -30dB.
 332 This allows increasing of the line distance.
 333 .It Sm Cm cablen No = Bro Cm on , off Brc Sm
 334 (Tau-PCI/T3 and Tau-PCI/STS-1 only.)
 335 Turn on/off adjusting of the transmit signal for a long cable T3/STS-1.
 336 .It Sm Cm monitor No = Bro Cm on , off Brc Sm
 337 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 338 Turn on/off increasing of the E1 receiver's linear sensitivity to -30dB.
 339 This can be used for the interception purposes.
 340 .It Sm Cm phony No = Bro Cm on , off Brc Sm
 341 (Tau32-PCI and Tau-PCI E1 family only.)
 342 Turn on/off the so-called
 343 .Dq phony
 344 mode.
 345 This mode allows
 346 receiving raw CEPT frames from the E1 line.
 347 Raw frames can be accessed, for example, with the raw protocol.
 348 Packets would come at a rate of 500 frames per second
 349 with length
 350 .No 16* Ns Ar N
 351 (for Tau-PCI/E1 model), where
 352 .Ar N
 353 is the number of timeslots.
 354 For
 355 Tau-PCI/2E1 and Tau-PCI/4E1,
 356 .Ar N
 357 should be equal to 32 regardless of the number of
 358 used timeslots.
 359 .It Sm Cm unfram No = Bro Cm on , off Brc Sm
 360 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 361 Turn on/off unframed mode.
 362 .Bl -tag -width ".Cm unfram Ns = Ns Cm off"
 363 .It Cm unfram Ns = Ns Cm on
 364 Switch channel to the unframed G.703 mode.
 365 .It Cm unfram Ns = Ns Cm off
 366 Switch channel to the framed E1 (G.704) mode.
 367 .El
 368 .It Sm Cm scrambler No = Bro Cm on , off Brc Sm
 369 (Tau32-PCI, Tau-PCI/G.703, Tau-PCI/2E1, and
 370 Tau-PCI/4E1 in unframed mode only.)
 371 Turn on/off scrambling of the G.703 data.
 372 .It Sm Cm use16 No = Bro Cm on , off Brc Sm
 373 (Tau32-PCI and Tau-PCI E1 family only.)
 374 Turn on/off the usage of the 16th timeslot for data transmission.
 375 Normally, the 16th timeslot is used for signalling information
 376 (multiframing CAS).
 377 .It Sm Cm crc4 No = Bro Cm on , off Brc Sm
 378 (E1 only.)
 379 Turn on/off CRC4 superframe mode.
 380 .It Sm Cm syn No = Bro Cm int , rcv , rcv0 , rcv1 , rcv2 , rcv3 Brc Sm
 381 .Bl -tag -width ".Cm rcv3"
 382 .It Cm int
 383 Use an internal clock generator for G703 transmitter
 384 (clock master).
 385 .It Cm rcv
 386 Use the G703 receiver data clock as the transmit clock
 387 (clock slave).
 388 .It Cm rcv0 , rcv1 , rcv2 , rcv3
 389 Use the G703 receiver clock of the other channel
 390 (E1 models only).
 391 .El
 392 .It Cm dir Ns = Ns Ar number
 393 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 394 Bind a logical channel to a physical channel.
 395 Using this parameter it is possible, for example, to split
 396 physical E1 channel into several logical channels.
 397 .It Cm ts Ns = Ns Ar interval
 398 (E1 only.)
 399 Set up the list of timeslots for use by the channel.
 400 The timeslots are numbered from 1 to 31,
 401 and are separated by a comma or a minus sign,
 402 giving an interval.
 403 Example:
 404 .Dq Li ts=1-3,5,17 .
 405 .It Cm pass Ns = Ns Ar interval
 406 (Tau/E1 only.)
 407 Set up the list of timeslots, translated to the E1 subchannel in
 408 .Cm cfg Ns = Ns Cm B
 409 and
 410 .Cm cfg Ns = Ns Cm C
 411 configurations.
 412 .It Sm Cm debug No = Bro Cm 0 , 1 , 2 Brc Sm
 413 Turn on/off debug messages.
 414 .Bl -tag -width 2n
 415 .It Cm 0
 416 Turn debug messages off.
 417 .It Cm 1
 418 Turn debug messages on, equivalent to the
 419 .Cm debug
 420 option of the
 421 .Xr ifconfig 8
 422 utility.
 423 .It Cm 2
 424 High intensive debug messages, for developers only.
 425 .El
 426 .El
 427 .\"--------------------------------------------------------------
 428 .Sh EXAMPLES
 429 Set up channel 1 for use with the HDSL modem or any other
 430 synchronous leased-line modem, and PPP/HDLC protocol (for Sigma):
 431 .Bd -literal -offset indent
 432 sconfig cx1 ppp extclock
 433 ifconfig cx1 158.250.244.2 158.250.244.1 up
 434 .Ed
 435 .Pp
 436 Set up channel 0 of Tau/E1 for use with the Cisco protocol
 437 over the E1 link, with a single virtual connection.
 438 The DLCI number is detected automatically.
 439 Use timeslots 1-10:
 440 .Bd -literal -offset indent
 441 sconfig ct0 cisco ts=1-10
 442 ifconfig ct0 158.250.244.2 158.250.244.1 up
 443 .Ed
 444 .Pp
 445 Set up channel 0 for the synchronous null-modem link to the nearby computer,
 446 internal clock source, 256000 bits/sec, protocol Cisco/HDLC (for Tau):
 447 .Bd -literal -offset indent
 448 sconfig ct0 cisco 256000
 449 ifconfig ct0 200.1.1.1 200.1.1.2 up
 450 .Ed
 451 .Pp
 452 Set up channel 1 for the leased line link using the data-only
 453 null-modem cable (or modems like Zelax+ M115).
 454 Synchronous DPLL mode, 128000
 455 bits/sec, protocol PPP/HDLC, NRZI encoding (for Sigma):
 456 .Bd -literal -offset indent
 457 sconfig cx1 ppp 128000 nrzi=on dpll=on
 458 ifconfig cx1 158.250.244.2 158.250.244.1 up
 459 .Ed
 460 .\"--------------------------------------------------------------
 461 .Sh DIAGNOSTICS
 462 This section contains a description of abbreviations used by
 463 .Nm
 464 while displaying various statistics.
 465 For a description of options related to
 466 statistics, please see above.
 467 .\"--------------------------------------------------------------
 468 .Ss Statistics
 469 When running, the driver gathers statistics about the channels, which
 470 can be accessed using the
 471 .Nm
 472 utility,
 473 or through the
 474 .Xr ioctl 2
 475 call
 476 .Dv SERIAL_GETSTAT .
 477 .Pp
 478 .Bl -tag -width indent -compact
 479 .It Va Rintr
 480 Total number of receive interrupts.
 481 .It Va Tintr
 482 Total number of transmit interrupts.
 483 .It Va Mintr
 484 Total number of modem interrupts.
 485 .It Va Ibytes
 486 Total bytes received.
 487 .It Va Ipkts
 488 Total packets received (for HDLC mode).
 489 .It Va Ierrs
 490 Number of receive errors.
 491 .It Va Obytes
 492 Total bytes transmitted.
 493 .It Va Opkts
 494 Total packets transmitted (for HDLC mode).
 495 .It Va Oerrs
 496 Number of transmit errors.
 497 .El
 498 .\"--------------------------------------------------------------
 499 .Ss E1/G.703 Statistics
 500 For E1 and G.703 channels, the SNMP-compatible statistics data are gathered
 501 (see RFC 1406).
 502 It can be accessed using the
 503 .Nm
 504 utility,
 505 or through the
 506 .Xr ioctl 2
 507 call
 508 .Dv SERIAL_GETESTAT .
 509 .Bl -tag -width ".Va RCRC Pq Va rcrce"
 510 .It Va Unav Pq Va uas
 511 Unavailable seconds: receiving all ones, loss of carrier, or loss of
 512 signal.
 513 .It Va Degr Pq Va dm
 514 Degraded minutes: having error rate more than 10E-6, not counting unavailable
 515 and severely errored seconds.
 516 .It Va Bpv Pq Va bpv
 517 HDB3 bipolar violation errors.
 518 .It Va Fsyn Pq Va fse
 519 Frame synchronization errors (E1 only).
 520 .It Va CRC Pq Va crce
 521 CRC4 errors (E1).
 522 .It Va RCRC Pq Va rcrce
 523 Remote CRC4 errors: E-bit counter (E1).
 524 .It Va Err Pq Va es
 525 Errored seconds: any framing errors, or out of frame sync, or any slip events.
 526 .It Va Lerr Pq Va les
 527 Line errored seconds: any BPV.
 528 .It Va Sev Pq Va ses
 529 Severely errored seconds: 832 or more framing errors, or 2048 or more bipolar
 530 violations.
 531 .It Va Bur Pq Va bes
 532 Bursty errored seconds: more than 1 framing error, but not severely errored.
 533 .It Va Oof Pq Va oofs
 534 Severely errored framing seconds: out of frame sync.
 535 .It Va Slp Pq Va css
 536 Controlled slip seconds: any slip buffer overflow or underflow.
 537 .El
 538 .\"--------------------------------------------------------------
 539 .Ss E1/G.703 Status
 540 The
 541 .Nm
 542 utility also prints the E1/G.703 channel status.
 543 The status can have the
 544 following values (non-exclusive):
 545 .Pp
 546 .Bl -tag -width ".Li FARLOMF" -compact
 547 .It Li Ok
 548 The channel is in a valid state, synchronized.
 549 .It Li LOS
 550 Loss of sync.
 551 .It Li AIS
 552 Receiving unframed all ones (E1 only).
 553 .It Li LOF
 554 Loss of framing (E1 only).
 555 .It Li LOMF
 556 Loss of multiframing (E1 only).
 557 .It Li FARLOF
 558 Receiving remote alarm (E1 only).
 559 .It Li AIS16
 560 Receiving all ones in the timeslot 16 (E1 only).
 561 .It Li FARLOMF
 562 Receiving distant multiframe alarm (E1 only).
 563 .It Li TSTREQ
 564 Receiving test request code (G.703 only).
 565 .It Li TSTERR
 566 Test error (G.703 only).
 567 .El
 568 .\"--------------------------------------------------------------
 569 .Sh SEE ALSO
 570 .Xr stty 1 ,
 571 .Xr ioctl 2 ,
 572 .Xr sppp 4 ,
 573 .Xr ifconfig 8 ,
 574 .Xr route 8 ,
 575 .Xr spppcontrol 8
 576 .\"--------------------------------------------------------------
 577 .Sh HISTORY
 578 The
 579 .Nm
 580 utility appeared in
 581 .Fx 5.2 .
 582 The
 583 .Nm
 584 utility is a replacement for the
 585 .Nm cxconfig
 586 and
 587 .Nm ctconfig
 588 utilities that were used in the past with
 589 .Fx
 590 drivers.
 591 Those two utilities and
 592 .Nm
 593 are not compatible,
 594 and therefore all scripts using them have to be rewritten.
 595 Moreover,
 596 .Tn Linux
 597 and
 598 .Fx
 599 versions of the
 600 .Nm
 601 utility are not fully compatible.
 602 .\"--------------------------------------------------------------
 603 .Sh AUTHORS
 604 .An Cronyx Engineering Aq Mt info@cronyx.ru
 605 .Pp
 606 .Pa http://www.cronyx.ru
 607 .\"--------------------------------------------------------------
 608 .Sh BUGS
 609 All software produced by Cronyx Engineering is thoroughly tested.
 610 But as created by a man, it can contain some bugs.
 611 If you have caught one, try to localize it and send an email with the
 612 description of the bug, and all operations that you have done.
 613 We will try to reproduce the error and fix it.