Add new documentation.

Submitted by:	Doug

1 files changed, 261 insertions, 0 deletions

diff --git a/release/sysinstall/help/trouble.hlp b/release/sysinstall/help/trouble.hlp
new file mode 100644
index 0000000..62061d9
--- /dev/null
+++ b/release/sysinstall/help/trouble.hlp
@@ -0,0 +1,261 @@
+===============
+Troubleshooting
+===============
+
+Repairing an existing FreeBSD installation
+------------------------------------------
+
+FreeBSD releases 2.2.1 and later feature a "Fixit" option in the top
+menu of the boot floppy.  To use it, you will also need either a
+fixit.flp image floppy, generated in the same fashion as the boot
+floppy, or the 2nd CDROM from Walnut Creek CDROM's FreeBSD
+distribution.
+
+To invoke fixit, simply boot the boot floppy, chose the "Fixit" item
+and insert the fixit floppy or CDROM when asked.  You will then be
+placed into a shell with a wide variety of commands available (in the
+/stand and /mnt2/stand directories) for checking, repairing and
+examining file systems and their contents.  Some UNIX administration
+experience *is* required to use the fixit option!
+
+
+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 HARDWARE.TXT) 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: FreeBSD claims to support the 3Com PCMCIA card, but my card isn't
+   recognized when it's plugged into my laptop.
+
+A: There are a couple of possible problems.  First of all, FreeBSD does
+   not support multi-function cards, so if you have a combo
+   ethernet/modem card (such as the 3C562), it won't work.  The
+   default driver for the 3C589 card was written just like all of the
+   other drivers in FreeBSD, and depend on the card's own configuration
+   data stored in NVRAM to work.  You must correctly configure FreeBSD's
+   driver to match the IRQ, port, and IOMEM stored in NVRAM.
+       Unfortunately, the only program capable of reading them is the
+   3COM supplied DOS program.  This program must be run on a absolutely
+   clean system (no other drivers must be running), and the program will
+   whine about CARD-Services not being found, but it will continue.
+   This is necessary to read the NVRAM values.  You want to know the
+   IRQ, port, and IOMEM values (the latter is called the CIS tuple by
+   3COM).  The first two can be set in the program, the third is
+   un-settable, and can only be read.  Once you have these values, set
+   them in UserConfig and your card will be recognized.
+
+
+Q: FreeBSD finds my PCMCIA network card, but no packets appear to
+   be sent even though it claims to be working.
+
+A: Many PCMCIA cards have the ability to use either the 10-Base2 (BNC)
+   or 10-BaseT connectors for connecting to the network.  The driver is
+   unable to 'auto-select' the correct connector, so you must tell it
+   which connector to use. In order to switch between the two
+   connectors, the link flags must be set.  Depending on the model of
+   the card, '-link0 link1' or 'link0 -link1' will choose the correct
+   network connector.  You can set these in sysinstall by using the
+   'Extra options to ifconfig:' field in the network setup screen.
+
+
+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 booted the install floppy on my IBM ThinkPad (tm) laptop, and the
+   keyboard is all messed up.
+
+A: Older IBM laptops use a non-standard keyboard controller, so you must
+   tell the console driver (sc0) to go into a special mode which works
+   on the ThinkPads.  Change the sc0 'Flags' to 0x10 in UserConfig and
+   it should work fine.  (Look in the Input Menu for 'Syscons Console
+   Driver'.)
+
+
+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.
+
+
+Q: When installing on an EISA HP Netserver, my on-board AIC-7xxx
+   SCSI controller isn't detected.
+
+A: This is a known problem, and will hopefully be fixed in the future.
+   In order to get your system installed at all, boot with the -c
+   option into UserConfig, but _don't_ use the pretty visual mode but
+   the plain old CLI mode.  Type
+
+        eisa 12
+        quit
+
+   there at the prompt.  (Instead of `quit', you might also type
+   `visual', and continue the rest of the configuration session in
+   visual mode.)  While it's recommended to compile a custom kernel,
+   dset(8) now also understands to save this value.
+
+   Refer to the FAQ topic 3.16 for an explanation of the problem, and
+   for how to continue.  Remember that you can find the FAQ on your
+   local system in /usr/share/doc/FAQ, provided you have installed the
+   `doc' distribution.
+
+
+Q: I have a Panasonic AL-N1 or Rios Chandler Pentium machine and I find
+   that the system hangs before ever getting into the installation
+   now.
+
+A: Your machine doesn't like the new i586_copyout and i586_copyin code
+   for some reason.  To disable this, boot the installation boot floppy
+   and when it comes to the very first menu (the choice to drop into
+   kernel UserConfig mode or not) choose the command-line interface
+   ("expert mode") version and type the following at it:
+
+        flags npx0 1
+
+   Then proceed normally to boot.  This will be saved into your kernel,
+   so you only need to do it once.
+
+
+Q: I have this CMD640 IDE controller that is said to be broken.
+
+A: Yes, it is.  There's a workaround available now and it is enabled
+   automatically if this chip is used on your system.
+   For the details refer to the manual page of the disk driver (man 4 wd).
+
+
+Q: On a Compaq Aero notebook, I get the message "No floppy devices found!
+   Please check ..." when trying to install from floppy.
+
+A: With Compaq being always a little different from other systems, they
+   do not announce their floppy drive in the CMOS RAM of an Aero notebook.
+   Therefore, the floppy disk driver assumes there is no drive configured.
+   Go to the UserConfig screen, and set the Flags value of the fdc0 device
+   to 0x1.  This pretends the existance of the first floppy drive (as a
+   1.44 MB drive) to the driver without asking the CMOS at all.
+
+
+Q: When I go to boot my Intel AL440LX ("Atlanta") -based system from the
+   hard disk the first time, it stops with a "Read Error" message.
+
+A: There appears to be a bug in the BIOS on at least some of these boards,
+   this bug results in the FreeBSD bootloader thinking that it is booting
+   from a floppy disk.
+   This is only a problem if you are not using the BootEasy boot manager.
+   Slice the disk in 'compatible' mode and install BootEasy during the
+   FreeBSD installation to avoid the bug.
+
+[ Please add more hardware tips to this Q&A section! ]