Serial FAQ version 1.0 Sat Jul  3 13:14:22 EDT 1993 
maintained by Greg Hankins <gregh@cc.gatech.edu>.

This FAQ attempts to provide answers to a variety of serial type problems.
There is a surprising complexity in getting things to work, and a broad
range of topics.

(1). How are serial devices named?

(2). What is all this about 'getty_ps 2.0.7b'?  

(3). How do I dial out with my modem?

(4). How do I dial in and out with my modem?

(5). How do I set up a terminal connected to my PC?

(6). Can I use more than 2 serial ports?  What are these interrupts all about?

(7). What kind of serial boards does Linux support? 

(8). What major and minor numbers should my serial devices in /dev have?

(9). How should I configure my modem?

(A). Troubleshooting

(B). Linux FTP sites

(C). Recommended Reading

(D). Contributions

===============================================================================

(1). How are serial devices named?

There are 4 basic serial devices corresponding to COM1 - COM4, /dev/cua0 - 
/dev/cua3 and /dev/ttyS0 - /dev/ttyS3. The /dev/ttyS* devices are for dialin
and /dev/cua* devices for dialout. 

Furthermore, when you install from SLS two extra devices will be created,
/dev/modem for your modem and /dev/mouse for your mouse. Both of these
are symbolic links to the appropriate /dev/cua* port which you specified
during the installation.

There has been some discussion on the merits of /dev/mouse and /dev/modem.
I recommend using the "real" device names, and not the symbolic links.  It just
seems less confusing to me.  Use them if you like, but make sure they point
to the right device.

A program like 'kermit' for instance uses the /dev/modem device if there is
no .kermrc file present in your $HOME which contains the settings for kermit.

===============================================================================

(2). What is 'getty_ps 2.0.7b'?  What's so great about it?

This is just another version of 'getty', which is a program that handles
some of the login process when you log in to a UNIX box.  This version is
better than the stock 'getty' that comes with most recent Linux distributions.
It was written by Paul Sutcliffe, Jr.  <paul@devon.lns.pa.us>.  2.0.7b is the 
latest version, and supercedes any older versions.

Please make sure you use 'getty_ps 2.0.7b' only if you're running on a pl6 
or higher kernel.  Previous versions of 'getty_ps' will not work with these.
Furthermore, users of SLS 1.0.1/1.0.2 should be very carefull because there 
might be two versions of 'getty_ps' lurking on your disks!  The default one 
is 2.0.4 and the non-default one is 2.0.7b.  Make sure you use the right one.

Be sure that the new 'getty_ps' works correctly *before* you remove all the
other stuff!  I recommend changing one of your virtual console lines from:
c2:23456:respawn:/etc/getty tty2
to:
c2:23456:respawn:/etc/getty_ps tty2 VC console

Put this line in your /etc/gettydefs:
VC# B9600 SANE CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #VC

and restart 'init':
yourbox# init q    	(for poegil init, use "kill -HUP 1")

If you can log in with 'getty_ps', it's working.  Remove all the old 'getty's.
Move 'getty_ps' to 'getty', or link it.  Be sure to update your /etc/inittab 
to correctly invoke the new 'getty'.  'getty_ps' can handle the stock
'getty's syntax.

Once you have installed it, and are certain it is working, you can remove any
other versions of 'getty' you have.  Be sure to check in /bin, /etc,
/usr/bin, /usr/etc, /usr/man/man1, and /usr/man/cat1 for any thing called
"getty" - there are old versions lurking everywhere...   Also, you can safely 
remove the old config file /etc/gettytab - you only need /etc/gettydefs.

There are lots of parameters you can tweak for each port you have.  These
are implemented in seperate config files for each port (if you want).  I'm not
convinced you need them at all.  Mine works fine without them.  In general you
should only need them to implement setups for unusual situations.  You might
consider using the ALTLOCK option, to be sure that all locks are checked
properly.  Here are a couple of /etc/default sample files - note the 
/etc/default/getty will be used by *all* instances of 'getty', and that 
/etc/default/getty.ttySX will only be used by that one port.

/etc/default/getty:
SYSTEM=<systemname>
VERSION=/proc/version
LOGIN=/bin/login
ISSUE=/etc/issue
CLEAR=NO
HANGUP=YES

/etc/default/getty.ttySX:
SYSTEM=<systemname>
VERSION=/proc/version
LOGIN=/bin/login
ISSUE=/etc/issue
CLEAR=NO
HANGUP=YES
INIT="" ATZ\r OK
TIMEOUT=60
WAITFOR=RING
CONNECT="" ATA\r CONNECT \s\A
ALTLINE=cuaX

/etc/default/uugetty.ttySX:
ALTLOCK=cuaX
TIMEOUT=60
INIT="" ATZ\r OK
DELAY=1
CLEAR=NO

/etc/default/uugetty.ttySX:
SYSTEM=<systemname>
VERSION=/proc/version
LOGIN=/bin/login
ISSUE=/etc/issue
CLEAR=NO
HANGUP=YES
INIT="" ATZ1\r
ALTLINE=cuaX
ALTLOCK=cuaX
INITLINE=cuaX
TIMEOUT=60

===============================================================================

(3). How do I dial out with my modem?

- First, make sure you have the right hardware.  You probably want to hook
the modem to COM2, the DB25 pin port on your PC.  This requires a straight
through cable, with no pins crossed.  (The 9 pin COM1 port works nicely for
a mouse, since most serial mice already have a DB9 connector.)  

For an internal modem, you will not need a modem cable.  You may have trouble
if you are using Rockwell chipsets claiming to emulate 16550A UARTs.  
Ted T'so is currently working on the problem.

Most internal modems try to emulate a 8250, 16450, 16550A UART.  It all depends
on the quality of this emulation if it will work under Linux too.  (DOS
is too simple about these things).  If choice allows, an external modem
is better because it allows you to check the little lights which tell
you which pin is active or not.  Furthermore in case of some real trouble,
you can switch off the modem without switching of the complete PC.
Lastly, an external modem has its own powersupply, which might make it a
bit more reliable than an internal one.

- For now, make sure that nothing is using that port.  Check to see if there
is a 'getty' watching it, or it is not locked by anything else.  If there is
a 'getty' process, check your /etc/inittab file for entries using your
serial port.  Comment the line out (with "#"), and restart 'init'.  Do
not comment any lines that contain a tty* device, only ones containing ttyS*
or cua*.  tty* are your virtual consoles.

- Use 'kermit' to test the setup.  You should set your line to 
/dev/cua1, and the speed to the highest speed your modem can handle.  Try 
dialing out, or talking to the modem.  If you are properly connected, your 
modem should respond to "AT" commands.  If you say "AT" to your modem, it 
should respond with "OK".  Once you are sure that the modem is functional, 
you can use more complex programs, like 'Seyon', or 'xconn'.

===============================================================================

(4). How do I dial in and out with my modem?

- Get your modem to dial out correctly.  

- Replace the stock 'getty' with 'getty_ps' as described in FAQ (2).
Update /etc/gettydefs to include entries for modems:
(note that the entries point to each other, these are not for fixed baud)

# Modem entries
38400# B38400 CS8 # B38400 SANE -ISTRIP HUPCL #@S @L @B login: #19200

19200# B19200 CS8 # B19200 SANE -ISTRIP HUPCL #@S @L @B login: #9600

9600# B9600 CS8 # B9600 SANE -ISTRIP HUPCL #@S @L @B login: #2400

2400# B2400 CS8 # B2400 SANE -ISTRIP HUPCL #@S @L @B login: #1200

1200# B1200 CS8 # B1200 SANE -ISTRIP HUPCL #@S @L @B login: #300

300# B300 CS8 # B300 SANE -ISTRIP HUPCL #@S @L @B login: #38400

- If you have your modem set up to do RTS/CTS hardware flow control, you
can add CRTSCTS to the entries.

- Next, make sure that you have a dialin and dialout device for the port
your modem is on.  If you have your modem on /dev/cua1, you will need
a device called /dev/ttyS1.  If you don't have the correct devices,
see the question on how to create devices, and create the devices.

- Edit your /etc/inittab, so that 'getty' is run on your serial port:

Add the following line:
S1:456:respawn:/etc/getty ttyS1 38400
(				^-- put your highest modem speed here)


- Restart 'init':
yourbox# init q    	(for poegil init, use "kill -HUP 1")

Now Linux will be watching your serial port for connections.

- Dial in from another site and log in to you Linux system.  Rejoice.  Party.

- For sites with UUCP feeds, you probably want to use 'uu_getty', instead of
plain 'getty'.  It's designed for use with UUCP.  Look at the README for
it for exact differences.  Most importantly, it checks the lock files
that UUCP creates.

===============================================================================

(5). How do I set up a terminal connected to my PC.

- Make sure you have the right kind of cable!  A null modem cable bought at a
computer store should do it.  At a minimum, you should have:
(If none of these work, please tell me what works for you!)

	              	2 - 3     		This works for me on a 
	              	3 - 2     		Wyse terminal.
		      	7 - 7     		You milage may vary.
		       20 - 20    

If that doesn't work, try the following (a full null modem cable):

			2 - 3     			Pin names:
			3 - 2    			1 Frame Ground 
			4 - 5     			2 TxD
			5 - 4    			3 RxD 
			6 - 20   			4 RTS 
			7 - 7    			5 CTS 
			8 - 20   			6 DSR 
		       20 - 6				7 Signal Ground
                       20 - 8				8 DCD
						       20 DTR

You will need pins 4 and 5 if you want to do any kind of hardware flow
control.

- Connect your terminal to your computer.  If you can, tell you terminal
to ignore modem control signals.  Try using 9600 bps, 8 data bits, 1 stop
bit, no parity bits.

- Replace the stock 'getty' with 'getty_ps' as described in FAQ (2).
Add an entry for 'getty' to use for your terminal in /etc/gettydefs.  
Mine looks like this:

# 9600 baud Dumb Terminal entry
DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #DT9600

You might add HUPCL so the login is killed whenever you switch of
the terminal (provided you use a proper null-modem cable).

- Edit your /etc/inittab file to run getty on the serial port.  Mine looks like
this:

S1:456:respawn:/etc/getty ttyS1 DT9600 vt100

- restart 'init'
yourbox# init q    	(for poegil init, use "kill -HUP 1")

- at this point, you should see a login prompt on your terminal.  Rejoice.
Party.  Login on your terminal and PC.  'talk' to yourself from accross
the room.

===============================================================================

(6). Can I use more than 2 serial ports?  Can I use a modem, a terminal, and
my mouse?

That depends.  The number of serial ports you can use is limited by the number
of interrupts (IRQ) we have to use.  Each serial devices must be assigned 
it's own interrupt.  On a PC, each serial port counts as a device. 
However, there are specially designed multiport serial cards which have 
multiple serial ports on one device.  (For those of you who are hardware
minded, all it means that is that there is a OR gate combining all of the 
IRQ outputs from each serial port.)

Your PC will normally come with COM1 and COM3 at IRQ 4, and COM2 and COM4
at IRQ 3.  To use more than 2 serial devices, you will have to give up an 
interrupt to use.  A good choice is to reassign an interrupt from your 
parallel port.  Your PC normally comes with IRQ 5 and IRQ 7 set up as 
interrupts for your parallel ports, but hardly anyone uses 2 parallel ports.  
You can reassign one of the interrupts to a serial device, and still happily 
use your parallel port.  You will need the 'setserial' program to do this 
(or you can play with the jumpers on your boards - 'setserial' is *much* 
easier!).  As far as I know, 'setserial' will work with Linux >= 0.99pl9.  
It is pretty much mandatory for Linux 0.99pl10, since this version of Linux 
does not do much auto detection of serial devices.

You will need to set things up so that there is one, and only one interrupt 
for each serial device.  Here is how I set mine up (in /etc/rc.local - you 
should do it upon startup):

/etc/setserial /dev/cua0 irq 5		# my mouse
/etc/setserial /dev/cua1 irq 4		# my terminal
/etc/setserial /dev/cua3 irq 3		# my modem
# my printer is hooked up on my parallel port IRQ 7 - no change necessary

The problem is that all of the bus lines on the ISA bus are electrically
connected together, in parallel, and all of the bus lines are driven by
TTL gates.  If there are two devices simultaneously trying to drive an
IRQ line, they end up "fighting" over that line.  You get undefined
behavior when one of the TTL gates is trying to drive the IRQ line low,
and the other TTL gate is trying to drive the IRQ line high.  Usually
one of the gates will consistently win, with the net result that the
computer will only see interrupts from one of the serial devices --- but
this is not guaranteed; there may be very erratic behavior as a result.

Standard IRQ assignments:
              IRQ  0    Timer channel 0
	      IRQ  1    Keyboard
              IRQ  2    Cascade for controller 2
              IRQ  3    Serial port 2
              IRQ  4    Serial port 1
              IRQ  5    Parallel port 2 (Reserved in PS/2)
              IRQ  6    Floppy diskette
              IRQ  7    Parallel port 1
              IRQ  8    Real-time clock
              IRQ  9    Redirected to IRQ2
              IRQ 10    Reserved
              IRQ 11    Reserved
              IRQ 12    Reserved (Auxillary device in PS/2)
              IRQ 13    Math coprocessor
              IRQ 14    Hard disk controller
              IRQ 15    Reserved

There is really no Right Thing to do when choosing interrupts.  Just make sure
it isn't being used.  5 is a good choice.

===============================================================================

(7). What kind of serial boards does linux support?

Linux supports standard PC serial boards, internal modems, and
a number of multiport serial boards, including the Usenet Serial Board
II, the Boca 4-port (BB-1004), 8-port (BB-1008), and 16-port (BB-2016)
boards, and AST FourPort boards and clones.  In general, Linux will
support any multiport serial board which uses a 8250, 16450, 16550, or
16550A (or compatible) UART, and assignes the UART registers to a
contiguous block of 8 I/O ports on the 386/486.

Linux does not support any intelligent serial ports, nor is it likely
that it will in the future.

===============================================================================

(8). What numbers should my serial devices in /dev have?

The recommended convention is:

/dev/ttyS0 major 4, minor 64	/dev/cua0 major 5, minor 64
/dev/ttyS1 major 4, minor 65	/dev/cua1 major 5, minor 65
/dev/ttyS2 major 4, minor 66	/dev/cua2 major 5, minor 66
/dev/ttyS3 major 4, minor 67	/dev/cua3 major 5, minor 67

If you don't have a device, you will have to create it with the 'mknod' 
command.

Example, suppose you needed to create devices for /dev/cua0:

yourbox# mknod /dev/cua0 c 5 64
yourbox# mknod /dev/ttyS0 c 4 64

===============================================================================

(9). How should I configure my modem?

- You'll have to get you modem connected before you try to set registers.

- For dialout use only, configure it however you want.

I like to see result codes, so I set Q0.  I also like to see what I'm typing,
so I set E1.

- For dialin use, you have to set it up a certain way.

Here is what you have to set:

E0	Command echo OFF	
Q1	NO result codes are reported		

If you don't shut up the modem completely, it will talk to 'getty'.
'getty' will think someone is trying to log in, and will spawn 'login'.  This
will cause all sorts of confusion.  Not setting these correctly will probably
cause the dreaded "respawning to fast" message.

&C1	DCD is on after connect *only*

If DCD is always on, there will always be a connection, and 'getty' will try
to log people in.  Not setting this can cause "device busy" errors.

Other things you should set:

&S0	DSR is always on
enable your data compression
autobaud
&D3	DTR on/off resets modem	

===============================================================================

(A). Troubleshooting:

1. I keep getting "line XXX of inittab invalid"

Make sure you are using the correct syntax for your version of 'init'.  The
different 'init's that are out there use different syntax in the /etc/inittab
file.  Make sure you are using the correct syntax for your version of 'getty'.

2. When I try to dial out, it says "/dev/cuaX: Device or resource busy"

- This is one of the most frequent errors people get.  It can happen for a 
variety of reasons.  If you followed the instructions carefully, this should
not happen, so double check to make sure you did everything right.  

This problem usually arrises when DCD is not set correctly.  DCD should only be
set when there is an actual connection (ie someone is dialed in), not when
'getty' is watching the port.  When 'getty' sees DCD get set, it will lock
the port and probably spawn 'login'.  Check to make sure that you modem is
configured to only set DCD when there is a connection.  DTR and RTS
should be set whenever something is using, or watching the line, like 'getty', 
'kermit', or some other comm program.

- Another common cause of "device busy" errors, is that you set up your serial
port with an interrupt already taken by something else.  As each device 
initializes, it asks Linux for permission to use its hardware interrupt.  
Linux keeps track of which interrupt is assigned to whom, and if your interrupt
is already taken, your device won't be able to initialize properly.  The 
device really doesn't have much of any way to tell you that this happened, 
except that when you try to use it, it will return a device-busy error.

A fix for this may be to remake the kernel, after doing "make config", and
answering "no" to all the devices that you don't actually have.  If they're
compiled in, the software for these devices may be grabbing your interrupt,
even though the physical device does not exist.  Also, you can search through 
the source and include files.  For example, 
"grep IRQ /usr/src/linux/include/linux/*" yields a "#define MOUSE_IRQ 5" line 
in busmouse.h.  Another good place to look is in 
/usr/src/linux/net/tcp/Space.c.  

- You might experience problems when you use the WAITFOR or WAITCHAR options in 
your /etc/defaults/getty.whatever file.  Try taking them out.

3. I keep getting "respawning too fast, disableing for 5 minutes".

Make sure your modem is configured correctly.  Look at registers E and Q.


===============================================================================

(B). Linux ftp sites:  (please choose the site nearest to you)

tsx-11.mit.edu:/pub/linux	(MA, USA)	
sunsite.unc.edu:/pub/Linux      (NC, USA)
nic.funet.fi			(Finland)

===============================================================================

(C). Recommended Reading:

init(1), getty(1), login(1)
gettydefs(4)
setserial(8)

Your modem manual

"The UNIX System Administration Handbook" by Nemeth, Snyder and Seebass

"Managing UUCP and Usenet" by Tom O'Reilly and Grace Todino, 
O'Reilly Associates, Inc  ISBN 0-937175-93-5   
(highly recommended by nearly everyone)

===============================================================================

(D). There was no possible way to write this FAQ alone.  Much of the material 
is repeated verbatim from the original sources.

Contributions, ideas, suggestions, and help came from (and many thanks) to:

Brandon S. Allbery <bsa@kf8nh.wariat.org>
Karl Buck <kxb@cis.ksu.edu>
Bryan Curnutt <bryan%uhura1@uunet.uu.net>
Arthur Donkers <arthur%ptt-iat@nluug.nl>
Michael Hamilton <hamilton@golem.wcc.govt.nz>
Cheng Chang Huang <huangch@cps.msu.edu>
Camillus Jayewardena <jayeward@abs.ascom.ch>
Jerry Kaidor <jkaidor@synoptics.com>
Juha Laiho <jlaiho@ichaos.nullnet.fi>
Mark Schwabacher <schwabac@yoko.rutgers.edu>
Theodore Ts'o <tytso@Athena.MIT.EDU>

And also thanks to Ian Kluft <ikluft@uts.amdahl.com> for his cool AUTO-FAQ
software.

Please send me any comments, suggestions, or additional material you have.

===============================================================================

Some things still to be answered:

- More detail on internal modems. 

- More info on using multiport cards.  Should 'setserial' be used with them?

