diff options
Diffstat (limited to 'handbook')
| -rw-r--r-- | handbook/cyclades.sgml | 57 | ||||
| -rw-r--r-- | handbook/goals.sgml | 9 | ||||
| -rw-r--r-- | handbook/linuxemu.sgml | 700 | ||||
| -rw-r--r-- | handbook/lists.sgml | 57 | ||||
| -rw-r--r-- | handbook/pgpkeys.sgml | 200 | ||||
| -rw-r--r-- | handbook/quotas.sgml | 208 | ||||
| -rw-r--r-- | handbook/sio.sgml | 207 | ||||
| -rw-r--r-- | handbook/stable.sgml | 108 | ||||
| -rw-r--r-- | handbook/synching.sgml | 21 | ||||
| -rw-r--r-- | handbook/uart.sgml | 1108 |
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 +$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='<freebsd-announce@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.doc "FreeBSD documentation project mailing list + <tt><htmlurl url='mailto:freebsd-doc@FreeBSD.ORG' + name='<freebsd-doc@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.bugs "FreeBSD problem reports mailing list + <tt><htmlurl url='mailto:freebsd-doc@FreeBSD.ORG' + name='<freebsd-doc@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.current "FreeBSD-current mailing list + <tt><htmlurl url='mailto:freebsd-current@FreeBSD.ORG' + name='<freebsd-current@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.emulation "FreeBSD-emulation mailing list + <tt><htmlurl url='mailto:freebsd-emulation@FreeBSD.ORG' + name='<freebsd-emulation@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.fs "FreeBSD filesystem project mailing list + <tt><htmlurl url='mailto:freebsd-fs@FreeBSD.ORG' + name='<freebsd-fs@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.hackers "FreeBSD technical discussions mailing list + <tt><htmlurl url='mailto:freebsd-hackers@FreeBSD.ORG' + name='<freebsd-hackers@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.ports "FreeBSD ports mailing list + <tt><htmlurl url='mailto:freebsd-ports@FreeBSD.ORG' + name='<freebsd-ports@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.questions "FreeBSD general questions mailing list + <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG' + name='<freebsd-questions@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.scsi "FreeBSD SCSI subsystem mailing list + <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG' + name='<freebsd-questions@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.stable "FreeBSD-stable mailing list + <tt><htmlurl url='mailto:freebsd-questions@FreeBSD.ORG' + name='<freebsd-questions@FreeBSD.ORG>'></tt>"> + +<!ENTITY a.majordomo "<tt><htmlurl url='mailto:majordomo@FreeBSD.ORG' + name='<majordomo@FreeBSD.ORG>'></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 <security-officer@freebsd.org> + </heading> <p> +<tscreen><verb> +FreeBSD Security Officer <security-officer@freebsd.org> +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 <jkh@FreeBSD.org> +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 <phk@FreeBSD.org> +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 <j@uriah.heep.sax.de> +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 <ache@FreeBSD.org> +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 <rich@FreeBSD.org> +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 + > 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 + > 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: + + ⊃ + &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 © 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 + $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 $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&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 ? --> + |