os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

New sections added: release notes, installation, kernel debugging.

Browse source 
Numerous other edits.  Empty sections now have an * in the section header.
This commit is contained in:
John Fieber 1995-06-14 18:38:56 +00:00
parent 7a5f061be2
commit 063fd33c0b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=15
9 changed files with 1664 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
handbook/authors.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: authors.sgml,v 1.3 1995-05-18 03:05:00 jfieber Exp $ -->
<!-- $Id: authors.sgml,v 1.4 1995-06-14 18:38:47 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
@ -21,4 +21,5 @@ entities when referencing people.
<!ENTITY a.martin "Martin Renters <tt>&lt;martin@innovus.com&gt;</tt>">
<!ENTITY a.md "Mark Dapoz <tt>&lt;md@bsc.no&gt;</tt>">
<!ENTITY a.phk "Poul-Henning Kamp <tt>&lt;phk@FreeBSD.org&gt;</tt>">
<!ENTITY a.paul "Paul Richards <tt>&lt;paul@FreeBSD.org&gt;</tt>">
<!ENTITY a.wilko "Wilko Bulte <tt>&lt;wilko@yedi.iaf.nl&gt;</tt>">

27
handbook/basics.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: basics.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- $Id: basics.sgml,v 1.2 1995-06-14 18:38:49 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Unix Basics</heading>
@ -14,13 +14,13 @@
<tt><bf>man</bf></tt> command. Use of the
<tt><bf>man</bf></tt> command is simple:
<tscreen>
<tt><bf>man</bf> <it>command</it></tt>
<bf>man</bf> <it>command</it>
</tscreen>
where <it>command</it> is the name of the command
you wish to find. For example, to learn more about
you wish to learn about. For example, to learn more about
<tt><bf>ls</bf></tt> command type:
<tscreen>
<tt><bf>man</bf> ls</tt>
% <bf>man ls</bf>
</tscreen>
<p>The online manual is divided up into numbered
@ -42,7 +42,7 @@
you can tell the <tt><bf>man</bf></tt> command which
you want by specifying the section:
<tscreen>
<tt><bf>man</bf> 1 chmod</tt>
% <bf>man 1 chmod</bf>
</tscreen>
which will display the manual page for the user command
<tt><bf>chmod</bf></tt>.
@ -50,10 +50,10 @@
<p>This is fine if you know the name of the command and
forgot how to use it, but what if you cannot recall the
command name? You can use <tt><bf>man</bf></tt> to
search through the command <em>descriptions</em> by
search for keywords in the command <em>descriptions</em> by
using the <tt><bf>-k</bf></tt> switch:
<tscreen>
<tt><bf>man</bf> -k mail</tt>
% <bf>man -k mail</bf>
</tscreen>
With this command you will be presented with a list of
commands that have the keyword `mail' in their
@ -65,9 +65,14 @@
<p>FreeBSD includes many applications and utilities
produced by the Free Software Foundation (FSF). In
addition to man pages, these programs come with more
extensive <em>info</em> files which can be viewed with
the <tt>info</tt> command or, if you installed
<tt>emacs</tt>, the info mode of <tt>emacs</tt>.
extensive hypertext documents called <em>info</em>
files which can be viewed with the <tt>info</tt>
command or, if you installed <tt>emacs</tt>, the info
mode of <tt>emacs</tt>.
To use the <tt>info(1)</tt> command, simply type:
<tscreen>% <bf>info</bf></tscreen> For a brief
introduction, type <tt><bf>h</bf></tt>, and for a quick
command reference, type <tt><bf>?</bf></tt>.
</sect>

4
handbook/booting.sgml
View file

@ -3,7 +3,7 @@
This conversion has been made by Ollivier Robert.
$Id: booting.sgml,v 1.2 1995-05-10 11:34:06 jfieber Exp $
$Id: booting.sgml,v 1.3 1995-06-14 18:38:50 jfieber Exp $
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
@ -22,7 +22,7 @@
<toc>
-->
<chapt><heading>Booting FreeBSD on a PC</heading>
<chapt><heading>The FreeBSD Booting Process</heading>
<p><em>Contributed by &a.phk;. v1.1, April 26th.</em>

4
handbook/glossary.sgml
View file

@ -1,5 +1,5 @@
<!-- $Id: glossary.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- $Id: glossary.sgml,v 1.2 1995-06-14 18:38:51 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Glossary</heading>
<chapt><heading>* Glossary</heading>

101
handbook/handbook.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: handbook.sgml,v 1.7 1995-05-18 03:05:08 jfieber Exp $ -->
<!-- $Id: handbook.sgml,v 1.8 1995-06-14 18:38:52 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@ -15,13 +15,18 @@
<!ENTITY eresources SYSTEM "eresources.sgml">
<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY history SYSTEM "history.sgml">
<!ENTITY hw SYSTEM "hw.sgml">
<!ENTITY install SYSTEM "install.sgml">
<!ENTITY kerberos SYSTEM "kerberos.sgml">
<!ENTITY kernelconfig SYSTEM "kernelconfig.sgml">
<!ENTITY kerneldebug SYSTEM "kerneldebug.sgml">
<!ENTITY memoryuse SYSTEM "memoryuse.sgml">
<!ENTITY nfs SYSTEM "nfs.sgml">
<!ENTITY nutshell SYSTEM "nutshell.sgml">
<!ENTITY porting SYSTEM "porting.sgml">
<!ENTITY ports SYSTEM "ports.sgml">
<!ENTITY ppp SYSTEM "ppp.sgml">
<!ENTITY relnotes SYSTEM "relnotes.sgml">
<!ENTITY scsi SYSTEM "scsi.sgml">
<!ENTITY slipc SYSTEM "slipc.sgml">
<!ENTITY slips SYSTEM "slips.sgml">
@ -55,10 +60,11 @@ OUTLINE:
<author>
<name>The FreeBSD Documentation Project</name>
</author>
<date>May 17, 1995</date>
<date>June 14, 1995</date>
<abstract>Welcome to FreeBSD! This handbook covers the
installation and day to day use of FreeBSD.
installation and day to day use of <bf>FreeBSD Release
2.0.5</bf>.
This manual is a <bf>work in progress</bf> and is the
work of many individials. Many sections do not yet exist
@ -77,26 +83,14 @@ OUTLINE:
<chapt><heading>Introduction</heading>
&nutshell;
&history;
<sect><heading>About this release</heading>
<sect><heading>FreeBSD now and in the future</heading>
<chapt><heading>Installing FreeBSD</heading>
<sect><heading>Preparing for the installation</heading>
<sect1><heading>Hardware checklist</heading>
<sect2><heading>minimal requirements</heading>
<sect2><heading>IRQs, IO Addresses, and DMA channels</heading>
<sect1><heading>Software checklist</heading>
<sect2><heading>Making the installation floppies</heading>
<sect2><heading>CD-ROM</heading>
<sect2><heading>Tape</heading>
<sect2><heading>Disk</heading>
<sect><heading>Installation</heading>
<sect><heading>Set up a user account</heading>
&relnotes;
<sect><heading>* FreeBSD now and in the future</heading>
&install;
&basics;
<chapt><heading>Installing applications</heading>
<sect><heading>Installing packages</heading>
<sect><heading>* Installing packages</heading>
&ports;
&porting;
@ -104,65 +98,36 @@ OUTLINE:
<part><heading>System Administration</heading>
<chapt><heading>Reconfiguring the kernel</heading>
<chapt><heading>Reconfiguring the Kernel<label id="kernelconfig:"></heading>
<!-- &kernelconfig; -->
<chapt><heading>Users, groups and security</heading>
<sect><heading>DES, MD5 and Crypt</heading>
<sect><heading>* DES, MD5 and Crypt</heading>
<sect><heading>* S/Key</heading>
&kerberos;
<sect><heading>S/Key</heading>
<sect><heading>Firewalls</heading>
<sect><heading>* Firewalls</heading>
<chapt><heading>The X-Window System</heading>
<chapt><heading>* Printing</heading>
<chapt><heading>Printing</heading>
<chapt><heading>* The X-Window System</heading>
<chapt><heading>Managing hardware</heading>
&scsi;
<sect><heading>adding/reconfiguring disks</heading>
<sect><heading>tapes and backups</heading>
<sect><heading>serial ports</heading>
<sect><heading>sound cards</heading>
<sect><heading>* Adding and reconfiguring disks</heading>
<sect><heading>* Tapes and backups</heading>
<sect><heading>* Serial ports</heading>
<sect><heading>* Sound cards</heading>
<chapt><heading>PC Hardware compatibility</heading>
<sect><heading>CORE/PROCESSING</heading>
<sect1><heading>Motherboards</heading>
<sect2><heading>ISA</heading>
<sect2><heading>EISA</heading>
<sect2><heading>VLB</heading>
<sect2><heading>PCI</heading>
<sect1><heading>CPUs/FPUs</heading>
<sect1><heading>Memory</heading>
<sect1><heading>BIOS</heading>
<sect><heading>INPUT/OUTPUT</heading>
<sect1><heading>Video cards</heading>
<sect1><heading>Sound cards</heading>
<sect1><heading>Serial ports (including multiport cards)</heading>
<sect1><heading>Parallel ports</heading>
<sect1><heading>Modems</heading>
<sect1><heading>Etherenet cards</heading>
<sect1><heading>Keyboards</heading>
<sect1><heading>Mice</heading>
<sect1><heading>Other (joysticks? tablets?)</heading>
<sect><heading>STORAGE</heading>
<sect1><heading>Disk/tape controllers</heading>
<sect2><heading>SCSI</heading>
<sect2><heading>IDE</heading>
<sect2><heading>Floppy</heading>
<sect1><heading>Hard drives</heading>
<sect1><heading>Tape drives</heading>
<sect1><heading>CD-ROM drives</heading>
<sect1><heading>Other</heading>
<sect><heading>OTHER</heading>
<sect1><heading>PCMCIA</heading>
&hw;
<!-- ************************************************************ -->
<part><heading>Network Communications</heading>
<chapt><heading>Basic Networking</heading>
<sect><heading>Ethernet basics</heading>
<sect><heading>Serial basics</heading>
<sect><heading>Hardwired Terminals</heading>
<sect><heading>* Ethernet basics</heading>
<sect><heading>* Serial basics</heading>
<sect><heading>* Hardwired Terminals</heading>
&dialup;
<chapt><heading>PPP and SLIP</heading>
@ -171,13 +136,13 @@ OUTLINE:
&slips;
<chapt><heading>Advanced networking</heading>
<sect><heading>Gateways and routing</heading>
<sect><heading>* Gateways and routing</heading>
&nfs;
<sect><heading>Yellow Pages/NIS</heading>
<sect><heading>* Yellow Pages/NIS</heading>
&diskless;
<sect><heading>ISDN</heading>
<sect><heading>* ISDN</heading>
<chapt><heading>Mail</heading>
<chapt><heading>* Mail</heading>
@ -187,7 +152,7 @@ OUTLINE:
&current;
&ctm;
&sup;
<chapt><heading>Kernel debugging</heading>
&kerneldebug;
&submitters;
&booting;
&memoryuse;

45
handbook/hw.sgml Normal file
View file

@ -0,0 +1,45 @@
<!-- $Id: hw.sgml,v 1.1 1995-06-14 18:38:53 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>* PC Hardware compatibility<label id="hw:"></heading>
<sect><heading>* Core/Processing<label id="hw:core"></heading>
<sect1><heading>* Motherboards</heading>
<sect2><heading>* ISA</heading>
<sect2><heading>* EISA</heading>
<sect2><heading>* VLB</heading>
<sect2><heading>* PCI</heading>
<sect1><heading>* CPUs/FPUs</heading>
<sect1><heading>* Memory</heading>
<sect1><heading>* BIOS</heading>
<sect><heading>* Input/Output Devices<label id="hw:io"></heading>
<sect1><heading>* Video cards</heading>
<sect1><heading>* Sound cards</heading>
<sect1><heading>* Serial ports (including multiport cards)</heading>
<sect1><heading>* Parallel ports</heading>
<sect1><heading>* Modems</heading>
<sect1><heading>* Network cards</heading>
<sect1><heading>* Keyboards</heading>
<sect1><heading>* Mice</heading>
<sect1><heading>* Other</heading>
<sect><heading>* Storage Devices<label id="hw:storage"></heading>
<sect1><heading>* Disk/tape controllers</heading>
<sect2><heading>* SCSI</heading>
<sect2><heading>* IDE</heading>
<sect2><heading>* Floppy</heading>
<sect1><heading>* Hard drives</heading>
<sect1><heading>* Tape drives</heading>
<sect1><heading>* CD-ROM drives</heading>
<sect1><heading>* Other</heading>
<sect><heading>* Other<label id="hw:other"></heading>
<sect1><heading>* PCMCIA</heading>

638
handbook/install.sgml Normal file
View file

@ -0,0 +1,638 @@
<!-- $Id: install.sgml,v 1.1 1995-06-14 18:38:54 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
<!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'>
-->
<chapt><heading>Installing FreeBSD</heading>
<sect>MS-DOS user's Questions and Answers
<p><bf>Help! I have no space! Do I need to delete
everything first?</bf>
If your machine is already running MS-DOS and has little
or no free space available for FreeBSD's installation,
all is not lost! You may find the FIPS utility, provided
in the <tt>tools</tt> directory on the FreeBSD CDROM or
on the various FreeBSD ftp sites, to be quite useful.
FIPS allows you to split an existing MS-DOS partition
into two pieces, preserving the original partition and
allowing you to install onto the second free piece. You
first defragment your MS-DOS partition, using the DOS
6.xx DEFRAG utility or the Norton Disk tools, then run
FIPS. It will prompt you for the rest of the information
it needs. Afterwards, you can reboot and install FreeBSD
on the new free slice. See the <em>Distributions</em>
menu for an estimation of how much free space you'll need
for the kind of installation you want.
<bf>Can I use compressed MS-DOS filesystems from
FreeBSD?</bf>
No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use
whatever portion of the filesystem you leave
uncompressed. The rest of the filesystem will show up as
one large file (the stacked/dblspaced file!). <bf>Do not
remove that file!</bf> You will probably regret it
greatly!
It is probably better to create another uncompressed
MS-DOS primary partition and use this for communications
between MS-DOS and FreeBSD.
<bf>Can I mount my MS-DOS extended partitions?</bf>
This feature isn't in FreeBSD 2.0.5 but should be in 2.1.
We've laid all the groundwork for making this happen, now
we just need to do the last 1 percent of the work involved.
<bf>Can I run MS-DOS binaries under FreeBSD?</bf>
Not yet! We'd like to add support for this someday, but
are still lacking anyone to actually do the work.
Ongoing work with Linux's PCEMU utility may bring this
much closer to being a reality sometime soon. Send mail
to hackers@freebsd.org if you're interested in joining
this effort!
<sect>Supported Configurations
<p>FreeBSD currently runs on a wide variety of ISA, VLB,
EISA and PCI bus based PC's, ranging from 386sx to
Pentium class machines (though the 386sx is not
recommended). Support for generic IDE or ESDI drive
configurations, various SCSI controller, network and
serial cards is also provided.
Following is a list of all disk controllers and ethernet
cards currently known to work with FreeBSD. Other
configurations may very well work, and we have simply not
received any indication of this.
<sect1>Disk Controllers
<p>
<itemize>
<item>WD1003 (any generic MFM/RLL)
<item>WD1007 (any generic IDE/ESDI)
<item>WD7000
<item>IDE
<item>ATA
<item>Adaptec 152x series ISA SCSI controllers
<item>Adaptec 154x series ISA SCSI controllers
<item>Adaptec 174x series EISA SCSI controller in
standard and enhanced mode.
<item>Adaptec 274X/284X/2940 (Narrow/Wide/Twin)
series ISA/EISA/PCI SCSI controllers
<item>Adaptec AIC-6260 and AIC-6360 based boards,
which includes the AHA-152x and SoundBlaster SCSI
cards.
<bf>Note:</bf> You cannot boot from the
SoundBlaster cards as they have no on-board BIOS,
which is necessary for mapping the boot device into
the system BIOS I/O vectors. They are perfectly
usable for external tapes, CDROMs, etc, however.
The same goes for any other AIC-6x60 based card
without a boot ROM. Some systems DO have a boot
ROM, which is generally indicated by some sort of
message when the system is first powered up or
reset. Check your system/board documentation for
more details.
<item>Buslogic 545S &amp; 545c
<bf>Note:</bf> that Buslogic was formerly known as "Bustec".
<item>Buslogic 445S/445c VLB SCSI controller
<item>Buslogic 742A, 747S, 747c EISA SCSI controller.
<item>Buslogic 946c PCI SCSI controller
<item>Buslogic 956c PCI SCSI controller
<item>NCR 53C810 and 53C825 PCI SCSI controller.
<item>NCR5380/NCR53400 ("ProAudio Spectrum") SCSI controller.
<item>DTC 3290 EISA SCSI controller in 1542 emulation mode.
<item>UltraStor 14F, 24F and 34F SCSI controllers.
<item>Seagate ST01/02 SCSI controllers.
<item>Future Domain 8xx/950 series SCSI controllers.
</itemize>
With all supported SCSI controllers, full support is
provided for SCSI-I &amp; SCSI-II peripherals,
including Disks, tape drives (including DAT) and CD ROM
drives.
The following CD-ROM type systems are supported at this
time:
<itemize>
<item>SCSI (also includes ProAudio Spectrum and
SoundBlaster SCSI) (cd)
<item>Mitsumi proprietary interface (mcd)
<item>Matsushita/Panasonic (Creative) proprietary
interface (matcd)
<item>Sony proprietary interface (scd)
</itemize>
<bf>Note:</bf> CD-Drives with IDE interfaces are not
supported at this time.
Some controllers have limitations with the way they
deal with &gt;16MB of memory, due to the fact that the
ISA bus only has a DMA address space of 24 bits. If
you do your arithmetic, you'll see that this makes it
impossible to do direct DMA to any address &gt;16MB.
This limitation is even true of some EISA controllers
(which are normally 32 bit) when they're configured to
emulate an ISA card, which they then do in *all*
respects. This problem is avoided entirely by IDE
controllers (which do not use DMA), true EISA
controllers (like the UltraStor, Adaptec 1742A or
Adaptec 2742) and most VLB (local bus) controllers. In
the cases where it's necessary, the system will use
"bounce buffers" to talk to the controller so that you
can still use more than 16Mb of memory without
difficulty.
<sect1>Ethernet cards
<p>
<itemize>
<item>SMC Elite 16 WD8013 ethernet interface, and
most other WD8003E, WD8003EBT, WD8003W, WD8013W,
WD8003S, WD8003SBT and WD8013EBT based clones. SMC
Elite Ultra is also supported.
<item>DEC EtherWORKS III NICs (DE203, DE204, and DE205)
<item>DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422)
<item>DEC DC21140 based NICs (SMC???? DE???)
<item>DEC FDDI (DEFPA/DEFEA) NICs
<item>Fujitsu MB86960A family of NICs
<item>Intel EtherExpress
<item>Isolan AT 4141-0 (16 bit)
<item>Isolink 4110 (8 bit)
<item>Novell NE1000, NE2000, and NE2100 ethernet interface.
<item>3Com 3C501 cards
<item>3Com 3C503 Etherlink II
<item>3Com 3c505 Etherlink/+
<item>3Com 3C507 Etherlink 16/TP
<item>3Com 3C509, 3C579, 3C589 (PCMCIA) Etherlink III
<item>Toshiba ethernet cards
<item>PCMCIA ethernet cards from IBM and National
Semiconductor are also supported.
</itemize>
<sect1>Misc
<p>
<itemize>
<item>AST 4 port serial card using shared IRQ.
<item>ARNET 8 port serial card using shared IRQ.
<item>BOCA ATIO66 6 port serial card using shared IRQ.
<item>Cyclades Cyclom-y Serial Board.
<item>STB 4 port card using shared IRQ.
<item>Mitsumi (all models) CDROM interface and drive.
<item>SDL Communications Riscom/8 Serial Board.
<item>Soundblaster SCSI and ProAudio Spectrum SCSI
CDROM interface and drive.
<item>Matsushita/Panasonic (Creative SoundBlaster)
CDROM interface and drive.
<item>Adlib, SoundBlaster, SoundBlaster Pro,
ProAudioSpectrum, Gravis UltraSound and Roland
MPU-401 sound cards.
</itemize>
FreeBSD currently does NOT support IBM's microchannel
(MCA) bus, but support is apparently close to
materializing. Details will be posted as the situation
develops.
<sect>Preparing for the installation</heading>
<p>There are a number of different methods by which FreeBSD
can be installed. The following describes what
preparation needs to be done for each type.
<sect1>Before installing from CDROM
<p>If your CDROM is of an unsupported type, such as an
IDE CDROM, then please skip to section 2.3: MS-DOS
Preparation.
There is not a lot of preparatory work that needs to be
done to successfully install from one of Walnut Creek's
FreeBSD CDROMs (other CDROM distributions may work as
well, but I can't say for sure as I have no hand or say
in their creation). You can either boot into the CD
installation directly from MS-DOS using Walnut Creek's
supplied "install" batch file or you can make a boot
floppy by writing the supplied image
(floppies/boot.flp) onto a floppy with the "go"
command, which invokes the rawrite.exe command found in
the tools/ subdirectory.
If you're creating the boot floppy from a UNIX machine,
you may find that ``dd if=floppies/boot.flp
of=/dev/rfd0'' or ``dd if=floppies/boot.flp
of=/dev/floppy'' works well, depending on your hardware
and operating system environment.
Once you've booted from MS-DOS or floppy, you should be
able to select CDROM as the media type in the Media
menu and load the entire distribution from CDROM. No
other types of installation media should be required.
After your system is fully installed and you have
rebooted from the hard disk, you should find the CD
mounted on the directory /cdrom. A utility called
`lndir' comes with the XFree86 distribution which you
may also find useful: It allows you to create "link
tree" directories to things on Read-Only media like
CDROM. One example might be something like this:
<tscreen>mkdir /usr/ports<newline>lndir /cdrom/ports
/usr/ports</tscreen>
Which would allow you to then "cd /usr/ports; make" and
get all the sources from the CD, but yet create all the
intermediate files in /usr/ports, which is presumably
on a more writable media!
<sect1>Before installing from Floppy</heading>
<p>If you must install from floppy disks, either due to
unsupported hardware or just because you enjoy doing
things the hard way, you must first prepare some
floppies for the install.
The first floppy you'll need is ``floppies/root.flp'',
which is somewhat special in that it's not a MS-DOS
filesystem floppy at all, but rather an "image" floppy
(it's actually a gzip'd cpio file). You can use the
rawrite.exe program to do this under DOS, or ``dd'' to
do it on a UNIX Workstation (see notes in section 2.1
concerning the ``floppies/boot.flp'' image). Once this
floppy is made, put it aside. You'll be asked for it
later.
You will also need, at minimum, as many 1.44MB or 1.2MB
floppies as it takes to hold all files in the bin
(binary distribution) directory. THESE floppies *must*
be formatted using MS-DOS, using with the FORMAT
command in MS-DOS or the File Manager format command in
Microsoft Windows(tm). Factory preformatted floppies
will also work well, provided that they haven't been
previously used for something else.
Many problems reported by our users in the past have
resulted from the use of improperly formatted media, so
we simply take special care to mention it here!
After you've MS-DOS formatted the floppies, you'll need
to copy the files onto them. The distribution files
are split into chunks conveniently sized so that 5 of
them will fit on a conventional 1.44MB floppy. Go
through all your floppies, packing as many files as
will fit on each one, until you've got all the
distributions you want packed up in this fashion.
Select ``Floppy'' from the Media menu at installation
time and you will be prompted for everything after
that.
<sect1>Before installing from a MS-DOS partition</heading>
<p>To prepare for installation from an MS-DOS partition,
you should simply copy the files from the distribution
into a directory called "FREEBSD". For example, to do
a minimal installation of FreeBSD from DOS using files
copied from the CDROM, you might do something like
this: <tscreen> C> MD C:\FREEBSD<newline> C> XCOPY /S
E:\DISTS\BIN C:\FREEBSD<newline> C> XCOPY /S
E:\FLOPPIES C:\FREEBSD</tscreen>
Asssuming that `C:' was where you had free space and
`E:' was where your CD was mounted. Note that you need
the FLOPPIES directory because the `root.flp' image is
automatically looked for there when you're doing a
MS-DOS installation.
For as many `DISTS' you wish to install from MS-DOS
(and you have free space for), install each one under
`C:\FREEBSD' - the BIN dist is only the minimal
requirement.
<sect1>Before installing from QIC/SCSI Tape</heading>
<p>Installing from tape is probably the easiest method,
short of an on-line install using FTP or a CDROM
instal. The installation program expects the files to
be simply tar'ed onto the tape, so after getting all of
the files for distribution you're interested in, simply
tar them onto the tape with a command like:
<tscreen>
cd /freebsd/distdir<newline>
tar cvf /dev/rwt0 (or /dev/rst0) dist1 .. dist2
</tscreen>
Make sure that the `floppies/' directory is one of the
"dists" given above, since the installation will look
for `floppies/root.flp' on the tape.
When you go to do the installation, you should also
make sure that you leave enough room in some temporary
directory (which you'll be allowed to choose) to
accommodate the FULL contents of the tape you've
created. Due to the non-random access nature of tapes,
this method of installation requires quite a bit of
temporary storage! You should expect to require as
much temporary storage as you have stuff written on
tape.
<sect1>Before installing over a network</heading>
<p>You can do network installations over 3 types of
communications links:
<descrip>
<tag>Serial port</tag> SLIP or PPP <tag>Parallel
port</tag> PLIP (laplink cable) <tag>Ethernet</tag> A
standard ethernet controller (includes some PCMCIA).
</descrip>
SLIP support is rather primitive, and limited primarily
to hard-wired links, such as a serial cable running
between a laptop computer and another computer. The link
should be hard-wired as the SLIP installation doesn't
currently offer a dialing capability; that facility is
provided with the PPP utility, which should be used in
preference to SLIP whenever possible.
If you're using a modem, then PPP is almost certainly
your only choice. Make sure that you have your service
provider's information handy as you'll need to know it
fairly soon in the installation process. You will need
to know, at the minimum, your service provider's IP
address and possibly your own (though you can also leave
it blank and allow PPP to negotiate it with your ISP).
You also need to know how to use the various "AT
commands" to dial the ISP with your particular modem as
the PPP dialer provides only a very simple terminal
emulator.
If a hard-wired connection to another FreeBSD (2.0R or
later) machine is available, you might also consider
installing over a "laplink" parallel port cable. The
data rate over the parallel port is much higher than is
what's typically possible over a serial line (up to
50k/sec), thus resulting in a quicker installation.
Finally, for the fastest possible network installation,
an ethernet adaptor is always a good choice! FreeBSD
supports most common PC ethernet cards, a table of
supported cards (and their required settings) provided as
part of the FreeBSD Hardware Guide - see the
Documentation menu on the boot floppy. If you are using
one of the supported PCMCIA ethernet cards, also be sure
that it's plugged in _before_ the laptop is powered on!
FreeBSD does not, unfortunately, currently support "hot
insertion" of PCMCIA cards.
You will also need to know your IP address on the
network, the "netmask" value for your address class and
the name of your machine. Your system administrator can
tell you which values to use for your particular network
setup. If you will be referring to other hosts by name
rather than IP address, you'll also need a name server
and possibly the address of a gateway (if you're using
PPP, it's your provider's IP address) to use in talking
to it. If you do not know the answers to all or most of
these questions, then you should really probably talk to
your system administrator _first_ before trying this type
of installation!
Once you have a network link of some sort working, the
installation can continue over NFS or FTP.
<sect2>Preparing for NFS installation
<p>NFS installation is fairly straight-forward: Simply
copy the FreeBSD distribution files you're interested
onto a server somewhere and then point the NFS media
selection at it.
If this server supports only "privileged port" access
(as is generally the default for Sun workstations),
you will need to set this option in the Options menu
before installation can proceed.
If you have a poor quality ethernet card which
suffers from very slow transfer rates, you may also
wish to toggle the appropriate Options flag.
In order for NFS installation to work, the server
must support "subdir mounts", e.g. if your FreeBSD
2.0.5 distribution directory lives on:
ziggy:/usr/archive/stuff/FreeBSD Then ziggy will have
to allow the direct mounting of
/usr/archive/stuff/FreeBSD, not just /usr or
/usr/archive/stuff.
In FreeBSD's /etc/exports file, this is controlled by
the ``-alldirs'' option. Other NFS servers may have
different conventions. If you are getting
`Permission Denied' messages from the server then
it's likely that you don't have this enabled
properly!
<sect2>Preparing for FTP Installation
<p>FTP installation may be done from any mirror site
containing a reasonably up-to-date version of FreeBSD
2.0.5, a full menu of reasonable choices from almost
anywhere in the world being provided by the FTP site
menu.
If you are installing from some other FTP site not
listed in this menu, or you are having troubles
getting your name server configured properly, you can
also specify your own URL by selecting the ``Other''
choice in that menu. A URL can also be a direct IP
address, so the following would work in the absence
of a name server: <tscreen>
ftp://192.216.222.4/pub/FreeBSD/2.0.5-RELEASE</tscreen>
<em><bf>NOTE:</bf> Substitute "ALPHA" for "RELEASE"
during the ALPHA test period!</em>
If you are installing through a firewall then you
should probably select ``Passive mode'' ftp, which is
the default. If you are talking to a server which
does not support passive mode for some reason, see
the Options menu to select Active mode transfers.
<sect>Installing FreeBSD
<p>Once you've taken note of the appropriate
preinstallation steps, you should be able to install
FreeBSD without any further trouble.
Should this not be true, then you may wish to go back and
re-read the relevant preparation section (section 2.x)
for the installation media type you're trying to use -
perhaps there's a helpful hint there that you missed the
first time? If you're having hardware trouble, or
FreeBSD refuses to boot at all, read the Hardware Guide
provided on the boot floppy for a list of possible
solutions.
The FreeBSD boot floppy contains all the on-line
documentation you should need to be able to navigate
through an installation and if it doesn't then I'd like
to know what you found most confusing! It is the
objective of the FreeBSD installation program
(sysinstall) to be self-documenting enough that painful
"step-by-step" guides are no longer necessary. It may
take us a little while to reach that objective, but
that's the objective!
Meanwhile, you may also find the following "typical
installation sequence" to be helpful:
<enum>
<item>Boot the boot floppy. After a boot sequence
which can take anywhere from from 30 seconds to 3
minutes, depending on your hardware, you should be
presented with a menu of initial choices. If the
floppy doesn't boot at all, or the boot hangs at some
stage, go read the Q&amp;A section of the Hardware Guide
for possible causes.
<item>Press F1. You should see some basic usage
instructions on the menu system and general
navigation. If you haven't used this menu system
before then PLEASE read this thoroughly!
<item>If English is not your native language, you may
wish to proceed directly to the Language option and
set your preferred language. This will bring up some
of the documentation in that language instead of
english.
<item>Select the Options item and set any special
preferences you may have.
<item>Select Proceed, bringing you to the Installation Menu.
</enum>
<sect1>The installation menu
<p>You can do anything you like in this menu without
altering your system <em>except</em> for "Commit",
which will perform any requests to alter your system
you may have made.
If you're confused at any point, the F1 key usually
pulls up the right information for the screen you're
in.
<enum>
<item>The first step is generally `Partition', which
allows you to chose how your drives will be used
for FreeBSD.
<item>Next, with the `Label' editor, you can specify
how the space in any allocated FreeBSD partitions
should be used by FreeBSD, or where to mount a
non-FreeBSD partition (such as DOS).
<item>Next, the `Distributions' menu allows you to
specify which parts of FreeBSD you wish to load. A
good choice is "User" for a small system or
"Developer" for someone wanting a bit more out of
FreeBSD. If none of the existing collections sound
applicable, select Custom.
<item>Next, the `Media' menu allows you to specify
what kind of media you wish to install from. If a
desired media choice is found and configured
automatically then this menu will simply return,
otherwise you'll be asked for additional details on
the media device type.
<item>Finally, the Commit command will actually
perform all the actions at once (nothing has been
written to your disk so far, nor will it until you
give the final confirmation). All new or changed
partition information will be written out, file
systems will be created and/or non-destructively
labelled (depending on how you set their newfs
flags in the Label editor) and all selected
distributions will be extracted.
<item>The Configure menu choice allows you to furthur
configure your FreeBSD installation by giving you
menu-driven access to various system defaults.
Some items, like networking, may be especially
important if you did a CDROM/Tape/Floppy
installation and have not yet configured your
network interfaces (assuming you have some).
Properly configuring your network here will allow
FreeBSD to come up on the network when you first
reboot from the hard disk.
<item>Exit returns you to the top menu.
</enum>
At this point, you're generally done with the
sysinstall utility and can select the final `Quit'. If
you're running it as an installer (e.g. before the
system is all the way up) then the system will now
reboot. If you selected the boot manager option, you
will see a small boot menu with an `F?' prompt. Press
the function key for BSD (it will be shown) and you
should boot up into FreeBSD off the hard disk.
If this fails to happen for some reason, see the Q&amp;A
section of the Hardware Guide for possible clues!

423
handbook/kerneldebug.sgml Normal file
View file

@ -0,0 +1,423 @@
<!-- $Id: kerneldebug.sgml,v 1.1 1995-06-14 18:38:55 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
<!ENTITY % authors SYSTEM "authors.sgml">
%authors;
]>
-->
<chapt><heading>Kernel Debugging</heading>
<p><em>Contributed by &a.paul; and &a.joerg;</em>
<sect><heading>Debugging a kernel crash dump with kgdb</heading>
<p>Here are some instructions for getting kernel debugging
working on a crash dump, it assumes that you have enough swap
space for a crash dump. If you happen to have multiple swap
partitions with the first one being too small to keep the dump,
you can configure your kernel to use an alternate dump device
(in the <tt>kernel</tt> line). Dumps to non-swap devices,
tapes for example, are currently not supported. Config your
kernel using <tt>config -g</tt>.
<!-- XXX obsolete?
Remember that you need to
specify
<tscreen><verb>
options DODUMP
</verb></tscreen>
in your config file in order to get kernel core dumps.
-->
See <ref id="kernelconfig:" name="Kernel Configuration"> for
details on configuring the FreeBSD kernel.
<em><bf>Note:</bf> In the following, the term `<tt>kgdb</tt>' refers
to <tt>gdb</tt> run in `kernel debug mode'. This can be accomplished by
either starting the <tt>gdb</tt> with the option <tt>-k</tt>, or by linking
and starting it under the name <tt>kgdb</tt>. This is not being
done by default, however.</em>
When the kernel has been built make a copy of it, say
<tt>kernel.debug</tt>, and then run <tt>strip -x</tt> on the
original. Install the original as normal. You may also install
the unstripped kernel, but symbol table lookup time for some
programs might drastically increase.
If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different
one in order to get your system up and running again, boot it
only into single user state using the <tt>-s</tt> flag at the
boot prompt, and then perform the following steps:
<tscreen><verb>
fsck -p
mount -a -t ufs # so your file system for /var/crash is writable
savecore -N /kernel.panicked /var/crash
exit # ...to multi-user
</verb></tscreen>
This instructs <tt>savecore(8)</tt> to use another kernel for symbol name
extraction. It would otherwise default to the currently running kernel.
Now, after a crash dump, go to <tt>/sys/compile/WHATEVER</tt> and run
<tt>kgdb</tt>. From <tt>kgdb</tt> do:
<tscreen><verb>
symbol-file kernel.debug
exec-file /var/crash/system.0
core-file /var/crash/ram.0
</verb></tscreen>
and voila, you can debug the crash dump using the kernel sources
just like you can for any other program.
If your kernel panicked due to a trap, perhaps the most common
case for getting a core dump, the following trick might help
you. Examine the stack using <tt>kgdb</tt>'s `where' command,
and look for the stack frame in the function <tt>trap()</tt>. Go `up'
to that frame, and then type:
<tscreen><verb>
frame frame->tf_ebp frame->tf_eip
</verb></tscreen>
This will tell <tt>kgdb</tt> to go to the stack frame explicitly named by a
frame pointer and instruction pointer, which is the location where
the trap occured. There are still some bugs in <tt>kgdb</tt> (you can go
`up' from there, but not `down'; the stack trace will still remain
as it was before going to here), but generally this method will lead
you much closer to the failing piece of code.
Here's a script log of a <tt>kgdb</tt> session illustrating the above. Long
lines have been folded to improve readability, and the lines are
numbered for reference. Despite of this, it's a real-world error
trace taken during the development of the pcvt console driver.
<tscreen><verb>
1:Script started on Fri Dec 30 23:15:22 1994
2:uriah # cd /sys/compile/URIAH
3:uriah # kgdb kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb) where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb) up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&amp;frame, FALSE);
36:(kgdb) frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb) list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb) print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb) print tp->t_line
56:$2 = 1767990816
57:(kgdb) up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb) up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb) up
64:#3 0xf012d014 in vn_open ()
65:(kgdb) up
66:#4 0xf012a183 in open ()
67:(kgdb) up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb) up
75:Initial frame selected; you cannot go up.
76:(kgdb) quit
77:uriah # exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994
</verb></tscreen>
Comments to the above script:
<descrip>
<tag/line 6:/ This is a dump taken from within DDB (see below), hence the
panic comment ``because you said to!'', and a rather long
stack trace; the initial reason for going into DDB has been
a page fault trap though.
<tag/line 20:/ This is the location of function <tt>trap()</tt>
in the stack trace.
<tag/line 36:/ Force usage of a new stack frame, kgdb responds and displays
the source line where the trap happened; from looking at the
code, there's a high probability that either the pointer
access for ``tp'' was messed up, or the array access was
out of bounds.
<tag/line 52:/ The pointer looks suspicious, but happens to be a valid
address.
<tag/line 56:/ However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece
of code: <tt>tp-&gt;t_line</tt> refers to the line discipline
of the console device here, which must be a rather small integer
number.)
</descrip>
<sect><heading>Post-mortem analysis of a dump</heading>
<p>What do you do if a kernel dumped core but you did not expect
it, and it's therefore not compiled using <tt>config -g</tt>?
Not everything is lost here. Don't panic!
<!-- XXX obsolete?
Of course, you still need to configure all your kernels with the
DODUMP option being set, otherwise you won't get a core dump at all.
(This is for safety reasons in the default kernels, to avoid them
trying to dump e.g. during system installation where there's no
FreeBSD partition at all and valuable data on the disk could be
destroyed.)
-->
Go to your kernel compile directory, and edit the line
containing <tt>COPTFLAGS?=-O</tt>. Add the <tt>-g</tt> option
there (but <em>don't</em> change anything on the level of
optimization). If you do already know roughly the probable
location of the failing piece of code (e.g., the <tt>pcvt</tt>
driver in the example above), remove all the object files for
this code. Rebuild the kernel. Due to the time stamp change on
the Makefile, there will be some other object files rebuild,
for example <tt>trap.o</tt>. With a bit of luck, the added
<tt>-g</tt> option won't change anything for the generated
code, so you'll finally get a new kernel with similiar code to
the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the <tt>size(1)</tt> command. If
there is a mismatch, you probably need to give up here.
Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in
the stack trace in the example above where some functions are
displayed without line numbers and argument lists. If you need
more debugging symbols, remove the appropriate object files and
repeat the <tt>kgdb</tt> session until you know enough.
All this is not guaranteed to work, but it will do it fine in
most cases.
<sect><heading>On-line kernel debugging using DDB</heading>
<p>While <tt>kgdb</tt> as an offline debugger provides a very
high level of user interface, there are some things it cannot do.
The most important ones being breakpointing and single-stepping
kernel code.
If you need to do low-level debugging on your kernel, there's
an on- line debugger available called DDB. It allows to
setting breakpoints, single-steping kernel functions, examining
and changeing kernel variables, etc. However, it cannot not
access kernel source files, and only has access to the global
and static symbols, not to the full debug information like
<tt>kgdb</tt>.
To configure your kernel to include DDB, add the option line
<tscreen><verb>
options DDB
</verb></tscreen>
to your config file, and rebuild. (See <ref id="kernelconfig:"
name="Kernel Configuration"> for details on configuring the
FreeBSD kernel. Note that if you have an older version of the
boot blocks, your debugger symbols might not be loaded at all.
Update the boot blocks, the recent ones do load the DDB symbols
automagically.)
Once your DDB kernel is running, there are several ways to
enter DDB. The first, and earliest way is to type the boot
flag <tt>-d</tt> right at the boot prompt. The kernel will
start up in debug mode and enter DDB prior to any device
probing. Hence you are able to even debug the device
probe/attach functions.
The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped, and some of
the distributed maps do this, so watch out. Patches for a
COMCONSOLE kernel, are available from &a.joerg;.
The third way is that any panic condition will branch to DDB if
the kernel is configured to use it. It is not wise to
configure a kernel with DDB for a machine running unattended
for this reason.
The DDB commands roughly resemble some <tt>gdb</tt> commands. The first you
probably need is to set a breakpoint:
<tscreen><verb>
b function-name
b address
</verb></tscreen>
Numbers are taken hexadecimal by default, but to make them
distinct from symbol names, hexadecimal numbers starting with the
letters <tt>a</tt>-<tt>f</tt> need to be preceded with
<tt>0x</tt> (for other numbers, this is optional). Simple
expressions are allowed, for example: <tt>function-name + 0x103</tt>.
To continue the operation of an interrupted kernel, simply type
<tscreen><verb>
c
</verb></tscreen>
To get a stack trace, use
<tscreen><verb>
trace
</verb></tscreen>
Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.
If you want to remove a breakpoint, use
<tscreen><verb>
del
del address-expression
</verb></tscreen>
The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address, as it can be
obtained from
<tscreen><verb>
show b
</verb></tscreen>
To single-step the kernel, try
<tscreen><verb>
s
</verb></tscreen>
This will step into functions, but you can make DDB trace them until
the matching return statement is reached by
<tscreen><verb>
n
</verb></tscreen>
Note: this is different from <tt>gdb</tt>'s `next' statement, it's like
<tt>gdb</tt>'s `finish'.
To examine data from memory, use (for example):
<tscreen><verb>
x/wx 0xf0133fe0,40
x/hd db_symtab_space
x/bc termbuf,10
x/s stringbuf
</verb></tscreen>
for word/halfword/byte access, and hexadecimal/decimal/character/
string display. The number after the comma is the object count.
To display the next 0x10 items, simply use
<tscreen><verb>
x ,10
</verb></tscreen>
Similiarly, use
<tscreen><verb>
x/ia foofunc,10
</verb></tscreen>
to disassemble the first 0x10 instructions of <tt>foofunc</tt>, and display
them along with their offset from the beginning of <tt>foofunc</tt>.
To modify the memory, use the write command:
<tscreen><verb>
w/b termbuf 0xa 0xb 0
w/w 0xf0010030 0 0
</verb></tscreen>
The command modifier (<tt>b</tt>/<tt>h</tt>/<tt>w</tt>)
specifies the size of the data to be writtten, the first
following expression is the address to write to, the remainder
is interpreted as data to write to successive memory locations.
If you need to know the current registers, use
<tscreen><verb>
show reg
</verb></tscreen>
Alternatively, you can display a single register value by e.g.
<tscreen><verb>
print $eax
</verb></tscreen>
and modify it by
<tscreen><verb>
set $eax new-value
</verb></tscreen>
Should you need to call some kernel functions from DDB, simply
say
<tscreen><verb>
call func(arg1, arg2, ...)
</verb></tscreen>
The return value will be printed.
For a <tt>ps(1)</tt> style summary of all running processes, use
<tscreen><verb>
ps
</verb></tscreen>
Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
as expected. Perform one of the following actions to shut down and
reboot your system:
<tscreen><verb>
call diediedie()
</verb></tscreen>
will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This
command usually must be followed by another
`<tt>continue</tt>' statement.
There is now an alias for this: `<tt>panic</tt>'.
<tscreen><verb>
call boot(0)
</verb></tscreen>
might be a good way to cleanly shut down the running system, <tt>sync()</tt>
all disks, and finally reboot. As long as the disk and file system
interfaces of the kernel are not damaged, this might be a good way
for an almost clean shutdown.
<tscreen><verb>
call cpu_reset()
</verb></tscreen>
is the final way out of disaster and almost the same as hitting
the Big Red Button.
<sect><heading>Debugging a console driver</heading>
<p>Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is flakey. You might
remember the <tt>options COMCONSOLE</tt> line, and hook up a standard
terminal onto your first serial port. DDB works on any configured
console driver, of course it also works on a <tt>COMCONSOLE</tt>.

503
handbook/relnotes.sgml Normal file
View file

@ -0,0 +1,503 @@
<!-- $Id: relnotes.sgml,v 1.1 1995-06-14 18:38:56 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
<!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'>
<linuxdoc><book><chapt>foo
-->
<sect>About this release
<p>Since our first release of FreeBSD 1.0 nearly two
years ago, FreeBSD has changed dramatically. Since
releas 2.0, FreeBSD has been based on the Berkeley BSD
4.4-lite code rather than the Net2 code used for
previous versions. In addition to clearing the legal
issues that surrounded the Net2 code, the port to 4.4
has also brought in numerous new features, filesystems
and enhanced driver support.
Since our release of FreeBSD 2.0 in November of 1994,
the performance, feature set, and stability of FreeBSD
has improved dramatically. The largest change is a
revamped Virtual Memory (VM) system with a merged
virtual memory and file buffer cache. This increases
performance while reducing FreeBSD's memory footprint,
making a system with 4 megabytes of RAM a more
acceptable minimum. Other enhancements include full
NIS client and server support, transaction TCP support,
dial on demand PPP, an improved SCSI subsystem, early
support for ISDN, support for FDDI and 100Mbit Fast
Ethernet adapters, improved support for the Adaptec
2940 and hundreds of bug fixes.
We've also taken the comments and suggestions of many
of our users to heart and have attempted to provide
what we hope is a more sane and easily understood
installation process. Your feedback on this constantly
evolving process is especially welcome!
In addition to the base distributions, FreeBSD offers a
new ported software collection with some 270 commonly
sought-after programs. The list of ports ranges from
World Wide Web (http) servers, to games, languages,
editors and almost everything in between. The entire
ports collection requires only 10MB of storage because
each port contains only the changes required for the
source code to compile on FreeBSD and the information
necessary to automatically retrieve the original
sources. The original distribution for each port you
build is automatically retrieved off of CD-ROM or a via
anonymous ftp, so you need only enough disk space to
build the ports you want. Each port is also provided
as a pre-compiled package which can be installed with
the <tt>pkg_add(1)</tt> command for those who do not
wish to compile their own ports from source. See <ref
id="ports:" name="The Ports Collection"> for a more
complete description.
<!-- XXX make xref
For a list of contributors and a general project
description, please see the file "CONTRIB.FreeBSD"
which should be bundled with your binary distribution.
Also see the "REGISTER.FreeBSD" file for information on
registering with the "Free BSD user counter". This
counter is for ALL freely available variants of BSD,
not just FreeBSD, and we urge you to register yourself
with it.
-->
The core of FreeBSD does not contain DES code which
would inhibit its being exported outside the United
States. An add-on package, for use only in the United
States, contains the programs that normally use DES.
The auxiliary packages provided separately can be used
by anyone. A freely exportable European distribution
of DES for our non-U.S. users also exists and is
described in the <url
url="http://www.freebsd.org/How/faq" name="FreeBSD
FAQ">. If password security for FreeBSD is all you
need, and you have no requirement for copying encrypted
passwords from other hosts using DES into FreeBSD
password entries, then FreeBSD's MD5 based security may
be all you require. We feel that our default security
model is more than a match for DES, and without any
messy export issues to deal with.
FreeBSD 2.0.5 represents the culmination of 2 years of
work and many thousands of man hours put in by an
international development team. We hope you enjoy it!
<sect1>New feature highlights
<p>The following features were added or substantially
improved between the release of 2.0 and this 2.0.5
release. In order to facilitate better
communication, the person, or persons, responsible
for each enhancement is noted. Any questions
regarding the new functionality should be directed to
them first.
<sect2>Kernel
<p>
<descrip>
<tag>Merged VM-File Buffer Cache</tag> A merged
VM/buffer cache design greatly enhances overall
system performance and makes it possible to do
a number of more optimal memory allocation
strategies that were not possible before.
Owner: David Greenman (davidg@FreeBSD.org) and
John Dyson (dyson@implode.root.com)
<tag>Network PCB hash optimization</tag> For
systems with a great number of active TCP
connections (WEB and ftp servers, for example),
this greatly speeds up the lookup time required
to match an incoming packet up to its
associated connection.
Owner: David Greenman (davidg@FreeBSD.org)
<tag>Name cache optimization</tag> The name-cache
would cache all files of the same name to the
same bucket, which would put for instance all
".." entries in the same bucket. We added the
parent directory version to frustrate the hash,
and improved the management of the cache in
various other ways while we were at it.
Owner: Poul-Henning Kamp (phk@FreeBSD.org)
David Greenman (davidg@FreeBSD.org)
<tag>Less restrictive swap-spaces</tag> The need
to compile the names of the swap devices into
the kernel has been removed. Now
<tt>swapon(8)</tt> will accept any block
devices, up to the maximum number of swap
devices configured in the kernel.
Owner: Poul-Henning Kamp (phk@FreeBSD.org)
David Greenman (davidg@FreeBSD.org)
<tag>Hard Wired SCSI Devices</tag> Prior to
2.0.5, FreeBSD performed dynamic assignment of
unit numbers to SCSI devices as they were
probed, allowing a SCSI device failure to
possibly change unit number assignment. This
could cause filesystems other disks in the
system to be incorrectly mounted, or not
mounted at all. Hard wiring allows static
allocation of unit numbers (and hence device
names) to scsi devices based on SCSI ID and
bus. SCSI configuration occurs in the kernel
config file. Samples of the configuration
syntax can be found in the <tt>scsi(4)</tt> man
page or the LINT kernel config file.
Owner: Peter Dufault (dufault@hda.com)
Sources involved: <tt>sys/scsi/*</tt>
<tt>usr.sbin/config/*</tt>
<tag>Slice Support</tag> FreeBSD now supports a
<em>slice</em> abstraction which enhances
FreeBSD's ability to share disks with other
operating systems. This support will allow
FreeBSD to inhabit DOS extended partitions.
Owner: Bruce Evans (bde@FreeBSD.org)
Sources involved: <tt>sys/disklabel.h</tt>
<tt>sys/diskslice.h</tt> <tt>sys/dkbad.h</tt>
<tt>kern/subr_diskslice.c</tt> <tt>kern/subr_dkbad.c</tt>
<tt>i386/isa/diskslice_machdep.c</tt> <tt>i386/isa/wd.c</tt>
<tt>scsi/sd.c</tt> <tt>dev/vn/vn.c</tt>
<tag>Support for Ontrack Disk Manager Version
6.0</tag> Support has been added for disks
which use Ontrack Disk Manager. The fdisk
program does <em>not</em> know about it
however, so make all changes using the install
program on the boot.flp or the Ontrack Disk
Manager tool under MS-DOS.
Owner: Poul-Henning Kamp (phk@FreeBSD.org)
<tag>Bad144 is back and working</tag> Bad144
works again, though the semantics are slightly
different than before in that the bad-spots are
kept relative to the slice rather than absolute
on the disk.
Owner: Bruce Evans (bde@FreeBSD.org)
Poul-Henning Kamp (phk@FreeBSD.org)
</descrip>
<sect2>New device support
<sect3>SCSI and CDROM devices
<p><descrip>
<tag>Matsushita/Panasonic (Creative) CD-ROM
driver</tag> The Matsushita/Panasonic CR-562 and
CR-563 drives are now supported when connected to
a Sound Blaster or 100% compatible host adapter.
Up to four host adapters are supported for a
total of 16 CD-ROM drives. The audio functions
are supported with the Karoke variable speed
playback.
Owner: Frank Durda IV
(bsdmail@nemesis.lonestar.org)
Sources involved: <tt>isa/matcd</tt>
<tag>Adaptec 2742/2842/2940 SCSI driver</tag> The
original 274x/284x driver has evolved
considerably since the 2.0 release of FreeBSD.
We now offer full support for the 2940 series as
well as the Wide models of these cards. The
arbitration bug that caused problems with fast
devices has been corrected and
<em>experimental</em> tagged queuing support has
been added (kernel option
<tt>AHC_TAGENABLE</tt>). John Aycock has also
released the sequencer code under a Berkeley
style copyright making the driver entirely clean
of the GPL.
Owner: Justin Gibbs (gibbs@FreeBSD.org)
Sources involved: <tt>isa/aic7770.c</tt> <tt>pci/aic7870.c</tt>
<tt>i386/scsi/*</tt> <tt>sys/dev/aic7xxx/*</tt>
<tag>NCR5380/NCR53400 SCSI (ProAudio Spectrum)
driver</tag> Owner: core
Submitted by: Serge Vakulenko (vak@cronyx.ru)
Sources involved: <tt>isa/ncr5380.c</tt>
<tag>Sony CDROM driver</tag> Owner: core
Submitted by: Mikael Hybsch (micke@dynas.se)
Sources involved: <tt>isa/scd.c</tt>
</descrip>
<sect3>Serial devices
<p><descrip>
<tag>SDL Communications Riscom/8 Serial Board
Driver</tag> Owner: Andrey Chernov
(ache@FreeBSD.org)
Sources involved: <tt>isa/rc.c</tt> <tt>isa/rcreg.h</tt>
<tag>Cyclades Cyclom-y Serial Board Driver</tag>
Owner: Bruce Evans (bde@FreeBSD.org)
Submitted by: Andrew Werple
(andrew@werple.apana.org.au) and Heikki Suonsivu
(hsu@cs.hut.fi)
Obtained from: NetBSD
Sources involved: <tt>isa/cy.c</tt>
<tag>Cronyx/Sigma sync/async serial driver</tag>
Owner: core
Submitted by: Serge Vakulenko
Sources involved: <tt>isa/cronyx.c</tt>
</descrip>
<sect2>Networking
<p><descrip>
<tag>Diskless booting</tag> Diskless booting in 2.0.5
is much improved over previous releases. The boot
program is in <tt>src/sys/i386/boot/netboot</tt>,
and can be run from an MS-DOS system or burned into
an EPROM. WD, SMC, 3COM and Novell ethernet cards
are currently supported. Local swapping is also
supported.
<tag>DEC DC21140 Fast Ethernet driver</tag> This
driver supports any of the numerous NICs using the
DC21140 chipset including the 100Mb DEC DE-500-XA
and SMC 9332.
Owner: core
Submitted by: Matt Thomas (thomas@lkg.dec.com)
Sources involved: <tt>pci/if_de.c</tt> <tt>pci/dc21040.h</tt>
<tag>DEC FDDI (DEFPA/DEFEA) driver</tag> Owner: core
Submitted by: Matt Thomas (thomas@lkg.dec.com)
Sources involved: <tt>pci/if_pdq.c</tt> <tt>pci/pdq.c</tt>
<tt>pci/pdq_os.h</tt> <tt>pci/pdqreg.h</tt>
<tag>3Com 3c505 (Etherlink/+) NIC driver</tag> Owner:
core
Submitted by: Dean Huxley (dean@fsa.ca)
Obtained from: NetBSD
Sources involved: <tt>isa/if_eg.c</tt>
<tag>Fujitsu MB86960A family of NICs driver</tag>
Owner: core
Submitted by: M.S. (seki@sysrap.cs.fujitsu.co.jp)
Sources involved: <tt>isa/if_fe.c</tt>
<tag>Intel EtherExpress driver</tag> Owner: Rodney
W. Grimes (rgrimes@FreeBSD.org)
Sources involved: <tt>isa/if_ix.c</tt> <tt>isa/if_ixreg.h</tt>
<tag>3Com 3c589 driver</tag> Owner: core
Submitted by: "HOSOKAWA Tatsumi"
(hosokawa@mt.cs.keio.ac.jp), Seiji Murata
(seiji@mt.cs.keio.ac.jp) and Noriyuki Takahashi
(hor@aecl.ntt.jp)
Sources involved: <tt>isa/if_zp.c</tt>
<tag>IBM Credit Card Adapter driver</tag> Owner: core
Submitted by: "HOSOKAWA Tatsumi"
(hosokawa@mt.cs.keio.ac.jp),
Sources involved: <tt>isa/pcic.c</tt> <tt>isa/pcic.h</tt>
<tag>EDSS1 and 1TR6 ISDN interface driver</tag>
Owner: core
Submitted by: Dietmar Friede
(dfriede@drnhh.neuhaus.de) and Juergen Krause
(jkr@saarlink.de)
Sources involved: <tt>gnu/isdn/*</tt>
</descrip>
<sect2>Miscellaneous drivers
<p><descrip>
<tag>Joystick driver</tag> Owner: Jean-Marc Zucconi
(jmz@FreeBSD.org)
Sources involved: <tt>isa/joy.c</tt>
<tag>National Instruments "LabPC" driver</tag> Owner:
Peter Dufault (dufault@hda.com)
Sources involved: <tt>isa/labpc.c</tt>
<tag>WD7000 driver</tag> Owner: Olof Johansson
(offe@ludd.luth.se)
<tag>Pcvt Console driver</tag> Owner: Joerg Wunsch
(joerg@FreeBSD.org)
Submitted by: Hellmuth Michaelis
(hm@altona.hamburg.com)
Sources involved: <tt>isa/pcvt/*</tt>
<tag>BSD-audio emulator for VAT driver</tag> Owner:
Amancio Hasty (ahasty@FreeBSD.org) and
Paul Traina (pst@FreeBSD.org)
Sources involved: <tt>isa/sound/vat_audio.c</tt>
<tt>isa/sound/vat_audioio.h</tt>
<tag>National Instruments AT-GPIB and AT-GPIB/TNT
GPIB driver</tag> Owner: core
Submitted by: Fred Cawthorne
(fcawth@delphi.umd.edu)
Sources involved: <tt>isa/gpib.c</tt> <tt>isa/gpib.h</tt>
<tt>isa/gpibreg.h</tt>
<tag>Genius GS-4500 hand scanner driver</tag> Owner:
core
Submitted by: Gunther Schadow
(gusw@fub46.zedat.fu-berlin.de)
Sources involved: <tt>isa/gsc.c</tt> <tt>isa/gscreg.h</tt>
<tag>CORTEX-I Frame Grabber</tag> Owner: core
Submitted by: Paul S. LaFollette, Jr. (
Sources involved: <tt>isa/ctx.c</tt> <tt>isa/ctxreg.h</tt>
<tag>Video Spigot video capture card</tag> Owner: Jim
Lowe
</descrip>
<sect1>Experimental features
<p><descrip>
<tag>UNIONFS and LFS</tag> The unionfs and LFS file
systems are known to be severely broken in FreeBSD
2.0.5. This is in part due to old bugs that we
haven't had time to resolve yet and the need to
update these file systems to deal with the new VM
system. We hope to address these issues in a later
release of FreeBSD.
<tag>iBCS2 Support</tag> FreeBSD now supports running
iBCS2 compatible binaries. Currently SCO UNIX 3.2.2
and 3.2.4, and ISC 2.2 COFF are supported. The iBCS2
emulator is in its early stages and has not been
extensively tested, but it is functional. Most of
SCO's 3.2.2 binaries work, as does an old
INFORMIX-2.10 for SCO. Further testing is nessesary
to complete this project. There is also work under
way for ELF and XOUT loaders, and most of the svr4
syscall wrappers are written.
Owner: Soren Schmidt (sos) and Sean Eric Fagan (sef)
Sources involved: <tt>sys/i386/ibcs2/*</tt> and misc
kernel changes.
</descrip>
<!--
<sect1>Reporting problems, making suggestions, submitting code
<p>Your suggestions, bug reports and contributions of code
are always valued - please do not hesitate to report any
problems you may find (preferably with a fix attached if
you can!).
The preferred method to submit bug reports from a machine
with internet mail connectivity is to use the send-pr
command. Bug reports will be dutifully filed by our
faithful bugfiler program and you can be sure that we'll
do our best to respond to all reported bugs as soon as
possible.
If, for some reason, you are unable to use the send-pr
command to submit a bug report, you can try to send it
to: <tscreen>bugs@FreeBSD.org</tscreen> Otherwise, for
any questions or suggestions, please send mail to:
<tscreen>questions@FreeBSD.org</tscreen>
Additionally, being a volunteer effort, we are always
happy to have extra hands willing to help - there are
already far more enhancements to be done than we can ever
manage to do by ourselves! To contact us on technical
matters, or with offers of help, you may send mail to:
<tscreen>hackers@FreeBSD.org</tscreen>
Since these mailing lists can experience significant
amounts of traffic, if you have slow or expensive mail
access and you are only interested in keeping up with
significant FreeBSD events, you may find it preferable to
subscribe to: <tscreen>announce@FreeBSD.org</tscreen>
All but the freebsd-bugs groups can be freely joined by
anyone wishing to do so. Send mail to
MajorDomo@FreeBSD.org and include the keyword `help' on a
line by itself somewhere in the body of the message.
This will give you more information on joining the
various lists, accessing archives, etc. There are a
number of mailing lists targeted at special interest
groups not mentioned here, so send mail to majordomo and
ask about them!
-->