aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDoc Manager <doceng@FreeBSD.org>1996-06-11 18:05:48 +0000
committerDoc Manager <doceng@FreeBSD.org>1996-06-11 18:05:48 +0000
commit31444442c3a0c70f1c4de4aa0e4f95e5a6b9c31a (patch)
treee190852c0758cb8fc8e9b5f89e3588a97454a271
parentab87b86033e9ba79acc0a8d38765fc142ce85ae3 (diff)
downloaddoc-31444442c3a0c70f1c4de4aa0e4f95e5a6b9c31a.tar.gz
doc-31444442c3a0c70f1c4de4aa0e4f95e5a6b9c31a.zip
Create branch 'RELENG_2_1_0'.
Notes
Notes: svn path=/branches/RELENG_2_1_0/; revision=367
-rw-r--r--handbook/cyclades.sgml57
-rw-r--r--handbook/goals.sgml9
-rw-r--r--handbook/linuxemu.sgml700
-rw-r--r--handbook/lists.sgml57
-rw-r--r--handbook/pgpkeys.sgml200
-rw-r--r--handbook/quotas.sgml208
-rw-r--r--handbook/sio.sgml207
-rw-r--r--handbook/stable.sgml108
-rw-r--r--handbook/synching.sgml21
-rw-r--r--handbook/uart.sgml1108
10 files changed, 2675 insertions, 0 deletions
diff --git a/handbook/cyclades.sgml b/handbook/cyclades.sgml
new file mode 100644
index 0000000000..632d8102b8
--- /dev/null
+++ b/handbook/cyclades.sgml
@@ -0,0 +1,57 @@
+<!-- $Id: cyclades.sgml,v 1.1 1996-06-07 15:56:35 alex Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<!--
+<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
+
+<!ENTITY % authors SYSTEM "authors.sgml">
+%authors;
+
+]>
+-->
+<sect2><heading>Configuring the <tt>cy</tt> driver<label id="cy"></heading>
+
+ <p><em>Contributed by &a.alex;.<newline>6 June 1996.</em>
+
+ The Cyclades multiport cards are based on the <tt>cy</tt>
+ driver instead of the usual <tt>sio</tt> driver used by
+ other multiport cards. Configuration is a simple matter
+ of:
+
+ <enum>
+ <item>Add the <tt>cy</tt> device to your
+ <ref id="kernelconfig:config" name="kernel configuration">
+ (note that your irq and iomem settings may differ).
+
+<tscreen><verb>
+device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr
+</verb></tscreen>
+
+ <item><ref id="kernelconfig:building" name="Rebuild and install">
+ the new kernel.
+
+ <item>Make the <ref id="kernelconfig:nodes" name="device nodes">
+ by typing (the following example assumes an 8-port board):
+
+<tscreen><verb>
+# cd /dev
+# for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done
+</verb></tscreen>
+
+ <item>If appropriate, add <ref id="dialup" name="dialup">
+ entries to <ref id="dialup:ttys" name="/etc/ttys"> by
+ duplicating serial device (<tt>ttyd</tt>) entries and
+ using <tt>ttyc</tt> in place of <tt>ttyd</tt>. For
+ example:
+
+<tscreen><verb>
+ttyc0 "/usr/libexec/getty std.38400" unknown on insecure
+ttyc1 "/usr/libexec/getty std.38400" unknown on insecure
+ttyc2 "/usr/libexec/getty std.38400" unknown on insecure
+[...]
+ttyc7 "/usr/libexec/getty std.38400" unknown on insecure
+</verb></tscreen>
+
+ <item>Reboot with the new kernel.
+
+ </enum>
diff --git a/handbook/goals.sgml b/handbook/goals.sgml
new file mode 100644
index 0000000000..24ca6c8ffc
--- /dev/null
+++ b/handbook/goals.sgml
@@ -0,0 +1,9 @@
+<!-- $Id: goals.sgml,v 1.1 1995-12-07 13:22:13 jkh Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<sect><heading>FreeBSD Project goals<label id="goals"></heading>
+
+<p><em>Contributed by &a.jkh;</em>.
+
+<p><em>Note: This section is under construction.</em>
+
diff --git a/handbook/linuxemu.sgml b/handbook/linuxemu.sgml
new file mode 100644
index 0000000000..384c549974
--- /dev/null
+++ b/handbook/linuxemu.sgml
@@ -0,0 +1,700 @@
+<!-- $Id: linuxemu.sgml,v 1.8 1996-05-24 19:33:32 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<chapt><heading>Linux Emulation<label id="linuxemu"></heading>
+
+<p><em>Contributed by &a.brian and &a.rich;</em>
+
+<sect><heading>How to install the Linux emulator</heading>
+
+<p>Linux emulation in FreeBSD has reached a point where it is possible
+to run a large fraction of Linux binaries in both a.out and ELF
+format. The linux emulation in the -STABLE branch is capable of
+running Linux DOOM and Mathematica; the version present in
+FreeBSD-CURRENT is vastly more capable and runs all these as well as
+Quake, Abuse, IDL, netrek for Linux and a whole host of other
+programs.
+
+There are some Linux-specific operating system features that are not
+supported on FreeBSD. Linux binaries will not work on FreeBSD if they
+use the Linux /proc filesystem (which is different from the optional
+FreeBSD /proc filesystem) or i386-specific calls, such as enabling
+virtual 8086 mode.
+
+<p>To tell whether your kernel is configured for Linux
+compatibility simply run any Linux binary. If it
+prints the error message
+<tscreen>
+<verb>
+linux-executable: Exec format error. Wrong Architecture.
+</verb>
+</tscreen>
+then you do not have linux compatibility support and
+you need to configure and install a new kernel.
+
+Depending on which version of FreeBSD you are running, how you get
+Linux-emulation up will vary slightly:
+
+<sect1><heading>Installing Linux Emulation in 2.1-STABLE</heading>
+
+<p>The GENERIC kernel in 2.1-stable is not configured for linux
+compatibility so you you must reconfigure your kernel for it. There
+are two ways to do this: 1. linking the emulator statically in the
+kernel itself and 2. configuring your kernel to dynamically load the
+linux loadable kernel module (LKM).
+
+<p>To enable the emulator, add the following to your configuration file
+(c.f. /sys/i386/conf/LINT):
+<tscreen>
+<verb>
+options "COMPAT_LINUX"
+</verb>
+</tscreen>
+If you want to run doom or other applications
+that need shared memory
+also add the following.
+<tscreen>
+<verb>
+options SYSVSHM
+</verb>
+</tscreen>
+The linux system calls require 4.3 BSD system call compatibility. So
+make sure you have the following.
+<tscreen>
+<verb>
+options "COMPAT_43"
+</verb>
+</tscreen>
+
+If you prefer to statically link the emulator in the kernel rather than
+use the loadable kernel module (LKM), then add
+<tscreen>
+<verb>
+options LINUX
+</verb>
+</tscreen>
+Then run config and install the new kernel as described in the
+<ref id="kernelconfig" name="kernel configuration"> section.
+
+If you decide to use the LKM you must also install the loadable
+module. A mismatch of versions between the kernel and loadable
+module can cause the kernel to crash, so the safest thing to do is to
+reinstall the LKM when you install the kernel.
+<tscreen>
+<verb>
+% cd /usr/src/lkm/linux
+% make all install
+</verb>
+</tscreen>
+Once you have installed the kernel and the LKM, you can invoke
+`linux' as root to load the LKM.
+<tscreen>
+<verb>
+% linux
+Linux emulator installed
+Module loaded as ID 0
+%
+</verb>
+</tscreen>
+To see whether the LKM is loaded, run `modstat'.
+<tscreen>
+<verb>
+% modstat
+Type Id Off Loadaddr Size Info Rev Module Name
+EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator
+%
+</verb>
+</tscreen>
+You can cause the LKM to be loaded when the system boots in either of
+two ways. On FreeBSD-CURRENT and FreeBSD-STABLE enable it in
+/etc/sysconfig
+<tscreen>
+<verb>
+linux=YES
+</verb>
+</tscreen>
+by changing it from NO to YES. FreeBSD 2.1 RELEASE and earlier do not
+have such a line and on those you will need to edit /etc/rc.local to
+add the following line.
+<tscreen>
+<verb>
+linux
+</verb>
+</tscreen>
+
+<sect1><heading>Installing Linux Emulation in 2.2-CURRENT</heading>
+
+<p>In -current it is no longer necessary to specify options "LINUX"
+or options "COMPAT_LINUX". Linux emulation is done with an LKM
+(``Loadable Kernel Module'') so it can be installed on the fly without
+having to reboot. You will need the following things in your startup files,
+however:
+<enum>
+<item> In /etc/sysconfig, you need the following line:
+<tscreen>
+<verb>
+linux=YES
+</verb>
+</tscreen>
+<item> This, in turn, triggers the following action in /etc/rc.i386:
+<tscreen>
+<verb>
+# Start the Linux binary emulation if requested.
+if [ "X${linux}" = X"YES" ]; then
+ echo -n ' '; linux
+ # XXX BOGUS - Linux script shouldn't make any output on success
+fi
+</verb>
+</tscreen>
+</enum>
+
+<p>If you want to verify it is running, modstat will do that:
+<tscreen>
+<verb>
+% modstat
+Type Id Off Loadaddr Size Info Rev Module Name
+EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod
+%
+</verb>
+</tscreen>
+However, there have been reports that this fails on some
+FreeBSD-current systems. If for some reason you cannot load the linux
+LKM, then statically link the emulator in the kernel by adding
+<tscreen>
+<verb>
+options LINUX
+</verb>
+</tscreen>
+to your kernel config file. Then run config and install the new
+kernel as described in the <ref id="kernelconfig" name="kernel
+configuration"> section.
+
+<sect1><heading>Installing Linux Runtime Libraries</heading>
+
+<sect2><heading>Installing using the linux_lib port</heading>
+
+<p>Most linux applications use shared libraries, so you are still not
+done until you install the shared libraries. It is possible to do
+this by hand, however, it is vastly simpler to just grab the
+linux_lib port:
+<tscreen>
+<verb>
+% cd /usr/ports-current/emulators/linux_lib
+% make all install
+</verb>
+</tscreen>
+
+and you should have a working linux emulator. Legend (and the mail
+archives :-) seems to hold that Linux emulation works best with
+linux binaries linked against the ZMAGIC libraries; QMAGIC libraries
+(such as those used in Slackware V2.0) may tend to give the
+Linuxulator heartburn. As of this writing (March 1996) ELF emulation
+is still in the formulative stages but seems to work pretty well. Also,
+expect some programs to complain about incorrect minor versions. In
+general this does not seem to be a problem.
+
+<sect2><heading>Installing libraries manually</heading>
+
+<p>If you don't have the ``ports'' distribution, you can install the
+libraries by hand instead. You will need the Linux shared libraries
+that the program depends on and the runtime linker. Also, you will
+need to create a "shadow root" directory, /compat/linux, for Linux
+libraries on your FreeBSD system. Any shared libraries opened by
+Linux programs run under FreeBSD will look in this tree first. So, if
+a Linux program loads, for example, /lib/libc.so, FreeBSD will first
+try to open /compat/linux/lib/libc.so, and if that does not exist then
+it will try /lib/libc.so. Shared libraries should be installed in the
+shadow tree /compat/linux/lib rather than the paths that the Linux
+ld.so reports.
+
+
+FreeBSD-current works slightly differently with respect to
+/compat/linux. On -current, all files, not just libraries, are
+searched for from the ``shadow root'' /compat/linux.
+
+Generally, you will need to look for the shared libraries that Linux
+binaries depend on only the first few times that you install a Linux
+program on your FreeBSD system. After a while, you will have a sufficient
+set of Linux shared libraries on your system to be able to run newly
+imported Linux binaries without any extra work.
+
+<sect2><heading>How to install additional shared libraries</heading>
+
+<p>What if you install the linux_lib port and your application still
+complains about missing shared libraries? How do you know which
+shared libraries Linux binaries need, and where to get them?
+Basically, there are 2 possibilities (when following these
+instructions: you will need to be root on your FreeBSD system to do
+the necessary installation steps).
+
+<p>If you have access to a Linux system, see what shared libraries
+it needs, and copy them to your FreeBSD system. Example: you have
+just ftp'ed the Linux binary of Doom. Put it on the Linux
+system you have access to, and check which shared libraries it
+needs by running `ldd linuxxdoom':
+
+<tscreen>
+<verb>
+% ldd linuxxdoom
+libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
+libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
+libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
+</verb>
+</tscreen>
+
+<p>You would need go get all the files from the last column, and
+put them under /compat/linux, with the names in the first column
+as symbolic links pointing to them. This means you eventually have
+these files on your FreeBSD system:
+<tscreen>
+<verb>
+/compat/linux/usr/X11/lib/libXt.so.3.1.0
+/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
+/compat/linux/usr/X11/lib/libX11.so.3.1.0
+/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
+/compat/linux/lib/libc.so.4.6.29
+/compat/linux/lib/libc.so.4 -> libc.so.4.6.29
+</verb>
+</tscreen>
+
+<p>Note that if you already have a Linux shared library with a
+matching major revision number to the first column of the 'ldd'
+output, you will not need to copy the file named in the last column to
+your system, the one you already have should work. It is advisable to
+copy the shared library anyway if it is a newer version, though. You
+can remove the old one, as long as you make the symbolic link point to
+the new one. So, if you have these libraries on your system:
+<tscreen>
+<verb>
+/compat/linux/lib/libc.so.4.6.27
+/compat/linux/lib/libc.so.4 -> libc.so.4.6.27
+</verb>
+</tscreen>
+
+and you find a new binary that claims to require a later version
+according to the output of ldd:
+<tscreen>
+<verb>
+libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29
+</verb>
+</tscreen>
+
+If it is only one or two versions out of date in the in the trailing
+digit then do not worry about copying /lib/libc.so.4.6.29 too, because
+the program should work fine with the slightly older version.
+However, if you like you can decide to replace the libc.so anyway, and
+that should leave you with:
+<tscreen>
+<verb>
+/compat/linux/lib/libc.so.4.6.29
+/compat/linux/lib/libc.so.4 -> libc.so.4.6.29
+</verb>
+</tscreen>
+
+<p>Please note that the symbolic link mechanism is <em>only</em>
+needed for Linux binaries, the FreeBSD runtime linker takes care of
+looking for matching major revision numbers itself, you do not need to
+worry about that.
+
+<sect2><heading>Configuring the ld.so -- for FreeBSD-current only</heading>
+
+<p>This section applies only to FreeBSD-current only. Those running
+FreeBSD-stable should skip this section.
+
+<p>Finally, if you run FreeBSD-current you must make sure that you
+have the Linux runtime linker and its config files on your system. You
+should copy these files from the Linux system to their appropriate
+place on your FreeBSD system (to the /compat/linux tree):
+<tscreen>
+<verb>
+/compat/linux/lib/ld.so
+/compat/linux/etc/ld.so.config
+</verb>
+</tscreen>
+
+<p>If you do not have access to a Linux system, you should get the
+extra files you need from various ftp sites. Information on where to
+look for the various files is appended below. For now, let us assume
+you know where to get the files.
+
+<p>
+Retrieve the following files (all from the same ftp site to avoid any
+version mismatches), and install them under /compat/linux
+(i.e. /foo/bar is installed as /compat/linux/foo/bar):
+<tscreen>
+<verb>
+/sbin/ldconfig
+/usr/bin/ldd
+/lib/libc.so.x.y.z
+/lib/ld.so
+</verb>
+</tscreen>
+
+<p>ldconfig and ldd do not necessarily need to be under /compat/linux,
+you can install them elsewhere in the system too. Just make sure they
+do not conflict with their FreeBSD counterparts. A good idea would be
+to install them in /usr/local/bin as ldconfig-linux and ldd-linux.
+<p>
+Create the file /compat/linux/etc/ld.so.conf, containing the
+directories in which the Linux runtime linker should look
+for shared libs. It is a plain text file, containing a directory
+name on each line. /lib and /usr/lib are standard, you could
+add the following:
+<tscreen>
+<verb>
+/usr/X11/lib
+/usr/local/lib
+</verb>
+</tscreen>
+
+<p>When a linux binary opens a library such as /lib/libc.so the
+emulator maps the name to /compat/linux/lib/libc.so internally. All
+linux libraries should be installed under /compat/linux (e.g.
+/compat/linux/lib/libc.so, /compat/linux/usr/X11/lib/libX11.so, etc.)
+in order for the emulator to find them.
+
+<p>Those running FreeBSD-current should run the Linux ldconfig program.
+<tscreen>
+<verb>
+% cd /compat/linux/lib
+% /compat/linux/sbin/ldconfig
+</verb>
+</tscreen>
+
+<p>Ldconfig is statically linked, so it does not need any shared
+libraries to run. It creates the file /compat/linux/etc/ld.so.cache
+which contains the names of all the shared libraries. It should rerun
+to recreate this file whenever you install additional shared
+libraries.
+
+On FreeBSD-stable do not install /compat/linux/etc/ld.so.cache or run
+ldconfig becuase in FreeBSD-stable the syscalls are implemented
+differently and ldconfig is not needed or used.
+
+<p>You should now be set up for Linux binaries which only need a
+shared libc. You can test this by running the Linux ldd on
+itself. Suppose that you have it installed as ldd-linux, it should
+produce something like:
+<tscreen>
+<verb>
+% ldd-linux `which ldd-linux`
+libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29
+</verb>
+</tscreen>
+
+<p>This being done, you are ready to install new Linux binaries.
+Whenever you install a new Linux program, you should check if it needs
+shared libraries, and if so, whether you have them installed in the
+/compat/linux tree. To do this, you run the Linux version ldd on the
+new program, and watch its output. ldd (see also the manual page for
+ldd(1)) will print a list of shared libraries that the program depends
+on, in the form majorname (jumpversion) => fullname.
+
+<p>If it prints "not found" instead of fullname it means that you
+need an extra library. Which library this is, is shown in majorname,
+which will be of the form libXXXX.so.N You will need to find a
+libXXXX.so.N.mm on a Linux ftp site, and install it on your
+system. The XXXX (name) and N (major revision number) should match;
+the minor number(s) mm are less important, though it is advised to
+take the most recent version.
+
+<sect1><heading>Configuring the host name resolver</heading>
+
+<p>If DNS does not work or you get the messages
+<tscreen>
+<verb>
+resolv+: "bind" is an invalid keyword
+resolv+: "hosts" is an invalid keyword
+</verb>
+</tscreen>
+
+then you need to configure a /compat/linux/etc/host.conf file
+containing:
+<tscreen>
+<verb>
+order hosts, bind
+multi on
+</verb>
+</tscreen>
+
+where the order here specifies that /etc/hosts is searched first and
+DNS is searched second. When /compat/linux/etc/host.conf is not
+installed linux applications find FreeBSD's /etc/host.conf and
+complain about the incompatible FreeBSD syntax. You should remove
+`bind,' if you have not configured a name-server using the
+/etc/resolv.conf file.
+
+<p>Lastly, those who run FreeBSD-stable need to set an the
+RESOLV_HOST_CONF environment variable so that applications will know
+how to search the host tables. If you run FreeBSD-current you can
+skip this. For the /bin/csh shell use:
+<tscreen>
+<verb>
+setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf
+</verb>
+</tscreen>
+
+For /bin/sh use:
+<tscreen>
+<verb>
+RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF
+</verb>
+</tscreen>
+
+<sect1><heading>Finding the necessary files</heading>
+
+<p>Note: the information below is valid as of the time this document
+was written, but certain details such as names of ftp sites,
+directories and distribution names may have changed by the time you
+read this.
+
+<p>Linux is distributed by several groups that make their own set
+of binaries that they distribute. Each distribution has its own
+name, like ``Slackware'' or ``Yggdrasil''. The distributions are
+available on a lot of ftp sites. Sometimes the files are unpacked,
+and you can get the individual files you need, but mostly they
+are stored in distribution sets, usually consisting of subdirectories
+with gzipped tar files in them. The primary ftp sites for the
+distributions are:
+<verb>
+sunsite.unc.edu:/pub/Linux/distributions
+tsx-11.mit.edu:/pub/linux/distributions
+</verb>
+
+<p>
+Some European mirrors:
+<verb>
+ftp.luth.se:/pub/linux/distributions
+ftp.demon.co.uk:/pub/linux/distributions
+src.doc.ic.ac.uk:/packages/linux/distributions
+</verb>
+
+<p>For simplicity, let us concentrate on Slackware here. This
+distribution consists of a number of subdirectories, containing
+separate packages. Normally, they are controlled by an install
+program, but you can retrieve files "by hand" too. First of all, you
+will need to look in the "contents" subdir of the distribution. You
+will find a lot of small text files here describing the contents of the
+separate packages. The fastest way to look something up is to retrieve
+all the files in the contents subdirectory, and grep through them for
+the file you need. Here is an example of a list of files that you
+might need, and in which contents-file you will find it by grepping
+through them:
+<tabular ca=ll>
+Library <colsep>Package <rowsep>
+ld.so <colsep>ldso <rowsep>
+ldconfig <colsep>ldso <rowsep>
+ldd <colsep>ldso <rowsep>
+libc.so.4 <colsep>shlibs <rowsep>
+libX11.so.6.0 <colsep>xf_lib <rowsep>
+libXt.so.6.0 <colsep>xf_lib <rowsep>
+libX11.so.3 <colsep>oldlibs <rowsep>
+libXt.so.3 <colsep>oldlibs <rowsep>
+</tabular>
+
+<p>So, in this case, you will need the packages ldso, shlibs, xf_lib
+and oldlibs. In each of the contents-files for these packages, look
+for a line saying ``PACKAGE LOCATION'', it will tell you on which `disk'
+the package is, in our case it will tell us in which subdirectory we
+need to look. For our example, we would find the following locations:
+<tabular ca=ll>
+Package <colsep>Location <rowsep>
+ldso <colsep>diska2 <rowsep>
+shlibs <colsep>diska2 <rowsep>
+oldlibs <colsep>diskx6 <rowsep>
+xf_lib <colsep>diskx9 <rowsep>
+</tabular>
+
+<p>The locations called ``diskXX'' refer to the ``slakware/XX''
+subdirectories of the distribution, others may be found in the
+``contrib'' subdirectory. In this case, we could now retrieve the
+packages we need by retrieving the following files (relative to
+the root of the Slackware distribution tree):
+<tscreen>
+<verb>
+slakware/a2/ldso.tgz
+slakware/a2/shlibs.tgz
+slakware/x6/oldlibs/tgz
+slakware/x9/xf_lib.tgz
+</verb>
+</tscreen>
+
+<p>Extract the files from these gzipped tarfiles in your
+/compat/linux directory (possibly omitting or afterwards
+removing files you don't need), and you are done.
+
+<p><bf>See also:</bf>
+<verb>
+ftp.freebsd.org:pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README
+
+/usr/src/sys/i386/ibcs2/README.iBCS2
+</verb>
+
+<sect><heading>How to Install Mathematica on FreeBSD<label id="mathematica"></heading>
+
+<p><em>Contributed by &a.rich and &a.chuck</em>
+
+This document shows how to install the Linux binary
+distribution of Mathematica 2.2 on FreeBSD 2.1.
+
+<p>Mathematica supports Linux but not FreeBSD as it stands. So once
+you have configured your system for Linux compatibility you have most
+of what you need to run Mathematica.
+
+<p>For those who already have the student edition of
+Mathematica for DOS the cost of upgrading to the Linux
+version at the time this was written, March 1996, was
+&dollar;45.00. It can be ordered directly from Wolfram at
+(217) 398-6500 and paid for by credit card.
+
+<sect1><heading>Unpacking the Mathematica distribution</heading>
+<p>The binaries are currently distributed by Wolfram on CDROM.
+The CDROM has about a dozen tar files, each of which is a binary
+distribution for one of the supported architectures. The one
+for Linux is named LINUX.TAR. You can, for example, unpack this
+into /usr/local/Mathematica:
+<tscreen>
+<verb>
+% cd /usr/local
+% mkdir Mathematica
+% cd Mathematica
+% tar -xvf /cdrom/LINUX.TAR
+</verb>
+</tscreen>
+
+<sect1><heading>Obtaining your Mathematica Password</heading>
+<p>Before you can run Mathematica you will have to obtain
+a password from Wolfram that corresponds to your
+`machine ID.'
+
+<p>Once you have installed the linux compatibility runtime
+libraries and unpacked the mathematica you can obtain
+the `machine ID' by running the program `mathinfo' in
+the Install directory.
+<tscreen>
+<verb>
+% cd /usr/local/Mathematica/Install
+% mathinfo
+LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented
+richc.isdn.bcm.tmc.edu 9845-03452-90255
+%
+</verb>
+</tscreen>
+So, for example, the `machine ID' of `richc' is `9845-03452-90255'.
+You can ignore the message about the ioctl that is not
+implemented. It won't prevent Mathematica from running
+in any way and you can safely ignore it, though you
+will see the message every time you run Mathematica.
+
+<p>When you register with Wolfram, either by email, phone
+or fax, you'll give them the 'machine ID' and they will
+respond with a corresponding password consisting of
+groups of numbers. You need to add them both along
+with the machine name and license number in your
+mathpass file.
+
+You can do this by invoking:
+<tscreen>
+<verb>
+% cd /usr/local/Mathematica/Install
+% math.install
+</verb>
+</tscreen>
+It will ask you to enter your license number and the
+Wolfram supplied password. If you get them mixed up or
+for some reason the math.install fails, That's OK,
+because you can simply edit the file 'mathpass' in this
+same directory to correct the info manually.
+
+<p>After getting past the password, math.install will ask
+you if you accept their canned install defaults, or if
+you want to use your own. If you are like us and
+distrust all install programs, you probably want to
+specify the actual directories. Beware. Although the
+math.install program asks you to specify directories,
+it won't create them for you, so you should perhaps
+have a second window open with another shell so that
+you can create them before you give them to the install
+program. Or, if it fails, you
+can create the directories and then restart the
+math.install program. The directories we chose to
+create beforehand and specify to math.install were:
+<tscreen>
+<verb>
+/usr/local/Mathematica/bin for binaries
+/usr/local/Mathematica/man/man1 for man pages
+/usr/local/Mathematica/lib/X11 for the XKeysymb file
+</verb>
+</tscreen>
+You can also tell it to use /tmp/math.record for the
+system record file, where it puts logs of sessions.
+After this math.install will continue on to
+unpacking things and placing everything where it should
+go.
+
+<p>The Mathematica Notebook feature is included separately,
+as the X Front End, and you have to install it separately.
+To get the X Front End stuff correctly installed, cd
+into the /usr/local/Mathematica/FrontEnd directory and
+executed the ./xfe.install shell script. You'll have
+to tell it where to put things, but you don't have to
+create any directories because it uses all the same
+directories that had been created for math.install.
+When it finished, there should be a new shell script in
+/usr/local/Mathematica/bin called "mathematica".
+
+<p>Lastly, you need to modify each of the shell scripts that
+Mathematica has installed. At the beginning of every shell script in
+/usr/local/Mathematica/bin add the following line:
+<tscreen>
+<verb>
+XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB
+</verb>
+</tscreen>
+This tells Mathematica were to find it's own version of the key
+mapping file XKeysymDB. Without this you will get pages of error
+messages about missing key mappings.
+
+On FreeBSD-stable you need to add the following as well:
+<tscreen>
+<verb>
+RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF
+</verb>
+</tscreen>
+This tells Mathematica to use the linux version of host.conf. This
+file has a different syntax from FreeBSD's host.conf, so you'll get an
+error message about /etc/host.conf if you leave this out.
+
+<p>You might want to also modify your /etc/manpath.config file
+to read the new man directory, and you may need to edit your
+~/.cshrc file to add /usr/local/Mathematica/bin
+to your path.
+
+<p>That's about all it takes, With this you should be able
+to type "mathematica" and get a really slick looking
+Mathematica Notebook screen up. Mathematica has included
+the Motif user interfaces, but it's compiled in statically,
+so you don't need the Motif libraries. Good luck doing this
+yourself!
+
+<sect1><heading>Bugs</heading>
+
+<p>The Notebook front end is known to hang sometimes when reading
+notebook files with an error messages similar to:
+<tscreen>
+<verb>
+File .../Untitled-1.mb appears to be broken for OMPR.257.0
+</verb>
+</tscreen>
+
+We haven't found the cause for this, but it only affects the
+Notebook's X window front end, not the mathematica engine itself. So
+the command line interface invoked by 'math' is unaffected by this
+bug.
+
+<sect1><heading>Acknowledgments</heading>
+
+<p>A well-deserved thanks should go to &a.sos; and &a.peter;
+who made linux emulation what it is today, and Michael Smith who
+drove these two guys like dogs to get it to the point where it runs
+Linux binaries better than linux! :-)
diff --git a/handbook/lists.sgml b/handbook/lists.sgml
new file mode 100644
index 0000000000..a3703f9481
--- /dev/null
+++ b/handbook/lists.sgml
@@ -0,0 +1,57 @@
+<!-- $Id: lists.sgml,v 1.1 1996-05-16 23:18:06 mpp Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<!--
+Names and email address of contributing authors and CVS committers
+and some of the common FreeBSD mailing lists. Use these
+entities when referencing people or mailing lists. Please
+note the use of single
+and double quotes.
+-->
+
+<!ENTITY a.announce "FreeBSD announcments mailing list
+ <tt><htmlurl url='mailto:freebsd-announce@FreeBSD.ORG'
+ name='&lt;freebsd-announce@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.doc "FreeBSD documentation project mailing list
+ <tt><htmlurl url='mailto:freebsd-doc@FreeBSD.ORG'
+ name='&lt;freebsd-doc@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.bugs "FreeBSD problem reports mailing list
+ <tt><htmlurl url='mailto:freebsd-doc@FreeBSD.ORG'
+ name='&lt;freebsd-doc@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.current "FreeBSD-current mailing list
+ <tt><htmlurl url='mailto:freebsd-current@FreeBSD.ORG'
+ name='&lt;freebsd-current@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.emulation "FreeBSD-emulation mailing list
+ <tt><htmlurl url='mailto:freebsd-emulation@FreeBSD.ORG'
+ name='&lt;freebsd-emulation@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.fs "FreeBSD filesystem project mailing list
+ <tt><htmlurl url='mailto:freebsd-fs@FreeBSD.ORG'
+ name='&lt;freebsd-fs@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.hackers "FreeBSD technical discussions mailing list
+ <tt><htmlurl url='mailto:freebsd-hackers@FreeBSD.ORG'
+ name='&lt;freebsd-hackers@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.ports "FreeBSD ports mailing list
+ <tt><htmlurl url='mailto:freebsd-ports@FreeBSD.ORG'
+ name='&lt;freebsd-ports@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.questions "FreeBSD general questions mailing list
+ <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG'
+ name='&lt;freebsd-questions@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.scsi "FreeBSD SCSI subsystem mailing list
+ <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG'
+ name='&lt;freebsd-questions@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.stable "FreeBSD-stable mailing list
+ <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG'
+ name='&lt;freebsd-questions@FreeBSD.ORG&gt;'></tt>">
+
+<!ENTITY a.majordomo "<tt><htmlurl url='mailto:majordomo@FreeBSD.ORG'
+ name='&lt;majordomo@FreeBSD.ORG&gt;'></tt>">
diff --git a/handbook/pgpkeys.sgml b/handbook/pgpkeys.sgml
new file mode 100644
index 0000000000..49838d9142
--- /dev/null
+++ b/handbook/pgpkeys.sgml
@@ -0,0 +1,200 @@
+<!-- $Id: pgpkeys.sgml,v 1.6 1996-06-11 18:05:47 rich Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<chapt><heading>PGP keys<label id="pgpkeys"></heading>
+ <p> In case you need to verify a signature or send encrypted
+ email to one of the officers or core team members a
+ number of keys are provided here for your convenience.
+ <sect><heading>Officers</heading>
+ <sect1><heading>
+FreeBSD Security Officer &lt;security-officer@freebsd.org&gt;
+ </heading> <p>
+<tscreen><verb>
+FreeBSD Security Officer &lt;security-officer@freebsd.org&gt;
+Fingerprint = 41 08 4E BB DB 41 60 71 F9 E5 0E 98 73 AF 3F 11
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.3i
+
+mQCNAzF7MY4AAAEEAK7qBgPuBejER5HQbQlsOldk3ZVWXlRj54raz3IbuAUrDrQL
+h3g57T9QY++f3Mot2LAf5lDJbsMfWrtwPrPwCCFRYQd6XH778a+l4ju5axyjrt/L
+Ciw9RrOC+WaPv3lIdLuqYge2QRC1LvKACIPNbIcgbnLeRGLovFUuHi5z0oilAAUR
+tDdGcmVlQlNEIFNlY3VyaXR5IE9mZmljZXIgPHNlY3VyaXR5LW9mZmljZXJAZnJl
+ZWJzZC5vcmc+iQCVAwUQMX6yrOJgpPLZnQjrAQHyowQA1Nv2AY8vJIrdp2ttV6RU
+tZBYnI7gTO3sFC2bhIHsCvfVU3JphfqWQ7AnTXcD2yPjGcchUfc/EcL1tSlqW4y7
+PMP4GHZp9vHog1NAsgLC9Y1P/1cOeuhZ0pDpZZ5zxTo6TQcCBjQA6KhiBFP4TJql
+3olFfPBh3B/Tu3dqmEbSWpuJAJUDBRAxez3C9RVb+45ULV0BAak8A/9JIG/jRJaz
+QbKom6wMw852C/Z0qBLJy7KdN30099zMjQYeC9PnlkZ0USjQ4TSpC8UerYv6IfhV
+nNY6gyF2Hx4CbEFlopnfA1c4yxtXKti1kSN6wBy/ki3SmqtfDhPQ4Q31p63cSe5A
+3aoHcjvWuqPLpW4ba2uHVKGP3g7SSt6AOYkAlQMFEDF8mz0ff6kIA1j8vQEBmZcD
+/REaUPDRx6qr1XRQlMs6pfgNKEwnKmcUzQLCvKBnYYGmD5ydPLxCPSFnPcPthaUb
+5zVgMTjfjS2fkEiRrua4duGRgqN4xY7VRAsIQeMSITBOZeBZZf2oa9Ntidr5PumS
+9uQ9bvdfWMpsemk2MaRG9BSoy5Wvy8VxROYYUwpT8Cf2iQCVAwUQMXsyqWtaZ42B
+sqd5AQHKjAQAvolI30Nyu3IyTfNeCb/DvOe9tlOn/o+VUDNJiE/PuBe1s2Y94a/P
+BfcohpKC2kza3NiW6lLTp00OWQsuu0QAPc02vYOyseZWy4y3Phnw60pWzLcFdemT
+0GiYS5Xm1o9nAhPFciybn9j1q8UadIlIq0wbqWgdInBT8YI/l4f5sf6JAJUDBRAx
+ezKXVS4eLnPSiKUBAc5OBACIXTlKqQC3B53qt7bNMV46m81fuw1PhKaJEI033mCD
+ovzyEFFQeOyRXeu25Jg9Bq0Sn37ynISucHSmt2tUD5W0+p1MUGyTqnfqejMUWBzO
+v4Xhp6a8RtDdUMBOTtro16iulGiRrCKxzVgEl4i+9Z0ZiE6BWlg5AetoF5n3mGk1
+lw==
+=ipyA
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
+
+ <sect><heading>Core team members</heading>
+ <sect1><heading>&a.jkh</heading><p>
+
+<tscreen><verb>
+Jordan K. Hubbard &lt;jkh@FreeBSD.org&gt;
+Fingerprint = 3C F2 27 7E 4A 6C 09 0A 4B C9 47 CD 4F 4D 0B 20
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.2i
+
+mQCNAzFjX0IAAAEEAML+nm9/kDNPp43ZUZGjYkm2QLtoC1Wxr8JulZXqk7qmhYcQ
+jvX+fyoriJ6/7ZlnLe2oG5j9tZOnRLPvMaz0g9CpW6Dz3nkXrNPkmOFV9B8D94Mk
+tyFeRJFqnkCuqBj6D+H8FtBwEeeTecSh2tJ0bZZTXnAMhxeOdvUVW/uOVC1dAAUR
+tCNKb3JkYW4gSy4gSHViYmFyZCA8amtoQEZyZWVCU0Qub3JnPokAlQMFEDF75D1r
+WmeNgbKneQEBXtcD+gJIv8JzZRKlDZyTCQanK8iRgE+zMhxptI0kDObaGxT1BrpY
+4/EPyiUN10G4k2Jb+DOc8Lg2xDQ3xmvgipFf9NMNV/ThaEuZ3wA31I6tW/arQEqB
+Tp8u6T3v20m62t7Afo9HaoE6MBpHQUk2TilxgAd5P57sporL3pgW9YojIO9ziQCV
+AwUQMXyV2h9/qQgDWPy9AQEMfgP/RmbSg2WlesATUQ4WuanjcdREduKPyfQatrXD
+2xt+jg9X78dTyiNN1YvLqvT6msfs04MKSC0hA2mou6ozw8Xak+1QmP0fBOZKp9pP
+8szO188Do9ByzJPvHF1eXT7jFMOXVq8ZIl9iwjxcIDLzlxOz49DC7LO6AT+LKQk7
+UGeP+lqJAJUDBRAxe+UG9RVb+45ULV0BAXZ9A/9F9gLpGukVNkeOjaqxQdJGTS+a
+xh/Abk0c/nKhAEyxpAl5JyQ3ifYk6BHhPvlTi9LrZoXGA8sk/eU4eRTZVzvGEC4G
++xsavlE/xzku8855QTLPpkCunUpQeu1wzaIrUUE6Zjh05imFbJYyQOBgTFpuqWsC
+rsUpl+2mr8IGIxG5rA==
+=LW9i
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
+
+ <sect1><heading>&a.phk</heading><p>
+
+<tscreen><verb>
+Poul-Henning Kamp &lt;phk@FreeBSD.org&gt;
+Fingerprint = A3 F3 88 28 2F 9B 99 A2 49 F4 E2 FA 5A 78 8B 3E
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.3i
+
+mQCNAzAdpMIAAAEEALHDgrFUwhZtb7PbXg3upELoDVEUPFRwnmpJH1rRqyROUGcI
+ooVe7u+FQlIs5OsXK8ECs/5Wpe2UrZSzHvjwBYOND5H42YtI5UULZLRCo5bFfTVA
+K9Rpo5icfTsYihrzU2nmnycwFMk+jYXyT/ZDYWDP/BM9iLjj0x9/qQgDWPy9AAUR
+tCNQb3VsLUhlbm5pbmcgS2FtcCA8cGhrQEZyZWVCU0Qub3JnPokAlQMFEDF+jX1r
+WmeNgbKneQEBCrID/i/ri8/eXUXRJp2fqJqzvrWGTP9Ix1O4vMguah9IILijgpYy
+OJYkezZKijjVCVmLX7EwfNXfYkqLAWUa08eov4QfJfJDgfe+Z/3/UoX7RcJoy2Aj
+TBZQzOI9JMkrzFdtFGYwMr/QXhOdVVpSGeZ/6Hkrs7pd2Z6MNNrRf81ZyJyYiQCV
+AwUQMXyV5/UVW/uOVC1dAQFyfAP/SujU+lS2WQuat4O2wZOQ1rswUt6CthG8MOsc
+7A9kfXnZbaM9Sdxj54CtAlqR4eJMOYk2kVqAtmCWETRuonJxr5TAJdf7q6kByVYc
+QEyDZvKJYwyrI9UQSelSgczWwiSB01aV9ACaKlEF9iHYvIKBa9HwJu3A9ggW9SYa
+AHcxHzuJAJUDBRAxSx5cH3+pCANY/L0BAY+TA/9YQPISXYaS+5r0I60wCJ+i3a9P
+C69Zak2ikgTHQi97LhpVtEsP3SAYInDw4YMS2oU9w1XxoiLLd9hUpcZlmO8Ip3vN
+F+E2ZCfR4sNzKarY5fdo+sxzatGWRPgnHjbm6RHWCw6qJACDD3VpaFjx2XD8QrOT
+yiObnbHhWBdoEAIyNokAlQMFEDE5Q6DvYbnpEdWO1QEBsvgD/0c6flBrSWr20oj8
+eRJ1zl8ZAP/rpV0IEBvb3ZFsHsJL8QzTsx1typFFghrT7SDBDc52xY90JWAflEiG
+n9aIL5Q+RHVxjw30yDaRPAl9ll82o34GBaWBEw83bsI6Fg2XxDfc2X0KkEutlYAE
+XjiM95PQS+9PM//llDtPvkSxgpiJiQCVAwUQMOavJADy2QnruxtBAQE92wQAsKPq
+/U4G4ksslOXGaauSoBk9XO3lB147cSpra1w9ZxTSeo+8dgzNlxnugWDnw1mxauFJ
+BAMgHl74rrlD+Hp0Ltb9oOyRl3riPG0TOdfaS3T8w6vw52wOKzUrZ/0pB+2sDHzU
+qZXBbhOq3OXs1ZMNe3jh8w62JsLBWry/YMWRMnI=
+=MDQ9
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
+
+ <sect1><heading>&a.joerg</heading><p>
+
+<tscreen><verb>
+Joerg Wunsch &lt;j@uriah.heep.sax.de&gt;
+Fingerprint = DC 47 E6 E4 FF A6 E9 8F 93 21 E0 7D F9 12 D6 4E
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.2i
+
+mQCNAzGCFeAAAAEEAKmRBU2Nvc7nZy1Ouid61HunA/5hF4O91cXm71/KPaT7dskz
+q5sFXvPJPpawwvqHPHfEbAK42ZaywyFp59L1GaYj87Pda+PlAYRJyY2DJl5/7JPe
+ziq+7B8MdvbX6D526sdmcR+jPXPbHznASjkx9DPmK+7TgFujyXW7bjh2o/exAAUR
+tCJKb2VyZyBXdW5zY2ggPGpAdXJpYWguaGVlcC5zYXguZGU+iQCVAwUQMalkbHW7
+bjh2o/exAQFwwQP+Pa82QeWpJE0m7f4DXd/DiYAvh/DeXWtub1fXQ9yqAL131n8O
+zsSLMb0PwG/qyZrpK61sT3bAvtVlNftaxmuD7yaf1SUQ3rNmsBq5/oju/3EKEiFc
+4gtuyaXG74y7y1XASIstck/0byfvO2t4z0R7d1RRnKRYeCspMcUjYshsoJeJAJUD
+BRAxpL3UPiAdBSUb0JkBAZg7BACE+mKhsrd39/P6NattCCOSg76Pf2CVgZdvbb7q
+K4SmsVGz+58pi2OWM1M0rcHgNZKTIg9rBy47gui2KOnqOR7ZuyMVJJqyEZZywmWm
+fCy/sR4Ui1PehZNNNBAi09u03ItbozrEH6Msa1oC8mp86XOA70Et8e4DYtj5a9tV
+bjjtJYkAlQMFEDGCUB31FVv7jlQtXQEB5KgD/iIJZe5lFkPr2B/Cr7BKMVBot1/J
+Su05NsHgJZ3uK15w4mVtNPZcFi/dKbn+qRM6LKDFe/GF0HZD/ZD1FJt8yQjzF2w3
+40B+F2GGEOwnClqZDtEAqnIBzM/ECQQqH+6Bi8gpkFZrFgg5eON7ikqmusDnOlYS
+tM/CBfgpSbR8kDmFtCZKb2VyZyBXdW5zY2ggPGpAaW50ZXJmYWNlLWJ1c2luZXNz
+LmRlPokAlQMFEDGpbnd1u244dqP3sQEBJnQD/RVSAzgf4uorv3fpbosI0LE3LUuf
+AYGBSJNJnskeKyudZkNkI5zGGDwVneH/cSkKT4ORooeqcTBxKeMaMuXPVl30Qahg
+NwWjfuTvl5OZ8orsQGGWIn5FhqYXsKkjEGxIOBOfvvlVQ0UbcR0N2+5F6Mb5GqrX
+ZpIesn7jFJpkQKPU
+=46Ab
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
+
+ <sect1><heading>&a.ache</heading><p>
+
+<tscreen><verb>
+Andrey A. Chernov &lt;ache@FreeBSD.org&gt;
+Fingerprint = 33 03 9F 48 33 7B 4A 15 63 48 88 0A C4 97 FD 49
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.3ia
+
+mQCNAiqUMGQAAAEEAPGhcD6A2Buey5LYz0sphDLpVgOZc/bb9UHAbaGKUAGXmafs
+Dcb2HnsuYGgX/zrQXuCi/wIGtXcZWB97APtKOhFsZnPinDR5n/dde/mw9FnuhwqD
+m+rKSL1HlN0z/Msa5y7g16760wHhSR6NoBSEG5wQAHIMMq7Q0uJgpPLZnQjrAAUT
+tDJBbmRyZXkgQS4gQ2hlcm5vdiwgQmxhY2sgTWFnZSA8YWNoZUBhc3RyYWwubXNr
+LnN1PokAlQMFEDArAKOf6xq8qC/IdwEB6tUEAIncjRagPYb65jHI6WO3LCVRZRr4
++e+Fo+Bj2qN6WXrkGjAZrFqmly2J1lPwJXW+pE8+vp0XEF+dMxR9Ex0j3wKcBFu8
+sm0kyOWqSZlk96oSjdr5izYNsjc4ai08xyw9ZR94taX0KvFnr6zX4y1HKOUv1bnp
+E5mv6LJ8wgsO30MwiQCVAwUQMCr8KGtaZ42Bsqd5AQEYoQQAqF696nxuuYRQsiiS
+Epozr2qBq2p8VCJHg0tMkHUx84UPncAdToYSteRNDcK9DCmoyzJvdJ+vmXW+cvxS
+I6T64rvHSK5R61mZXsGvPHhAzPkPzcU9YmIPh2igwBNe9Y5i6UqQi9DIibTtIt+i
+93pFQ+x7/L33zmRz0h4qyMyTmU2JAJUDBRAwGrusxS1HbQ2/kG0BAUF/A/wMcJGH
+hWmMWWDBTgxyL0pNt4QLIwplANlIpdRXlgLrG/qPMUXzw3O056LKyInyamxefn3B
+whuVUkxpYQYXdfGFlHmm3/4fTtgbEF+eclkbgdsd3YidcSP1VXRvq8ZTAphOGUdU
+5fcfjLbp/SqilaQd/VZZAgWEN4ZYDbf0yVGOK4kAlQMFEDARzJsiUZbZZm0AUQEB
+UJMD/2At2obN2TDKK4jpbd2cRjVFD0xe6yBEd4/nO5qhhuOnRJwwebFK5M2nKaC1
++bI9bRkd278/WuL5pNQL9yhTTb62Wd/wWRRqat5gk4gAvc7MjWEPC9AHxiFDuYKA
+iI6sDkzUCADqTbCeUvpzAJEAeGJpjZSOhk29w9fM34T2ernIiQCVAgUQMA9LJeLl
+u+H7XhUZAQFrAAP/TWKgUQSm5pbUA6ciuPowQGI5FwSZgERVyiWE5Z04DhzKWaqF
+clvesZ2muTM8RIru2VpuaC9dEAyKdZK5AT9inJr30jDB2+WhggkHNvz/DZX1wLh7
+TRs2IiNFACMIvIof0tZYlX756hfbld3d5KBO1bEPTgOEKNGS9oIFvv4BGmCJAJUD
+BRAwDs+qsfyMh3t65eEBASL2A/4yK/F6qP9iOYJ3IIUnhUdNZ9LxCxSL2heHB6Hx
+s8swaWLHwPuqYBSNSDPi1Bd5G1JAGP9rkn/VORAnGjAk1gsFYCVTvqBtO+UhxDOG
+7oa87rWYjNXU8k2nqWj6U8kTFFMfWTDGCbO7G6iyHdXg8KycVD4awTb3/8NltrGB
+0mPHHYkAlQMFEDAM6oB3HZKuiXLHwQEBk8cEALYHixYtq4UjnZZaQ11MM/kkumxI
+xU1oEbFhTMvUJznKq8sOy8rhZlnop+I2rI2NN9ybDg31kD4j1TQN1BJ11YPfp/AL
+zTDzvCZEbwp9XjYNFWicvSd+vLgK4qPd2oHdmH/0ea/kBLj4yLLFZPIXXMv5bhIU
+ol1n+myzFRxANCfjiQCVAwUQMA1IvuJgpPLZnQjrAQGrQQQAhwfqrVvPNLHkQg2S
+45f209W9eOaaOtFO7umtzxAZGNDQO9rVg0LkTxfwp/9PlXRTcUFLIJK28GiVjqIt
+CkLL5Tpt0a7MSm5/brxCi8RMcih96cae+pL8/5RFsBHirwSvvOD29Zc6Rt1u7tlw
+34t1UD04t+UmTAB3OgtArf5ozZWJAJUDBRAwDKzw+8I/jbEzFDkBASXJA/4pOFrG
+c5tqjsfRcHqxqu2cHIXPiatWHjeT8ac6kn+ABu/u3RSJ/qHul9hXCM4G2GPiH5oC
+SBxFYwxx+frgF8m+peIinPPXkGsDt7fPKXxyyVm085p74M9nDK8bfeB0b4JB373K
+RhIG8pXauhAd9zrp2sxXH2RUSHF5NbH8iw72BA==
+=ekPo
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
+
+ <sect1><heading>&a.rich</heading><p>
+
+<tscreen><verb>
+Rich Murphey &lt;rich@FreeBSD.org&gt;
+fingerprint = AF A0 60 C4 84 D6 0C 73 D1 EF C0 E9 9D 21 DB E4
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: 2.6.2
+
+mQCNAy97V+MAAAEEALiNM3FCwm3qrCe81E20UOSlNclOWfZHNAyOyj1ahHeINvo1
+FBF2Gd5Lbj0y8SLMno5yJ6P4F4r+x3jwHZrzAIwMs/lxDXRtB0VeVWnlj6a3Rezs
+wbfaTeSVyh5JohEcKdoYiMG5wjATOwK/NAwIPthB1RzRjnEeer3HI3ZYNEOpAAUR
+tCRSaWNoIE11cnBoZXkgPHJpY2hAbGFtcHJleS51dG1iLmVkdT6JAJUDBRAve15W
+vccjdlg0Q6kBAZTZBACcNd/LiVnMFURPrO4pVRn1sVQeokVX7izeWQ7siE31Iy7g
+Sb97WRLEYDi686osaGfsuKNA87Rm+q5F+jxeUV4w4szoqp60gGvCbD0KCB2hWraP
+/2s2qdVAxhfcoTin/Qp1ZWvXxFF7imGA/IjYIfB42VkaRYu6BwLEm3YAGfGcSw==
+=QoiM
+-----END PGP PUBLIC KEY BLOCK-----
+</verb></tscreen>
diff --git a/handbook/quotas.sgml b/handbook/quotas.sgml
new file mode 100644
index 0000000000..4f10b91396
--- /dev/null
+++ b/handbook/quotas.sgml
@@ -0,0 +1,208 @@
+<!-- This is an SGML document in the linuxdoc DTD describing
+ disk quotas under FreeBSD. By Mike Pritchard, 1996.
+
+ $Id: quotas.sgml,v 1.3 1996-05-15 19:40:57 mpp Exp $
+
+ The FreeBSD Documentation Project
+
+<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
+
+ <article>
+ <title> Disk quotas
+ <author> Mike Pritchard <tt/mpp@FreeBSD.org/
+ <date> 26 February 1996, (c) 1996
+
+ <abstract> This document describes configuration and administration
+ of disk quotas under FreeBSD. </abstract>
+
+ <toc>
+-->
+
+ <chapt><heading>Disk quotas<label id="quotas"></heading>
+
+ <p><em>Contributed by &a.mpp;.<newline>26 February 1996</em>
+
+ Quotas are an optional feature of the operating system that allow
+ you to limit the amount of disk space and/or the number of files
+ a user, or members of a group, may allocate on a per-file system basis.
+ This is used most often on timesharing systems where it is desirable
+ to limit the amount of resources any one user or group of users may
+ allocate. This will prevent one user from consuming all of
+ the available disk space.
+
+<sect><heading>Configuring your system to enable disk quotas</heading>
+
+ <p>Before attempting to use disk quotas it is
+ necessary to make sure that quotas are configured in your kernel.
+ This is done by adding the following line to your kernel configuration file:
+<verb>
+options QUOTA
+</verb>
+ The stock GENERIC kernel does not have this enabled by default, so you
+ will have to configure, build and install a custom kernel in order to use
+ disk quotas. Please refer to the
+ <ref id="kernelconfig" name="Configuring the FreeBSD Kernel">
+ section for more information on kernel configuration.
+
+ <p>Next you will need to enable disk quotas in <tt>/etc/sysconfig</tt>.
+ This is done by changing the line:
+<verb>
+quotas=NO
+</verb>
+to:
+<verb>
+quotas=YES
+</verb>
+
+ <p>Finally you will need to edit <tt>/etc/fstab</tt> to enable
+ disk quotas on a per-file system basis. This is where you can
+ either enable user or group quotas or both for all of your file
+ systems.
+
+ <p>To enable per-user quotas on a file system, add the
+ <tt>userquota</tt> option to the options field in the
+ <tt>/etc/fstab</tt> entry for the file system you want to
+ to enable quotas on. For example:
+<verb>
+/dev/sd1s2g /home ufs rw,userquota 1 2
+</verb>
+
+ <p>Similarly, to enable group quotas, use the <tt>groupquota</tt>
+ option instead of the <tt>userquota</tt> keyword. To enable both
+ user and group quotas, change the entry as follows:
+<verb>
+/dev/sd1s2g /home ufs rw,userquota,groupquota 1 2
+</verb>
+
+ <p>By default the quota files are stored in the root directory of the file
+ system with the names <tt>quota.user</tt> and <tt>quota.group</tt>
+ for user and group quotas respectively. See <tt>man fstab</tt> for more
+ information. Even though that man page says that you can specify an
+ alternate location for the quota files, this is not recommended since
+ all of the various quota utilities do not seem to handle this
+ properly.
+
+ <p>At this point you should reboot your system with your new kernel.
+ <tt>/etc/rc</tt> will automatically run the appropriate commands to
+ create the initial quota files for all of quotas you enabled
+ in <tt>/etc/fstab</tt>, so there is no need to manually create any
+ zero length quota files.
+
+ <p>In the normal course of operations you should not be required
+ to run the <tt>quotacheck</tt>, <tt>quotaon</tt>, or <tt>quotaoff</tt>
+ commands manually. However, you may want to read their man pages
+ just to be familiar with their operation.
+
+<sect><heading>Setting quota limits</heading>
+
+ <p>Once you have configured your system to enable quotas, verify that
+ they really are enabled. An easy way to do this is to run
+ <tt>quota -v</tt>. You should see a one line summary of disk
+ usage and current quota limits for each file system that
+ quotas are enabled on.
+
+ <p>You are now ready to start assigning quota limits
+ with the <tt>edquota</tt> command.
+
+ <p>You have several options on how to enforce limits on the amount of
+ disk space a user or group may allocate, and how many files they may create.
+ You may limit allocations based on disk space (block quotas) or
+ number of files (inode quotas) or a combination of both.
+ Each of these limits are further broken down into two categories: hard and
+ soft limits.
+
+ <p>A hard limit may not be exceeded. Once a user reaches their hard
+ limit they may not make any further allocations on the file system
+ in question. For example, if the user has a hard limit of 500 blocks
+ on a file system and is currently using 490 blocks, the user can only allocate
+ an additional 10 blocks. Attempting to allocate an additional 11 blocks
+ will fail.
+
+ <p>Soft limits on the other hand can be exceeded for a limited amount
+ of time. This period of time is known as the grace period, which is
+ one week by default. If a user stays over his or her soft limit longer
+ than their grace period, the soft limit will turn into a hard limit
+ and no further allocations will be allowed. When the user drops
+ back below the soft limit, the grace period will be reset.
+
+ <p>The following is an example of what you might see when
+ you run then <tt>edquota</tt> command. When the <tt>edquota</tt>
+ command is invoked, you are placed into the editor specified by the
+ <tt>EDITOR</tt> environment variable, or in the <tt>vi</tt> editor
+ if the <tt>EDITOR</tt> variable is not set, to
+ allow you to edit the quota limits.
+<verb>
+# edquota -u test
+Quotas for user test:
+/usr: blocks in use: 65, limits (soft = 50, hard = 75)
+ inodes in use: 7, limits (soft = 50, hard = 60)
+/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
+ inodes in use: 0, limits (soft = 50, hard = 60)
+</verb>
+ You will normally see two lines for each file system that has
+ quotas enabled. One line for the block limits, and one line
+ for inode limits. Simply change the value you want updated
+ to modify the quota limit. For example, to raise this users
+ block limit from a soft limit of 50 and a hard limit of 75
+ to a soft limit of 500 and a hard limit of 600, change:
+<verb>
+/usr: blocks in use: 65, limits (soft = 50, hard = 75)
+</verb>
+to:
+<verb>
+/usr: blocks in use: 65, limits (soft = 500, hard = 600)
+</verb>
+ The new quota limits will be in place when you exit the editor.
+
+ <p>Sometimes it is desirable to set quota limits on a range
+ of uids. This can be done by use of the <tt>-p</tt> option
+ on the <tt>edquota</tt> command. First, assign the desired
+ quota limit to a user, and then run
+ <tt>edquota -p protouser startuid-enduid</tt>.
+ For example, if user <tt>test</tt> has the desired quota
+ limits, the following command can be used to duplicate
+ those quota limits for uids 10,000 through 19,999:
+<verb>
+edquota -p test 10000-19999
+</verb>
+
+ <p>The ability to specify uid ranges was added to the system
+ after 2.1 was released. If you need this feature on a 2.1
+ system, you will need to obtain a newer copy of edquota.
+
+ <p>See <tt>man edquota</tt> for more detailed information.
+
+<sect><heading>Checking quota limits and disk usage</heading>
+
+ <p>You can use either the <tt>quota</tt> or the <tt>repquota</tt>
+ commands to check quota limits and disk usage. The <tt>quota</tt>
+ command can be used to check individual user and group quotas and
+ disk usage. Only the super-user may examine quotas and usage for
+ other users, or for groups that they are not a member of.
+ The <tt>repquota</tt> command can be used to get a summary of all
+ quotas and disk usage for file systems with quotas enabled.
+
+ <p>The following is some sample output from the <tt>quota -v</tt>
+ command for a user that has quota limits on two file systems.
+
+<verb>
+Disk quotas for user test (uid 1002):
+ Filesystem blocks quota limit grace files quota limit grace
+ /usr 65* 50 75 5days 7 50 60
+ /usr/var 0 50 75 0 50 60
+</verb>
+ On the /usr file system in the above example this user is
+ currently 15 blocks over their soft limit of 50 blocks and has 5 days of
+ their grace period left. Note the asterisk (*) which indicates that
+ the user is currently over their quota limit.
+
+ <p>Normally file systems that the user is not using any disk space
+ on will not show up in the output from the <tt>quota</tt> command,
+ even if they have a quota limit assigned for that file system.
+ The <tt>-v</tt> option will display those file systems, such as
+ the <tt>/usr/var</tt> file system in the above example.
+
+<sect><heading>* Quotas over NFS</heading>
+
+ <p>This section is still under development.
+
diff --git a/handbook/sio.sgml b/handbook/sio.sgml
new file mode 100644
index 0000000000..116a5159f7
--- /dev/null
+++ b/handbook/sio.sgml
@@ -0,0 +1,207 @@
+<!-- $Id: sio.sgml,v 1.2 1996-03-26 23:22:03 mpp Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<!--
+<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
+
+<!ENTITY % authors SYSTEM "authors.sgml">
+%authors;
+
+]>
+-->
+<sect2><heading>Configuring the <tt>sio</tt> driver<label id="sio"></heading>
+
+ <p>The <tt>sio</tt> driver provides support for NS8250-,
+ NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT
+ V.24) communications interfaces. Several multiport
+ cards are supported as well. See the <tt>sio(4)</tt>
+ manual page for detailed technical documentation.
+
+<sect3><heading>Digi International (DigiBoard) PC/8</heading>
+
+ <p><em>Contributed by &a.awebster;.<newline>26 August
+ 1995.</em>
+
+ Here is a config snippet from a machine with
+ a Digi International PC/8 with 16550. It has 8 modems connected
+ to these 8 lines, and they work just great. Do not
+ forget to add <tt>options "COM_MULTIPORT"</tt> or it
+ will not work very well!
+
+<tscreen><verb>
+device sio4 at isa? port 0x100 tty flags 0xb05
+device sio5 at isa? port 0x108 tty flags 0xb05
+device sio6 at isa? port 0x110 tty flags 0xb05
+device sio7 at isa? port 0x118 tty flags 0xb05
+device sio8 at isa? port 0x120 tty flags 0xb05
+device sio9 at isa? port 0x128 tty flags 0xb05
+device sio10 at isa? port 0x130 tty flags 0xb05
+device sio11 at isa? port 0x138 tty flags 0xb05 irq 9 vector siointr
+</verb></tscreen>
+
+ The trick in setting this up is that the MSB of the
+ flags represent the last SIO port, in this case 11 so
+ flags are 0xb05.
+
+<sect3><heading>Boca 16</heading>
+
+ <p><em>Contributed by &a.whiteside;.<newline>26 August
+ 1995.</em>
+
+ The procedures to make a Boca 16 pord board with
+ FreeBSD are pretty straightforward, but you will need
+ a couple things to make it work:
+
+ <enum>
+ <item>You either need the kernel sources installed
+ so you can recompile the necessary options or
+ you will need someone else to compile it for you.
+ The 2.0.5 default kernel does <bf>not</bf> come with
+ multiport support enabled and you will need to add
+ a device entry for each port anyways.
+ </item>
+ <item>Two, you will need to know the interrupt and IO
+ setting for your Boca Board so you can set these
+ options properly in the kernel.</item>
+ </enum>
+
+ One important note - the actual UART chips for the
+ Boca 16 are in the connector box, not on the internal
+ board itself. So if you have it unplugged, probes of
+ those ports will fail. I have never tested booting with
+ the box unplugged and plugging it back in, and I
+ suggest you do not either.
+
+ If you do not already have a custom kernel
+ configuration file set up, refer to <ref
+ id="kernelconfig" name="Kernel Configuration"> for
+ general procedures. The following are the specifics
+ for the Boca 16 board and assume you are using the
+ kernel name MYKERNEL and editing with vi.
+
+ <enum>
+ <item>Add the line
+<tscreen><verb>
+options "COM_MULTIPORT"
+</verb></tscreen>
+to the config file.
+</item>
+
+ <item>Where the current <tt>device sio
+ <em>xxx</em></tt> lines are, you will need to add
+ 16 more devices. <em>Only the last device
+ includes the interrupt vector for the
+ board</em>. (See the <tt>sio(4)</tt> manual page
+ for detail as to why.)
+
+ The following example is for a Boca Board with an
+ interrupt of 3, and a base IO address 100h. The
+ IO address for Each port is +8 hexadecimal from
+ the previous port, thus the 100h, 108h, 110h...
+ addresses.
+
+<tscreen><verb>
+device sio1 at isa? port 0x100 tty flags 0x1005
+device sio2 at isa? port 0x108 tty flags 0x1005
+device sio3 at isa? port 0x110 tty flags 0x1005
+device sio4 at isa? port 0x118 tty flags 0x1005
+[...]
+device sio15 at isa? port 0x170 tty flags 0x1005
+device sio16 at isa? port 0x178 tty flags 0x1005 irq 3 vector siointr
+</verb></tscreen>
+
+ The flags entry <em>must</em> be changed from
+ this example unless you are using the exact same
+ sio assignments. Flags are set according to
+ 0x<em>MYY</em> where <em>M</em> indicates the
+ minor number of the master port (the last port on
+ a Boca 16) and <em>YY</em> indicates if FIFO is
+ enabled or disabled(enabled), IRQ sharing is
+ used(yes) and if there is an AST/4 compatible IRQ
+ control register(no).
+
+ In this example,
+<tscreen><verb>
+flags 0x1005
+</verb></tscreen>
+
+ indicates that the master port is sio16. If I
+ added another board and assigned sio17 through
+ sio28, the flags for all 16 ports on
+ <em>that</em> board would be 0x1C05, where 1C
+ indicates the minor number of the master port.
+ Do not change the 05 setting.</item>
+
+ <item>Save and complete the kernel configuration,
+ recompile, install and reboot.
+
+ Presuming you have successfully installed the
+ recompiled kernel and have it set to the correct
+ address and IRQ, your boot message should
+ indicate the successful probe of the Boca ports
+ as follows: (obviously the sio numbers, IO and
+ IRQ could be different)
+
+<tscreen><verb>
+sio1 at 0x100-0x107 flags 0x1005 on isa
+sio1: type 16550A (multiport)
+sio2 at 0x108-0x10f flags 0x1005 on isa
+sio2: type 16550A (multiport)
+sio3 at 0x110-0x117 flags 0x1005 on isa
+sio3: type 16550A (multiport)
+sio4 at 0x118-0x11f flags 0x1005 on isa
+sio4: type 16550A (multiport)
+sio5 at 0x120-0x127 flags 0x1005 on isa
+sio5: type 16550A (multiport)
+sio6 at 0x128-0x12f flags 0x1005 on isa
+sio6: type 16550A (multiport)
+sio7 at 0x130-0x137 flags 0x1005 on isa
+sio7: type 16550A (multiport)
+sio8 at 0x138-0x13f flags 0x1005 on isa
+sio8: type 16550A (multiport)
+sio9 at 0x140-0x147 flags 0x1005 on isa
+sio9: type 16550A (multiport)
+sio10 at 0x148-0x14f flags 0x1005 on isa
+sio10: type 16550A (multiport)
+sio11 at 0x150-0x157 flags 0x1005 on isa
+sio11: type 16550A (multiport)
+sio12 at 0x158-0x15f flags 0x1005 on isa
+sio12: type 16550A (multiport)
+sio13 at 0x160-0x167 flags 0x1005 on isa
+sio13: type 16550A (multiport)
+sio14 at 0x168-0x16f flags 0x1005 on isa
+sio14: type 16550A (multiport)
+sio15 at 0x170-0x177 flags 0x1005 on isa
+sio15: type 16550A (multiport)
+sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa
+sio16: type 16550A (multiport master)
+</verb></tscreen>
+
+ If the messages go by too fast to see, <tt>dmesg
+ &gt; more</tt> will show you the boot
+ messages.</item>
+
+ <item>Next, appropriate entries in <tt>/dev</tt> for the devices
+ must be made using the <tt>/dev/MAKEDEV</tt>
+ script. After becoming root:
+<tscreen>
+# cd /dev<newline>
+# ./MAKEDEV tty1<newline>
+# ./MAKEDEV cua1<newline>
+<em>(everything in between)</em><newline>
+# ./MAKEDEV ttyg<newline>
+# ./MAKEDEV cuag
+</tscreen>
+
+ If you do not want or need callout devices for some
+ reason, you can dispense with making the <tt>cua*</tt>
+ devices.</item>
+
+ <item>If you want a quick and sloppy way to make
+ sure the devices are working, you can simply plug
+ a modem into each port and (as root) <tt>echo at
+ &gt; ttyd*</tt> for each device you have
+ made. You <em>should</em> see the RX lights flash
+ for each working port.</item>
+ </enum>
+
diff --git a/handbook/stable.sgml b/handbook/stable.sgml
new file mode 100644
index 0000000000..0ca1f74526
--- /dev/null
+++ b/handbook/stable.sgml
@@ -0,0 +1,108 @@
+<!-- $Id: stable.sgml,v 1.2 1996-05-16 23:18:19 mpp Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+
+<chapt><heading>Staying stable with FreeBSD<label id="stable"></heading>
+
+<p><em>Contributed by &a.jkh;.</em>
+
+<!--
+
+ THE FREEBSD STABLE POLICY
+
+Last updated: $Date: 1996-05-16 23:18:19 $
+
+This document attempts to explain the rationale behind
+FreeBSD-stable, what you should expect should you decide to run it,
+and states some prerequisites for making sure the process goes as
+smoothly as possible.
+-->
+
+<sect><heading>What is FreeBSD-stable?</heading>
+
+<p>FreeBSD-stable is our development branch for a more low-key and
+conservative set of changes intended for our next mainstream release.
+Changes of an experimental or untested nature do not go into this
+branch (see <ref id="current" name="FreeBSD-current">).
+
+<sect><heading>Who needs FreeBSD-stable?</heading>
+
+<p>If you are a commercial user or someone who puts maximum stability of
+their FreeBSD system before all other concerns, you should consider tracking
+<em>stable</em>. This is especially true if you have installed the most
+recent release (<htmlurl url="ftp://ftp.freebsd.org/pub/FreeBSD/2.1.0-RELEASE"
+name="2.1.0-RELEASE"> at the time of this writing) since the <em>stable</em>
+branch is effectively a bug-fix stream relative to the previous release.
+
+<p>Please note that the <em>stable</em> tree endevors, above all, to
+be fully compilable and stable at all times, but we do occasionally
+make mistakes (these are still active sources with quickly-transmitted
+updates, after all). We also do our best to thoroughly test fixes in
+<em>current</em> before bringing them into <em>stable</em>, but sometimes
+our tests fail to catch every case. If something breaks for you in
+<em>stable</em>, please let us know <em>immediately!</em> (see
+next section).
+
+<sect><heading>Using FreeBSD-stable</heading>
+
+ <p><enum><item> Join the freebsd-stable mailing list. This will
+ keep you informed of build-dependencies that may appear in
+ <em>stable</em> or any other issues requring special attention.
+ Developers will also make announcements in this mailing list when
+ they are contemplating some contraversal fix or update, giving
+ the users a chance to respond if they have any issues to raise concerning
+ the proposed change.
+
+ To join this list, send mail to &a.majordomo and say:
+<verb>
+ subscribe freebsd-stable
+</verb>
+ In the body of your message. Optionally, you can also say `help'
+ and Majordomo will send you full help on how to subscribe and
+ unsubscribe to the various other mailing lists we support.
+
+ <item> Grab the sources from ftp.FreeBSD.ORG. You can do this in
+ three ways:
+
+ <enum>
+ <item> Using the CTM facility described below. Unless you
+ have a good TCP/IP connection at a flat rate, this is
+ the way to do it.
+
+ <item> Use the CMU `sup' program (Software Update
+ Protocol), also described below.
+ This is the second most recommended method, since it allows
+ you to grab the entire collection once and then only what has
+ changed from then on. Many people run sup from cron
+ and keep their sources up-to-date automatically.
+
+ <item> Use ftp. The source tree for FreeBSD-stable is always
+ "exported" on:
+ <htmlurl url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable"
+ name="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable">
+
+ <p>We also use `wu-ftpd' which allows compressed/tar'd grabbing
+ of whole trees. e.g. you see:
+<verb>
+ usr.bin/lex
+</verb>
+ You can do:
+<verb>
+ ftp> cd usr.bin
+ ftp> get lex.tar.Z
+</verb>
+ And it will get the whole directory for you as a compressed
+ tar file.
+ </enum>
+
+ <item> Essentially, if you need rapid on-demand access to the source and
+ communications bandwidth is not a consideration, use sup or ftp.
+ Otherwise, use CTM.
+
+ <item> Before compiling stable, read the Makefile in /usr/src
+ carefully. You should at least run a `make world' the first time
+ through as part of the upgrading process.
+ Reading freebsd-stable will keep you up-to-date on other bootstrapping
+ procedures that sometimes become necessary as we move towards the next
+ release.
+</enum>
diff --git a/handbook/synching.sgml b/handbook/synching.sgml
new file mode 100644
index 0000000000..ea5cd85a84
--- /dev/null
+++ b/handbook/synching.sgml
@@ -0,0 +1,21 @@
+<!-- $Id: synching.sgml,v 1.1 1996-02-11 00:16:20 jkh Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<chapt><heading>Synchronizing source trees over the Internet<label id="synching"></heading>
+
+<p><em>Contributed by &a.jkh;.</em>
+
+<!--
+
+Last updated: $Date: 1996-02-11 00:16:20 $
+
+This document tries to describe the various ways in which a user may
+use the internet to keep development sources in synch.
+-->
+
+ <p>There are various ways of using an Internet (or email) connection
+ to stay up-to-date with whatever collection of FreeBSD project sources
+ it is that interests you. The primary services we offer are:
+
+ &sup;
+ &ctm;
diff --git a/handbook/uart.sgml b/handbook/uart.sgml
new file mode 100644
index 0000000000..1db38b5973
--- /dev/null
+++ b/handbook/uart.sgml
@@ -0,0 +1,1108 @@
+<!-- $Id: uart.sgml,v 1.2 1996-02-27 15:57:51 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<!--
+<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
+
+<!ENTITY % authors SYSTEM "authors.sgml">
+%authors;
+
+]>
+-->
+<sect2><heading>The UART: What it is and how it works<label id="uart"></heading>
+
+<p><em>Copyright &copy; 1996 &a.uhclem;, All Rights Reserved.<newline>
+13 January 1996.</em>
+
+<!-- Version 1(2) 13-Jan-96 -->
+
+ The Universal Asynchronous Receiver/Transmitter (UART) controller
+ is the key component of the serial communications subsystem of a
+ computer. The UART takes bytes of data and transmits the individual
+ bits in a sequential fashion. At the destination, a second UART
+ re-assembles the bits into complete bytes.
+
+ Serial transmission is commonly used with modems and for
+ non-networked communication between computers, terminals
+ and other devices.
+
+ There are two primary forms of serial transmission: Synchronous and
+ Asynchronous. Depending on the modes that are supported by the
+ hardware, the name of the communication sub-system will usually
+ include a "A" if it supports Asynchronous communications, and a
+ "S" if it supports Synchronous communications. Both forms are
+ described below.
+
+ Some common acryonyms are:
+<quote>UART Universal Asynchronous Receiver/Transmitter</quote>
+<quote>USART Universal Synchronous-Asynchronous Receiver/Transmitter</quote>
+
+
+<sect3><heading>Synchronous Serial Transmission</heading>
+
+ <p>Synchronous serial transmission requires that the sender and
+ receiver share a clock with one another, or that the sender provide
+ a strobe or other timing signal so that the receiver knows when to
+ "read" the next bit of the data. In most forms of serial
+ Synchronous communication, if there is no data available at a given
+ instant to transmit, a fill character must be sent instead so that
+ data is always being transmitted. Synchronous communication is
+ usually more efficient because only data bits are transmitted
+ between sender and receiver, and synchronous communication can be
+ more more costly if extra wiring and circuits are required to
+ share a clock signal between the sender and receiver.
+
+ A form of Synchronous transmission is used with printers and
+ fixed disk devices in that the data is sent on one set of wires
+ while a clock or strobe is sent on a different wire. Printers and
+ fixed disk devices are not normally serial devices because most
+ fixed disk interface standards send an entire word of data for each
+ clock or strobe signal by using a separate wire for each bit of the
+ word. In the PC industry, these are known as Parallel devices.
+
+ The standard serial communications hardware in the PC does not
+ support Synchronous operations. This mode is described here for
+ comparison purposes only.
+
+
+<sect3><heading>Asynchronous Serial Transmission</heading>
+
+ <p>Asynchronous transmission allows data to be transmitted without
+ the sender having to send a clock signal to the receiver. Instead,
+ the sender and receiver must agree on timing parameters in advance
+ and special bits are added to each word which are used to
+ synchronize the sending and receiving units.
+
+ When a word is given to the UART for Asynchronous transmissions,
+ a bit called the "Start Bit" is added to the beginning of each word
+ that is to be transmitted. The Start Bit is used to alert the
+ receiver that a word of data is about to be sent, and to force the
+ clock in the receiver into synchronization with the clock in the
+ transmitter. These two clocks must be accurate enough to not
+ have the frequency drift by more than 10% during the transmission
+ of the remaining bits in the word. (This requirement was set in
+ the days of mechanical teleprinters and is easily met by modern
+ electronic equipment.)
+
+ After the Start Bit, the individual bits of the word of data are
+ sent, with the Least Significant Bit (LSB) being sent first. Each
+ bit in the transmission is transmitted for exactly the same
+ amount of time as all of the other bits, and the receiver "looks"
+ at the wire at approximately halfway through the period assigned
+ to each bit to determine if the bit is a "1" or a "0". For example,
+ if it takes two seconds to send each bit, the receiver will examine
+ the signal to determine if it is a "1" or a "0" after one second
+ has passed, then it will wait two seconds and then examine the value
+ of the next bit, and so on.
+
+ The sender does not know when the receiver has "looked" at the
+ value of the bit. The sender only knows when the clock says to
+ begin transmitting the next bit of the word.
+
+ When the entire data word has been sent, the transmitter may add
+ a Parity Bit that the transmitter generates. The Parity Bit may
+ be used by the receiver to perform simple error checking. Then at
+ least one Stop Bit is sent by the transmitter.
+
+ When the receiver has received all of the bits in the data word,
+ it may check for the Parity Bits (both sender and receiver must
+ agree on whether a Parity Bit is to be used), and then the receiver
+ looks for a Stop Bit. If the Stop Bit does not appear when it is
+ supposed to, the UART considers the entire word to be garbled and
+ will report a Framing Error to the host processor when the data
+ word is read. The usual cause of a Framing Error is that the sender
+ and receiver clocks were not running at the same speed, or that
+ the signal was interrupted.
+
+ Regardless of whether the data was received correctly or not, the
+ UART automatically discards the Start, Parity and Stop bits. If the
+ sender and receiver are configured identically, these bits are not
+ passed to the host.
+
+ If another word is ready for transmission, the Start Bit for the new
+ word can be sent as soon as the Stop Bit for the previous
+ word has been sent.
+
+ Because asynchronous data is "self synchronizing", if there is no
+ data to transmit, the transmission line can be idle.
+
+
+<sect3><heading>Other UART Functions</heading>
+
+ <p>In addition to the basic job of converting data from parallel to
+ serial for transmission and from serial to parallel on reception,
+ a UART will usually provide additional circuits for signals that
+ can be used to indicate the state of the transmission media, and
+ to regulate the flow of data in the event that the remote device
+ is not prepared to accept more data. For example, when the
+ device connected to the UART is a modem, the modem may report the
+ presence of a carrier on the phone line while the computer may be
+ able to instruct the modem to reset itself or to not take calls
+ by asserting or deasserting one more more of these extra signals.
+ The function of each of these additional signals is defined in
+ the EIA RS232-C standard.
+
+
+<sect3><heading>The RS232-C and V.24 Standards</heading>
+
+ <p>In most computer systems, the UART is connected to circuitry that
+ generates signals that comply with the EIA RS232-C specification.
+ There is also a CCITT standard named V.24 that mirrors the
+ specifications included in RS232-C.
+
+<sect4><heading>RS232-C Bit Assignments (Marks and Spaces)</heading>
+
+ <p>In RS232-C, a value of "1" is called a "Mark" and a value of "0"
+ is called a "Space". When a communication line is idle, the line
+ is said to be "Marking", or transmitting continuous "1" values.
+
+ The Start bit always has a value of "0" (a Space). The Stop Bit
+ always has a value of "1" (a Mark). This means that there will
+ always be a Mark (1) to Space (0) transition on the line at the
+ start of every word, even when multiple word are
+ transmitted back to back. This guarantees that sender and
+ receiver can resynchronize their clocks regardless of the content
+ of the data bits that are being transmitted.
+
+ The idle time between Stop and Start bits does not have
+ to be an exact multiple (including zero) of the bit rate of the
+ communication link, but most UARTs are designed this way for
+ simplicity.
+
+ In RS232-C, the "Marking" signal (a "1") is represented by a voltage
+ between -2 VDC and -12 VDC, and a "Spacing" signal (a "0") is
+ represented by a voltage between 0 and +12 VDC. The transmitter
+ is supposed to send +12 VDC or -12 VDC, and the receiver is supposed
+ to allow for some voltage loss in long cables. Some transmitters
+ in low power devices (like portable computers) sometimes use only
+ +5 VDC and -5 VDC, but these values are still acceptable to a
+ RS232-C receiver, provided that the cable lengths are short.
+
+
+<sect4><heading>RS232-C Break Signal</heading>
+
+ <p>RS232-C also specifies a signal called a "Break", which is caused
+ by sending continuous Spacing values (no Start or Stop bits). When
+ there is no electricity present on the data circuit, the line is
+ considered to be sending "Break".
+
+ The "Break" signal must be of a duration longer than the time
+ it takes to send a complete byte plus Start, Stop and Parity bits.
+ Most UARTs can distinguish between a Framing Error and a
+ Break, but if the UART cannot do this, the Framing Error detection
+ can be used to identify Breaks.
+
+ In the days of teleprinters, when numerous printers around the
+ country were wired in series (such as news services), any unit
+ could cause a "Break" by temporarily opening the entire circuit
+ so that no current flowed. This was used to allow a location with
+ urgent news to interrupt some other location that was currently
+ sending information.
+
+ In modern systems there are two types of Break signals. If the
+ Break is longer than 1.6 seconds, it is considered a "Modem Break",
+ and some modems can be programmed to terminate the conversation and
+ go on-hook or enter the modems' command mode when the modem detects
+ this signal. If the Break is smaller than 1.6 seconds, it signifies
+ a Data Break and it is up to the remote computer to respond to
+ this signal. Sometimes this form of Break is used as an Attention
+ or Interrupt signal and sometimes is accepted as a substitute for
+ the ASCII CONTROL-C character.
+
+ Marks and Spaces are also equivalent to "Holes" and "No Holes"
+ in paper tape systems.
+
+ Note that Breaks cannot be generated from paper tape or from any
+ other byte value, since bytes are always sent with Start and Stop
+ bit. The UART is usually capable of generating the continuous
+ Spacing signal in response to a special command from the host
+ processor.
+
+<sect4><heading>RS232-C DTE and DCE Devices</heading>
+
+ <p>The RS232-C specification defines two types of equipment: the Data
+ Terminal Equipment (DTE) and the Data Carrier Equipment (DCE).
+ Usually, the DTE device is the terminal (or computer), and the DCE
+ is a modem. Across the phone line at the other end of a
+ conversation, the receiving modem is also a DCE device and the
+ computer that is connected to that modem is a DTE device. The DCE
+ device receives signals on the pins that the DTE device transmits on,
+ and vice versa.
+
+ When two devices that are both DTE or both DCE must be connected
+ together without a modem or a similar media translater between them,
+ a NULL modem must be used. The NULL modem electrically re-arranges
+ the cabling so that the transmitter output is connected to the
+ receiver input on the other device, and vice versa. Similar
+ translations are performed on all of the control signals so that
+ each device will see what it thinks are DCE (or DTE) signals from
+ the other device.
+
+ The number of signals generated by the DTE and DCE devices are
+ not symmetrical. The DTE device generates fewer signals for
+ the DCE device than the DTE device receives from the DCE.
+
+<sect4><heading>RS232-C Pin Assignments</heading>
+
+ <p>The EIA RS232-C specification (and the ITU equivalent, V.24) calls
+ for a twenty-five pin connector (usually a DB25) and defines the
+ purpose of most of the pins in that connector.
+
+ In the IBM Personal Computer and similar systems, a subset of
+ RS232-C signals are provided via nine pin connectors (DB9).
+ The signals that are not included on the PC connector deal mainly
+ with synchronous operation, and this transmission mode is not
+ supported by the UART that IBM selected for use in the IBM PC.
+
+ Depending on the computer manufacturer, a DB25, a DB9, or
+ both types of connector may be used for RS232-C communications.
+ (The IBM PC also uses a DB25 connector for the parallel printer
+ interface which causes some confusion.)
+
+ Below is a table of the RS232-C signal assignments in the DB25
+ and DB9 connectors.
+
+<verb>
+DB25 DB9 EIA CCITT Common Signal Description
+RS232-C IBM PC Circuit Circuit Name Source
+Pin Pin Symbol Symbol
+
+1 - AA 101 PG/FG --- Frame/Protective Ground
+2 3 BA 103 TD DTE Transmit Data
+3 2 BB 104 RD DCE Receive Data
+4 7 CA 105 RTS DTE Request to Send
+5 8 CB 106 CTS DCE Clear to Send
+6 6 CC 107 DSR DCE Data Set Ready
+7 5 AV 102 SG/GND --- Signal Ground
+8 1 CF 109 DCD/CD DCE Data Carrier Detect
+9 - - - - - Reserved for Test
+10 - - - - - Reserved for Test
+11 - - - - - Unassigned
+12 - CI 122 SRLSD DCE Sec. Recv. Line Signal Detector
+13 - SCB 121 SCTS DCE Secondary Clear To Send
+14 - SBA 118 STD DTE Secondary Transmit Data
+15 - DB 114 TSET DCE Trans. Sig. Element Timing
+16 - SBB 119 SRD DCE Secondary Received Data
+17 - DD 115 RSET DCE Receiver Signal Element Timing
+18 - - 141 LOOP DTE Local Loopback
+19 - SCA 120 SRS DTE Secondary Request to Send
+20 4 CD 108.2 DTR DTE Data Terminal Ready
+21 - - - RDL DTE Remote Digital Loopback
+22 9 CE 125 RI DCE Ring Indicator
+23 - CH 111 DSRS DTE Data Signal Rate Selector
+24 - DA 113 TSET DTE Trans. Sig. Element Timing
+25 - - 142 - DCE Test Mode
+</verb>
+
+
+ <sect3><heading>Bits, Baud and Symbols</heading>
+
+ <p>Baud is a measurment of transmission speed in asynchronous
+ communication. Because of advances in modem communication
+ technology, this term is frequently misused when describing
+ the data rates in newer devices.
+
+ Traditionally, a Baud Rate represents the number of bits that are
+ actually being sent over the media, not the amount of data
+ that is actually moved from one DTE device to the other. The
+ Baud count includes the overhead bits Start, Stop and Parity
+ that are generated by the sending UART and removed by the
+ receiving UART. This means that seven-bit words of data
+ actually take 10 bits to be completely transmitted.
+ Therefore, a modem capable of moving 300 bits per second from one
+ place to another can normally only move 30 7-bit words if
+ Parity is used and one Start and Stop bit are present.
+
+ If 8-bit data words are used and Parity bits are also used, the
+ data rate falls to 27.27 words per second, because it now
+ takes 11 bits to send the eight-bit words, and the modem still
+ only sends 300 bits per second.
+
+ The formula for converting bytes per second into a baud rate
+ and vice versa was simple until error-correcting modems
+ came along. These modems receive the serial stream of bits
+ from the UART in the host computer (even when internal modems
+ are used the data is still frequently serialized) and converts
+ the bits back into bytes. These bytes are then combined into
+ packets and sent over the phone line using a Synchronous
+ transmission method. This means that the Stop, Start, and Parity
+ bits added by the UART in the DTE (the computer) were removed by
+ the modem before transmission by the sending modem. When these
+ bytes are received by the remote modem, the remote modem adds
+ Start, Stop and Parity bits to the words, converts them to a
+ serial format and then sends them to the receiving UART in the remote
+ computer, who then strips the Start, Stop and Parity bits.
+
+ The reason all these extra conversions are done is so that the
+ two modems can perform error correction, which means that the
+ receiving modem is able to ask the sending modem to resend a
+ block of data that was not received with the correct checksum.
+ This checking is handled by the modems, and the DTE devices are
+ usually unaware that the process is occurring.
+
+ By striping the Start, Stop and Parity bits, the additional bits of
+ data that the two modems must share between themselves to perform
+ error-correction are mostly concealed from the effective
+ transmission rate seen by the sending and receiving DTE equipment.
+ For example, if a modem sends ten 7-bit words to another modem
+ without including the Start, Stop and Parity bits, the sending
+ modem will be able to add 30 bits of its own information that
+ the receiving modem can use to do error-correction without
+ impacting the transmission speed of the real data.
+
+ The use of the term Baud is further confused by modems that perform
+ compression. A single 8-bit word passed over the telephone
+ line might represent a dozen words that were transmitted to
+ the sending modem. The receiving modem will expand the data back
+ to its original content and pass that data to the receiving DTE.
+
+ Modern modems also include buffers that allow the rate that
+ bits move across the phone line (DCE to DCE) to be a different speed
+ than the speed that the bits move between the DTE and DCE on both
+ ends of the conversation. Normally the speed between the DTE and
+ DCE is higher than the DCE to DCE speed because of the use of
+ compression by the modems.
+
+ Because the number of bits needed to describe a byte varied
+ during the trip between the two machines plus the differing
+ bits-per-seconds speeds that are used present on the DTE-DCE and
+ DCE-DCE links, the usage of the term Baud to describe the
+ overall communication speed causes problems and can misrepresent
+ the true transmission speed. So Bits Per Second (bps) is the correct
+ term to use to describe the transmission rate seen at the
+ DCE to DCE interface and Baud or Bits Per Second are acceptable
+ terms to use when a connection is made between two systems with a
+ wired connection, or if a modem is in use that is not performing
+ error-correction or compression.
+
+ Modern high speed modems (2400, 9600, 14,400, and 19,200bps) in
+ reality still operate at or below 2400 baud, or more accurately,
+ 2400 Symbols per second. High speed modem are able to encode more
+ bits of data into each Symbol using a technique called Constellation
+ Stuffing, which is why the effective bits per second rate of the
+ modem is higher, but the modem continues to operate within the
+ limited audio bandwidth that the telephone system provides.
+ Modems operating at 28,800 and higher speeds have variable Symbol
+ rates, but the technique is the same.
+
+ <sect3><heading>The IBM Personal Computer UART</heading>
+
+ <p>Starting with the original IBM Personal Computer, IBM selected
+ the National Semiconductor INS8250 UART for use in the IBM PC
+ Parallel/Serial Adapter. Subsequent generations of compatible
+ computers from IBM and other vendors continued to use the INS8250
+ or improved versions of the National Semiconductor UART family.
+
+
+<sect4><heading>National Semiconductor UART Family Tree</heading>
+
+ <p>There have been several versions and subsequent generations of
+ the INS8250 UART. Each major version is described below.
+
+<verb>
+ INS8250 -> INS8250B
+ \
+ \
+ \-> INS8250A -> INS82C50A
+ \
+ \
+ \-> NS16450 -> NS16C450
+ \
+ \
+ \-> NS16550 -> NS16550A -> PC16550D
+</verb>
+
+<descrip>
+ <tag>INS8250</tag>This part was used in the original IBM PC and
+ IBM PC/XT. The original name for this part was the INS8250 ACE
+ (Asynchronous Communications Element) and it is made from NMOS
+ technology.
+
+ The 8250 uses eight I/O ports and has a one-byte send and
+ a one-byte receive buffer. This original UART has several
+ race conditions and other flaws. The original IBM BIOS
+ includes code to work around these flaws, but this made
+ the BIOS dependent on the flaws being present, so subsequent
+ parts like the 8250A, 16450 or 16550 could not be used in
+ the original IBM PC or IBM PC/XT.
+
+ <tag>INS8250-B</tag>This is the slower speed of the INS8250 made
+ from NMOS technology. It contains the same problems as the original
+ INS8250.
+
+ <tag>INS8250A</tag>An improved version of the INS8250 using XMOS
+ technology with various functional flaws corrected. The INS8250A
+ was used initially in PC clone computers by vendors who used
+ "clean" BIOS designs. Because of the corrections in the chip, this
+ part could not be used with a BIOS compatible with the INS8250
+ or INS8250B.
+
+ <tag>INS82C50A</tag>This is a CMOS version (low power consumption)
+ of the INS8250A and has similar functional characteristics.
+
+ <tag>NS16450</tag>Same as NS8250A with improvements so it can be
+ used with faster CPU bus designs. IBM used this part in the IBM AT
+ and updated the IBM BIOS to no longer rely on the bugs in the
+ INS8250.
+
+ <tag>NS16C450</tag>This is a CMOS version (low power consumption)
+ of the NS16450.
+
+ <tag>NS16550</tag>Same as NS16450 with a 16-byte send and receive
+ buffer but the buffer design was flawed and could not be reliably
+ be used.
+
+ <tag>NS16550A</tag>Same as NS16550 with the buffer flaws corrected.
+ The 16550A and its successors have become the most popular UART
+ design in the PC industry, mainly due it its ability to reliably
+ handle higher data rates on operating systems with sluggish interrupt
+ response times.
+
+ <tag>NS16C552</tag>This component consists of two NS16C550A CMOS
+ UARTs in a single package.
+
+ <tag>PC16550D</tag>Same as NS16550A with subtle flaws corrected. This
+ is revision D of the 16550 family and is the latest design available
+ from National Semiconductor.
+</descrip>
+
+<sect4><heading>The NS16550AF and the PC16550D are the same thing</heading>
+
+ <p>National reorganized their part numbering system a few years ago,
+ and the NS16550AFN no longer exists by that name. (If you
+ have a NS16550AFN, look at the date code on the part, which is a
+ four digit number that usually starts with a nine. The first two
+ digits of the number are the year, and the last two digits are the
+ week in that year when the part was packaged. If you have a
+ NS16550AFN, it is probably a few years old.)
+
+ The new numbers are like PC16550DV, with minor differences in the
+ suffix letters depending on the package material and its shape.
+ (A description of the numbering system can be found below.)
+
+ It is important to understand that in some stores, you may pay
+ &dollar;15(US) for a NS16550AFN made in 1990 and in the next bin are the
+ new PC16550DN parts with minor fixes that National has made since the
+ AFN part was in production, the PC16550DN was probably made in the
+ past six months and it costs half (as low as &dollar;5(US) in volume) as
+ much as the NS16550AFN because they are readily available.
+
+ As the supply of NS16550AFN chips continues to shrink, the price will
+ probably continue to increase until more people discover and accept
+ that the PC16550DN really has the same function as the old part
+ number.
+
+<sect4><heading>National Semiconductor Part Numbering System</heading>
+
+ <p>The older NS<em>nnnnnrqp</em> part numbers are now of the
+ format PC<em>nnnnnrgp</em>.
+
+ The "<em>r</em>" is the revision field. The current revision of
+ the 16550 from National Semiconductor is "D".
+
+ The "<em>p</em>" is the package-type field. The types are:
+<verb> "F" QFP (quad flat pack) L lead type
+ "N" DIP (dual inline package) through hole straight lead type
+ "V" LPCC (lead plastic chip carrier) J lead type</verb>
+
+ The "<em>g</em>" is the product grade field. If an "I" preceeds
+ the package-type letter, it indicates an "industrial" grade part,
+ which has higher specs than a standard part but not as high as
+ Miltary Specification (Milspec) component. This is an optional field.
+
+ So what we used to call a NS16550AFN (DIP Package) is now called a
+ PC16550DN or PC16550DIN.
+
+
+ <sect3><heading>Other Vendors and Similar UARTs</heading>
+
+ <p>Over the years, the 8250, 8250A, 16450 and 16550 have been licensed
+ or copied by other chip vendors. In the case of the 8250, 8250A
+ and 16450, the exact circuit (the "megacell") was licensed to many
+ vendors, including Western Digital and Intel. Other vendors
+ reverse-engineered the part or produced emulations that had similar
+ behavior.
+
+ In internal modems, the modem designer will frequently emulate the
+ 8250A/16450 with the modem microprocessor, and the emulated UART will
+ frequently have a hidden buffer consisting of several hundred bytes.
+ Because of the suze of the buffer, these emulations can be as
+ reliable as a 16550A in their ability to handle high speed data.
+ However, most operating systems will still report that
+ the UART is only a 8250A or 16450, and may not make effective use
+ of the extra buffering present in the emulated UART unless special
+ drivers are used.
+
+ Some modem makers are driven by market forces to abandon a design
+ that has hundreds of bytes of buffer and instead use a 16550A UART
+ so that the product will compare favorably in market comparisons
+ even though the effective performance may be lowered by this action.
+
+ A common misconception is that all parts with "16550A" written on
+ them are identical in performance. There are differences, and in
+ some cases, outright flaws in most of these 16550A clones.
+
+ When the NS16550 was developed, the National Semiconductor obtained
+ several patents on the design and they also limited licensing, making
+ it harder for other vendors to provide a chip with similar features.
+ Because of the patents, reverse-engineered designs and emulations
+ had to avoid infringing the claims covered by the patents.
+ Subsequently, these copies almost never perform exactly the same as
+ the NS16550A or PC16550D, which are the parts most computer and
+ modem makers want to buy but are sometimes unwilling to pay the
+ price required to get the genuine part.
+
+ Some of the differences in the clone 16550A parts are unimportant,
+ while others can prevent the device from being used at all with a
+ given operating system or driver. These differences may show up
+ when using other drivers, or when particular combinations of events
+ occur that were not well tested or considered in the Windows driver.
+ This is because most modem vendors and 16550-clone makers use the
+ Microsoft drivers from Windows for Workgroups 3.11 and the Microsoft
+ MSD utility as the primary tests for compatibility with the
+ NS16550A. This over-simplistic criteria means that if a different
+ operating system is used, problems could appear due to subtle
+ differences between the clones and genuine components.
+
+ National Semiconductor has made available a program named COMTEST
+ that performs compatibility tests independent of any OS drivers.
+ It should be remembered that the purpose of this type of program is
+ to demonstrate the flaws in the products of the competition, so the
+ program will report major as well as extremely subtle differences in
+ behavior in the part being tested.
+
+ In a series of tests performed by the author of this document in
+ 1994, components made by National Semiconductor, TI, StarTech, and
+ CMD as well as megacells and emulations embedded in internal modems
+ were tested with COMTEST. A difference count for some of these
+ components is listed below. Because these tests were performed in
+ 1994, they may not reflect the current performance of the given
+ product from a vendor.
+
+ It should be noted that COMTEST normally aborts when an excessive
+ number or certain types of problems have been detected. As part of
+ this testing, COMTEST was modified so that it would not abort no
+ matter how many differences were encountered.
+
+
+<verb>Vendor Part number Errors aka "differences" reported
+National (PC16550DV) 0 *
+
+National (NS16550AFN) 0
+
+National (NS16C552V) 0 *
+
+TI (TL16550AFN) 3
+
+CMD (16C550PE) 19
+
+StarTech (ST16C550J) 23
+
+Rockwell reference modem
+ with internal 16550 or an
+ emulation (RC144DPi/C3000-25) 117
+
+Sierra modem with an internal
+ 16550 (SC11951/SC11351) 91</verb>
+
+ <p>It is important to understand that a simple count of differences
+ from COMTEST does not reveal a lot about what differences are
+ important and which are not. For example, about half of the
+ differences reported in the two modems listed above that have
+ internal UARTs were caused by the clone UARTs not supporting
+ five- and six-bit character modes. The real 16550, 16450, and
+ 8250 UARTs all support these modes and COMTEST checks the
+ functionality of these modes so over fifty differences are
+ reported. However, almost no modern modem supports five- or
+ six-bit characters, particularly those with error-correction
+ and compression capabilities. This means that the differences
+ related to five- and six-bit character modes can be discounted.
+
+ Many of the differences COMTEST reports have to do with timing. In
+ many of the clone designs, when the host reads from one port, the
+ status bits in some other port may not update in the same amount
+ of time (some faster, some slower) as a <em>real</em> NS16550AFN
+ and COMTEST looks for these differences. This means that the number
+ of differences can be misleading in that one device may only have
+ one or two differences but they are extremely serious, and some
+ other device that updates the status registers faster or slower
+ than the reference part (that would probably never affect the
+ operation of a properly written driver) could have dozens of
+ differences reported.
+
+ * To date, the author of this document has not found any non-National
+ parts that report zero differences using the COMTEST program. It
+ should also be noted that National has had five versions of the
+ 16550 over the years and the newest parts behave a bit differently
+ than the classic NS16550AFN that is considered the benchmark for
+ functionality. COMTEST appears to turn a blind eye to the
+ differences within the National product line and reports no errors
+ on the National parts (except for the original 16550) even when
+ there are official erattas that describe bugs in the A, B and C
+ revisions of the parts, so this bias in COMTEST must be taken into
+ account.
+
+ COMTEST can be used as a screening tool to alert the administrator
+ to the presence of potentially incompatible components
+ that might cause problems or have to be handled as a special case.
+
+ If you run COMTEST on a 16550 that is in a modem or a modem is
+ attached to the serial port, you need to first issue a ATE0&amp;W
+ command to the modem so that the modem will not echo any of the test
+ characters. If you forget to do this, COMTEST will report at least
+ this one difference:
+ <quote>Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61</quote>
+
+
+ <sect3><heading>8250/16450/16550 Registers</heading>
+
+ <p>The 8250/16450/16550 UART occupies eight contiguous I/O port
+ addresses. In the IBM PC, there are two defined locations for
+ these eight ports and they are known collectively as COM1 and COM2.
+ The makers of PC-clones and add-on cards have created two additional
+ areas known as COM3 and COM4, but these extra COM ports conflict
+ with other hardware on some systems. The most common conflict is
+ with video adapters that provide IBM 8514 emulation.
+
+<verb>
+COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4
+COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3
+COM3 is located from 0x3e8 to 0x3ef and has no standardized IRQ
+COM4 is located from 0x2e8 to 0x2ef and has no standardized IRQ
+</verb>
+<p>A description of the I/O ports of the 8250/16450/16550 UART is
+provided below.
+
+<verb>
+I/O Access Description
+Port Allowed
+
++0x00 write Transmit Holding Register (THR)
+ (DLAB==0) Information written to this port are treated
+ as data words and will be transmitted by the
+ UART.
+
++0x00 read Receive Buffer Register (RBR)
+ (DLAB==0) Any data words received by the UART from the
+ serial link are accessed by the host by
+ reading this port.
+
+
++0x00 write/read Divisor Latch LSB (DLL)
+ (DLAB==1) This value will be divided from the master
+ input clock (in the IBM PC, the master
+ clock is 1.8432MHz) and the resulting clock
+ will determine the baud rate of the UART.
+ This register holds bits 0 thru 7 of the
+ divisor.
+
+
++0x01 write/read Divisor Latch MSB (DLH)
+ (DLAB==1) This value will be divided from the master
+ input clock (in the IBM PC, the master
+ clock is 1.8432MHz) and the resulting clock
+ will determine the baud rate of the UART.
+ This register holds bits 8 thru 15 of the
+ divisor.
+
+
++0x01 write/read Interrupt Enable Register (IER)
+ (DLAB==0) The 8250/16450/16550 UART classifies events into
+ one of four categories. Each category can be
+ configured to generate an interrupt when any of
+ the events occurs. The 8250/16450/16550 UART
+ generates a single external interrupt signal
+ regardless of how many events in the enabled
+ categories have occurred. It is up to the host
+ processor to respond to the interrupt and then
+ poll the enabled interrupt categories (usually
+ all categories have interrupts enabled) to
+ determine the true cause(s) of the interrupt.
+
+ Bit 7 Reserved, always 0.
+
+ Bit 6 Reserved, always 0.
+
+ Bit 5 Reserved, always 0.
+
+ Bit 4 Reserved, always 0.
+
+ Bit 3 Enable Modem Status Interrupt (EDSSI)
+ Setting this bit to "1" allows the UART
+ to generate an interrupt when a
+ change occurs on one or more of the
+ status lines.
+
+ Bit 2 Enable Receiver Line Status
+ Interrupt (ELSI)
+ Setting this bit to "1" causes the UART
+ to generate an interrupt when the
+ an error (or a BREAK signal) has been
+ detected in the incoming data.
+
+ Bit 1 Enable Transmitter Holding Register
+ Empty Interrupt (ETBEI)
+ Setting this bit to "1" causes the UART
+ to generate an interrupt when the
+ UART has room for one or more
+ additional characters that are to
+ be transmitted.
+
+ Bit 0 Enable Received Data Available
+ Interrupt (ERBFI)
+ Setting this bit to "1" causes the UART
+ to generate an interrupt when the UART
+ has received enough characters to exceed
+ the trigger level of the FIFO, or the
+ FIFO timer has expired (stale data), or
+ a single character has been received
+ when the FIFO is disabled.
+
+
++0x02 write FIFO Control Register (FCR)
+ (This port does not exist on the 8250 and 16450
+ UART.)
+
+ Bit 7 Receiver Trigger Bit #1
+ Bit 6 Receiver Trigger Bit #0
+ These two bits control at what point the
+ receiver is to generate an interrupt when
+ the FIFO is active.
+
+ 7 6 How many words are received
+ before an interrupt is generated.
+ 0 0 1
+
+ 0 1 4
+
+ 1 0 8
+
+ 1 1 14
+
+ Bit 5 Reserved, always 0.
+
+ Bit 4 Reserved, always 0.
+
+ Bit 3 DMA Mode Select
+ If Bit 0 is set to "1" (FIFOs enabled),
+ setting this bit changes the operation
+ of the -RXRDY and -TXRDY signals from
+ Mode 0 to Mode 1.
+
+ Bit 2 Transmit FIFO Reset
+ When a "1" is written to this bit,
+ the contents of the FIFO are discarded.
+ Any word currently being transmitted
+ will be sent intact. This function is
+ useful in aborting transfers.
+
+ Bit 1 Receiver FIFO Reset
+ When a "1" is written to this bit,
+ the contents of the FIFO are discarded.
+ Any word currently being assembled
+ in the shift register will be received
+ intact.
+
+ Bit 0 16550 FIFO Enable
+ When set, both the transmit and receive
+ FIFOs are enabled. Any contents in the
+ holding register, shift registers or
+ FIFOs are lost when FIFOs are enabled or
+ disabled.
+
+
++0x02 read Interrupt Identification Register (IIR)
+
+ Bit 7 FIFOs enabled.
+ On the 8250/16450 UART, this bit is zero.
+
+ Bit 6 FIFOs enabled.
+ On the 8250/16450 UART, this bit is zero.
+
+ Bit 5 Reserved, always 0.
+
+ Bit 4 Reserved, always 0.
+
+ Bit 3 Interrupt ID Bit #2
+ On the 8250/16450 UART, this bit is zero.
+ Bit 2 Interrupt ID Bit #1
+ Bit 1 Interrupt ID Bit #0
+ These three bits combine to report
+ the category of event that caused the
+ interrupt that is in progress. These
+ categories have priorities, so if
+ multiple categories of events occur at
+ the same time, the UART will report the
+ more important events first and the host
+ must resolve the events in the order they
+ are reported. All events that caused the
+ current interrupt must be resolved before
+ any new interrupts will be generated.
+ (This is a limitation of the PC
+ architecture.)
+
+ 2 1 0 Priority Description
+
+ 0 1 1 First Receiver Error
+ (OE, PE, BI or FE)
+
+ 0 1 0 Second Received Data
+ Available
+
+ 1 1 0 Second Trigger level
+ identification
+ (Stale data in
+ receive buffer)
+
+ 0 0 1 Third Transmitter has
+ room for more
+ words (THRE)
+
+ 0 0 0 Fourth Modem Status
+ Change (-CTS,
+ -DSR, -RI, or
+ -DCD)
+
+ Bit 0 Interrupt Pending Bit
+ If this bit is set to "0", then at least
+ one interrupt is pending.
+
+
++0x03 write/read Line Control Register (LCR)
+
+ Bit 7 Divisor Latch Access Bit (DLAB)
+ When set, access to the data
+ transmit/receive register (THR/RBR) and
+ the Interrupt Enable Register (IER) is
+ disabled. Any access to these ports is
+ now redirected to the Divisor Latch
+ Registers. Setting this bit, loading
+ the Divisor Registers, and clearing
+ DLAB should be done with interrupts
+ disabled.
+
+ Bit 6 Set Break
+ When set to "1", the transmitter begins
+ to transmit continuous Spacing until
+ this bit is set to "0". This overrides
+ any bits of characters that are being
+ transmitted.
+
+ Bit 5 Stick Parity
+ When parity is enabled, setting this
+ bit causes parity to always be "1" or
+ "0", based on the value of Bit 4.
+
+ Bit 4 Even Parity Select (EPS)
+ When parity is enabled and Bit 5 is "0",
+ setting this bit causes even parity
+ to be transmitted and expected.
+ Otherwise, odd parity is used.
+
+ Bit 3 Parity Enable (PEN)
+ When set to "1", a parity bit is
+ inserted between the last bit of the
+ data and the Stop Bit. The UART will
+ also expect parity to be present in
+ the received data.
+
+ Bit 2 Number of Stop Bits (STB)
+ If set to "1" and using 5-bit data words,
+ 1.5 Stop Bits are transmitted and
+ expected in each data word. For 6, 7
+ and 8-bit data words, 2 Stop Bits are
+ transmitted and expected. When this bit
+ is set to "0", one Stop Bit is used on
+ each data word.
+
+ Bit 1 Word Length Select Bit #1 (WLSB1)
+ Bit 0 Word Length Select Bit #0 (WLSB0)
+ Together these bits specify the number
+ of bits in each data word.
+
+ 1 0 Word Length
+
+ 0 0 5 Data Bits
+ 0 1 6 Data Bits
+ 1 0 7 Data Bits
+ 1 1 8 Data Bits
+
+
++0x04 write/read Modem Control Register (MCR)
+
+ Bit 7 Reserved, always 0.
+
+ Bit 6 Reserved, always 0.
+
+ Bit 5 Reserved, always 0.
+
+ Bit 4 Loop-Back Enable
+ When set to "1", the UART transmitter
+ and receiver are internally connected
+ together to allow diagnostic operations.
+ In addition, the UART modem control
+ outputs are connected to the UART modem
+ control inputs. CTS is connected to RTS,
+ DTR is connected to DSR, OUT1 is
+ connected to RI, and OUT 2 is connected
+ to DCD.
+
+ Bit 3 OUT 2
+ An auxillary output that the host
+ processor may set high or low.
+ In the IBM PC serial adapter (and most
+ clones), OUT 2 is used to tri-state
+ (disable) the interrupt signal from the
+ 8250/16450/16550 UART.
+
+ Bit 2 OUT 1
+ An auxillary output that the host
+ processor may set high or low.
+ This output is not used on the IBM PC
+ serial adapter.
+
+ Bit 1 Request to Send (RTS)
+ When set to "1", the output of the UART
+ -RTS line is Low (Active).
+
+ Bit 0 Data Terminal Ready (DTR)
+ When set to "1", the output of the UART
+ -DTR line is Low (Active).
+
+
++0x05 write/read Line Status Register (LSR)
+
+ Bit 7 Error in Receiver FIFO
+ On the 8250/16450 UART, this bit is zero.
+ This bit is set to "1" when any of
+ the bytes in the FIFO have one or more
+ of the following error conditions: PE,
+ FE, or BI.
+
+ Bit 6 Transmitter Empty (TEMT)
+ When set to "1", there are no words
+ remaining in the transmit FIFO or the
+ transmit shift register. The
+ transmitter is completely idle.
+
+ Bit 5 Transmitter Holding Register Empty (THRE)
+ When set to "1", the FIFO (or holding
+ register) now has room for at least one
+ additional word to transmit. The
+ transmitter may still be transmitting
+ when this bit is set to "1".
+
+ Bit 4 Break Interrupt (BI)
+ The receiver has detected a Break signal.
+
+ Bit 3 Framing Error (FE)
+ A Start Bit was detected but the Stop
+ Bit did not appear at the expected time.
+ The received word is probably garbled.
+
+ Bit 2 Parity Error (PE)
+ The parity bit was incorrect for the
+ word received.
+
+ Bit 1 Overrun Error (OE)
+ A new word was received and there
+ was no room in the receive buffer. The
+ newly-arrived word in the shift
+ register is discarded. On 8250/16450
+ UARTs, the word in the holding
+ register is discarded and the newly-
+ arrived word is put in the holding
+ register.
+
+ Bit 0 Data Ready (DR)
+ One or more words are in the
+ receive FIFO that the host may read.
+ A word must be completely received
+ and moved from the shift register into
+ the FIFO (or holding register for
+ 8250/16450 designs) before this bit is
+ set.
+
+
++0x06 write/read Modem Status Register (MSR)
+
+ Bit 7 Data Carrier Detect (DCD)
+ Reflects the state of the DCD line
+ on the UART.
+
+ Bit 6 Ring Indicator (RI)
+ Reflects the state of the RI line on
+ the UART.
+
+ Bit 5 Data Set Ready (DSR)
+ Reflects the state of the DSR line on
+ the UART.
+
+ Bit 4 Clear To Send (CTS)
+ Reflects the state of the CTS line on
+ the UART.
+
+ Bit 3 Delta Data Carrier Detect (DDCD)
+ Set to "1" if the -DCD line has changed
+ state one more more times since the last
+ time the MSR was read by the host.
+
+ Bit 2 Trailing Edge Ring Indicator (TERI)
+ Set to "1" if the -RI line has had a
+ low to high transition since the last
+ time the MSR was read by the host.
+
+ Bit 1 Delta Data Set Ready (DDSR)
+ Set to "1" if the -DSR line has changed
+ state one more more times since the last
+ time the MSR was read by the host.
+
+ Bit 0 Delta Clear To Send (DCTS)
+ Set to "1" if the -CTS line has changed
+ state one more more times since the last
+ time the MSR was read by the host.
+
+
++0x07 write/read Scratch Register (SCR)
+ This register performs no function in the
+ UART. Any value can be written by the host to
+ this location and read by the host later on.
+</verb>
+
+ <sect3><heading>Beyond the 16550A UART</heading>
+
+ <p>Although National Semiconductor has not offered any components
+ compatible with the 16550 that provide additional features,
+ various other vendors have. Some of these components are described
+ below. It should be understood that to effectively utilize these
+ improvements, drivers may have to be provided by the chip vendor
+ since most of the popular operating systems do not support features
+ beyond those provided by the 16550.
+
+<descrip>
+<tag>ST16650</tag>By default this part is similar to the NS16550A, but an
+ extended 32-byte send and receive buffer can be optionally
+ enabled. Made by Startech.
+
+<tag>TIL16660</tag>By default this part behaves similar to the NS16550A,
+ but an extended 64-byte send and receive buffer can be
+ optionally enabled. Made by Texas Instruments.
+
+<tag>Hayes ESP</tag>This proprietary plug-in card contains a 2048-byte
+ send and receive buffer, and supports data rates
+ to 230.4Kbit/sec. Made by Hayes.
+</descrip>
+
+ <p>In addition to these "dumb" UARTs, many vendors produce
+ intelligent serial communication boards. This type of design
+ usually provides a microprocessor that interfaces with several
+ UARTs, processes and buffers the data, and then alerts the main
+ PC processor when necessary. Because the UARTs are not directly
+ accessed by the PC processor in this type of communication system,
+ it is not necessary for the vendor to use UARTs that are compatible
+ with the 8250, 16450, or the 16550 UART. This leaves the
+ designer free to components that may have better performance
+ characteristics.
+
+<!-- 601131 ? -->
+