path: root/release/sysinstall/help/hardware.hlp

Hardware Documentation Guide:  $Id: hardware.hlp,v 1.6 1996/07/05 01:24:38 jkh Exp $

Contents last changed:  July 4th, 1996

Table of Contents
-----------------
0.  Document Conventions
1.  Default Configuration (GENERIC kernel)
2.  Using UserConfig to change FreeBSD kernel settings
3.  LINT - other possible configurations.
4.  Known Hardware Problems.

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

0.      Document Conventions
--      --------------------

We have `underlined' text which represents user input with `-' symbols
throughout this document to differentiate it from the machine output.

1.      Default (GENERIC) Configuration
--      -------------------------------

The following table contains a list of all of the devices that are
present in the GENERIC kernel, that being the kernel (the operating
system) that was placed in your root partition during the FreeBSD
installation process.  A compressed version of the GENERIC kernel is
also used on the installation floppy diskette and DOS boot image.

The table describes the various parameters used by the driver to
communicate with the hardware in your system.  There are four
parameters in the table, though not all are used by each and every
device.

Detail:

   Port   The starting I/O port used by the device, shown in hexadecimal.

   IOMem  The lowest (or starting) memory address used by the device,
          also shown in hexadecimal.

   IRQ    The interrupt the device uses to alert the driver to an event,
          given in decimal.

   DRQ    The DMA (direct memory access) channel the device uses to move
          data to and from main memory, also given in decimal.

If an entry in the table has `n/a' for a value then it means that the
parameter in question does not apply to that device.  A value of `dyn'
means that the correct value should be determined automatically by the
kernel when the system boots.


FreeBSD GENERIC kernel:

        Port    IRQ     DRQ     IOMem   Description
        ----    ---     ---     -----   ---------------------------------
fdc0    3f0     6       2       n/a     Floppy disk controller
wdc0    1f0     14      n/a     n/a     IDE/MFM/RLL disk controller
wdc1    170     15      n/a     n/a     IDE/MFM/RLL disk controller

ncr0    n/a     n/a     n/a     n/a     NCR PCI SCSI controller
ahc0    n/a     n/a     n/a     n/a     Adaptec 294x PCI SCSI controller
bt0     330     dyn     dyn     dyn     Buslogic SCSI controller
uha0    330     dyn     6       dyn     Ultrastore 14f
aha0    330     dyn     5       dyn     Adaptec 154x SCSI controller
ahb0    dyn     dyn     dyn     dyn     Adaptec 174x SCSI controller
ahc0    dyn     dyn     dyn     dyn     Adaptec 274x/284x/294x SCSI controller
aic0    340     11      dyn     dyn     Adaptec 152x/AIC-6360 SCSI
                                        controller
nca0    1f88    10      dyn     dyn     ProAudioSpectrum cards
sea0    dyn     5       dyn     c8000   Seagate ST01/02 8 bit controller

wt0     300     5       1       dyn     Wangtek and Archive QIC-02/QIC-36

mse0    23c     5       n/a     n/a     Microsoft Bus Mouse
psm0    60      12      n/a     n/a     PS/2 Mouse (disabled by default)

mcd0    300     10      n/a     n/a     Mitsumi CD-ROM
matcd0  230     n/a     n/a     n/a     Matsushita/Panasonic CD-ROM
scd0    230     n/a     n/a     n/a     Sony CD-ROM

sio0    3f8     4       n/a     n/a     Serial Port 0 (COM1)
sio1    2f8     3       n/a     n/a     Serial Port 1 (COM2)

lpt0    dyn     7       n/a     n/a     Printer Port 0
lpt1    dyn     dyn     n/a     n/a     Printer Port 1

de0     n/a     n/a     n/a     n/a     DEC DC21x40 PCI based cards
                                        (including 21140 100bT cards)
ed0     280     5       dyn     d8000   WD & SMC 80xx; Novell NE1000 &
                                        NE2000; 3Com 3C503
ed1     300     5       dyn     d8000   Same as ed0
eg0     310     5       dyn     dyn     3Com 3C505
ep0     300     10      dyn     dyn     3Com 3C509
fe0     300     dyn     n/a     n/a     Fujitsu MB86960A/MB86965A cards
fxp0    dyn     dyn     n/a     dyn     Intel EtherExpress Pro/100B
ie0     360     7       dyn     d0000   AT&T StarLAN 10 and EN100;
                                        3Com 3C507; NI5210
ix0     300     10      dyn     d0000   Intel EtherExpress cards
le0     300     5       dyn     d0000   Digital Equipment EtherWorks
                                        2 and EtherWorks 3
lnc0    280     10      n/a     dyn     Lance/PCnet cards
                                        (Isolan, Novell NE2100, NE32-VL)
vx0     dyn     dyn     n/a     dyn
ze0     300     5       dyn     d8000   IBM/National Semiconductor
                                        PCMCIA Ethernet Controller
zp0     300     10      dyn     d8000   3Com PCMCIA Etherlink III
                                        Ethernet Controller
--- End of table ---


If the hardware in your computer is not set to the same settings as
those shown in the table and the item in conflict is not marked 'dyn',
you will have to either reconfigure your hardware or use UserConfig
('-c' boot option) to reconfigure the kernel to match the way your
hardware is currently set (see the next section).

If the settings do not match, the kernel may be unable to locate
or reliably access the devices in your system.


2.      Using UserConfig to change FreeBSD kernel settings
--      --------------------------------------------------

The UserConfig utility allows you to override various settings of
the FreeBSD kernel before the system has booted.  This allows you to
make minor adjustments to the various drivers in the system without
necessarily having to recompile the kernel.

UserConfig is activated by specifying the `-c' flag at the initial
boot prompt.  For example:

        >> FreeBSD BOOT @ 0x10000: 640/7168 k of memory
        Use hd(1,a)/kernel to boot sd0 when wd0 is also installed.
        Usage: [[wd(0,a)]/kernel][-abcCdhrsv]
        Use ? for file list or press Enter for defaults

        Boot: -c
              --

This command causes the system to boot the default kernel ("/kernel") and
the UserConfig utility to be started once the kernel is loaded into memory.

The `-c' flag follows any of the other parameters you may need to provide
for the system to boot properly.   For example, to boot off the second of
two SCSI drives installed and run UserConfig, you would type:

        Boot: sd(1,a)/kernel -c
              -----------------

As always, the kernel will report some information on your processor
and how much memory your system has.  Then UserConfig will be invoked
and you will see the prompt:

        config>

To see the list of commands that UserConfig accepts, you may type '?' and
press [ENTER].  The help message looks something like this:

Command                 Description
-------                 -----------
ls                      List currently configured devices
port <devname> <addr>   Set device port (i/o address)
irq <devname> <number>  Set device irq
drq <devname> <number>  Set device drq (DMA Request)
iomem <devname> <addr>  Set device maddr (memory address)
iosize <devname> <size> Set device memory size
flags <devname> <mask>  Set device flags
enable <devname>        Enable device
disable <devname>       Disable device (will not be probed)
visual                  Go to visual mode
quit                    Exit this configuration utility
help                    This message


You may alter nearly all of the default settings present in the FreeBSD
generic kernel.  This includes reassigning IRQs, disabling troublesome
devices (or drivers that conflict with the hardware your system has),
setting special device flags, etc.

Since people's tastes in user interface design vary widely, we have
provided two different interfaces to the UserConfig utility.  If you
type `visual' you will be placed in the "GUI" oriented device
attributes editor.  If you're someone who's more at home with
command-line flavored interfaces then simply don't type `visual' at
any point! :)

Since the visual interface pretty much describes itself, we'll use the
more verbose command line interface while describing UserConfig in the
following examples.

The most common use of UserConfig is to adjust or disable a driver
which is causing trouble.  The "ls" command displays the current
settings for all the drivers present in the booted kernel, and once
you have located an entry of interest you may use the displayed device
name to change its settings or even disable the driver completely.

For example, to change the memory address of network adapter 'ed0' to
the address 0xd4000, you would type
        
        config> iomem ed0 0xd4000
                -----------------

To entirely disable a device driver you are not using, use the
"disable" command.  In this example, you would disable device
`ie0' by typing:

        config> disable ie0
                -----------

You can use the "ls" command to verify your changes and correct
any other problems before continuing the boot process.

Once you are happy with a given configuration you may type: "quit"

This will cause the kernel to boot with the new settings you
have chosen.

Once you have a fully installed system (e.g. the `bin' distribution
has been successfully extracted), any changes you make in UserConfig
are permanently stored in the `/kernel' file on the root filesystem.
This action is performed by the `dset' utility, which will ensure that
these settings remain in effect until you replace the kernel with
a new one.  If you do not want your changes to be permanently
stored like this, remove `dset' from the /etc/rc file before you
make any changes.

If you accidentally change a setting for a device that you did not mean
to change, the safest thing to do is to reset the computer and start
over.  Do not allow the boot to proceed (e.g. do not type "quit") with
bad settings as these may be permanently stored by dset and
leave your system in a state where it will no longer run properly.

We suggest as a general rule that you disable any drivers that are not
used by your particular hardware configuration.  There are known problems
with certain device drivers (see section 4.0) that can cause conflicts
with other devices if they're also not disabled.  You should move or
disable any device that resides at the same port or IRQ as a device
you actually have!

You can also remove drivers that are not needed by building yourself a
custom kernel that contains only the device drivers which your system
really needs (see section 6.0 of the FreeBSD.FAQ).  If your system has
sufficient free disk space to store and compile the kernel sources,
this is the option we most highly recommend.

IMPORTANT NOTE:  Because dset only runs when the system has been fully
installed onto the hard disk, any changes you make when initially booting
off the floppy will NOT BE SAVED.  If you had to change your settings
in order to install the system then you will have to make them again
the first time you boot from the hard disk, after that you will not need
to do so again as dset will have run and saved them to your installed kernel
image.


3.      LINT - other possible configurations
--      ------------------------------------

The following drivers are not in the GENERIC kernel but remain
available to those who do not mind compiling a custom kernel (see
section 6 of FreeBSD.FAQ).  The LINT configuration file
(/sys/i386/conf/LINT) also contains prototype entries for just about
every device supported by FreeBSD and is a good general reference.

The device names and a short description of each are listed below. The port
numbers, etc, are not meaningful here since you will need to compile a
custom kernel to gain access to these devices anyway and can thus
adjust the addresses to match the hardware in your computer in the process.
The LINT file contains prototype entries for all of the below which you
can easily cut-and-paste into your own file (or simply copy LINT and edit
it to taste):

ctx:    Cortex-I frame grabber
cx:     Cronyx/Sigma multiport sync/async
cy:     Cyclades high-speed serial driver
el:     3Com 3C501
fea:    DEV DEFEA EISA FDDI adater
fpa:    DEC DEFPA PCI FDDI adapter
gp:     National Instruments AT-GPIB and AT-GPIB/TNT board
gsc:    Genius GS-4500 hand scanner
gus:    Gravis Ultrasound - Ultrasound, Ultrasound 16, Ultrasound MAX
gusxvi: Gravis Ultrasound 16-bit PCM
joy:    Joystick
labpc:  National Instrument's Lab-PC and Lab-PC+
meteor:	Matrox Meteor frame-grabber card
mpu:    Roland MPU-401 stand-alone card
mse:    Logitech & ATI InPort bus mouse ports
mss:    Microsoft Sound System
nic:    Dr Neuhaus NICCY 3008, 3009 & 5000 ISDN cards
opl:    Yamaha OPL-2 and OPL-3 FM - SB, SB Pro, SB 16, ProAudioSpectrum
pas:    ProAudioSpectrum PCM and MIDI
pca:    PCM audio ("/dev/audio") through your PC speaker
psm:    PS/2 mouse port
rc:     RISCom/8 multiport card
sb:     SoundBlaster PCM - SoundBlaster, SB Pro, SB16, ProAudioSpectrum
sbmidi: SoundBlaster 16 MIDI interface
sbxvi:  SoundBlaster 16
spigot: Creative Labs Video Spigot video-acquisition board
uart:   Stand-alone 6850 UART for MIDI
wds:    Western Digital WD7000 IDE

--- end of list ---


4.      Known Hardware Problems, Q & A:
--      -------------------------------

Q: mcd0 keeps thinking that it has found a device and this stops my Intel
   EtherExpress card from working.

A: Use the UserConfig utility (see section 1.0) and disable the probing of
   the mcd0 and mcd1 devices.  Generally speaking, you should only leave
   the devices that you will be using enabled in your kernel.


Q: The system finds my ed network card, but I keep getting device 
   timeout errors.

A: Your card is probably on a different IRQ from what is specified in the
   kernel configuration.  The ed driver does not use the `soft' configuration
   by default (values entered using EZSETUP in DOS), but it will use the
   software configuration if you specify `?' in the IRQ field of your kernel
   config file.  

   Either move the jumper on the card to a hard configuration setting
   (altering the kernel settings if necessary), or specify the IRQ as
   `-1' in UserConfig or `?' in your kernel config file.  This will
   tell the kernel to use the soft configuration.

   Another possibility is that your card is at IRQ 9, which is shared
   by IRQ 2 and frequently a cause of problems (especially when you
   have a VGA card using IRQ 2! :).  You should not use IRQ 2 or 9 if at
   all possible.


Q: I go to boot from the hard disk for the first time after installing
   FreeBSD, but the Boot Manager prompt just prints `F?' at the boot menu
   each time but the boot won't go any further.

A: The hard disk geometry was set incorrectly in the Partition editor when
   you installed FreeBSD.  Go back into the partition editor and specify
   the actual geometry of your hard disk.  You must reinstall FreeBSD
   again from the beginning with the correct geometry.

   If you are failing entirely in figuring out the correct geometry for
   your machine, here's a tip:  Install a small DOS partition at the
   beginning of the disk and install FreeBSD after that.  The install
   program will see the DOS partition and try to infer the correct
   geometry from it, which usually works.

   If you are setting up a truly dedicated FreeBSD server or work-
   station where you don't care for (future) compatibility with DOS,
   Linux or another operating system, you've also got the option to use
   the entire disk (`A' in the partition editor), selecting the
   non-standard option where FreeBSD occupies the entire disk from
   the very first to the very last sector.  This will leave all geometry
   considerations aside, but is somewhat limiting unless you're never
   going to run anything other than FreeBSD on a disk.

Q: I have a Matsushita/Panasonic drive but it isn't recognized by the
   system.

A: Make certain that the I/O port that the matcd driver is set to is
   correct for the host interface card you have.  (Some SoundBlaster DOS
   drivers report a hardware I/O port address for the CD-ROM interface
   that is 0x10 lower than it really is.)

   If you are unable to determine the settings for the card by examining 
   the board or documentation, you can use UserConfig to change the 'port'
   address (I/O port) to -1 and start the system.  This setting causes the
   driver to look at a number of I/O ports that various manufacturers
   use for their Matsushita/Panasonic/Creative CD-ROM interfaces.
   Once the driver locates the address, you should run UserConfig again
   and specify the correct address.  Leaving the 'port' parameter set to -1
   increases the amount of time that it takes the system to boot, and
   this could interfere with other devices.

   The double-speed Matsushita CR-562 and CR-563 are the only drives
   that are supported.
   

Q: I have a Matsushita/Panasonic CR-522, a Matsushita/Panasonic CR-523 or
   a TEAC CD55a drive, but it is not recognized even when the correct I/O
   port is set.

A: These CD-ROM drives are currently not supported by FreeBSD.  The command
   sets for these drives are not compatible with the double-speed CR-562
   and CR-563 drives.
   
   The single-speed CR-522 and CR-523 drives can be identified by their
   use of a CD-caddy. 


Q: I'm trying to install from a tape drive but all I get is something like:
        st0(aha0:1:0) NOT READY csi 40,0,0,0
   on the screen.  Help!

A: There's a limitation in the current sysinstall that the tape MUST
   be in the drive while sysinstall is started or it won't be detected.
   Try again with the tape in the drive the whole time.


Q: I've installed FreeBSD onto my system, but it hangs when booting from 
   the hard drive with the message: ``Changing root to /dev/sd0a''.

A: This problem may occur in a system with a 3com 3c509 ethernet adaptor.
   The ep0 device driver appears to be sensitive to probes for other
   devices that also use address 0x300.  Boot your FreeBSD system by power
   cycling the machine (turn off and on).  At the ``Boot:'' prompt specify
   the ``-c''.  This will invoke UserConfig (see Section 1. above).  Use
   the ``disable'' command to disable the device probes for all devices
   at address 0x300 except the ep0 driver.   On exit, your machine should
   successfully boot FreeBSD.


Q: My system hangs during boot, right after the "fd0: [my floppy drive]"
   line.

A: This is not actually a hang, simply a very LONG "wdc0" probe that
   often takes a long time to complete on certain systems (where there
   usually _isn't_ a WD controller).  Be patient, your system will boot!
   To eliminate the problem, boot with the -c flag and eliminate the wdc0
   device, or compile a custom kernel.

Q: My system can not find my Intel EtherExpress 16 card.

A: You must set your Intel EtherExpress 16 card to be memory mapped at
   address 0xD0000, and set the amount of mapped memory to 32K using
   the Intel supplied softset.exe program.

[ Please add more hardware tips to this Q&A section! ]