setSCCserial
                            ==============

				Roman.Hodek@informatik.uni-erlangen.de



1) Introduction
===============

This is release 0.1 of setSCCserial, a tool for telling the kernel
about the clock frequencies attached to the SCC ("serial
communications controller"), the chip controlling the serial ports
ttyS1, ttyS3, and ttyS4 (named Modem2, Serial2, and LAN under TOS) of
the Atari.

The Linux kernel knows about the standard clocks for the SCC in the TT
and Falcon/MegaSTE. If you have one of these machines and haven't made
any changes to your SCC hardware, you don't need this tool. The kernel
does things right by itself.

But if you have some other machine with non-standard SCC clocks or if
you have altered your SCC's clock frequencies to get more/faster baud
rates, you have to tell the kernel about them. Else it can't set
properly the baud rates you select.


2) How the SCC works
====================

This section will tell you (briefly) what's the story about the
clocks in the SCC. If you're not interested in that technical details,
you can skip to the next section.

The SCC has five different pins for clock input, which it uses to send
or receive the bit streams at certain rates. Each channel (the SCC has
two) has a RTxC and a TRxC input, also called RTxCA, RTxCB, TRxCA, and
TRxCB, resp. RTxC is always a input, but TRxC can be used as both,
input and output. In synchronous modes, these two lines can be used to
transmit or receive the clock along with the data signal and thus
achieve higher rates. In asynchronous modes, clocks aren't transmitted
separately, so normally both pins are used as input. The fifth clock
input is PCLK, the SCC's master clock itself. Besides RTxC and TRxC,
it can also be used for controlling the bps rate.

Now, the SCC has two different ways of generating the actual bps rate
from the selected clock: The one is by a divider unit that can work in
1:16, 1:32, and 1:64 modes only. The other is the baud rate generator
(BRG), that can be driven by PCLK or RTxC. The BRG has a 16 bit
counter register that is decremented by the clock input. Each time it
reaches 0, a clock change is output and the counter starts over
again. Since it needs two changes to make a full cycle, the division
is by really twice the value of the BRG counter. (The complete formula
can be found below). This method is used to generate more rates as
would be possible by simple hardware dividers, that most times only
divide by powers of 2.

In asynchronous modes (about which we're talking here), the SCC has to
reconstruct the actual clock used to send the characters it is
receiving, because the transmit clock isn't sent together with the
data signal. To do this, the SCC needs 16 clock cycles per bit. This
division by 16 must be included in all calculations, so clock/16 is
also called the "baud_base". This baud_base rate can be further
divided by certain divisors (what's possible depends on the clock
input) to yield lower rates. But the maximum rate possible is always
the baud_base. This, because only integer divisors are allowed and the
minimum integer divisor is 1.

In the direct modes mentioned above, the division by 16 is already
included, thus the direct mode 1:16, e.g., can be seen as a divisor of
1 relative to the baud_base. Modes 1:32 and 1:64 are the divisors 2
and 4, resp. But direct modes are possible only with RTxC and TRxC,
but not with PCLK. The divisors 1, 2, and 4 are thus only valid with
these two clock sources.

The formula for the BRG is

             base_baud
  bps = --------------------
         2 * (BRGvalue + 2)

with BRGvalue ranging from 0 to 65535 (it is a 16 bit register). The
minimum divisor thus is 4, relative to the base_baud. And valid
divisors are always even values. And, remember, the input to the BRG
can be PCLK and RTxC. 

All together, the possible divisors for the various clocks are:

  RTxC: 1, 2, 4, 6, 8, 10, ..., 131074
  TRxC: 1, 2, 4
  PCLK:       4, 6, 8, 10, ..., 131074

(Note that a divisor of 4 of RTxC can be implemented as both, a direct
and a BRG mode. But this is of little use in practice.)

And now to the clocks attachted to the SCC in the Atari: The standard
assignment is:

  RTxC = 3.6864 MHz = 230400 base_baud
  TRxC = no input
  PCLK = 8.0000 MHz = 500000 base_baud

(At least I never heard that anything useful is connected to TRxC. If
you know better, tell me!)

Here, RTxC is suitable for generating most of the standard baud rates
from 115200 bps down to 50 bps. Just for 110, 134, and 1800 bps, PCLK
must be used for an approximation of these unusual rates.

A special case is the channel B in the TT (Modem2):

  RTxC =   307.2 kHz =  19200 baud_base
  TRxC = 2.4576  MHz = 153600 baud_base
  PCLK = 8.0000  MHz = 500000 baud_base

The RTxC clock here is generated by timer C of the TT-MFP and could be
programmed to other frequencies than 307.2 kHz. But this is (1) the
highest possible frequency and (2) very suitable for generating the
lower standard bps rates. TRxC makes the higher rates 153600, 76800
and 38400 bps possible. But, unfortunately, there's no chance to get
the more common 115200 or 57600 :-(

PCLK is of course the same as above. There is just one PCLK for both
channels!


3) setSCCserial Usage
=====================

3.1) Current Values
-------------------

First, you can use setSCCserial to see which clocks are attached to a
channel of your SCC (at least what the kernel believes) and how
certain bps rates are generated from these. For this, call
setSCCserial just with the device name of the serial port you want to
examine (the example is for Modem2 on a TT):

  $ setSCCserial /dev/ttyS1
  RTxC: f=307.200 kHz, baud_base = 19200
  TRxC: f=2457.600 kHz, baud_base = 153600
  PCLK: f=8000.000 kHz, baud_base = 500000
  	   50: RTxC /   384 ->      50.000 bps (via BRG value 190)
  	   75: RTxC /   256 ->      75.000 bps (via BRG value 126)
  	  110: PCLK /  4546 ->     109.986 bps (via BRG value 2271)
  	  134: PCLK /  3732 ->     133.976 bps (via BRG value 1864)
  	  150: RTxC /   128 ->     150.000 bps (via BRG value 62)
  	  200: RTxC /    96 ->     200.000 bps (via BRG value 46)
  	  300: RTxC /    64 ->     300.000 bps (via BRG value 30)
  	  600: RTxC /    32 ->     600.000 bps (via BRG value 14)
  	 1200: RTxC /    16 ->    1200.000 bps (via BRG value 6)
  	 1800: PCLK /   278 ->    1798.561 bps (via BRG value 137)
  	 2400: RTxC /     8 ->    2400.000 bps (via BRG value 2)
  	 4800: RTxC /     4 ->    4800.000 bps (direct mode 1:64)
  	 9600: RTxC /     2 ->    9600.000 bps (direct mode 1:32)
  	19200: RTxC /     1 ->   19200.000 bps (direct mode 1:16)
  	38400: TRxC /     4 ->   38400.000 bps (direct mode 1:64)
  	57600: TRxC /     2 ->   76800.000 bps (direct mode 1:32)
   115200: TRxC /     1 ->  153600.000 bps (direct mode 1:16)

If you have read the chapter before, the output should be easy to
interpret. If you haven't, just look at the three clock frequencies to
the top and compare them to the freqencies you have (if you know
them... :-). If they don't match, you have to use setSCCserial to set
the correct values (see below), best in a /etc/rc* file executed at
boot time.


3.2) Setting New Values
-----------------------

setSCCserial's main job is it to tell the kernel about the real clock
frequencies of the SCC. This is done by putting these values on the
command line. E.g., if your PCLK is 16 MHz instead of 8 MHz, you would
enter

  $ setSCCserial /dev/ttyS1 pclk=16M

Remember that this sets PCLK for both channels, since there is only
one PCLK pin. But RTxC and TRxC settings are private for each
channel. You do them like

  $ setSCCserial /dev/ttyS3 rtxc=4.5678M trxc=987.6k

As you see, you can append the characters 'M' and 'k' to denote MHz or
kHz,  resp. ('m' and 'K' will also do the job). If no letter is
appended, the number is seens as Hz, so you it's likely you have to
type many 0's... You can also tell setSCCserial that a clock pin
hasn't any input at all by setting its frequency to 0.

If you mention at least one new frequency on the command line, the
speed table for that channel has to be recalculated. This speed table
tells the kernel which clock source and which divisor to use for a
certain standard baud rate. setSCCserial does this job of
recalculating automatically. You can watch the results by adding a
"-v" option:

  $ setSCCserial -v /dev/ttyS1 pclk=16M
  	   50 bps: RTxC / 384, error 0.000 %
  	   75 bps: RTxC / 256, error 0.000 %
  	  110 bps: PCLK / 9090, error 0.010 %
  	  134 bps: PCLK / 7462, error 0.008 %
  	  150 bps: RTxC / 128, error 0.000 %
  	  200 bps: RTxC / 96, error 0.000 %
  	  300 bps: RTxC / 64, error 0.000 %
  	  600 bps: RTxC / 32, error 0.000 %
  	 1200 bps: RTxC / 16, error 0.000 %
  	 1800 bps: PCLK / 556, error 0.079 %
  	 2400 bps: RTxC / 8, error 0.000 %
  	 4800 bps: RTxC / 4, error 0.000 %
  	 9600 bps: RTxC / 2, error 0.000 %
  	19200 bps: RTxC / 1, error 0.000 %
  	38400 bps: TRxC / 4, error 0.000 %
  	57600 bps: PCLK / 18, error 3.549 %
   115200 bps: PCLK / 8, error 8.506 %

You see that setSCCserial prints which clock sources and which
divisors it uses for certain bps rates, along with the error that is
made by this decision. Sometimes little errors cannot be avoided. If
they're less than 0.5 ... 1 %, you need not worry about it. But the
errors listed for 57.6 kbps and 115.2 kbps are too much. This results
from the clocks attached to channel B of a TT. These aren't suitable
for these rates. (With PCLK=8MHz the errors are even worse.)

This problem is usually solved by using alternative rates in place of
the ones not possible: 76.8 kbps and 153.6 kbps. (This is also the
Linux boot time default on a TT and under TOS, too.) Thus if you
select 115200 bps (by "setserial spd_vhi" and "stty 38400"), you
really get 153600 bps. But you have to tell setSCCserial about that
you want to do such a substitution when it calculates a new speed
table. This is done by a "subst" parameter:

  $ setSCCserial -v /dev/ttyS1 pclk=16M subst 57.6k=76.8k subst 115.2k=153.6k
  	   50 bps: RTxC / 384, error 0.000 %
  	   75 bps: RTxC / 256, error 0.000 %
  	  110 bps: PCLK / 9090, error 0.010 %
  	  134 bps: PCLK / 7462, error 0.008 %
  	  150 bps: RTxC / 128, error 0.000 %
  	  200 bps: RTxC / 96, error 0.000 %
  	  300 bps: RTxC / 64, error 0.000 %
  	  600 bps: RTxC / 32, error 0.000 %
  	 1200 bps: RTxC / 16, error 0.000 %
  	 1800 bps: PCLK / 556, error 0.079 %
  	 2400 bps: RTxC / 8, error 0.000 %
  	 4800 bps: RTxC / 4, error 0.000 %
  	 9600 bps: RTxC / 2, error 0.000 %
  	19200 bps: RTxC / 1, error 0.000 %
  	38400 bps: TRxC / 4, error 0.000 %
  	76800 bps: TRxC / 2, error 0.000 %
   153600 bps: TRxC / 1, error 0.000 %

Now, you see, the errors are gone. This is, because 76.8 kbps and
153.6 kbps can be directly derived from a base_baud of 153600, which
is TRxC on a TT's channel B. Note also that you can use the 'k'
notation for the bps rates, too.

And now your question: How does setSCCserial figure out which clock
source to use for a certain bps rate? The answer is easy: First it
calculates the divisors for all three clocks that best approximate the
desired speed and then it compares the errors made. The clock with the
least error is then picked (obviously!). You can watch this process by
giving setSCCserial a double -v option:

  $ setSCCserial -vv /dev/ttyS1 pclk=8m subst 57.6k=76.8k subst 115.2k=153.6k 
  Computation for 50 bps:
  	RTxC base_baud 19200 / 384 = 50.000, error 0.000 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 76700.000 %
  	PCLK base_baud 500000 / 10000 = 50.000, error 0.000 %
  	   50 bps: RTxC / 384, error 0.000 %
  
  Computation for 75 bps:
  	RTxC base_baud 19200 / 256 = 75.000, error 0.000 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 51100.000 %
  	PCLK base_baud 500000 / 6666 = 75.008, error 0.010 %
  	   75 bps: RTxC / 256, error 0.000 %
  
  Computation for 110 bps:
  	RTxC base_baud 19200 / 174 = 110.345, error 0.313 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 34809.090 %
  	PCLK base_baud 500000 / 4546 = 109.987, error 0.011 %
  	  110 bps: PCLK / 4546, error 0.011 %
  
  Computation for 134 bps:
  	RTxC base_baud 19200 / 144 = 133.333, error 0.497 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 28556.716 %
  	PCLK base_baud 500000 / 3732 = 133.976, error 0.017 %
  	  134 bps: PCLK / 3732, error 0.017 %
  
  Computation for 150 bps:
  	RTxC base_baud 19200 / 128 = 150.000, error 0.000 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 25500.000 %
  	PCLK base_baud 500000 / 3334 = 149.970, error 0.020 %
  	  150 bps: RTxC / 128, error 0.000 %

  [...]  

  Computation for 19200 bps:
  	RTxC base_baud 19200 / 1 = 19200.000, error 0.000 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 100.000 %
  	PCLK base_baud 500000 / 26 = 19230.769, error 0.160 %
  	19200 bps: RTxC / 1, error 0.000 %
  
  Computation for 38400 bps:
  	RTxC base_baud 19200 / 1 = 19200.000, error 50.000 %
  	TRxC base_baud 153600 / 4 = 38400.000, error 0.000 %
  	PCLK base_baud 500000 / 14 = 35714.286, error 6.994 %
  	38400 bps: TRxC / 4, error 0.000 %
  
  Computation for 76800 bps:
  	RTxC base_baud 19200 / 1 = 19200.000, error 75.000 %
  	TRxC base_baud 153600 / 2 = 76800.000, error 0.000 %
  	PCLK base_baud 500000 / 6 = 83333.333, error 8.506 %
  	76800 bps: TRxC / 2, error 0.000 %
  
  Computation for 153600 bps:
  	RTxC base_baud 19200 / 1 = 19200.000, error 87.500 %
  	TRxC base_baud 153600 / 1 = 153600.000, error 0.000 %
  	PCLK base_baud 500000 / 4 = 125000.000, error 18.619 %
   153600 bps: TRxC / 1, error 0.000 %

Take a special look at the calculations for 110 and 134 bps, where a
error of 0 isn't possible with any clock. Indeed, the table above
shows the standard calculation for TT's channel B.


3.3) Resetting the Default Values
---------------------------------

If you have misconfigured your SCC somehow, you can recall the
kernel's boot time default values by the keyword "default" on the
setSCCserial command line:

  $ setSCCserial /dev/ttyS1 default

Nothing more to tell you here...


4) Compiling and Using setSCCserial
===================================

For using this version of setSCCserial, you need at least a 0.9.10
version of the Linux/68k kernel. (0.9.9 already has the SCC driver,
but the ioctl interface to setSCCserial is buggy! Alternativly, you
can apply the patches in kernel.patch to your 0.9.9 sources.)

For compiling setSCCserial, you need the kernel header file
atari_SCCserial.h, which is included in the kernel's header directory
linux/include/linux. It defines constants and data structures of the
ioctl interface to the SCC driver in the kernel. If /usr/include/linux
is a symlink to where your kernel headers are, and you have the right
version of the kernel sources installed, you shouldn't have any
problems with this header. But if there are any problems, you can add
a "-I." to CFLAGS in the Makefile. Then the atari_SCCserial.h in the
setSCCserial directory is used. But beware: This header is from 0.9.10
and may be outdated in future if the interface changes!

For changing clock frequencies or the speed table (this includes
resetting the default values!), you must be root. But all users are
allowed to view the current settings.


5) Author and Copyright
=======================

setSCCserial is (c) 1995 by Roman Hodek
<Roman.Hodek@informatik.uni-erlangen.de> 

It is subject to the terms and conditions of the GNU General Public
License. See the file COPYING for details.