diff --git a/handbook/authors.sgml b/handbook/authors.sgml index 5380e7f1d0..7c27a71b42 100644 --- a/handbook/authors.sgml +++ b/handbook/authors.sgml @@ -1,24 +1,25 @@ - + <asami@FreeBSD.org>"> <davidg@Root.COM>"> <dufault@hda.com>"> <gclarkii@FreeBSD.org>"> <gena@NetVision.net.il>"> <ghelmer@alpha.dsu.edu>"> <gpalmer@FreeBSD.org>"> <jfieber@FreeBSD.org>"> <jkh@FreeBSD.org>"> <joerg_wunsch@uriah.heep.sax.de>"> <john@starfire.MN.ORG>"> <mark@grondar.za>"> <martin@innovus.com>"> <md@bsc.no>"> <phk@FreeBSD.org>"> +<paul@FreeBSD.org>"> <wilko@yedi.iaf.nl>"> diff --git a/handbook/basics.sgml b/handbook/basics.sgml index dfa49b6569..06cddbc254 100644 --- a/handbook/basics.sgml +++ b/handbook/basics.sgml @@ -1,73 +1,78 @@ - + Unix Basics The online manual

The most comprehensive documentation on FreeBSD is in the form of man pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and various argument. These manuals can be view with the man command. Use of the man command is simple: - man command + man command where command 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 ls command type: - man ls + % man ls

The online manual is divided up into numbered sections: User commands System calls and error numbers Functions in the C libraries Device drivers File formats Games and other diversions Miscellaneous information System maintenance and operation commands in some cases, the same topic may appear in more than one section of the on-line manual. For example, there is a chmod user command and a chmod() system call. In this case, you can tell the man command which you want by specifying the section: - man 1 chmod + % man 1 chmod which will display the manual page for the user command chmod.

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 man to - search through the command descriptions by + search for keywords in the command descriptions by using the -k switch: - man -k mail + % man -k mail With this command you will be presented with a list of commands that have the keyword `mail' in their descriptions. GNU Info files

FreeBSD includes many applications and utilities produced by the Free Software Foundation (FSF). In addition to man pages, these programs come with more - extensive info files which can be viewed with - the info command or, if you installed - emacs, the info mode of emacs. + extensive hypertext documents called info + files which can be viewed with the info + command or, if you installed emacs, the info + mode of emacs. + + To use the info(1) command, simply type: + % info For a brief + introduction, type h, and for a quick + command reference, type ?. - diff --git a/handbook/booting.sgml b/handbook/booting.sgml index 57a6eeee62..ad412332d4 100644 --- a/handbook/booting.sgml +++ b/handbook/booting.sgml @@ -1,175 +1,175 @@ - Booting FreeBSD on a PC + The FreeBSD Booting Process

Contributed by &a.phk;. v1.1, April 26th. Booting FreeBSD is essentially a three step: Load the kernel, determine the root filesystem and initialize user-land things. This leads to some interesting possibilities shown below. Loading a kernel

We presently have three basic mechanisms for loading the kernel: biosboot dosboot netboot Each will be described in detail below. They all pass some information to the kernel to help the kernel decide what to do next. Biosboot

Biosboot is our ``bootblocks'', it consists of two files, which will be installed in the first 8Kbytes of the floppy or hard-disk slice to be booted from. Biosboot can load a kernel from a FreeBSD filesystem. Dosboot

Dosboot was written by DI. Christian Gusenbauer, and is unfortunately at this time one of the few pieces of code that isn't compilable under FreeBSD itself because it is written for MicroSoft compilers. Dosboot will boot the kernel from a MS-DOS file or from a FreeBSD filesystem partition on the disk. It attempts to negotiate with the various and strange kinds of memory manglers that lurk in high memory on MS/DOS systems and usually wins them for it's case. Netboot

Netboot will try to find a supported ethernet card, and use BOOTP, TFTP and NFS to find a kernel file to boot. Determine the root filesystem

Once the kernel is loaded and the boot-code jumps to it, the kernel will initialize itself, trying to determine what hardware is present and so on, and then it needs to find a root filesystem. Presently we support the following types of rootfilesystems: UFS MSDOS MFS CD9660 NFS UFS

This is the most normal type of root filesystem. It can reside on a floppy or on harddisk. MSDOS

While this is technically possible, it isn't particular useful, because of ``FAT'' filesystems inability to make links, device nodes and such ``UNIXisms''. MFS

This is actually a UFS filesystem which has been compiled into the kernel. That means that the kernel does not really need any disks/floppies or other HW to function. CD9660

This is for using a CD-ROM as root filesystem. NFS

This is for using a fileserver as root filesystem, basically making it a diskless machine. Initialize user-land things

To get the user-land going, when the kernel has finished initialization, it will create a with ``/sbin/init''. You can substitute any program for /sbin/init, as long as you keep in mind that: there is no stdin/out/err unless you open it yourself, if you exit, the machine panics signal handling is special for ``Interesting combinations

Boot a kernel with a MFS in it with a special /sbin/init which... mounts your /C: Attaches C:/freebsd.fs on /dev/vn0 mounts /dev/vn0 as /rootfs makes symlinks /rootfs/bin -> /bin /rootfs/etc -> /etc /rootfs/sbin -> /sbin ... Now you run FreeBSD without repartitioning your hard disk... server:˜you/FreeBSD as /nfs, chroots to /nfs and executes /sbin/init there Now you run FreeBSD diskless, even though you don't control the NFS server... /dev/rwd0 and writes it to a remote tape station or fileserver. Now you finally got that backup you should have made a year ago... E -- Acts as a firewall/web-server/what do I know... This is particular interesting since you can boot from a write- protected floppy, but still write to your root filesystem... diff --git a/handbook/glossary.sgml b/handbook/glossary.sgml index 385e6731a6..fc5c69afb7 100644 --- a/handbook/glossary.sgml +++ b/handbook/glossary.sgml @@ -1,5 +1,5 @@ - + -Glossary +* Glossary diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index 6255de5531..91714ad243 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,204 +1,169 @@ - + %authors; + + + + + ]> FreeBSD Handbook <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 and some of those that do exist need to be updated. If you are interested in helping with this project, send email to &a.jfieber; or to the FreeBSD Documentantion Project mailing list <tt><doc@freebsd.org></tt>. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <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; <!-- ************************************************************ --> <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> - - <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> + <sect><heading>* Adding and reconfiguring disks</heading> + <sect><heading>* Tapes and backups</heading> + <sect><heading>* Serial ports</heading> + <sect><heading>* Sound cards</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> &ppp; &slipc; &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> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> ¤t; &ctm; ⊃ - <chapt><heading>Kernel debugging</heading> + &kerneldebug; &submitters; &booting; &memoryuse; &troubleshooting; <!-- ************************************************************ --> <part><heading>Additional resources</heading> &bibliography; &eresources; &glossary; </book> </linuxdoc> diff --git a/handbook/hw.sgml b/handbook/hw.sgml new file mode 100644 index 0000000000..f577c96f58 --- /dev/null +++ b/handbook/hw.sgml @@ -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> + + + diff --git a/handbook/install.sgml b/handbook/install.sgml new file mode 100644 index 0000000000..016ea0057c --- /dev/null +++ b/handbook/install.sgml @@ -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 & 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 & 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 >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 >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&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&A + section of the Hardware Guide for possible clues! + diff --git a/handbook/kerneldebug.sgml b/handbook/kerneldebug.sgml new file mode 100644 index 0000000000..5365066a20 --- /dev/null +++ b/handbook/kerneldebug.sgml @@ -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(&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->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>. + + diff --git a/handbook/relnotes.sgml b/handbook/relnotes.sgml new file mode 100644 index 0000000000..4687bed14c --- /dev/null +++ b/handbook/relnotes.sgml @@ -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! + +-->