0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 =========================================================
0005 SCC.C - Linux driver for Z8530 based HDLC cards for AX.25
0006 =========================================================
0007
0008
0009 This is a subset of the documentation. To use this driver you MUST have the
0010 full package from:
0011
0012 Internet:
0013
0014 1. ftp://ftp.ccac.rwth-aachen.de/pub/jr/z8530drv-utils_3.0-3.tar.gz
0015
0016 2. ftp://ftp.pspt.fi/pub/ham/linux/ax25/z8530drv-utils_3.0-3.tar.gz
0017
0018 Please note that the information in this document may be hopelessly outdated.
0019 A new version of the documentation, along with links to other important
0020 Linux Kernel AX.25 documentation and programs, is available on
0021 http://yaina.de/jreuter
0022
0023 Copyright |copy| 1993,2000 by Joerg Reuter DL1BKE <jreuter@yaina.de>
0024
0025 portions Copyright |copy| 1993 Guido ten Dolle PE1NNZ
0026
0027 for the complete copyright notice see >> Copying.Z8530DRV <<
0028
0029 1. Initialization of the driver
0030 ===============================
0031
0032 To use the driver, 3 steps must be performed:
0033
0034 1. if compiled as module: loading the module
0035 2. Setup of hardware, MODEM and KISS parameters with sccinit
0036 3. Attach each channel to the Linux kernel AX.25 with "ifconfig"
0037
0038 Unlike the versions below 2.4 this driver is a real network device
0039 driver. If you want to run xNOS instead of our fine kernel AX.25
0040 use a 2.x version (available from above sites) or read the
0041 AX.25-HOWTO on how to emulate a KISS TNC on network device drivers.
0042
0043
0044 1.1 Loading the module
0045 ======================
0046
0047 (If you're going to compile the driver as a part of the kernel image,
0048 skip this chapter and continue with 1.2)
0049
0050 Before you can use a module, you'll have to load it with::
0051
0052 insmod scc.o
0053
0054 please read 'man insmod' that comes with module-init-tools.
0055
0056 You should include the insmod in one of the /etc/rc.d/rc.* files,
0057 and don't forget to insert a call of sccinit after that. It
0058 will read your /etc/z8530drv.conf.
0059
0060 1.2. /etc/z8530drv.conf
0061 =======================
0062
0063 To setup all parameters you must run /sbin/sccinit from one
0064 of your rc.*-files. This has to be done BEFORE you can
0065 "ifconfig" an interface. Sccinit reads the file /etc/z8530drv.conf
0066 and sets the hardware, MODEM and KISS parameters. A sample file is
0067 delivered with this package. Change it to your needs.
0068
0069 The file itself consists of two main sections.
0070
0071 1.2.1 configuration of hardware parameters
0072 ==========================================
0073
0074 The hardware setup section defines the following parameters for each
0075 Z8530::
0076
0077 chip 1
0078 data_a 0x300 # data port A
0079 ctrl_a 0x304 # control port A
0080 data_b 0x301 # data port B
0081 ctrl_b 0x305 # control port B
0082 irq 5 # IRQ No. 5
0083 pclock 4915200 # clock
0084 board BAYCOM # hardware type
0085 escc no # enhanced SCC chip? (8580/85180/85280)
0086 vector 0 # latch for interrupt vector
0087 special no # address of special function register
0088 option 0 # option to set via sfr
0089
0090
0091 chip
0092 - this is just a delimiter to make sccinit a bit simpler to
0093 program. A parameter has no effect.
0094
0095 data_a
0096 - the address of the data port A of this Z8530 (needed)
0097 ctrl_a
0098 - the address of the control port A (needed)
0099 data_b
0100 - the address of the data port B (needed)
0101 ctrl_b
0102 - the address of the control port B (needed)
0103
0104 irq
0105 - the used IRQ for this chip. Different chips can use different
0106 IRQs or the same. If they share an interrupt, it needs to be
0107 specified within one chip-definition only.
0108
0109 pclock - the clock at the PCLK pin of the Z8530 (option, 4915200 is
0110 default), measured in Hertz
0111
0112 board
0113 - the "type" of the board:
0114
0115 ======================= ========
0116 SCC type value
0117 ======================= ========
0118 PA0HZP SCC card PA0HZP
0119 EAGLE card EAGLE
0120 PC100 card PC100
0121 PRIMUS-PC (DG9BL) card PRIMUS
0122 BayCom (U)SCC card BAYCOM
0123 ======================= ========
0124
0125 escc
0126 - if you want support for ESCC chips (8580, 85180, 85280), set
0127 this to "yes" (option, defaults to "no")
0128
0129 vector
0130 - address of the vector latch (aka "intack port") for PA0HZP
0131 cards. There can be only one vector latch for all chips!
0132 (option, defaults to 0)
0133
0134 special
0135 - address of the special function register on several cards.
0136 (option, defaults to 0)
0137
0138 option - The value you write into that register (option, default is 0)
0139
0140 You can specify up to four chips (8 channels). If this is not enough,
0141 just change::
0142
0143 #define MAXSCC 4
0144
0145 to a higher value.
0146
0147 Example for the BAYCOM USCC:
0148 ----------------------------
0149
0150 ::
0151
0152 chip 1
0153 data_a 0x300 # data port A
0154 ctrl_a 0x304 # control port A
0155 data_b 0x301 # data port B
0156 ctrl_b 0x305 # control port B
0157 irq 5 # IRQ No. 5 (#)
0158 board BAYCOM # hardware type (*)
0159 #
0160 # SCC chip 2
0161 #
0162 chip 2
0163 data_a 0x302
0164 ctrl_a 0x306
0165 data_b 0x303
0166 ctrl_b 0x307
0167 board BAYCOM
0168
0169 An example for a PA0HZP card:
0170 -----------------------------
0171
0172 ::
0173
0174 chip 1
0175 data_a 0x153
0176 data_b 0x151
0177 ctrl_a 0x152
0178 ctrl_b 0x150
0179 irq 9
0180 pclock 4915200
0181 board PA0HZP
0182 vector 0x168
0183 escc no
0184 #
0185 #
0186 #
0187 chip 2
0188 data_a 0x157
0189 data_b 0x155
0190 ctrl_a 0x156
0191 ctrl_b 0x154
0192 irq 9
0193 pclock 4915200
0194 board PA0HZP
0195 vector 0x168
0196 escc no
0197
0198 A DRSI would should probably work with this:
0199 --------------------------------------------
0200 (actually: two DRSI cards...)
0201
0202 ::
0203
0204 chip 1
0205 data_a 0x303
0206 data_b 0x301
0207 ctrl_a 0x302
0208 ctrl_b 0x300
0209 irq 7
0210 pclock 4915200
0211 board DRSI
0212 escc no
0213 #
0214 #
0215 #
0216 chip 2
0217 data_a 0x313
0218 data_b 0x311
0219 ctrl_a 0x312
0220 ctrl_b 0x310
0221 irq 7
0222 pclock 4915200
0223 board DRSI
0224 escc no
0225
0226 Note that you cannot use the on-board baudrate generator off DRSI
0227 cards. Use "mode dpll" for clock source (see below).
0228
0229 This is based on information provided by Mike Bilow (and verified
0230 by Paul Helay)
0231
0232 The utility "gencfg"
0233 --------------------
0234
0235 If you only know the parameters for the PE1CHL driver for DOS,
0236 run gencfg. It will generate the correct port addresses (I hope).
0237 Its parameters are exactly the same as the ones you use with
0238 the "attach scc" command in net, except that the string "init" must
0239 not appear. Example::
0240
0241 gencfg 2 0x150 4 2 0 1 0x168 9 4915200
0242
0243 will print a skeleton z8530drv.conf for the OptoSCC to stdout.
0244
0245 ::
0246
0247 gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10
0248
0249 does the same for the BAYCOM USCC card. In my opinion it is much easier
0250 to edit scc_config.h...
0251
0252
0253 1.2.2 channel configuration
0254 ===========================
0255
0256 The channel definition is divided into three sub sections for each
0257 channel:
0258
0259 An example for scc0::
0260
0261 # DEVICE
0262
0263 device scc0 # the device for the following params
0264
0265 # MODEM / BUFFERS
0266
0267 speed 1200 # the default baudrate
0268 clock dpll # clock source:
0269 # dpll = normal half duplex operation
0270 # external = MODEM provides own Rx/Tx clock
0271 # divider = use full duplex divider if
0272 # installed (1)
0273 mode nrzi # HDLC encoding mode
0274 # nrzi = 1k2 MODEM, G3RUH 9k6 MODEM
0275 # nrz = DF9IC 9k6 MODEM
0276 #
0277 bufsize 384 # size of buffers. Note that this must include
0278 # the AX.25 header, not only the data field!
0279 # (optional, defaults to 384)
0280
0281 # KISS (Layer 1)
0282
0283 txdelay 36 # (see chapter 1.4)
0284 persist 64
0285 slot 8
0286 tail 8
0287 fulldup 0
0288 wait 12
0289 min 3
0290 maxkey 7
0291 idle 3
0292 maxdef 120
0293 group 0
0294 txoff off
0295 softdcd on
0296 slip off
0297
0298 The order WITHIN these sections is unimportant. The order OF these
0299 sections IS important. The MODEM parameters are set with the first
0300 recognized KISS parameter...
0301
0302 Please note that you can initialize the board only once after boot
0303 (or insmod). You can change all parameters but "mode" and "clock"
0304 later with the Sccparam program or through KISS. Just to avoid
0305 security holes...
0306
0307 (1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not
0308 present at all (BayCom). It feeds back the output of the DPLL
0309 (digital pll) as transmit clock. Using this mode without a divider
0310 installed will normally result in keying the transceiver until
0311 maxkey expires --- of course without sending anything (useful).
0312
0313 2. Attachment of a channel by your AX.25 software
0314 =================================================
0315
0316 2.1 Kernel AX.25
0317 ================
0318
0319 To set up an AX.25 device you can simply type::
0320
0321 ifconfig scc0 44.128.1.1 hw ax25 dl0tha-7
0322
0323 This will create a network interface with the IP number 44.128.20.107
0324 and the callsign "dl0tha". If you do not have any IP number (yet) you
0325 can use any of the 44.128.0.0 network. Note that you do not need
0326 axattach. The purpose of axattach (like slattach) is to create a KISS
0327 network device linked to a TTY. Please read the documentation of the
0328 ax25-utils and the AX.25-HOWTO to learn how to set the parameters of
0329 the kernel AX.25.
0330
0331 2.2 NOS, NET and TFKISS
0332 =======================
0333
0334 Since the TTY driver (aka KISS TNC emulation) is gone you need
0335 to emulate the old behaviour. The cost of using these programs is
0336 that you probably need to compile the kernel AX.25, regardless of whether
0337 you actually use it or not. First setup your /etc/ax25/axports,
0338 for example::
0339
0340 9k6 dl0tha-9 9600 255 4 9600 baud port (scc3)
0341 axlink dl0tha-15 38400 255 4 Link to NOS
0342
0343 Now "ifconfig" the scc device::
0344
0345 ifconfig scc3 44.128.1.1 hw ax25 dl0tha-9
0346
0347 You can now axattach a pseudo-TTY::
0348
0349 axattach /dev/ptys0 axlink
0350
0351 and start your NOS and attach /dev/ptys0 there. The problem is that
0352 NOS is reachable only via digipeating through the kernel AX.25
0353 (disastrous on a DAMA controlled channel). To solve this problem,
0354 configure "rxecho" to echo the incoming frames from "9k6" to "axlink"
0355 and outgoing frames from "axlink" to "9k6" and start::
0356
0357 rxecho
0358
0359 Or simply use "kissbridge" coming with z8530drv-utils::
0360
0361 ifconfig scc3 hw ax25 dl0tha-9
0362 kissbridge scc3 /dev/ptys0
0363
0364
0365 3. Adjustment and Display of parameters
0366 =======================================
0367
0368 3.1 Displaying SCC Parameters:
0369 ==============================
0370
0371 Once a SCC channel has been attached, the parameter settings and
0372 some statistic information can be shown using the param program::
0373
0374 dl1bke-u:~$ sccstat scc0
0375
0376 Parameters:
0377
0378 speed : 1200 baud
0379 txdelay : 36
0380 persist : 255
0381 slottime : 0
0382 txtail : 8
0383 fulldup : 1
0384 waittime : 12
0385 mintime : 3 sec
0386 maxkeyup : 7 sec
0387 idletime : 3 sec
0388 maxdefer : 120 sec
0389 group : 0x00
0390 txoff : off
0391 softdcd : on
0392 SLIP : off
0393
0394 Status:
0395
0396 HDLC Z8530 Interrupts Buffers
0397 -----------------------------------------------------------------------
0398 Sent : 273 RxOver : 0 RxInts : 125074 Size : 384
0399 Received : 1095 TxUnder: 0 TxInts : 4684 NoSpace : 0
0400 RxErrors : 1591 ExInts : 11776
0401 TxErrors : 0 SpInts : 1503
0402 Tx State : idle
0403
0404
0405 The status info shown is:
0406
0407 ============== ==============================================================
0408 Sent number of frames transmitted
0409 Received number of frames received
0410 RxErrors number of receive errors (CRC, ABORT)
0411 TxErrors number of discarded Tx frames (due to various reasons)
0412 Tx State status of the Tx interrupt handler: idle/busy/active/tail (2)
0413 RxOver number of receiver overruns
0414 TxUnder number of transmitter underruns
0415 RxInts number of receiver interrupts
0416 TxInts number of transmitter interrupts
0417 EpInts number of receiver special condition interrupts
0418 SpInts number of external/status interrupts
0419 Size maximum size of an AX.25 frame (*with* AX.25 headers!)
0420 NoSpace number of times a buffer could not get allocated
0421 ============== ==============================================================
0422
0423 An overrun is abnormal. If lots of these occur, the product of
0424 baudrate and number of interfaces is too high for the processing
0425 power of your computer. NoSpace errors are unlikely to be caused by the
0426 driver or the kernel AX.25.
0427
0428
0429 3.2 Setting Parameters
0430 ======================
0431
0432
0433 The setting of parameters of the emulated KISS TNC is done in the
0434 same way in the SCC driver. You can change parameters by using
0435 the kissparms program from the ax25-utils package or use the program
0436 "sccparam"::
0437
0438 sccparam <device> <paramname> <decimal-|hexadecimal value>
0439
0440 You can change the following parameters:
0441
0442 =========== =====
0443 param value
0444 =========== =====
0445 speed 1200
0446 txdelay 36
0447 persist 255
0448 slottime 0
0449 txtail 8
0450 fulldup 1
0451 waittime 12
0452 mintime 3
0453 maxkeyup 7
0454 idletime 3
0455 maxdefer 120
0456 group 0x00
0457 txoff off
0458 softdcd on
0459 SLIP off
0460 =========== =====
0461
0462
0463 The parameters have the following meaning:
0464
0465 speed:
0466 The baudrate on this channel in bits/sec
0467
0468 Example: sccparam /dev/scc3 speed 9600
0469
0470 txdelay:
0471 The delay (in units of 10 ms) after keying of the
0472 transmitter, until the first byte is sent. This is usually
0473 called "TXDELAY" in a TNC. When 0 is specified, the driver
0474 will just wait until the CTS signal is asserted. This
0475 assumes the presence of a timer or other circuitry in the
0476 MODEM and/or transmitter, that asserts CTS when the
0477 transmitter is ready for data.
0478 A normal value of this parameter is 30-36.
0479
0480 Example: sccparam /dev/scc0 txd 20
0481
0482 persist:
0483 This is the probability that the transmitter will be keyed
0484 when the channel is found to be free. It is a value from 0
0485 to 255, and the probability is (value+1)/256. The value
0486 should be somewhere near 50-60, and should be lowered when
0487 the channel is used more heavily.
0488
0489 Example: sccparam /dev/scc2 persist 20
0490
0491 slottime:
0492 This is the time between samples of the channel. It is
0493 expressed in units of 10 ms. About 200-300 ms (value 20-30)
0494 seems to be a good value.
0495
0496 Example: sccparam /dev/scc0 slot 20
0497
0498 tail:
0499 The time the transmitter will remain keyed after the last
0500 byte of a packet has been transferred to the SCC. This is
0501 necessary because the CRC and a flag still have to leave the
0502 SCC before the transmitter is keyed down. The value depends
0503 on the baudrate selected. A few character times should be
0504 sufficient, e.g. 40ms at 1200 baud. (value 4)
0505 The value of this parameter is in 10 ms units.
0506
0507 Example: sccparam /dev/scc2 4
0508
0509 full:
0510 The full-duplex mode switch. This can be one of the following
0511 values:
0512
0513 0: The interface will operate in CSMA mode (the normal
0514 half-duplex packet radio operation)
0515 1: Fullduplex mode, i.e. the transmitter will be keyed at
0516 any time, without checking the received carrier. It
0517 will be unkeyed when there are no packets to be sent.
0518 2: Like 1, but the transmitter will remain keyed, also
0519 when there are no packets to be sent. Flags will be
0520 sent in that case, until a timeout (parameter 10)
0521 occurs.
0522
0523 Example: sccparam /dev/scc0 fulldup off
0524
0525 wait:
0526 The initial waittime before any transmit attempt, after the
0527 frame has been queue for transmit. This is the length of
0528 the first slot in CSMA mode. In full duplex modes it is
0529 set to 0 for maximum performance.
0530 The value of this parameter is in 10 ms units.
0531
0532 Example: sccparam /dev/scc1 wait 4
0533
0534 maxkey:
0535 The maximal time the transmitter will be keyed to send
0536 packets, in seconds. This can be useful on busy CSMA
0537 channels, to avoid "getting a bad reputation" when you are
0538 generating a lot of traffic. After the specified time has
0539 elapsed, no new frame will be started. Instead, the trans-
0540 mitter will be switched off for a specified time (parameter
0541 min), and then the selected algorithm for keyup will be
0542 started again.
0543 The value 0 as well as "off" will disable this feature,
0544 and allow infinite transmission time.
0545
0546 Example: sccparam /dev/scc0 maxk 20
0547
0548 min:
0549 This is the time the transmitter will be switched off when
0550 the maximum transmission time is exceeded.
0551
0552 Example: sccparam /dev/scc3 min 10
0553
0554 idle:
0555 This parameter specifies the maximum idle time in full duplex
0556 2 mode, in seconds. When no frames have been sent for this
0557 time, the transmitter will be keyed down. A value of 0 is
0558 has same result as the fullduplex mode 1. This parameter
0559 can be disabled.
0560
0561 Example: sccparam /dev/scc2 idle off # transmit forever
0562
0563 maxdefer
0564 This is the maximum time (in seconds) to wait for a free channel
0565 to send. When this timer expires the transmitter will be keyed
0566 IMMEDIATELY. If you love to get trouble with other users you
0567 should set this to a very low value ;-)
0568
0569 Example: sccparam /dev/scc0 maxdefer 240 # 2 minutes
0570
0571
0572 txoff:
0573 When this parameter has the value 0, the transmission of packets
0574 is enable. Otherwise it is disabled.
0575
0576 Example: sccparam /dev/scc2 txoff on
0577
0578 group:
0579 It is possible to build special radio equipment to use more than
0580 one frequency on the same band, e.g. using several receivers and
0581 only one transmitter that can be switched between frequencies.
0582 Also, you can connect several radios that are active on the same
0583 band. In these cases, it is not possible, or not a good idea, to
0584 transmit on more than one frequency. The SCC driver provides a
0585 method to lock transmitters on different interfaces, using the
0586 "param <interface> group <x>" command. This will only work when
0587 you are using CSMA mode (parameter full = 0).
0588
0589 The number <x> must be 0 if you want no group restrictions, and
0590 can be computed as follows to create restricted groups:
0591 <x> is the sum of some OCTAL numbers:
0592
0593
0594 === =======================================================
0595 200 This transmitter will only be keyed when all other
0596 transmitters in the group are off.
0597 100 This transmitter will only be keyed when the carrier
0598 detect of all other interfaces in the group is off.
0599 0xx A byte that can be used to define different groups.
0600 Interfaces are in the same group, when the logical AND
0601 between their xx values is nonzero.
0602 === =======================================================
0603
0604 Examples:
0605
0606 When 2 interfaces use group 201, their transmitters will never be
0607 keyed at the same time.
0608
0609 When 2 interfaces use group 101, the transmitters will only key
0610 when both channels are clear at the same time. When group 301,
0611 the transmitters will not be keyed at the same time.
0612
0613 Don't forget to convert the octal numbers into decimal before
0614 you set the parameter.
0615
0616 Example: (to be written)
0617
0618 softdcd:
0619 use a software dcd instead of the real one... Useful for a very
0620 slow squelch.
0621
0622 Example: sccparam /dev/scc0 soft on
0623
0624
0625 4. Problems
0626 ===========
0627
0628 If you have tx-problems with your BayCom USCC card please check
0629 the manufacturer of the 8530. SGS chips have a slightly
0630 different timing. Try Zilog... A solution is to write to register 8
0631 instead to the data port, but this won't work with the ESCC chips.
0632 *SIGH!*
0633
0634 A very common problem is that the PTT locks until the maxkeyup timer
0635 expires, although interrupts and clock source are correct. In most
0636 cases compiling the driver with CONFIG_SCC_DELAY (set with
0637 make config) solves the problems. For more hints read the (pseudo) FAQ
0638 and the documentation coming with z8530drv-utils.
0639
0640 I got reports that the driver has problems on some 386-based systems.
0641 (i.e. Amstrad) Those systems have a bogus AT bus timing which will
0642 lead to delayed answers on interrupts. You can recognize these
0643 problems by looking at the output of Sccstat for the suspected
0644 port. If it shows under- and overruns you own such a system.
0645
0646 Delayed processing of received data: This depends on
0647
0648 - the kernel version
0649
0650 - kernel profiling compiled or not
0651
0652 - a high interrupt load
0653
0654 - a high load of the machine --- running X, Xmorph, XV and Povray,
0655 while compiling the kernel... hmm ... even with 32 MB RAM ... ;-)
0656 Or running a named for the whole .ampr.org domain on an 8 MB
0657 box...
0658
0659 - using information from rxecho or kissbridge.
0660
0661 Kernel panics: please read /linux/README and find out if it
0662 really occurred within the scc driver.
0663
0664 If you cannot solve a problem, send me
0665
0666 - a description of the problem,
0667 - information on your hardware (computer system, scc board, modem)
0668 - your kernel version
0669 - the output of cat /proc/net/z8530
0670
0671 4. Thor RLC100
0672 ==============
0673
0674 Mysteriously this board seems not to work with the driver. Anyone
0675 got it up-and-running?
0676
0677
0678 Many thanks to Linus Torvalds and Alan Cox for including the driver
0679 in the Linux standard distribution and their support.
0680
0681 ::
0682
0683 Joerg Reuter ampr-net: dl1bke@db0pra.ampr.org
0684 AX-25 : DL1BKE @ DB0ABH.#BAY.DEU.EU
0685 Internet: jreuter@yaina.de
0686 WWW : http://yaina.de/jreuter
