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 .It Sm Cm keepalive No = Bro Cm on , off Brc Sm
 220 Turn on/off transmission of keepalive messages.
 221 This option is used only for synchronous PPP.
 222 If this option is
 223 .Cm on ,
 224 PPP will periodically send ECHO-REQUEST messages.
 225 If it will not receive any ECHO-REPLY messages for
 226 some (definite) period of time it will break the connection.
 227 It is used for tracking the line state.
 228 .It Cm idle
 229 This mode is reported when using Netgraph.
 230 An actual protocol depends on the type of a connected Netgraph node,
 231 and it cannot be changed with
 232 .Nm .
 233 .El
 234 .\"--------------------------------------------------------------
 235 .Ss "Interface Options"
 236 Not all of these options can be set on a busy channel, and not all of them
 237 are applicable to all kinds of adapters/channels.
 238 For all dual-state options,
 239 .Cm off
 240 is the default value.
 241 None of these options can be used in the asynchronous mode,
 242 except for the
 243 .Cm debug
 244 option.
 245 .Bl -tag -width indent
 246 .It Sm Cm port No = Bro Cm rs232 , v35 , rs449 Brc Sm
 247 Set the port type for old Sigma models.
 248 .It Sm Cm cfg No = Bro Cm A , B , C Brc Sm
 249 Set the configuration for the adapter.
 250 This option can be used only with Tau/E1
 251 and Tau/G703 adapters, and only if all channels are free.
 252 .Bl -tag -width ".Cm cfg Ns = Ns Cm A"
 253 .It Cm cfg Ns = Ns Cm A
 254 Two independent E1/G703 channels.
 255 This is the default setting.
 256 .It Cm cfg Ns = Ns Cm B
 257 (Only for ISA models.)
 258 For Tau/G703 this means one G703 channel and one digital channel.
 259 For Tau/E1, the first physical channel is divided into two subchannels.
 260 One of them goes to the first logical channel, another one goes to the
 261 second physical channel.
 262 Second (logical) channel is the digital channel.
 263 .It Cm cfg Ns = Ns Cm C
 264 (Only for E1 models.)
 265 In this mode, first
 266 physical channel consists of three data flows.
 267 Two of them go to the two (logical) channels.
 268 The last one goes to the second physical channel.
 269 On newer models (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1),
 270 this programs the hardware to use a single source of synchronization
 271 and pass all unused (in both channels) timeslots from
 272 one channel to another.
 273 .El
 274 .Pp
 275 For a detailed description of available configuration modes,
 276 see the adapter documentation.
 277 This option cannot be set on a busy channel.
 278 .It Sm Cm loop No = Bro Cm on , off Brc Sm
 279 Turn on/off internal loopback.
 280 This mode is useful for debugging.
 281 When this mode is
 282 .Cm on ,
 283 some data should be sent.
 284 If no interrupts are generated, chances are that
 285 the corresponding IRQ configuration entry in the BIOS
 286 was not switched from
 287 .Dq Li "PCI/ISA PNP"
 288 to
 289 .Dq Li "Legacy ISA" .
 290 .It Sm Cm rloop No = Bro Cm on , off Brc Sm
 291 (Only for Tau32-PCI and Tau-PCI/E3.)
 292 Turn on/off remote loopback feature.
 293 This mode is also useful for debugging.
 294 .It Sm Cm dpll No = Bro Cm on , off Brc Sm
 295 Turn on/off digital phase locked loop mode (DPLL).
 296 When enabled, the receiver
 297 timing clock signal is derived from the received data.
 298 Must be used with the NRZI
 299 encoding to avoid the synchronization loss.
 300 .It Sm Cm nrzi No = Bro Cm on , off Brc Sm
 301 Turn on/off NRZI encoding.
 302 If
 303 .Cm off ,
 304 NRZ encoding is used.
 305 .Bl -tag -width "NRZI"
 306 .It NRZ
 307 The zero bit is transmitted by the zero signal level,
 308 the one bit is transmitted by the positive signal level.
 309 .It NRZI
 310 The zero bit is transmitted by the change of the signal
 311 level, the one bit is by the constant signal level.
 312 Commonly used with the
 313 .Cm dpll Ns = Ns Cm on
 314 option.
 315 .El
 316 .It Sm Cm invclk No = Bro Cm on , off Brc Sm
 317 (Tau and Tau-PCI only.)
 318 Invert both the transmit and receive clock signals.
 319 .It Sm Cm invrclk No = Bro Cm on , off Brc Sm
 320 (Tau-PCI only.)
 321 Invert the receive clock signals.
 322 .It Sm Cm invtclk No = Bro Cm on , off Brc Sm
 323 (Tau-PCI only.)
 324 Invert the transmit clock signals.
 325 .It Sm Cm higain No = Bro Cm on , off Brc Sm
 326 (E1 only.)
 327 In off state the sensitivity is -12 dB.
 328 Turn on/off increasing the E1 receiver's non-linear sensitivity to -30dB.
 329 This allows increasing of the line distance.
 330 .It Sm Cm cablen No = Bro Cm on , off Brc Sm
 331 (Tau-PCI/T3 and Tau-PCI/STS-1 only.)
 332 Turn on/off adjusting of the transmit signal for a long cable T3/STS-1.
 333 .It Sm Cm monitor No = Bro Cm on , off Brc Sm
 334 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 335 Turn on/off increasing of the E1 receiver's linear sensitivity to -30dB.
 336 This can be used for the interception purposes.
 337 .It Sm Cm phony No = Bro Cm on , off Brc Sm
 338 (Tau32-PCI and Tau-PCI E1 family only.)
 339 Turn on/off the so-called
 340 .Dq phony
 341 mode.
 342 This mode allows
 343 receiving raw CEPT frames from the E1 line.
 344 Raw frames can be accessed, for example, with the raw protocol.
 345 Packets would come at a rate of 500 frames per second
 346 with length
 347 .No 16* Ns Ar N
 348 (for Tau-PCI/E1 model), where
 349 .Ar N
 350 is the number of timeslots.
 351 For
 352 Tau-PCI/2E1 and Tau-PCI/4E1,
 353 .Ar N
 354 should be equal to 32 regardless of the number of
 355 used timeslots.
 356 .It Sm Cm unfram No = Bro Cm on , off Brc Sm
 357 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 358 Turn on/off unframed mode.
 359 .Bl -tag -width ".Cm unfram Ns = Ns Cm off"
 360 .It Cm unfram Ns = Ns Cm on
 361 Switch channel to the unframed G.703 mode.
 362 .It Cm unfram Ns = Ns Cm off
 363 Switch channel to the framed E1 (G.704) mode.
 364 .El
 365 .It Sm Cm scrambler No = Bro Cm on , off Brc Sm
 366 (Tau32-PCI, Tau-PCI/G.703, Tau-PCI/2E1, and
 367 Tau-PCI/4E1 in unframed mode only.)
 368 Turn on/off scrambling of the G.703 data.
 369 .It Sm Cm use16 No = Bro Cm on , off Brc Sm
 370 (Tau32-PCI and Tau-PCI E1 family only.)
 371 Turn on/off the usage of the 16th timeslot for data transmission.
 372 Normally, the 16th timeslot is used for signalling information
 373 (multiframing CAS).
 374 .It Sm Cm crc4 No = Bro Cm on , off Brc Sm
 375 (E1 only.)
 376 Turn on/off CRC4 superframe mode.
 377 .It Sm Cm syn No = Bro Cm int , rcv , rcv0 , rcv1 , rcv2 , rcv3 Brc Sm
 378 .Bl -tag -width ".Cm rcv3"
 379 .It Cm int
 380 Use an internal clock generator for G703 transmitter
 381 (clock master).
 382 .It Cm rcv
 383 Use the G703 receiver data clock as the transmit clock
 384 (clock slave).
 385 .It Cm rcv0 , rcv1 , rcv2 , rcv3
 386 Use the G703 receiver clock of the other channel
 387 (E1 models only).
 388 .El
 389 .It Cm dir Ns = Ns Ar number
 390 (Tau32-PCI, Tau-PCI/2E1 and Tau-PCI/4E1 only.)
 391 Bind a logical channel to a physical channel.
 392 Using this parameter it is possible, for example, to split
 393 physical E1 channel into several logical channels.
 394 .It Cm ts Ns = Ns Ar interval
 395 (E1 only.)
 396 Set up the list of timeslots for use by the channel.
 397 The timeslots are numbered from 1 to 31,
 398 and are separated by a comma or a minus sign,
 399 giving an interval.
 400 Example:
 401 .Dq Li ts=1-3,5,17 .
 402 .It Cm pass Ns = Ns Ar interval
 403 (Tau/E1 only.)
 404 Set up the list of timeslots, translated to the E1 subchannel in
 405 .Cm cfg Ns = Ns Cm B
 406 and
 407 .Cm cfg Ns = Ns Cm C
 408 configurations.
 409 .It Sm Cm debug No = Bro Cm 0 , 1 , 2 Brc Sm
 410 Turn on/off debug messages.
 411 .Bl -tag -width 2n
 412 .It Cm 0
 413 Turn debug messages off.
 414 .It Cm 1
 415 Turn debug messages on, equivalent to the
 416 .Cm debug
 417 option of the
 418 .Xr ifconfig 8
 419 utility.
 420 .It Cm 2
 421 High intensive debug messages, for developers only.
 422 .El
 423 .El
 424 .\"--------------------------------------------------------------
 425 .Sh EXAMPLES
 426 Set up channel 1 for use with the HDSL modem or any other
 427 synchronous leased-line modem, and PPP/HDLC protocol (for Sigma):
 428 .Bd -literal -offset indent
 429 sconfig cx1 ppp extclock
 430 ifconfig cx1 158.250.244.2 158.250.244.1 up
 431 .Ed
 432 .Pp
 433 Set up channel 0 of Tau/E1 for use with the Cisco protocol
 434 over the E1 link, with a single virtual connection.
 435 The DLCI number is detected automatically.
 436 Use timeslots 1-10:
 437 .Bd -literal -offset indent
 438 sconfig ct0 cisco ts=1-10
 439 ifconfig ct0 158.250.244.2 158.250.244.1 up
 440 .Ed
 441 .Pp
 442 Set up channel 0 for the synchronous null-modem link to the nearby computer,
 443 internal clock source, 256000 bits/sec, protocol Cisco/HDLC (for Tau):
 444 .Bd -literal -offset indent
 445 sconfig ct0 cisco 256000
 446 ifconfig ct0 200.1.1.1 200.1.1.2 up
 447 .Ed
 448 .Pp
 449 Set up channel 1 for the leased line link using the data-only
 450 null-modem cable (or modems like Zelax+ M115).
 451 Synchronous DPLL mode, 128000
 452 bits/sec, protocol PPP/HDLC, NRZI encoding (for Sigma):
 453 .Bd -literal -offset indent
 454 sconfig cx1 ppp 128000 nrzi=on dpll=on
 455 ifconfig cx1 158.250.244.2 158.250.244.1 up
 456 .Ed
 457 .\"--------------------------------------------------------------
 458 .Sh DIAGNOSTICS
 459 This section contains a description of abbreviations used by
 460 .Nm
 461 while displaying various statistics.
 462 For a description of options related to
 463 statistics, please see above.
 464 .\"--------------------------------------------------------------
 465 .Ss Statistics
 466 When running, the driver gathers statistics about the channels, which
 467 can be accessed using the
 468 .Nm
 469 utility,
 470 or through the
 471 .Xr ioctl 2
 472 call
 473 .Dv SERIAL_GETSTAT .
 474 .Pp
 475 .Bl -tag -width indent -compact
 476 .It Va Rintr
 477 Total number of receive interrupts.
 478 .It Va Tintr
 479 Total number of transmit interrupts.
 480 .It Va Mintr
 481 Total number of modem interrupts.
 482 .It Va Ibytes
 483 Total bytes received.
 484 .It Va Ipkts
 485 Total packets received (for HDLC mode).
 486 .It Va Ierrs
 487 Number of receive errors.
 488 .It Va Obytes
 489 Total bytes transmitted.
 490 .It Va Opkts
 491 Total packets transmitted (for HDLC mode).
 492 .It Va Oerrs
 493 Number of transmit errors.
 494 .El
 495 .\"--------------------------------------------------------------
 496 .Ss E1/G.703 Statistics
 497 For E1 and G.703 channels, the SNMP-compatible statistics data are gathered
 498 (see RFC 1406).
 499 It can be accessed using the
 500 .Nm
 501 utility,
 502 or through the
 503 .Xr ioctl 2
 504 call
 505 .Dv SERIAL_GETESTAT .
 506 .Bl -tag -width ".Va RCRC Pq Va rcrce"
 507 .It Va Unav Pq Va uas
 508 Unavailable seconds: receiving all ones, loss of carrier, or loss of
 509 signal.
 510 .It Va Degr Pq Va dm
 511 Degraded minutes: having error rate more than 10E-6, not counting unavailable
 512 and severely errored seconds.
 513 .It Va Bpv Pq Va bpv
 514 HDB3 bipolar violation errors.
 515 .It Va Fsyn Pq Va fse
 516 Frame synchronization errors (E1 only).
 517 .It Va CRC Pq Va crce
 518 CRC4 errors (E1).
 519 .It Va RCRC Pq Va rcrce
 520 Remote CRC4 errors: E-bit counter (E1).
 521 .It Va Err Pq Va es
 522 Errored seconds: any framing errors, or out of frame sync, or any slip events.
 523 .It Va Lerr Pq Va les
 524 Line errored seconds: any BPV.
 525 .It Va Sev Pq Va ses
 526 Severely errored seconds: 832 or more framing errors, or 2048 or more bipolar
 527 violations.
 528 .It Va Bur Pq Va bes
 529 Bursty errored seconds: more than 1 framing error, but not severely errored.
 530 .It Va Oof Pq Va oofs
 531 Severely errored framing seconds: out of frame sync.
 532 .It Va Slp Pq Va css
 533 Controlled slip seconds: any slip buffer overflow or underflow.
 534 .El
 535 .\"--------------------------------------------------------------
 536 .Ss E1/G.703 Status
 537 The
 538 .Nm
 539 utility also prints the E1/G.703 channel status.
 540 The status can have the
 541 following values (non-exclusive):
 542 .Pp
 543 .Bl -tag -width ".Li FARLOMF" -compact
 544 .It Li Ok
 545 The channel is in a valid state, synchronized.
 546 .It Li LOS
 547 Loss of sync.
 548 .It Li AIS
 549 Receiving unframed all ones (E1 only).
 550 .It Li LOF
 551 Loss of framing (E1 only).
 552 .It Li LOMF
 553 Loss of multiframing (E1 only).
 554 .It Li FARLOF
 555 Receiving remote alarm (E1 only).
 556 .It Li AIS16
 557 Receiving all ones in the timeslot 16 (E1 only).
 558 .It Li FARLOMF
 559 Receiving distant multiframe alarm (E1 only).
 560 .It Li TSTREQ
 561 Receiving test request code (G.703 only).
 562 .It Li TSTERR
 563 Test error (G.703 only).
 564 .El
 565 .\"--------------------------------------------------------------
 566 .Sh SEE ALSO
 567 .Xr stty 1 ,
 568 .Xr ioctl 2 ,
 569 .Xr ifconfig 8 ,
 570 .Xr route 8 ,
 571 .\"--------------------------------------------------------------
 572 .Sh HISTORY
 573 The
 574 .Nm
 575 utility appeared in
 576 .Fx 5.2 .
 577 The
 578 .Nm
 579 utility is a replacement for the
 580 .Nm cxconfig
 581 and
 582 .Nm ctconfig
 583 utilities that were used in the past with
 584 .Fx
 585 drivers.
 586 Those two utilities and
 587 .Nm
 588 are not compatible,
 589 and therefore all scripts using them have to be rewritten.
 590 Moreover,
 591 .Tn Linux
 592 and
 593 .Fx
 594 versions of the
 595 .Nm
 596 utility are not fully compatible.
 597 .\"--------------------------------------------------------------
 598 .Sh AUTHORS
 599 .An Cronyx Engineering Aq Mt info@cronyx.ru
 600 .Pp
 601 .Pa http://www.cronyx.ru
 602 .\"--------------------------------------------------------------
 603 .Sh BUGS
 604 All software produced by Cronyx Engineering is thoroughly tested.
 605 But as created by a man, it can contain some bugs.
 606 If you have caught one, try to localize it and send an email with the
 607 description of the bug, and all operations that you have done.
 608 We will try to reproduce the error and fix it.