z8530drv.txt 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657
  1. This is a subset of the documentation. To use this driver you MUST have the
  2. full package from:
  3. Internet:
  4. =========
  5. 1. ftp://ftp.ccac.rwth-aachen.de/pub/jr/z8530drv-utils_3.0-3.tar.gz
  6. 2. ftp://ftp.pspt.fi/pub/ham/linux/ax25/z8530drv-utils_3.0-3.tar.gz
  7. Please note that the information in this document may be hopelessly outdated.
  8. A new version of the documentation, along with links to other important
  9. Linux Kernel AX.25 documentation and programs, is available on
  10. http://yaina.de/jreuter
  11. -----------------------------------------------------------------------------
  12. SCC.C - Linux driver for Z8530 based HDLC cards for AX.25
  13. ********************************************************************
  14. (c) 1993,2000 by Joerg Reuter DL1BKE <jreuter@yaina.de>
  15. portions (c) 1993 Guido ten Dolle PE1NNZ
  16. for the complete copyright notice see >> Copying.Z8530DRV <<
  17. ********************************************************************
  18. 1. Initialization of the driver
  19. ===============================
  20. To use the driver, 3 steps must be performed:
  21. 1. if compiled as module: loading the module
  22. 2. Setup of hardware, MODEM and KISS parameters with sccinit
  23. 3. Attach each channel to the Linux kernel AX.25 with "ifconfig"
  24. Unlike the versions below 2.4 this driver is a real network device
  25. driver. If you want to run xNOS instead of our fine kernel AX.25
  26. use a 2.x version (available from above sites) or read the
  27. AX.25-HOWTO on how to emulate a KISS TNC on network device drivers.
  28. 1.1 Loading the module
  29. ======================
  30. (If you're going to compile the driver as a part of the kernel image,
  31. skip this chapter and continue with 1.2)
  32. Before you can use a module, you'll have to load it with
  33. insmod scc.o
  34. please read 'man insmod' that comes with module-init-tools.
  35. You should include the insmod in one of the /etc/rc.d/rc.* files,
  36. and don't forget to insert a call of sccinit after that. It
  37. will read your /etc/z8530drv.conf.
  38. 1.2. /etc/z8530drv.conf
  39. =======================
  40. To setup all parameters you must run /sbin/sccinit from one
  41. of your rc.*-files. This has to be done BEFORE you can
  42. "ifconfig" an interface. Sccinit reads the file /etc/z8530drv.conf
  43. and sets the hardware, MODEM and KISS parameters. A sample file is
  44. delivered with this package. Change it to your needs.
  45. The file itself consists of two main sections.
  46. 1.2.1 configuration of hardware parameters
  47. ==========================================
  48. The hardware setup section defines the following parameters for each
  49. Z8530:
  50. chip 1
  51. data_a 0x300 # data port A
  52. ctrl_a 0x304 # control port A
  53. data_b 0x301 # data port B
  54. ctrl_b 0x305 # control port B
  55. irq 5 # IRQ No. 5
  56. pclock 4915200 # clock
  57. board BAYCOM # hardware type
  58. escc no # enhanced SCC chip? (8580/85180/85280)
  59. vector 0 # latch for interrupt vector
  60. special no # address of special function register
  61. option 0 # option to set via sfr
  62. chip - this is just a delimiter to make sccinit a bit simpler to
  63. program. A parameter has no effect.
  64. data_a - the address of the data port A of this Z8530 (needed)
  65. ctrl_a - the address of the control port A (needed)
  66. data_b - the address of the data port B (needed)
  67. ctrl_b - the address of the control port B (needed)
  68. irq - the used IRQ for this chip. Different chips can use different
  69. IRQs or the same. If they share an interrupt, it needs to be
  70. specified within one chip-definition only.
  71. pclock - the clock at the PCLK pin of the Z8530 (option, 4915200 is
  72. default), measured in Hertz
  73. board - the "type" of the board:
  74. SCC type value
  75. ---------------------------------
  76. PA0HZP SCC card PA0HZP
  77. EAGLE card EAGLE
  78. PC100 card PC100
  79. PRIMUS-PC (DG9BL) card PRIMUS
  80. BayCom (U)SCC card BAYCOM
  81. escc - if you want support for ESCC chips (8580, 85180, 85280), set
  82. this to "yes" (option, defaults to "no")
  83. vector - address of the vector latch (aka "intack port") for PA0HZP
  84. cards. There can be only one vector latch for all chips!
  85. (option, defaults to 0)
  86. special - address of the special function register on several cards.
  87. (option, defaults to 0)
  88. option - The value you write into that register (option, default is 0)
  89. You can specify up to four chips (8 channels). If this is not enough,
  90. just change
  91. #define MAXSCC 4
  92. to a higher value.
  93. Example for the BAYCOM USCC:
  94. ----------------------------
  95. chip 1
  96. data_a 0x300 # data port A
  97. ctrl_a 0x304 # control port A
  98. data_b 0x301 # data port B
  99. ctrl_b 0x305 # control port B
  100. irq 5 # IRQ No. 5 (#)
  101. board BAYCOM # hardware type (*)
  102. #
  103. # SCC chip 2
  104. #
  105. chip 2
  106. data_a 0x302
  107. ctrl_a 0x306
  108. data_b 0x303
  109. ctrl_b 0x307
  110. board BAYCOM
  111. An example for a PA0HZP card:
  112. -----------------------------
  113. chip 1
  114. data_a 0x153
  115. data_b 0x151
  116. ctrl_a 0x152
  117. ctrl_b 0x150
  118. irq 9
  119. pclock 4915200
  120. board PA0HZP
  121. vector 0x168
  122. escc no
  123. #
  124. #
  125. #
  126. chip 2
  127. data_a 0x157
  128. data_b 0x155
  129. ctrl_a 0x156
  130. ctrl_b 0x154
  131. irq 9
  132. pclock 4915200
  133. board PA0HZP
  134. vector 0x168
  135. escc no
  136. A DRSI would should probably work with this:
  137. --------------------------------------------
  138. (actually: two DRSI cards...)
  139. chip 1
  140. data_a 0x303
  141. data_b 0x301
  142. ctrl_a 0x302
  143. ctrl_b 0x300
  144. irq 7
  145. pclock 4915200
  146. board DRSI
  147. escc no
  148. #
  149. #
  150. #
  151. chip 2
  152. data_a 0x313
  153. data_b 0x311
  154. ctrl_a 0x312
  155. ctrl_b 0x310
  156. irq 7
  157. pclock 4915200
  158. board DRSI
  159. escc no
  160. Note that you cannot use the on-board baudrate generator off DRSI
  161. cards. Use "mode dpll" for clock source (see below).
  162. This is based on information provided by Mike Bilow (and verified
  163. by Paul Helay)
  164. The utility "gencfg"
  165. --------------------
  166. If you only know the parameters for the PE1CHL driver for DOS,
  167. run gencfg. It will generate the correct port addresses (I hope).
  168. Its parameters are exactly the same as the ones you use with
  169. the "attach scc" command in net, except that the string "init" must
  170. not appear. Example:
  171. gencfg 2 0x150 4 2 0 1 0x168 9 4915200
  172. will print a skeleton z8530drv.conf for the OptoSCC to stdout.
  173. gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10
  174. does the same for the BAYCOM USCC card. In my opinion it is much easier
  175. to edit scc_config.h...
  176. 1.2.2 channel configuration
  177. ===========================
  178. The channel definition is divided into three sub sections for each
  179. channel:
  180. An example for scc0:
  181. # DEVICE
  182. device scc0 # the device for the following params
  183. # MODEM / BUFFERS
  184. speed 1200 # the default baudrate
  185. clock dpll # clock source:
  186. # dpll = normal half duplex operation
  187. # external = MODEM provides own Rx/Tx clock
  188. # divider = use full duplex divider if
  189. # installed (1)
  190. mode nrzi # HDLC encoding mode
  191. # nrzi = 1k2 MODEM, G3RUH 9k6 MODEM
  192. # nrz = DF9IC 9k6 MODEM
  193. #
  194. bufsize 384 # size of buffers. Note that this must include
  195. # the AX.25 header, not only the data field!
  196. # (optional, defaults to 384)
  197. # KISS (Layer 1)
  198. txdelay 36 # (see chapter 1.4)
  199. persist 64
  200. slot 8
  201. tail 8
  202. fulldup 0
  203. wait 12
  204. min 3
  205. maxkey 7
  206. idle 3
  207. maxdef 120
  208. group 0
  209. txoff off
  210. softdcd on
  211. slip off
  212. The order WITHIN these sections is unimportant. The order OF these
  213. sections IS important. The MODEM parameters are set with the first
  214. recognized KISS parameter...
  215. Please note that you can initialize the board only once after boot
  216. (or insmod). You can change all parameters but "mode" and "clock"
  217. later with the Sccparam program or through KISS. Just to avoid
  218. security holes...
  219. (1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not
  220. present at all (BayCom). It feeds back the output of the DPLL
  221. (digital pll) as transmit clock. Using this mode without a divider
  222. installed will normally result in keying the transceiver until
  223. maxkey expires --- of course without sending anything (useful).
  224. 2. Attachment of a channel by your AX.25 software
  225. =================================================
  226. 2.1 Kernel AX.25
  227. ================
  228. To set up an AX.25 device you can simply type:
  229. ifconfig scc0 44.128.1.1 hw ax25 dl0tha-7
  230. This will create a network interface with the IP number 44.128.20.107
  231. and the callsign "dl0tha". If you do not have any IP number (yet) you
  232. can use any of the 44.128.0.0 network. Note that you do not need
  233. axattach. The purpose of axattach (like slattach) is to create a KISS
  234. network device linked to a TTY. Please read the documentation of the
  235. ax25-utils and the AX.25-HOWTO to learn how to set the parameters of
  236. the kernel AX.25.
  237. 2.2 NOS, NET and TFKISS
  238. =======================
  239. Since the TTY driver (aka KISS TNC emulation) is gone you need
  240. to emulate the old behaviour. The cost of using these programs is
  241. that you probably need to compile the kernel AX.25, regardless of whether
  242. you actually use it or not. First setup your /etc/ax25/axports,
  243. for example:
  244. 9k6 dl0tha-9 9600 255 4 9600 baud port (scc3)
  245. axlink dl0tha-15 38400 255 4 Link to NOS
  246. Now "ifconfig" the scc device:
  247. ifconfig scc3 44.128.1.1 hw ax25 dl0tha-9
  248. You can now axattach a pseudo-TTY:
  249. axattach /dev/ptys0 axlink
  250. and start your NOS and attach /dev/ptys0 there. The problem is that
  251. NOS is reachable only via digipeating through the kernel AX.25
  252. (disastrous on a DAMA controlled channel). To solve this problem,
  253. configure "rxecho" to echo the incoming frames from "9k6" to "axlink"
  254. and outgoing frames from "axlink" to "9k6" and start:
  255. rxecho
  256. Or simply use "kissbridge" coming with z8530drv-utils:
  257. ifconfig scc3 hw ax25 dl0tha-9
  258. kissbridge scc3 /dev/ptys0
  259. 3. Adjustment and Display of parameters
  260. =======================================
  261. 3.1 Displaying SCC Parameters:
  262. ==============================
  263. Once a SCC channel has been attached, the parameter settings and
  264. some statistic information can be shown using the param program:
  265. dl1bke-u:~$ sccstat scc0
  266. Parameters:
  267. speed : 1200 baud
  268. txdelay : 36
  269. persist : 255
  270. slottime : 0
  271. txtail : 8
  272. fulldup : 1
  273. waittime : 12
  274. mintime : 3 sec
  275. maxkeyup : 7 sec
  276. idletime : 3 sec
  277. maxdefer : 120 sec
  278. group : 0x00
  279. txoff : off
  280. softdcd : on
  281. SLIP : off
  282. Status:
  283. HDLC Z8530 Interrupts Buffers
  284. -----------------------------------------------------------------------
  285. Sent : 273 RxOver : 0 RxInts : 125074 Size : 384
  286. Received : 1095 TxUnder: 0 TxInts : 4684 NoSpace : 0
  287. RxErrors : 1591 ExInts : 11776
  288. TxErrors : 0 SpInts : 1503
  289. Tx State : idle
  290. The status info shown is:
  291. Sent - number of frames transmitted
  292. Received - number of frames received
  293. RxErrors - number of receive errors (CRC, ABORT)
  294. TxErrors - number of discarded Tx frames (due to various reasons)
  295. Tx State - status of the Tx interrupt handler: idle/busy/active/tail (2)
  296. RxOver - number of receiver overruns
  297. TxUnder - number of transmitter underruns
  298. RxInts - number of receiver interrupts
  299. TxInts - number of transmitter interrupts
  300. EpInts - number of receiver special condition interrupts
  301. SpInts - number of external/status interrupts
  302. Size - maximum size of an AX.25 frame (*with* AX.25 headers!)
  303. NoSpace - number of times a buffer could not get allocated
  304. An overrun is abnormal. If lots of these occur, the product of
  305. baudrate and number of interfaces is too high for the processing
  306. power of your computer. NoSpace errors are unlikely to be caused by the
  307. driver or the kernel AX.25.
  308. 3.2 Setting Parameters
  309. ======================
  310. The setting of parameters of the emulated KISS TNC is done in the
  311. same way in the SCC driver. You can change parameters by using
  312. the kissparms program from the ax25-utils package or use the program
  313. "sccparam":
  314. sccparam <device> <paramname> <decimal-|hexadecimal value>
  315. You can change the following parameters:
  316. param : value
  317. ------------------------
  318. speed : 1200
  319. txdelay : 36
  320. persist : 255
  321. slottime : 0
  322. txtail : 8
  323. fulldup : 1
  324. waittime : 12
  325. mintime : 3
  326. maxkeyup : 7
  327. idletime : 3
  328. maxdefer : 120
  329. group : 0x00
  330. txoff : off
  331. softdcd : on
  332. SLIP : off
  333. The parameters have the following meaning:
  334. speed:
  335. The baudrate on this channel in bits/sec
  336. Example: sccparam /dev/scc3 speed 9600
  337. txdelay:
  338. The delay (in units of 10 ms) after keying of the
  339. transmitter, until the first byte is sent. This is usually
  340. called "TXDELAY" in a TNC. When 0 is specified, the driver
  341. will just wait until the CTS signal is asserted. This
  342. assumes the presence of a timer or other circuitry in the
  343. MODEM and/or transmitter, that asserts CTS when the
  344. transmitter is ready for data.
  345. A normal value of this parameter is 30-36.
  346. Example: sccparam /dev/scc0 txd 20
  347. persist:
  348. This is the probability that the transmitter will be keyed
  349. when the channel is found to be free. It is a value from 0
  350. to 255, and the probability is (value+1)/256. The value
  351. should be somewhere near 50-60, and should be lowered when
  352. the channel is used more heavily.
  353. Example: sccparam /dev/scc2 persist 20
  354. slottime:
  355. This is the time between samples of the channel. It is
  356. expressed in units of 10 ms. About 200-300 ms (value 20-30)
  357. seems to be a good value.
  358. Example: sccparam /dev/scc0 slot 20
  359. tail:
  360. The time the transmitter will remain keyed after the last
  361. byte of a packet has been transferred to the SCC. This is
  362. necessary because the CRC and a flag still have to leave the
  363. SCC before the transmitter is keyed down. The value depends
  364. on the baudrate selected. A few character times should be
  365. sufficient, e.g. 40ms at 1200 baud. (value 4)
  366. The value of this parameter is in 10 ms units.
  367. Example: sccparam /dev/scc2 4
  368. full:
  369. The full-duplex mode switch. This can be one of the following
  370. values:
  371. 0: The interface will operate in CSMA mode (the normal
  372. half-duplex packet radio operation)
  373. 1: Fullduplex mode, i.e. the transmitter will be keyed at
  374. any time, without checking the received carrier. It
  375. will be unkeyed when there are no packets to be sent.
  376. 2: Like 1, but the transmitter will remain keyed, also
  377. when there are no packets to be sent. Flags will be
  378. sent in that case, until a timeout (parameter 10)
  379. occurs.
  380. Example: sccparam /dev/scc0 fulldup off
  381. wait:
  382. The initial waittime before any transmit attempt, after the
  383. frame has been queue for transmit. This is the length of
  384. the first slot in CSMA mode. In full duplex modes it is
  385. set to 0 for maximum performance.
  386. The value of this parameter is in 10 ms units.
  387. Example: sccparam /dev/scc1 wait 4
  388. maxkey:
  389. The maximal time the transmitter will be keyed to send
  390. packets, in seconds. This can be useful on busy CSMA
  391. channels, to avoid "getting a bad reputation" when you are
  392. generating a lot of traffic. After the specified time has
  393. elapsed, no new frame will be started. Instead, the trans-
  394. mitter will be switched off for a specified time (parameter
  395. min), and then the selected algorithm for keyup will be
  396. started again.
  397. The value 0 as well as "off" will disable this feature,
  398. and allow infinite transmission time.
  399. Example: sccparam /dev/scc0 maxk 20
  400. min:
  401. This is the time the transmitter will be switched off when
  402. the maximum transmission time is exceeded.
  403. Example: sccparam /dev/scc3 min 10
  404. idle
  405. This parameter specifies the maximum idle time in full duplex
  406. 2 mode, in seconds. When no frames have been sent for this
  407. time, the transmitter will be keyed down. A value of 0 is
  408. has same result as the fullduplex mode 1. This parameter
  409. can be disabled.
  410. Example: sccparam /dev/scc2 idle off # transmit forever
  411. maxdefer
  412. This is the maximum time (in seconds) to wait for a free channel
  413. to send. When this timer expires the transmitter will be keyed
  414. IMMEDIATELY. If you love to get trouble with other users you
  415. should set this to a very low value ;-)
  416. Example: sccparam /dev/scc0 maxdefer 240 # 2 minutes
  417. txoff:
  418. When this parameter has the value 0, the transmission of packets
  419. is enable. Otherwise it is disabled.
  420. Example: sccparam /dev/scc2 txoff on
  421. group:
  422. It is possible to build special radio equipment to use more than
  423. one frequency on the same band, e.g. using several receivers and
  424. only one transmitter that can be switched between frequencies.
  425. Also, you can connect several radios that are active on the same
  426. band. In these cases, it is not possible, or not a good idea, to
  427. transmit on more than one frequency. The SCC driver provides a
  428. method to lock transmitters on different interfaces, using the
  429. "param <interface> group <x>" command. This will only work when
  430. you are using CSMA mode (parameter full = 0).
  431. The number <x> must be 0 if you want no group restrictions, and
  432. can be computed as follows to create restricted groups:
  433. <x> is the sum of some OCTAL numbers:
  434. 200 This transmitter will only be keyed when all other
  435. transmitters in the group are off.
  436. 100 This transmitter will only be keyed when the carrier
  437. detect of all other interfaces in the group is off.
  438. 0xx A byte that can be used to define different groups.
  439. Interfaces are in the same group, when the logical AND
  440. between their xx values is nonzero.
  441. Examples:
  442. When 2 interfaces use group 201, their transmitters will never be
  443. keyed at the same time.
  444. When 2 interfaces use group 101, the transmitters will only key
  445. when both channels are clear at the same time. When group 301,
  446. the transmitters will not be keyed at the same time.
  447. Don't forget to convert the octal numbers into decimal before
  448. you set the parameter.
  449. Example: (to be written)
  450. softdcd:
  451. use a software dcd instead of the real one... Useful for a very
  452. slow squelch.
  453. Example: sccparam /dev/scc0 soft on
  454. 4. Problems
  455. ===========
  456. If you have tx-problems with your BayCom USCC card please check
  457. the manufacturer of the 8530. SGS chips have a slightly
  458. different timing. Try Zilog... A solution is to write to register 8
  459. instead to the data port, but this won't work with the ESCC chips.
  460. *SIGH!*
  461. A very common problem is that the PTT locks until the maxkeyup timer
  462. expires, although interrupts and clock source are correct. In most
  463. cases compiling the driver with CONFIG_SCC_DELAY (set with
  464. make config) solves the problems. For more hints read the (pseudo) FAQ
  465. and the documentation coming with z8530drv-utils.
  466. I got reports that the driver has problems on some 386-based systems.
  467. (i.e. Amstrad) Those systems have a bogus AT bus timing which will
  468. lead to delayed answers on interrupts. You can recognize these
  469. problems by looking at the output of Sccstat for the suspected
  470. port. If it shows under- and overruns you own such a system.
  471. Delayed processing of received data: This depends on
  472. - the kernel version
  473. - kernel profiling compiled or not
  474. - a high interrupt load
  475. - a high load of the machine --- running X, Xmorph, XV and Povray,
  476. while compiling the kernel... hmm ... even with 32 MB RAM ... ;-)
  477. Or running a named for the whole .ampr.org domain on an 8 MB
  478. box...
  479. - using information from rxecho or kissbridge.
  480. Kernel panics: please read /linux/README and find out if it
  481. really occurred within the scc driver.
  482. If you cannot solve a problem, send me
  483. - a description of the problem,
  484. - information on your hardware (computer system, scc board, modem)
  485. - your kernel version
  486. - the output of cat /proc/net/z8530
  487. 4. Thor RLC100
  488. ==============
  489. Mysteriously this board seems not to work with the driver. Anyone
  490. got it up-and-running?
  491. Many thanks to Linus Torvalds and Alan Cox for including the driver
  492. in the Linux standard distribution and their support.
  493. Joerg Reuter ampr-net: dl1bke@db0pra.ampr.org
  494. AX-25 : DL1BKE @ DB0ABH.#BAY.DEU.EU
  495. Internet: jreuter@yaina.de
  496. WWW : http://yaina.de/jreuter