This part is in 3 HOWTOs: Modem, Serial, and Text-Terminal. There are some minor differences, depending on which HOWTO it appears in.
The setserial program doesn't seem to work if the serial port is for
a linmodem such as ttySHCF0.
If you have a Laptop (PCMCIA) don't use setserial until you
read
Laptops: PCMCIA.
setserial is a program used for the user to communicate with
the serial device driver. You normally never need to use it, provided
that you only use the one or two serial ports that come as standard
equipment with a PC. Even in other cases, most extra serial ports
should be auto-detected by modern kernels. Except you'll need to use
setserial if you have an old ISA serial port set by jumpers on the
physical hardware or if your kernel (such as 2.2 or older) doesn't
both detect and set your add-on PCI serial ports.
setserial allows you (or a shell script) to talk to the serial
software. But there's also another program, tt/stty/, that also deals
with the serial port and is used for setting the port speed, etc.
setserial deals with the lower-level configuring of the serial
port, such as dealing with IRQs (such as 5), port addresses (such as
3f8), and the like. A major problem with it is that it can't
set or configure the serial port hardware: It can't set the IRQ or
port addresses into the hardware. Furthermore, when it seemingly
reports the configuration of the hardware, it's sometimes wrong since
it doesn't actually probe the hardware unless you specifically tell it
to. Even then, it doesn't do the modern type of bus probing and some
hardware may never be found by it. Still, what it shows is right most
all the time but if you're having trouble getting a serial port to
work, then there's a fair chance it's wrong.
In olden days, when the IRQ and port address was set by jumpers on the
serial card, one would use setserial to tell the driver how these
jumpers were set. Today, when plug-and-play methods detect how the
jumperless serial port is set, setserial is not really needed
anymore unless you're having problems or using old hardware.
Furthermore, if the configuration file used by setserial is
wrong, then there's trouble. In this case, if you use setserial
to try to find out how the port is configured, it may just repeat the
incorrect information in the configuration file.
setserial can sometimes be of help to find a serial port. But
it's only of use if you know the port address and use the right
options. For modern ports, there's usually better ways to look for
them by plug-and-play methods.
Thus the name setserial is somewhat of a misnomer since it
doesn't set the I/O address nor IRQ in the hardware, it just "sets"
them in the driver software. And the driver naively believes that
what setserial tells it, even if it conflicts with what the driver
has found by using plug-and-play methods. Too bad that it fails to
at least issue a warning message for such a conflict. Since the
device driver is considered to be part of the kernel, the word
"kernel" is often used in other documentation with no mention made of
any "serial driver".
Some distributions (and versions) set things up so that setserial
is run at boot-time by an initialization shell script (in the
/etc directory tree). But the configuration file which this script
uses may be either in the /etc tree or the /var tree. In some cases,
if you want setserial to run at boot-time, you may have to take
some action. setserialwill not work without either serial
support built into the kernel or loaded as a module. The module may
get loaded automatically if you (or a script) attempt to use
setserial.
While setserial can be made to probe the hardware I0 port
addresses to try to determine the UART type and IRQ, this has
severe limitations. See
Probing. It
can't set the IRQ or the port address in the hardware of PnP or PCI
serial ports (but the plug-and-play features of the serial driver may
do this). It also can't directly read the PnP data stored in
configuration registers in the hardware. But since the device driver
can read these registers and setserial tells you what the device
driver thinks, it might be correct. Or it could be telling you what
setserial had previously (and perhaps erroneously) told the
driver. There's no way to know for sure without doing some other
checks.
The serial driver (for Linux Kernel 2.4+) looks for a few "standard"
legacy serial ports, for PnP ports on the ISA bus, and for all
supported port hardware on the PCI bus. If it finds your ports
correctly, then there's no need to use setserial. The driver
doesn't probe for legacy IRQs and may get these wrong and it may miss
old ISA serial ports set with jumpers on the card.
Besides the man page for setserial, check out info in
/usr/doc/setserial.../ or /usr/share/doc/setserial.
This should tell you how setserial is handled for your distribution of
Linux. While setserial behaves the same in all distributions,
the scripts for running it, how to configure such scripts (including
automatic configuration), and the names and locations of the script
files, etc., are all distribution-dependent.
If a serial module gets unloaded, the changes previously made by
setserial will be forgotten by the driver. But while the driver
forgets it, a script provided by the distribution may save it in a
file somewhere so that it can the restored if the module is reloaded.
setserial commandRemember, that setserial can't set any I/O addresses or IRQs
in the hardware. That's done either by plug-and-play software (run by
the driver) or by jumpers for legacy serial ports. Even if you give
an I/O address or IRQ to the driver via setserial it will not set
such values and assumes that they have already been set. If you give
it wrong values, the serial port will not work right (if at all).
For legacy ports, if you know the I/O address but don't know the IRQ you may command setserial to attempt to determine the IRQ.
You can see a list of possible commands by just typing setserial
with no arguments. This fails to show you the one-letter options such
as -v for verbose which you should normally use when troubleshooting.
Note that setserial calls an IO address a "port". If you type:
setserial -g /dev/ttyS*
"UART: unknown" just ignore the entire line
since no serial port exists at that address.
If you add -a to the option -g you will see more info although few
people need to deal with (or understand) this additional info since
the default settings you see usually work fine. In normal cases the
hardware is set up the same way as "setserial" reports. But if you are
having problems there is a good chance that setserial has it wrong.
In fact, you can run "setserial" and assign a purely fictitious I/O
port address, any IRQ, and whatever uart type you would like to have.
Then the next time you type "setserial ..." it will display these
bogus values you've supplied to the driver. They will also be officially
registered with the kernel as displayed (at the top of the screen) by
the "scanport" command (Debian). Of course the serial
port driver will not work correctly (if at all) if you attempt to use
such a port. Thus, when giving parameters to setserial, "anything
goes". Well almost. If you assign one port a base address that is
already assigned (such as 3e8) it may not accept it. But if you use
3e9 it will accept it. Unfortunately 3e9 is actually assigned since it
is within the range starting at base address 3e8. Thus the moral of
the story is to make sure your data is correct before assigning
resources with setserial.
While assignments made by setserial are lost when the PC is powered
off, a configuration file may restore them when the PC is started
up again. In newer versions, what you change by setserial might get
automatically saved to a configuration file. When setserial runs
it uses the info from the configuration file.
Where this configuration file resides depends on your distribution. Look at the start-up scripts somewhere in the /etc/ tree (such as /etc/init.d/ or /etc/rc.d/) and read the startup script for "serial" or "setserial" or the like. It should show where the configuration file(s) reside. In Debian there are 4 options for use of this configuration file:
setserial reports when the system is first
shutdown and put it in the configuration file. After that, don't ever
make any changes to the configuration file, even if someone has made
changes by running the setserial command on the command line and
then shuts down the system. ("autosave-once" option)setserial detects to the
configuration file. ("autosave" option)In olden days (perhaps before 2000), there wasn't any configuration
file and the configuration was manually set (hard coded) inside the
shell script that ran setserial. See
Edit a script (prior to version 2.15).
You probe for a port with setserial only when you suspect that
it has been enabled (by PnP methods, the BIOS, jumpers, etc.).
Otherwise setserial probing will never find it since its address
doesn't exist. A problem is where the software looks for a port at
specified I/O addresses. Prior to probing with "setserial", one may
run the "scanport" (Debian) command to check all possible ports in one
scan. It makes crude guesses as to what is on some ports but doesn't
determine the IRQ. It's a fast first start. It may hang your PC but
so far it's worked fine for me. Note that non-Debian distributions
don't seem to supply "scanport". Is there another scan program?
With appropriate options, setserial can probe (at a given I/O
address) for a serial port but you must guess the I/O address. If you
ask it to probe for /dev/ttyS2 for example, it will only probe at the
address it thinks ttyS2 is at (2F8). If you tell setserial that ttyS2
is at a different address, then it will probe at that address, etc.
See
Probing
The purpose of such probing is to see if there is a uart there, and if
so, what its IRQ is. Use setserial mainly as a last resort as
there are faster ways to attempt it such as wvdialconf to detect
modems, looking at very early boot-time messages, or using pnpdump
--dumpregs, or lspci -vv. But if you want to detect hardware
with setserial use for example :
setserial
/dev/ttyS2 -v autoconfig
If the resulting message shows a uart type such as 16550A, then you're
OK. If instead it shows "unknown" for the uart type, then there
is supposedly no serial port at all at that I/O address. Some cheap
serial ports don't identify themselves correctly so if you see
"unknown" you still might have a serial port there.
Besides auto-probing for a uart type, setserial can auto-probe for
IRQ's but this doesn't always work right either. In one case it first
gave the wrong irq but when the command was repeated it found the
correct irq. In versions of setserial >= 2.15, the results of your
last probe test could be automatically saved and put into a
distribution-specific configuration file such as
/etc/serial.conf or /etc/sysconfig/serial or
/var/lib/setserial/autoserial.conf for Debian. This will be
used next time you start Linux.
It may be that two serial ports both have the same IO address set in
the hardware. Of course this is not normally permitted for the ISA
bus but it sometimes happens anyway. Probing detects one serial port
when actually there are two. However if they have different IRQs,
then the probe for IRQs may show IRQ = 0. For me, it only did this if
I first used setserial to give the IRQ a fictitious value.
While setserial may run via an initialization script,
something akin to setserial also runs earlier when the serial
module is loaded (or when the kernel starts the built-in serial driver
if it was compiled into the kernel). Thus when you watch the start-up
messages on the screen it may look like it ran twice, and in fact it
has.
If the first message is for a legacy port, the IRQs shown may be wrong since it didn't probe for IRQs. If there is a second report of serial ports, it may the result of a script such as /etc/init.d/setserial. It usually does no probing and thus could be wrong about how the hardware is actually set. It only shows configuration data that got saved in a configuration files. The old method, prior to setserial 2.15, was to manually write such data directly into the script.
When the kernel loads the serial module (or if the "module equivalent"
is built into the kernel) then all supported PnP ports are detected.
For legacy (non-PnP) ports, only ttyS{0-3} are auto-detected
and the driver is set to use only IRQs 4 and 3 (regardless of what
IRQs are actually set in the hardware). No probing is done for IRQs
but it's possible to do this manually. You see this as a boot-time
message just as if setserial had been run.
To correct possible errors in IRQs (or for other
reasons) there may be a script file somewhere that runs
setserial. Unfortunately, if this file has some IRQs wrong, the
kernel will still have incorrect info about the IRQs. This file is
usually part of the initialization done at boot-time. Whether it
runs or not depends on how you (and/or your distribution) have set
things up. It may also depends on the runlevel.
Before modifying a configuration file, you can test out a "proposed"
setserial command by just typing it on the command line. In some
cases the results of this use of setserial will automatically get
saved somewhere such as /etc/serial.conf (or autoserial.conf or
serial) when you shutdown. So if it worked OK (and solved your
problem) then there's no need to modify any configuration file. See
Configuration method using /etc/serial.conf, etc..
This is how it was done prior to setserial 2.15 (1999)
The objective was to modify (or create) a script file in the /etc
tree that runs setserial at boot-time. Most distributions provided
such a file (but it may not have initially resided in the /etc tree).
So prior to version 2.15 (1999) it was simpler. All you did was edit a script. There was no /etc/serial.conf file (or the like) to configure setserial. Thus you needed to find the file that runs "setserial" at boot time and edit it. If it didn't exist, you needed to create one (or place the commands in a file that ran early at boot-time). If such a file was currently being used it's likely was somewhere in the /etc directory-tree. But Redhat <6.0 has supplied it in /usr/doc/setserial/ but you need to move it to the /etc tree before using it.
The script /etc/rc.d/rc.serial was commonly used in the past.
The Debian distribution used /etc/rc.boot/0setserial.
Another file once used was /etc/rc.d/rc.local but it's may
not have run early enough. It was reported that other processes may
try to open the serial port before rc.local ran resulting in serial
communication failure. Later on it most likely was found in
/etc/init.d/ but wasn't normally intended to be edited.
If such a file was supplied, it likely contained a number of
commented-out examples. By uncommenting some of these and/or
modifying them, you could set things up correctly. It was important
use a valid path for setserial, and a valid
device name. You could do a test by executing this file manually
(just type its name as the super-user) to see if it works right.
Testing like this was a lot faster than doing repeated reboots to get
it right.
For versions >= 2.15 (provided your distribution implemented the change, Redhat didn't at first) it may be more tricky to do since the file that runs setserial on startup, /etc/init.d/setserial or the like was not intended to be edited by the user. See Configuration method using /etc/serial.conf, etc..
An example line in such a script was:
/sbin/setserial /dev/ttyS3 irq 5 uart 16550A skip_test
or, if you wanted setserial to automatically determine the uart and the IRQ for ttyS3 you would have used something like this:
/sbin/setserial /dev/ttyS3 auto_irq skip_test autoconfig
This was done for every serial port you wanted to auto configure, using a device name that really does exist on your machine. In some cases it didn't work right due to the hardware.
Prior to setserial version 2.15 (1999), the way to configure
setserial was to manually edit the shell-script that ran setserial at
boot-time. See
Edit a script (before version 2.15). This was simple, but the simple and clear method has
been changed to something that is unnecessarily complex. Today the
script and configuration file are two different files instead of one.
This shell-script is not edited but gets its data from a configuration
file such as /etc/serial.conf (or
/var/lib/setserial/autoserial.conf).
Furthermore you may not even need to edit serial.conf (or the like) because using the "setserial" command on the command line may automatically cause serial.conf to be edited appropriately. This was done so that you may not need to edit any file in order to set up (or change) what setserial does each time that Linux is booted.
What often happens is this: When you shut down your PC the script
that ran "setserial" at boot-time is run again, but this time it only
does what the part for the "stop" case says to do: It uses
"setserial" to find out what the current state of "setserial" is, and
it puts that info into the serial configuration file such as
serial.conf. Thus when you run "setserial" to change
the serial.conf file, it doesn't get changed immediately but only when
and if you shut down normally.
Now you can perhaps guess what problems might occur. Suppose you don't shut down normally (someone turns the power off, etc.) and the changes don't get saved. Suppose you experiment with "setserial" and forget to run it a final time to restore the original state (or make a mistake in restoring the original state). Then your "experimental" settings are saved. And worst of all, unless you know which options were set in the configuration file, you don't know what will happen. One option in Debian (and likely other distributions) is known as "AUTOSAVE-ONCE" which saves changes only for the first time you make them with the setserial command.
If the option "###AUTOSAVE###" is set and you manually edit serial.conf, then your editing is destroyed when you shut down because it gets changed back to the state of setserial at shutdown. There is a way to disable the changing of serial.conf at shutdown and that is to remove "###AUTOSAVE###" or the like from first line of serial.conf. In the Debian distribution, the removal of "###AUTOSAVE###" from the first line was once automatically done after the first time you shutdown just after installation. To retain this effect the "AUTOSAVE-ONCE" option was created which only does a save when time the system is shut down for the first time (just after you install or update the setserial program).
The file most commonly used to run setserial at boot-time (in conformance with the configuration file) is now /etc/init.d/setserial (Debian) or /etc/init.d/serial (Redhat), or etc., but it should not normally be edited. For 2.15, Redhat 6.0 just had a file /usr/doc/setserial-2.15/rc.serial which you have to move to /etc/init.d/ if you want setserial to run at boot-time.
To disable a port, use setserial to set it to "uart none". This
will not be saved. The format of /etc/serial.conf appears to be just
like that of the parameters placed after "setserial" on the command
line with one line for each port. If you don't use autosave, you may
edit /etc/serial.conf manually.
In order to force the current settings set by setserial to be saved to
the configuration file (serial.conf) without shutting down, do what
normally happens when you shutdown: Run the shell-script
/etc/init.d/{set}serial stop. The "stop" command will save
the current configuration but the serial ports still keep working OK.
In some cases you may wind up with both the old and new configuration methods installed but hopefully only one of them runs at boot-time. Debian labeled obsolete files with "...pre-2.15".
By default, both ttyS0 and ttyS2 will share IRQ 4, while ttyS1 and ttyS3 share IRQ 3. But while sharing serial interrupts (using them in running programs) is OK for the PCI bus, it's not permitted for the ISA bus unless you: 1. have kernel 2.2 or better, and 2. you've compiled in support for this, and 3. your serial hardware supports it. See
Interrupt sharing and Kernels 2.2+ If you only have two serial ports, ttyS0 and ttyS1, you're still OK since IRQ sharing conflicts don't exist for non-existent devices.
If you add a legacy internal modem (without plug-and-play) and retain ttyS0 and ttyS1, then you should attempt to find an unused IRQ and set it in your serial port (or modem card) and then use setserial to assign it to your device driver. If IRQ 5 is not being used for a sound card, this could be used for a modem.
If you have a Laptop, read PCMCIA-HOWTO for info on the serial configuration. For serial ports on the motherboard, setserial is used just like it is for a desktop. But for PCMCIA cards (such as a modem) it's a different story. The configuring of the PCMCIA system should automatically run setserial so you shouldn't need to run it. If you do run it (by a script file or by /etc/serial.conf) it might be different and cause trouble. The autosave feature for serial.conf shouldn't save anything for PCMCIA cards (but Debian did until 2.15-7). Of course, it's always OK to use setserial to find out how the driver is configured for PCMCIA cards.
isapnp is a program to configure Plug-and-Play (PnP) devices
on the ISA bus including internal modems. It comes in a package
called "isapnptools" and includes another program, "pnpdump" which
finds all your ISA PnP devices and shows you options for configuring
them in a format which may be added to the PnP configuration file:
/etc/isapnp.conf. It may also be used with the --dumpregs option to
show the current IO address and IRQ of the modem's serial port. The
isapnp command may be put into a startup file so that it runs each
time you start the computer and thus will configure ISA PnP devices.
It is able to do this even if your BIOS doesn't support PnP. See
Plug-and-Play-HOWTO.
wvdialconf will try to find which serial port (ttyS?) has a
modem on it. It also creates a configuration program for the wvdial
program. wvdial is used for simplified dialing out using the PPP
protocol to an ISP. It can also look for modems which are not
currently in use. It will automatically devise a "suitable" init
string for the modem but sometimes gets it wrong. Since this command
has no options, it's simple to use but you must give it the name of a
file to put the init string (and other data) into. For example type:
wvdialconf my_config_file_name.