About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / z8530drv.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:04 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.