home *** CD-ROM | disk | FTP | other *** search
- This is a subset of the documentation. To use this driver you MUST have the
- full package "z8530drv-2.4c.dl1bke.tar.gz" from either ftp.pspt.fi,
- sunsite.unc.edu or db0bm.automation.fh-aachen.de. Do not try to use the
- utilities from z8530drv-utils-3.0 as they will not work with the 2.4 series
- of the driver!
-
- ---------------------------------------------------------------------------
-
-
- SCC.C - Linux driver for Z8530 based HDLC cards for AX.25
-
- ********************************************************************
-
- (c) 1993,1997 by Joerg Reuter DL1BKE
-
- portions (c) 1993 Guido ten Dolle PE1NNZ
-
- for the complete copyright notice see >> Copying.Z8530DRV <<
-
- ********************************************************************
-
-
- 1. Initialization of the driver
- ===============================
-
- To use the driver, 3 steps must be performed:
-
- 1. if compiled as module: loading the module
- 2. Setup of hardware, MODEM and KISS parameters with sccinit
- 3. Attachment of each channel in the packet software
-
-
- 1.1 Loading the module
- ======================
-
- (If you're going to compile the driver as a part of the kernel image,
- skip this chapter and continue with 1.2)
-
- Before you can use a module, you'll have to load it with
-
- insmod scc.o
-
- please read 'man insmod' that comes with modutils.
-
- You should include the insmod in one of the /etc/rc.d/rc.* files,
- and don't forget to insert a call of sccinit after that. It
- will read your
-
-
- 1.2. /etc/z8530drv.rc
- =====================
-
- To setup all parameters you must run /sbin/sccinit from one
- of your rc.*-files. This has to be done BEFORE the start of
- NET or axattach. Sccinit reads the file /etc/z8530drv.rc
- and sets the hardware, MODEM and KISS parameters. A sample file is
- delivered with this package. Change it to your needs.
-
- The file itself consists of two main sections.
-
- 1.2.1 configuration of hardware parameters
- ==========================================
-
- The hardware setup section defines the following parameters for each
- Z8530:
-
- chip 1
- data_a 0x300 # data port A
- ctrl_a 0x304 # control port A
- data_b 0x301 # data port B
- ctrl_b 0x305 # control port B
- irq 5 # IRQ No. 5
- pclock 4915200 # clock
- board BAYCOM # hardware type
- escc no # enhanced SCC chip? (8580/85180/85280)
- vector 0 # latch for interrupt vector
- special no # address of special function register
- option 0 # option to set via sfr
-
-
- chip - this is just a delimiter to make sccinit a bit simpler to
- program. A parameter has no effect.
-
- data_a - the address of the data port A of this Z8530 (needed)
- ctrl_a - the address of the control port A (needed)
- data_b - the address of the data port B (needed)
- ctrl_b - the address of the control port B (needed)
-
- irq - the used IRQ for this chip. Different chips can use different
- IRQs or the same. If they share an interrupt, it needs to be
- specified within one chip-definition only.
-
- pclock - the clock at the PCLK pin of the Z8530 (option, 4915200 is
- default), measured in Hertz
-
- board - the "type" of the board:
-
- SCC type value
- ---------------------------------
- PA0HZP SCC card PA0HZP
- EAGLE card EAGLE
- PC100 card PC100
- PRIMUS-PC (DG9BL) card PRIMUS
- BayCom (U)SCC card BAYCOM
-
- escc - if you want support for ESCC chips (8580, 85180, 85280), set
- this to "yes" (option, defaults to "no")
-
- vector - address of the vector latch (aka "intack port") for PA0HZP
- cards. There can be only one vector latch for all chips!
- (option, defaults to 0)
-
- special - address of the special function register on several cards.
- (option, defaults to 0)
-
- option - The value you write into that register (option, default is 0)
-
- You can specify up to four chips (8 channels). If this is not enough,
- just change
-
- #define MAXSCC 4
-
- to a higher value.
-
- Example for the BayCom USCC:
- ----------------------------
-
- chip 1
- data_a 0x300 # data port A
- ctrl_a 0x304 # control port A
- data_b 0x301 # data port B
- ctrl_b 0x305 # control port B
- irq 5 # IRQ No. 5 (#)
- board BAYCOM # hardware type (*)
- #
- # SCC chip 2
- #
- chip 2
- data_a 0x302
- ctrl_a 0x306
- data_b 0x303
- ctrl_b 0x307
- board BAYCOM
-
- An example for a PA0HZP card:
- -----------------------------
-
- chip 1
- data_a 0x153
- data_b 0x151
- ctrl_a 0x152
- ctrl_b 0x150
- irq 9
- pclock 4915200
- board PA0HZP
- vector 0x168
- escc no
- #
- #
- #
- chip 2
- data_a 0x157
- data_b 0x155
- ctrl_a 0x156
- ctrl_b 0x154
- irq 9
- pclock 4915200
- board PA0HZP
- vector 0x168
- escc no
-
- A DRSI would should probably work with this:
- --------------------------------------------
- (actually: two DRSI cards...)
-
- chip 1
- data_a 0x303
- data_b 0x301
- ctrl_a 0x302
- ctrl_b 0x300
- irq 7
- pclock 4915200
- board DRSI
- escc no
- #
- #
- #
- chip 2
- data_a 0x313
- data_b 0x311
- ctrl_a 0x312
- ctrl_b 0x310
- irq 7
- pclock 4915200
- board DRSI
- escc no
-
- Note that you cannot use the on-board baudrate generator off DRSI
- cards. Use "mode dpll" for clock source (see below).
-
- This is based on information provided by Mike Bilow (and verified
- by Paul Helay)
-
- The utility "gencfg"
- --------------------
-
- If you only know the parameters for the PE1CHL driver for DOS,
- run gencfg. It will generate the correct port addresses (I hope).
- Its parameters are exactly the same as the ones you use with
- the "attach scc" command in net, except that the string "init" must
- not appear. Example:
-
- gencfg 2 0x150 4 2 0 1 0x168 9 4915200
-
- will print a skeleton z8530drv.rc for the OptoSCC to stdout.
-
- gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10
-
- does the same for the BayCom USCC card. I my opinion it is much easier
- to edit scc_config.h...
-
-
- 1.2.2 channel configuration
- ===========================
-
- The channel definition is divided into three sub sections for each
- channel:
-
- An example for /dev/scc0:
-
- # DEVICE
-
- device /dev/scc0 # the device for the following params
-
- # MODEM / BUFFERS
-
- speed 1200 # the default baudrate
- clock dpll # clock source:
- # dpll = normal halfduplex operation
- # external = MODEM provides own Rx/Tx clock
- # divider = use fullduplex divider if
- # installed (1)
- mode nrzi # HDLC encoding mode
- # nrzi = 1k2 MODEM, G3RUH 9k6 MODEM
- # nrz = DF9IC 9k6 MODEM
- #
- rxbuffers 8 # number of rx buffers allocated
- # (option, default is 4)
- txbuffers 16 # number of tx buffers allocated
- # (option, default is 16)
- bufsize 384 # size of buffers. Note that this must include
- # the AX.25 header, not only the data field!
- # (optional, defaults to 384)
-
- # KISS (Layer 1)
-
- txdelay 36 # (see chapter 1.4)
- persist 64
- slot 8
- tail 8
- fulldup 0
- wait 12
- min 3
- maxkey 7
- idle 3
- maxdef 120
- group 0
- txoff off
- softdcd on
- slip off
-
- The order WITHIN these sections is unimportant. The order OF these
- sections IS important. The MODEM parameters are set with the first
- recognized KISS parameter...
-
- Please note that you can initialize the board only once after boot.
- You can change all parameters but "mode" and "clock" later with the
- Sccparam program or through KISS. Just to avoid security holes...
-
- (1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not
- present at all (BayCom). It feeds back the output of the DPLL
- (digital pll) as transmit clock. Using this mode without a divider
- installed will normally result in keying the transceiver until
- maxkey expires --- of course without sending anything (useful).
-
-
- 2. Attachment of a channel by your AX.25 software
- =================================================
-
- 2.1 KA9Q NOS derivates
- ======================
-
- When the linux has startup, the SCC driver has been initialized,
- you can attach the channels in your packet software. This is done
- by open the scc devices by using the attach asy command.
- The SCC-drivers emulates the scc devices as serial asy ports,
- this means e.g. that the baudrate can be set in the attach command.
-
-
- Example Wampes:
-
- #############################################################################################
- # Wampes device attach
- # NOTE: Interfacename and the device must be the same!!
- # Usage: attach asy 0 0 slip|vjslip|ax25ui|ax25i|nrs|kissui <label> 0 <mtu> <speed> [ip_addr]
- #
- attach asy 0 0 kissi scc0 256 256 1200 # Attach SCC channel 1 in 1200 baud
- attach asy 0 0 kissi scc1 256 256 1200 # Attach SCC channel 2 in 1200 baud
- attach asy 0 0 kissui scc2 256 256 38400 # Attach SCC channel 3 in 38400 baud
- attach asy 0 0 kissui scc3 256 256 9600 # Attach SCC channel 4 in 9600 baud
- # ^^^^
- # for WAMPES 921229 use here: ax25
- #
-
- Example JNOS:
-
- ############################################
- # JNOS device attach
- #
- attach asy scc0 0 ax25 scc0 256 256 1200
- attach asy scc1 0 ax25 scc1 256 256 1200
- attach asy scc2 0 ax25 scc2 256 256 300
- attach asy scc3 0 ax25 scc3 256 256 4800
- #
- #
-
-
- It allows AX.25 communication without a TNC. Only a MODEM is
- needed. The parameters have the same meaning as in KISS mode.
- In fact, the AX.25 mode is emulating an extended KISS TNC, so
- the same commands can be used to set the parameters of the
- interface (see below).
-
- To be able to run fullduplex using an SCC in AX.25 mode, an
- external divider must be available, that divides the baudrate
- generator clock available on the TRxC pin by 32, and puts the
- resulting signal on the RTxC pint of the same channel of the SCC.
- Such a divider is not necessary for normal CSMA packet radio
- operation, but interrupt overhead is slightly reduced if you
- still install it.
-
- 2.2 Kernel AX.25
- ================
-
- Well, as said before: The driver emulates a KISS TNC, so you
- can simply run
-
- axattach -s 1200 /dev/scc0 DL1BKE
-
- to establish the link between kernel AX.25 and z8530drv.
-
-
- 3. Adjustment and Display of parameters
- =======================================
-
- 3.1 Displaying SCC Parameters:
- ==============================
-
- Once a SCC channel has been attached, the parameter settings and
- some statistic information can be shown using the param program:
-
- dl1bke-u:~$ sccstat /dev/scc0
-
- Parameters:
-
- speed : 1200 baud
- txdelay : 36
- persist : 255
- slottime : 0
- txtail : 8
- fulldup : 1
- waittime : 12
- mintime : 3 sec
- maxkeyup : 7 sec
- idletime : 3 sec
- maxdefer : 120 sec
- group : 0x00
- txoff : off
- softdcd : on
- SLIP : off
-
- Status:
-
- HDLC Z8530 Interrupts Queues
- -----------------------------------------------------------------------
- Sent : 273 RxOver : 0 RxInts : 125074 RxQueue : 0
- Received : 1095 TxUnder: 0 TxInts : 4684 TxQueue : 0
- RxErrors : 1591 ExInts : 11776 NoSpace : 0
- KissErrors : 0 SpInts : 1503
- Tx State : idle
-
- Memory allocated:
-
- Buffer size: 384
- rx buffers : 4
- tx buffers : 8
-
-
- The status info shown is:
-
- Sent - number of frames transmitted
- Received - number of frames received
- RxErrors - number of receive errors (CRC, ABORT)
- KissErrors - number of KISS errors (should be zero...)
- Tx State - status of the Tx interrupt handler: idle/busy/active/tail (2)
- RxOver - number of receiver overruns
- TxUnder - number of transmitter underruns
- RxInts - number of receiver interrupts
- TxInts - number of transmitter interrupts
- EpInts - number of receiver special condition interrupts
- SpInts - number of external/status interrupts
- RxQueue - number of received packets enqueued for this channel
- TxQueue - number of packets enqueued for Tx
- NoSpace - number of times the receiver buffer pool was found empty
-
-
- An overrun is abnormal. If lots of these occur, the product of
- baudrate and number of interfaces is too high for the processing
- power of you computer. If "Space" errors occur, specify a higher
- number of buffers in the "scc.h" file.
-
-
- 3.2 Setting Parameters
- ======================
-
-
- The setting of parameters of the emulated KISS TNC is done in the
- same way in the SCC driver. You can change parameters by using
- the command param in NET or NOS
-
- param <iface> <paramname> <value>
-
- or use the program "sccparam":
-
- sccparam <device> <paramname> <decimal-|hexadecimal value>
-
- You can change the following parameters:
-
- param : value
- ------------------------
- speed : 1200
- txdelay : 36
- persist : 255
- slottime : 0
- txtail : 8
- fulldup : 1
- waittime : 12
- mintime : 3
- maxkeyup : 7
- idletime : 3
- maxdefer : 120
- group : 0x00
- txoff : off
- softdcd : on
- SLIP : off
-
-
- The parameters have the following meaning:
-
- speed:
- The baudrate on this channel in bits/sec
-
- Example: sccparam /dev/scc3 speed 9600
-
- txdelay:
- The delay (in units of 10ms) after keying of the
- transmitter, until the first byte is sent. This is usually
- called "TXDELAY" in a TNC. When 0 is specified, the driver
- will just wait until the CTS signal is asserted. This
- assumes the presence of a timer or other circuitry in the
- MODEM and/or transmitter, that asserts CTS when the
- transmitter is ready for data.
- A normal value of this parameter is 30-36.
-
- Example: sccparam /dev/scc0 txd 20
-
- persist:
- This is the probability that the transmitter will be keyed
- when the channel is found to be free. It is a value from 0
- to 255, and the probability is (value+1)/256. The value
- should be somewhere near 50-60, and should be lowered when
- the channel is used more heavily.
-
- Example: sccparam /dev/scc2 persist 20
-
- slottime:
- This is the time between samples of the channel. It is
- expressed in units of 10ms. About 200-300 ms (value 20-30)
- seems to be a good value.
-
- Example: sccparam /dev/scc0 slot 20
-
- tail:
- The time the transmitter will remain keyed after the last
- byte of a packet has been transferred to the SCC. This is
- necessary because the CRC and a flag still have to leave the
- SCC before the transmitter is keyed down. The value depends
- on the baudrate selected. A few character times should be
- sufficient, e.g. 40ms at 1200 baud. (value 4)
- The value of this parameter is in 10ms units.
-
- Example: sccparam /dev/scc2 4
-
- full:
- The full-duplex mode switch. This can be one of the following
- values:
-
- 0: The interface will operate in CSMA mode (the normal
- half-duplex packet radio operation)
- 1: Fullduplex mode, i.e. the transmitter will be keyed at
- any time, without checking the received carrier. It
- will be unkeyed when there are no packets to be sent.
- 2: Like 1, but the transmitter will remain keyed, also
- when there are no packets to be sent. Flags will be
- sent in that case, until a timeout (parameter 10)
- occurs.
-
- Example: sccparam /dev/scc0 fulldup off
-
- wait:
- The initial waittime before any transmit attempt, after the
- frame has been queue for transmit. This is the length of
- the first slot in CSMA mode. In fullduplex modes it is
- set to 0 for maximum performance.
- The value of this parameter is in 10ms units.
-
- Example: sccparam /dev/scc1 wait 4
-
- maxkey:
- The maximal time the transmitter will be keyed to send
- packets, in seconds. This can be useful on busy CSMA
- channels, to avoid "getting a bad reputation" when you are
- generating a lot of traffic. After the specified time has
- elapsed, no new frame will be started. Instead, the trans-
- mitter will be switched off for a specified time (parameter
- min), and then the selected algorithm for keyup will be
- started again.
- The value 0 as well as "off" will disable this feature,
- and allow infinite transmission time.
-
- Example: sccparam /dev/scc0 maxk 20
-
- min:
- This is the time the transmitter will be switched off when
- the maximum transmission time is exceeded.
-
- Example: sccparam /dev/scc3 min 10
-
- idle
- This parameter specifies the maximum idle time in fullduplex
- 2 mode, in seconds. When no frames have been sent for this
- time, the transmitter will be keyed down. A value of 0 is
- has same result as the fullduplex mode 1. This parameter
- can be disabled.
-
- Example: sccparam /dev/scc2 idle off # transmit forever
-
- maxdefer
- This is the maximum time (in seconds) to wait for a free channel
- to send. When this timer expires the transmitter will be keyed
- IMMEDIATELY. If you love to get trouble with other users you
- should set this to a very low value ;-)
-
- Example: sccparam /dev/scc0 maxdefer 240 # 2 minutes
-
-
- txoff:
- When this parameter has the value 0, the transmission of packets
- is enable. Otherwise it is disabled.
-
- Example: sccparam /dev/scc2 txoff on
-
- group:
- It is possible to build special radio equipment to use more than
- one frequency on the same bad, e.g. using several receivers and
- only one transmitter that can be switched between frequencies.
- Also, you can connect several radios that are active on the same
- band. In these cases, it is not possible, or not a good idea, to
- transmit on more than one frequency. The SCC driver provides a
- method to lock transmitters on different interfaces, using the
- "param <interface> group <x>" command. This will only work when
- you are using CSMA mode (parameter full = 0).
- The number <x> must be 0 if you want no group restrictions, and
- can be computed as follows to create restricted groups:
- <x> is the sum of some OCTAL numbers:
-
- 200 This transmitter will only be keyed when all other
- transmitters in the group are off.
- 100 This transmitter will only be keyed when the carrier
- detect of all other interfaces in the group is off.
- 0xx A byte that can be used to define different groups.
- Interfaces are in the same group, when the logical AND
- between their xx values is nonzero.
-
- Examples:
- When 2 interfaces use group 201, their transmitters will never be
- keyed at the same time.
- When 2 interfaces use group 101, the transmitters will only key
- when both channels are clear at the same time. When group 301,
- the transmitters will not be keyed at the same time.
-
- Don't forget to convert the octal numbers into decimal before
- you set the parameter.
-
- Example: (to be written)
-
- softdcd:
- use a software dcd instead of the real one... Useful for a very
- slow squelch.
-
- Example: sccparam /dev/scc0 soft on
-
-
- slip:
- use slip encoding instead of kiss
-
- Example: sccparam /dev/scc1 slip on
-
-
-
- 4. Problems
- ===========
-
- If you have tx-problems with your BayCom USCC card please check
- the manufacturer of the 8530. SGS chips have a slightly
- different timing. Try Zilog... I have no information if this
- driver works with baudrates higher than 1200 baud. A solution is
- to write to register 8 instead to the data port, but this won't
- work with the ESCC chips *SIGH!*
-
- I got reports that the driver has problems on some 386-based systems.
- (i.e. Amstrad) Those systems have a bogus AT bus timing which will
- lead to delayed answers on interrupts. You can recognize these
- problems by looking at the output of Sccstat for the suspected
- port. See if it shows under- and overruns you own such a system.
- Perhaps it will help if you simplify the scc_isr() function a bit.
- You'll find a slightly faster version in the files scc_isr_intack
- or scc_isr_novec.
-
-
- Delayed processing of received data: This depends on
-
- - the kernel version
-
- - kernel profiling compiled or not
-
- - the rather slow receiver in tty_io.c
-
- - a high interrupt load
-
- - a high load of the machine --- running X, Xmorph, XV and Povray,
- while compiling the kernel... hmm ... even with 32 MB RAM ... ;-)
-
- - NET's speed itself.
-
-
- Kernel panics: please read to /linux/README and find out if it
- really occurred within the scc driver.
-
- If you can't solve a problem, send me
-
- - a description of the problem,
- - information on your hardware (computer system, scc board, modem)
- - your kernel version
- - the output of sccstat /dev/scc# ("#" is the No. of the channel)
- - the settings of "speed", "clock" and "mode" for that channel
- in /etc/z8530drv.rc
- - your scc_config.h
-
-
- And always remember:
- The 1.1.* kernel series is for alpha tests -- use at your own risk ;-)
- The 1.2.* series should run reliable. This driver perhaps NOT!
- The 1.3.* kernel series is for alpha tests again... you get the idea!
-
-
- 3. DRSI Boards
- ==============
-
- I still can't test the DRSI board, but this configuration derived from
- the PE1CHL SCC driver configuration should work:
-
- An example of scc_config.h for
-
- One DRSI board installed:
- =========================
-
- /* gencfg 1 0x300 0x10 2 0 1 0 7 4915200 */
-
- /* file generated by $Id: gencfg.c,v 1.2 1994/11/29 21:42:24 JReuter Exp JReuter $ */
-
- #include <linux/scc.h>
-
- int Nchips = 1;
- io_port Vector_Latch = 0x0;
- int Ivec = 7;
- long Clock = 4915200;
- char Board = PA0HZP;
- int Option = 0;
- io_port Special_Port = 0x0;
-
- io_port SCC_ctrl[MAXSCC * 2] =
- {0x302, 0x300, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};
-
- io_port SCC_data[MAXSCC * 2] =
- {0x303, 0x301, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};
-
- /* set to '1' if you have and want ESCC chip (8580/85180/85280) support */
-
- /* Chip */
- /* ======== */
- int SCC_Enhanced[MAXSCC] = {0, /* ...one... */
- 0, /* ...two... */
- 0, /* ...three... */
- 0}; /* ...four... */
-
- #define VERBOSE_BOOTMSG 1
- #undef SCC_DELAY /* perhaps a 486DX2 is a *bit* too fast */
- #undef SCC_LDELAY /* slow it even a bit more down */
- #undef DONT_CHECK /* don't look if the SCCs you specified are available */
-
-
-
- Two boards installed:
- =====================
-
- /* file generated by $Id: gencfg.c,v 1.2 1994/11/29 21:42:24 JReuter Exp JReuter $ */
-
- #include <linux/scc.h>
-
- int Nchips = 2;
- io_port Vector_Latch = 0x0;
- int Ivec = 7;
- long Clock = 4915200;
- char Board = PA0HZP;
- int Option = 0;
- io_port Special_Port = 0x0;
-
- io_port SCC_ctrl[MAXSCC * 2] =
- {0x302, 0x300, 0x312, 0x310, 0x0, 0x0, 0x0, 0x0};
-
- io_port SCC_data[MAXSCC * 2] =
- {0x303, 0x301, 0x313, 0x311, 0x0, 0x0, 0x0, 0x0};
-
- /* set to '1' if you have and want ESCC chip (8580/85180/85280) support */
-
- /* Chip */
- /* ======== */
- int SCC_Enhanced[MAXSCC] = {0, /* ...one... */
- 0, /* ...two... */
- 0, /* ...three... */
- 0}; /* ...four... */
-
- #define VERBOSE_BOOTMSG 1
- #undef SCC_DELAY /* perhaps a 486DX2 is a *bit* too fast */
- #undef SCC_LDELAY /* slow it even a bit more down */
- #undef DONT_CHECK /* don't look if the SCCs you specified are available */
-
-
- *****************
-
- You m u s t use "clock dpll" in /etc/z8530drv.rc for operation,
- the on-board baudrate generator is not supported.
-
- *****************
- (mni tnx to Mike Bilow)
-
-
- 4. Thor RLC100
- ==============
-
- Mysteriously this board seems not to work with the driver. Anyone
- got it up-and-running?
-
-
- Many thanks to Linus Torvalds and Alan Cox for including the driver
- in the Linux standard distribution and their support.
-
- Joerg Reuter ampr-net: dl1bke@db0pra.ampr.org
- WWW : http://www.rat.de/jr
- Internet: jreuter@poboxes.com
-