diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
index c7bb721c09..12ce626731 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
@@ -1,597 +1,597 @@
Kernel Debugging
Contributed by &a.paul; and &a.joerg;
Debugging a Kernel Crash Dump with <command>kgdb</command>
Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the config kernel line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the dumpdev variable in
/etc/rc.conf. Typically you want to specify one of
the swap devices specified in /etc/fstab. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using config -g. See Kernel Configuration for details on
configuring the FreeBSD kernel.
Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via /etc/rc.conf and /etc/rc.
Alternatively, you can hard-code the dump device via the
dump clause in the config line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.
In the following, the term kgdb refers to
gdb run in kernel debug mode
. This
can be accomplished by either starting the gdb with
the option , or by linking and starting it under
the name kgdb. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.
When the kernel has been built make a copy of it, say
kernel.debug, and then run strip
-g on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.
If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the flag at the boot prompt, and
then perform the following steps:
&prompt.root; fsck -p
&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable
&prompt.root; savecore -N /kernel.panicked /var/crash
&prompt.root; exit # ...to multi-user
This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.
Now, after a crash dump, go to
/sys/compile/WHATEVER and run
kgdb. From kgdb do:
symbol-file kernel.debug
exec-file /var/crash/kernel.0
core-file /var/crash/vmcore.0
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.
Here is a script log of a kgdb session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.
1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; cd /sys/compile/URIAH
3:&prompt.root; kgdb kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb) where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb) up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&frame, FALSE);
36:(kgdb) frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb) list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb) print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb) print tp->t_line
56:$2 = 1767990816
57:(kgdb) up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb) up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb) up
64:#3 0xf012d014 in vn_open ()
65:(kgdb) up
66:#4 0xf012a183 in open ()
67:(kgdb) up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb) up
75:Initial frame selected; you cannot go up.
76:(kgdb) quit
77:&prompt.root; exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994
Comments to the above script:
line 6:
This is a dump taken from within DDB (see below), hence the
panic comment because you said to!
, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.
line 20:
This is the location of function trap()
in the stack trace.
line 36:
Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy <g>, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
tp
was messed up, or the array access was out of
bounds.
line 52:
The pointer looks suspicious, but happens to be a valid
address.
line 56:
However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
tp->t_line refers to the line discipline of
the console device here, which must be a rather small integer
number.)
Debugging a Crash Dump with DDD
Examining a kernel crash dump with a graphical debugger like
ddd is also possible. Add the
option to the ddd command line you would use
normally. For example;
&prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0
You should then be able to go about looking at the crash dump using
ddd's graphical interface.
Post-Mortem Analysis of a Dump
What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using config -g? Not
everything is lost here. Do not panic!
Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.
Go to your kernel config directory
(/usr/src/sys/arch/conf)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following line
makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
Rebuild the kernel. Due to the time stamp change on the Makefile,
there will be some other object files rebuild, for example
trap.o. With a bit of luck, the added
option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.
Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the kgdb
session until you know enough.
All this is not guaranteed to work, but it will do it fine in most
cases.
On-Line Kernel Debugging Using DDB
- While kgdb as an offline debugger provides a very
+ While kgdb as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.
If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like kgdb.
To configure your kernel to include DDB, add the option line
options DDB
to your config file, and rebuild. (See Kernel Configuration for details on
configuring the FreeBSD kernel.
Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)
Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.
The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (options BREAK_TO_DEBUGGER
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.
The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.
The DDB commands roughly resemble some gdb
commands. The first thing you probably need to do is to set a
breakpoint:
b function-name
b address
Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
a-f need to be preceded with 0x
(this is optional for other numbers). Simple expressions are allowed,
for example: function-name + 0x103.
To continue the operation of an interrupted kernel, simply
type:
c
To get a stack trace, use:
trace
Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.
If you want to remove a breakpoint, use
del
del address-expression
The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:
show b
To single-step the kernel, try:
s
This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:
n
This is different from gdb's
next statement; it is like gdb's
finish.
To examine data from memory, use (for example):
x/wx 0xf0133fe0,40
x/hd db_symtab_space
x/bc termbuf,10
x/s stringbuf
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:
x ,10
Similarly, use
x/ia foofunc,10
to disassemble the first 0x10 instructions of
foofunc, and display them along with their offset
from the beginning of foofunc.
To modify memory, use the write command:
w/b termbuf 0xa 0xb 0
w/w 0xf0010030 0 0
The command modifier
(b/h/w)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.
If you need to know the current registers, use:
show reg
Alternatively, you can display a single register value by e.g.
p $eax
and modify it by:
set $eax new-value
Should you need to call some kernel functions from DDB, simply
say:
call func(arg1, arg2, ...)
The return value will be printed.
For a &man.ps.1; style summary of all running processes, use:
ps
Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:
panic
This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another continue
statement.
call boot(0)
Which might be a good way to cleanly shut down the running system,
sync() all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.
call cpu_reset()
is the final way out of disaster and almost the same as hitting the
Big Red Button.
If you need a short command summary, simply type:
help
However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.
On-Line Kernel Debugging Using Remote GDB
This feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.
GDB has already supported remote debugging for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).
You should configure the kernel in question with config
-g, include into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with strip -x, and boot it
using the boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:
&prompt.user; gdb -k kernel
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
(kgdb)
Initialize the remote debugging session (assuming the first serial
port is being used) by:
(kgdb) target remote /dev/cuaa0
Now, on the target host (the one that entered DDB right before even
starting the device probe), type:
Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
db> gdb
DDB will respond with:
Next trap will enter GDB remote protocol mode
Every time you type gdb, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type s (step). Your hosting GDB
will now gain control over the target kernel:
Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
(kgdb)
You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.
Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:
&prompt.root; cd /usr/src/lkm/linux
&prompt.root; make clean; make COPTS=-g
Then install this version of the module on the target machine, load
it and use modstat to find out where it was
loaded:
&prompt.root; linux
&prompt.root; modstat
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod
Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module code
was relocated to. Use the add-symbol-file command in
GDB to tell the debugger about the module:
(kgdb) add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) y
(kgdb)
You now have access to all the symbols in the LKM.
Debugging a Console Driver
Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying at the Boot: prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index 8b3744d8a6..b7f3e22014 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,1673 +1,1673 @@
Installing FreeBSD
Restructured, updated, and parts rewritten by &a.jim;,
January 2000.
Synopsis
The following chapter will attempt to guide you through the
install of FreeBSD on your system. It can be installed through a
variety of methods, including anonymous FTP (assuming you have
network connectivity via modem or local network), CDROM, floppy
disk, tape, an MS-DOS partition, or even NFS.
No matter which method you choose, you will need to get started
by creating the installation disks as described
in the next section. By
booting into the FreeBSD installer, even if you are not planning on
installing FreeBSD right away, will provide important information
about compatibility with your hardware. This information may
dictate which installation options are even possible for you. It
can also provide clues early-on in the process to potential problems
you may come across later.
If you plan to install FreeBSD via anonymous FTP, the only
things you will need are the installation floppies. The
install program itself will handle anything else that is
required.
For more information about obtaining FreeBSD, see the Obtaining FreeBSD section of the
Appendix.
By now, you are probably wondering what exactly it is you need
to do. Continue on to the installation guide.
Installation Guide
The following sections will guide you through preparing for and
actually installing FreeBSD. If you find something missing, please
let us know about it by sending email to the &a.doc;.
Preparing for the Installation
There are various things you should do in preparation for the
install. The following describes what needs to be done prior to
each type of installation.
The first thing you should do is make sure your hardware is
supported by FreeBSD. The list of supported hardware should
come in handy here. ;-) It would also be a good idea to make a
list of any special
cards you have installed,
such as SCSI controllers, ethernet cards, sound cards, etc..
The list should include their IRQs and IO port addresses.
Creating the Boot Floppies
Please read the installation
boot image information before proceeding. To make the
installation boot disks from the image files, do the
following:
The first thing you will need to do is download the image
files. These can be retrieved from the floppies directory
of the FreeBSD FTP site or your local mirror.
If you are installing from an MS-DOS partition,
download the fdimage.exe
program or get it from tools\fdimage.exe
on the CDROM and then run it like so:
E:\> tools\fdimage floppies\kern.flp a:
The fdimage program will format
the A: drive and then copy
kern.flp to it (assuming that you are
at the top level of a FreeBSD distribution and the floppy
images live in a floppies
subdirectory, which is typically the case).
If you are using a UNIX-based system to create the
boot floppies, do the following:
&prompt.root; dd if=kern.flp of=disk_device
disk_device is the
/dev entry for the floppy drive. On
FreeBSD, this is /dev/rfd0 for the
A: drive and
/dev/rfd1 for the
B: drive.
With the kern.flp disk in your floppy
drive, reboot your computer. After a couple of minutes
(while the kernel loads from the floppy), you
will be prompted to insert
the mfsroot.flp, after which the
installation will proceed normally.
Before Installing from CDROM
If your CDROM is of an unsupported type, please skip ahead
to the MS-DOS Preparation
section.
There is not a whole lot of preparation needed if you are
installing from one of Walnut Creek CDROM's
FreeBSD CDROMs (other CDROM distributions may work as well,
though we cannot say for certain as we have no hand or say in
how they created). You can either boot into the CD installation
directly from DOS using the install.bat or
you can make floppies with the makeflp.bat
command.
If the CD has El Torito boot support and your system
supports booting directly from the CDROM drive (many older
systems do NOT), simply insert the first
FreeBSD of the set into the drive and reboot your system. You
will be put into the install menu directly from the CD.
If you are installing from an MS-DOS partition and have
the proper drivers to access your CD, run the
install.bat script provided on the CDROM.
This will attempt to boot the FreeBSD installation directly
from DOS.
You must do this from actual DOS (i.e., boot in DOS
mode) and not from a DOS window under Windows.
For the easiest interface of all (from DOS), type
view. This will bring up a DOS menu utility
that leads you through all of the available options.
If you are creating the boot floppies from a UNIX machine,
see the Creating the Boot
Floppies section of this guide for examples.
Once you have booted from DOS or floppy, you should then be
able to select CDROM as the media type during the install
process and load the entire distribution from CDROM. No other
types of installation media should be required.
After your system is fully installed and you have rebooted
(from the hard disk), you can mount the CDROM at any time by
typing:
&prompt.root; mount /cdrom
Before removing the CD from the drive again, you must first
unmount it. This is done with the following command:
&prompt.root; umount /cdrom
Do not just remove it from the drive!
Before invoking the installation, be sure that the CDROM
is in the drive so that the install probe can find it. This
is also true if you wish the CDROM to be added to the default
system configuration automatically during the install (whether
or not you actually use it as the installation media).
Finally, if you would like people to be able to FTP install
FreeBSD directly from the CDROM in your machine, you will find
it quite easy. After the machine is fully installed, you simply
need to add the following line to the password file (using the
vipw command):
ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent
Anyone with network connectivity to your machine can now
chose a media type of FTP and type in
ftp://your machine
after picking Other
in the FTP sites menu during
the install.
If you choose to enable anonymous FTP during the
installation of your system, the installation program will do
the above procedure for you.
Before installing from Floppies
If you must install from floppy disk (which we suggest you
do NOT do), either due to unsupported
hardware or simply because you insist on doing things the hard
way, you must first prepare some floppies for the install.
At a minimum, you will need as many 1.44MB or 1.2MB floppies
as it takes to hold all the files in the
bin (binary distribution) directory. If
you are preparing the floppies from DOS, then they
MUST be formatted using the MS-DOS
FORMAT command. If you are using Windows,
use Explorer to format the disks (right-click on the
A: drive, and select "Format".
Do NOT trust factory pre-formatted
floppies! Format them again yourself, just to be sure. Many
problems reported by our users in the past have resulted from
the use of improperly formatted media, which is why we are
making a point of it now.
If you are creating the floppies on another FreeBSD machine,
a format is still not a bad idea, though you do not need to put
a DOS filesystem on each floppy. You can use the
disklabel and newfs
commands to put a UFS filesystem on them instead, as the
following sequence of commands (for a 3.5" 1.44MB floppy)
illustrate:
&prompt.root; fdformat -f 1440 fd0.1440
&prompt.root; disklabel -w -r fd0.1440 floppy3
&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0
Use fd0.1200 and
floppy5 for 5.25" 1.2MB disks.
Then you can mount and write to them like any other
filesystem.
After you have formatted the floppies, you will need to copy
the files to them. The distribution files are split into chunks
conveniently sized so that 5 of them will fit on a conventional
1.44MB floppy. Go through all your floppies, packing as many
files as will fit on each one, until you have all of the
distributions you want packed up in this fashion. Each
distribution should go into a subdirectory on the floppy, e.g.:
a:\bin\bin.aa,
a:\bin\bin.ab, and so on.
Once you come to the Media screen during the install
process, select Floppy
and you will be prompted
for the rest.
Before Installing from MS-DOS
To prepare for an installation from an MS-DOS partition,
copy the files from the distribution into a directory named,
for example, c:\FreeBSD. The directory
structure of the CDROM or FTP site must be partially reproduced
within this directory, so we suggest using the DOS
xcopy command if you are copying it from a
CD. For example, to prepare for a minimal installation of
FreeBSD:
C:\> md c:\FreeBSD
C:\> xcopy /s e:\bin c:\FreeBSD\bin\
C:\> xcopy /s e:\manpages c:\FreeBSD\manpages\
Assuming that C: is where you have
free space and E: is where your CDROM
is mounted.
If you do not have a CDROM drive, you can download the
distribution from
ftp.FreeBSD.org. Each distribution is in its own directory;
for example, the bin distribution can be
found in the &rel.current;/bin directory.
For as many distributions you wish to install from an MS-DOS
partition (and you have the free space for), install each one
under c:\FreeBSD — the
BIN distribution is the only one required for
a minimum installation.
Before Installing from QIC/SCSI Tape
Installing from tape is probably the easiest method, short
of an online FTP install or CDROM install. The installation
- program expects the files to be simply tar'ed onto the tape, so
+ program expects the files to be simply tarred onto the tape, so
after getting all of the distribution files you are interested
in, simply tar them onto the tape like so:
&prompt.root; cd /freebsd/distdir
&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2
When you go to do the installation, you should also make
sure that you leave enough room in some temporary directory
(which you will be allowed to choose) to accommodate the
full contents of the tape you have created.
Due to the non-random access nature of tapes, this method of
installation requires quite a bit of temporary storage. You
should expect to require as much temporary storage as you have
stuff written on tape.
When starting the installation, the tape must be in the
drive before booting from the boot
floppy. The installation probe may otherwise fail to find
it.
Before Installing over a Network
There are three types of network installations you can do.
Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
or Ethernet (a standard ethernet controller (includes some
PCMCIA)).
The SLIP support is rather primitive, and limited primarily
to hard-wired links, such as a serial cable running between a
laptop computer and another computer. The link should be
hard-wired as the SLIP installation does not currently offer a
dialing capability; that facility is provided with the PPP
utility, which should be used in preference to SLIP whenever
possible.
If you are using a modem, then PPP is almost certainly
your only choice. Make sure that you have your service
provider's information handy as you will need to know it fairly
early in the installation process.
If you use PAP or CHAP to connect your ISP (in other
words, if you can connect to the ISP in Windows without
using a script), then all you will need to do is type in
dial at the
ppp prompt. Otherwise,
you will need to know
how to dial your ISP using the AT commands
specific to your modem, as the PPP dialer provides only a very
simple terminal emulator. Please
to the user-ppp handbook and FAQ entries for further
information. If you have problems, logging can be directed to
the screen using the command set log local
....
If a hard-wired connection to another FreeBSD (2.0-R or
later) machine is available, you might also consider installing
over a laplink
parallel port cable. The data rate
over the parallel port is much higher than what is typically
possible over a serial line (up to 50kbytes/sec), thus resulting
in a quicker installation.
Finally, for the fastest possible network installation, an
ethernet adapter is always a good choice! FreeBSD supports most
common PC ethernet cards; a table of supported cards (and their
required settings) is provided in the Supported Hardware list. If you are
using one of the supported PCMCIA ethernet cards, also be sure
that it is plugged in before the laptop is
powered on! FreeBSD does not, unfortunately, currently support
hot insertion of PCMCIA cards during installation.
You will also need to know your IP address on the network,
the netmask value for your address class, and the name of your
machine. If you are installing over a PPP connection and do not
have a static IP, fear not, the IP address can be dynamically
assigned by your ISP. Your system administrator can tell you
which values to use for your particular network setup. If you
will be referring to other hosts by name rather than IP address,
you will also need a name server and possibly the address of a
gateway (if you are using PPP, it is your provider's IP address)
to use in talking to it. If you do not know the answers to all
or most of these questions, then you should really probably talk
to your system administrator or ISP before trying
this type of installation.
Before Installing via NFS
The NFS installation is fairly straight-forward. Simply
copy the FreeBSD distribution files you want onto a server
somewhere and then point the NFS media selection at it.
If this server supports only privileged port
(as is generally the default for Sun workstations), you will
need to set this option in the Options menu before
installation can proceed.
If you have a poor quality ethernet card which suffers
from very slow transfer rates, you may also wish to toggle the
appropriate Options flag.
In order for NFS installation to work, the server must
support subdir mounts, e.g., if your FreeBSD 3.4 distribution
directory lives
on:ziggy:/usr/archive/stuff/FreeBSD, then
ziggy will have to allow the direct mounting
of /usr/archive/stuff/FreeBSD, not just
/usr or
/usr/archive/stuff.
In FreeBSD's /etc/exports file, this
is controlled by the . Other NFS
servers may have different conventions. If you are getting
permission denied
messages from the server, then
it is likely that you do not have this enabled
properly.
Before Installing via FTP
FTP installation may be done from any FreeBSD mirror site
containing a reasonably up-to-date version of FreeBSD. A full
list of FTP mirrors located all over the world is provided
during the install process.
If you are installing from an FTP site not listed in this
menu, or are having trouble getting your name server
configured properly, you can also specify a URL to use by
selecting the choice labeled Other
in that menu.
You can also use the IP address of a machine you wish to
install from, so the following would work in the absence of a
name server:
ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASE
There are two FTP installation modes you can choose from,
active or passive FTP.
FTP Active
This option will make all FTP transfers
use Active
mode. This will not work through firewalls, but will
often work with older FTP servers that do not support
passive mode. If your connection hangs with passive
mode (the default), try active!
FTP Passive
This option instructs FreeBSD to use
Passive
mode for all FTP operations.
This allows the user to pass through firewalls
that do not allow incoming connections on random port
addresses.
Active and passive modes are not the same as a
proxy
connection, where a proxy FTP server is
listening and forwarding FTP requests!
For a proxy FTP server, you should usually give the name
of the server you really want as a part of the username, after
an @
sign. The proxy server then
fakes
the real server. For example, assuming
you want to install from ftp.FreeBSD.org, using the proxy FTP
server foo.bar.com, listening on
port 1024.
In this case, you go to the options menu, set the FTP
username to ftp@ftp.FreeBSD.org, and the password to your
email address. As your installation media, you specify FTP
(or passive FTP, if the proxy supports it), and the URL
ftp://foo.bar.com:1234/pub/FreeBSD.
Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, you are able to install from
that machine (which will fetch the files
from ftp.FreeBSD.org as your
installation requests them.
Check your BIOS drive numbering
If you have used features in your BIOS to renumber your disk
drives without recabling them then you should read first to ensure you do not
confused.
Installing FreeBSD
Once you have completed the pre-installation step relevant to
your situation, you are ready to install FreeBSD!
Although you should not experience any difficulties, there is
always the chance you might, no matter how slight it is. If this
is the case in your situation, then you may wish to go back and
re-read the relevant preparation section or sections. Perhaps you
will come across something you missed the first time. If you are
having hardware problems, or FreeBSD refuses to boot at all, read
the Hardware Guide on the boot floppy for a list of possible
solutions.
The FreeBSD boot floppies contain all of the online
documentation you should need to be able to navigate through an
installation. If it does not, please let us know what you found
to be the most confusing or most lacking. Send your comments to
the &a.doc;. It is the objective of the installation program
(sysinstall) to be self-documenting enough that painful
step-by-step
guides are no longer necessary. It may
take us a little while to reach that objective, but nonetheless,
it is still our objective :-)
Meanwhile, you may also find the following typical
installation sequence
to be helpful:
Boot the kern.flp floppy and when
asked, remove it and insert the
mfsroot.flp and hit return. After a
boot sequence which can take anywhere from 30 seconds to 3
minutes, depending on your hardware, you should be presented
with a menu of initial choices. If the
kern.flp floppy does not boot at all or
the boot hangs at some stage, read the Q&A section of the
Hardware Guide on the floppy for possible causes.
Press F1. You should see some basic usage instructions on
the menu screen and general navigation. If you have not used
this menu system before then please read
this thoroughly.
Select the Options item and set any special preferences
you may have.
Select a Standard, Express, or Custom install, depending on
whether or not you would like the installation to help you
through a typical installation, give you a high degree of
- control over each step, or simply whizz through it (using
+ control over each step, or simply whiz through it (using
reasonable defaults when possible) as fast as possible. If
you have never used FreeBSD before, the Standard installation
method is most recommended.
The final configuration menu choice allows you to further
configure your FreeBSD installation by giving you menu-driven
access to various system defaults. Some items, like
networking, may be especially important if you did a CDROM,
tape, or floppy install and have not yet configured your
network interfaces (assuming you have any). Properly
configuring such interfaces here will allow FreeBSD to come up
on the network when you first reboot from the hard
disk.
Supported Hardware
FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and
PCI bus based PCs, ranging from the 386SX to Pentium class machines
(though the 386SX is not recommended). Support for generic IDE or
ESDI drive configurations, various SCSI controllers, and network and
serial cards is also provided.
- In order to run FreeBSD, a recommmended minimum of eight
+ In order to run FreeBSD, a recommended minimum of eight
megabytes of RAM is suggested. Sixteen megabytes is the preferred
amount of RAM as you may have some trouble with anything less than
sixteen depending on your hardware.
What follows is a list of hardware currently known to work with
FreeBSD. There may be other hardware that works as well, but we
have simply not received any confirmation of it.
Disk Controllers
WD1003 (any generic MFM/RLL)
WD1007 (any generic IDE/ESDI)
IDE
ATA
Adaptec 1535 ISA SCSI controllers
Adaptec 154X series ISA SCSI controllers
Adaptec 174X series EISA SCSI controllers in standard and
enhanced mode
Adaptec 274X/284X/2920C/294X/2950/3940/3950
(Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers
Adaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI
controllers
Adaptec 1510 series ISA SCSI controllers (not for bootable
devices)
Adaptec 152X series ISA SCSI controllers
Adaptec AIC-6260 and AIC-6360 based boards, which include
the AHA-152X and SoundBlaster SCSI cards
AdvanSys SCSI controllers (all models)
BusLogic MultiMaster W
Series Host Adapters
including BT-948, BT-958, BT-9580
BusLogic MultiMaster C
Series Host Adapters
including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C,
BT-757C, BT-757CD, BT-545C, BT-540CF
BusLogic MultiMaster S
Series Host Adapters
including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D,
BT-545S, BT-542D, BT-742A, BT-542B
BusLogic MultiMaster A
Series Host Adapters
including BT-742A, BT-542B
AMI FastDisk controllers that are true BusLogic
MultiMaster clones are also supported.
BusLogic/Mylex Flashpoint
adapters are NOT
yet supported.
DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III,
SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The
DPT SmartRAID/CACHE V is not yet supported.
Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES,
SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and
Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES.
SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820,
53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI
controllers including ASUS SC-200, Data Technology DTC3130
(all variants), Diamond FirePort (all), NCR cards (all),
SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan
S1365
QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre
Channel Adapters
DTC 3290 EISA SCSI controller in 1542 evaluation
mode
With all supported SCSI controllers, full support is provided
for SCSI-I and SCSI-II peripherals, including hard disks, optical
disks, tape drives (including DAT and 8mm Exabyte), medium
changers, processor target devices, and CDROM drives. WORM
devices that support CDROM commands are supported for read-only
access by the CDROM driver. WORM/CD-R/CD-RW writing support is
provided by cdrecord, which is in the ports tree.
The following CD-ROM type systems are supported at this
time:
cd - SCSI interface (includes
ProAudio Spectrum and SoundBlaster SCSI)
matcd - Matsushita/Panasonic
(Creative Soundblaster) proprietary interface (562/563
models)
scd - Sony proprietary interface
(all models)
acd - ATAPI IDE interface
The following drivers were supported under the old SCSI
subsystem, but are NOT YET supported under the new CAM SCSI
subsystem:
NCR5380/NCR53400 (ProAudio Spectrum
) SCSI
controller
UltraStor 14F, 24F, and 34F SCSI controllers
Seagate ST01/02 SCSI controllers
Future Domain 8XX/950 series SCSI controllers
WD7000 SCSI controller
There is work-in-progress to port the UltraStor driver
to the new CAM framework, but no estimates on when or if it
will be completed.
Unmaintained drivers, they might or might not work for your
hardware:
Floppy tape interface (Colorado/Mountain/Insight)
mcd - Mitsumi proprietary CD-ROM
interface (all models)
Network Cards
Adaptec Duralink PCI fast ethernet adapters based on the
Adaptec AIC-6195 fast ethernet controller chip, including the
following:
ANA-62011 64-bit single port 10/100baseTX
adapter
ANA-62022 64-bit dual port 10/100baseTX adapter
ANA-62044 64-bit quad port 10/100baseTX adapter
ANA-69011 32-bit single port 10/100baseTX
adapter
ANA-62020 64-bit single port 100baseFX adapter
Allied-Telesyn AT1700 and RE2000 cards
Alteon Networks PCI gigabit ethernet NICs based on the
Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC
(Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620
(Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq
EtherWORKS 1000, NEC Gigabit Ethernet
AMD PCnet/PCI (79c970 and 53c974 or 79c974)
RealTek 8129/8139 fast ethernet NICs including the
following:
Allied-Telesyn AT2550
Allied-Telesyn AT2500TX
Genius GF100TXR (RTL8139)
NDC Communications NE100TX-E
OvisLink LEF-8129TX
OvisLink LEF-8139TX
Netronix Inc. EA-1210 NetEther 10/100
KTX-9130TX 10/100 Fast Ethernet
Accton Cheetah
EN1027D (MPX 5030/5038;
RealTek 8139 clone?)
SMC EZ Card 10/100 PCI 1211-TX
Lite-On 98713, 98713A, 98715, and 98725 fast ethernet
NICs, including the LinkSys EtherFast LNE100TX, NetGear
FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston
KNE110TX
Macronix 98713, 98713A, 98715, 98715A, and 98725 fast
ethernet NICs including the NDC Communications SFA100A
(98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B
(98715), SVEC PN102TX (98713)
Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs
including the LinkSys EtherFast LNE100TX version 2
- Winbond W89C840F fast ethernet nics including the
+ Winbond W89C840F fast ethernet NICs including the
Trendware TE100-PCIE
VIA Technologies VT3043 Rhine I
and
VT86C100A Rhine II
fast ethernet NICs including
the Hawking Technologies PN102TX and D-Link DFE-530TX
Silicon Integrated Systems SiS 900 and SiS 7016 PCI fast
ethernet NICs
Sundance Technologies ST201 PCI fast ethernet NICs
including the D-Link DFE-550TX
SysKonnect SK-984x PCI gigabit ethernet cards including
the SK-9841 1000baseLX (single mode fiber, single port),
the SK-9842 1000baseSX (multimode fiber, single port), the
SK-9843 1000baseLX (single mode fiber, dual port), and the
SK-9844 1000baseSX (multimode fiber, dual port).
Texas Instruments ThunderLAN PCI NICs, including the
Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100
Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and
10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P
w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX
UTP, and the Racore 8165 10/100baseTX and 8148
10baseT/100baseTX/100baseFX multi-personality cards
ADMtek AL981-based and AN985-based PCI fast ethernet
NICs
ASIX Electronics AX88140A PCI NICs including the Alfa Inc.
GFC2204 and CNet Pro110B
DEC EtherWORKS III NICs (DE203, DE204, and DE205)
DEC EtherWORKS II NICs (DE200, DE201, DE202, and
DE422)
DEC DC21040, DC21041, or DC21140 based NICs (SMC
Etherpower 8432T, DE245, etc.)
DEC FDDI (DEFPA/DEFEA) NICs
Efficient ENI-155p ATM PCI
FORE PCA-200E ATM PCI
Fujitsu MB86960A/MB86965A
HP PC Lan+ cards (model numbers: 27247B and 27252A)
Intel EtherExpress (not recommended due to driver
instability)
Intel EtherExpress Pro/10
Intel EtherExpress Pro/100B PCI Fast Ethernet
Isolan AT 4141-0 (16 bit)
Isolink 4110 (8 bit)
Novell NE1000, NE2000, and NE2100 Ethernet
interfaces
PCI network cards emulating the NE2000, including the
RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA
VT86C926
3Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507
Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA),
3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink
III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL
server adapter, 3CSOHO100-TX OfficeConnect adapter
Toshiba ethernet cards
PCMCIA ethernet cards from IBM and National Semiconductor
are also supported
USB Peripherals
A wide range of USB peripherals are supported. Owing to the
generic nature of most USB devices, with some exceptions any
device of a given class will be supported even if not explicitly
listed here.
USB keyboards
USB mice
USB printers and USB to parallel printer conversion
cables
USB hubs
Motherboard chipsets:
ALi Aladdin-V
Intel 82371SB (PIIX3) and 82371AB and EB (PIIX4)
chipsets
NEC uPD 9210 Host Controller
VIA 83C572 USB Host Controller
and any other UHCI or OHCI compliant motherboard chipset
(no exceptions known).
PCI plug-in USB host controllers
ADS Electronics PCI plug-in card (2 ports)
Entrega PCI plug-in card (4 ports)
Specific USB devices reported to be working:
Agiler Mouse 29UO
Andromeda hub
Apple iMac mouse and keyboard
ATen parallel printer adapter
Belkin F4U002 parallel printer adapter and Belkin
mouse
BTC BTC7935 keyboard with mouse port
Cherry G81-3504
Chic mouse
Cypress mouse
Entrega USB-to-parallel printer adapter
Genius Niche mouse
Iomega USB Zip 100 MB
Kensington Mouse-in-a-Box
Logitech M2452 keyboard
Logictech wheel mouse (3 buttons)
Logitech PS/2 / USB mouse (3 buttons)
MacAlly mouse (3 buttons)
MacAlly self-powered hub (4 ports)
Microsoft Intellimouse (3 buttons)
Microsoft keyboard
NEC hub
Trust Ami Mouse (3 buttons)
ISDN (European DSS1 [Q.921/Q.931] protocol)
Asuscom I-IN100-ST-DV (experimental, may work)
Asuscom ISDNlink 128K
AVM A1
AVM Fritz!Card classic
AVM Fritz!Card PCI
AVM Fritz!Card PCMCIA (currently FreeBSD 3.x only)
AVM Fritz!Card PnP (currently FreeBSD 3.x only)
Creatix ISDN-S0/8
Creatix ISDN-S0/16
Creatix ISDN-S0 PnP
Dr.Neuhaus Niccy 1008
Dr.Neuhaus Niccy 1016
Dr.Neuhaus Niccy GO@ (ISA PnP)
Dynalink IS64PH (no longer maintained)
ELSA 1000pro ISA
ELSA 1000pro PCI
ELSA PCC-16
ITK ix1 micro (currently FreeBSD 3.x only)
ITK ix1 micro V.3 (currently FreeBSD 3.x only)
Sagem Cybermod (ISA PnP, may work)
Sedlbauer Win Speed
Siemens I-Surf 2.0
Stollman Tina-pp (under development)
Teles S0/8
Teles S0/16
Teles S0/16.3 (the c
Versions - like 16.3c
- are unsupported!)
Teles S0 PnP (experimental, may work)
3Com/USRobotics Sportster ISDN TA intern (non-PnP
version)
Miscellaneous Devices
AST 4 port serial card using shared IRQ
ARNET 8 port serial card using shared IRQ
ARNET (now Digiboard) Sync 570/i high-speed serial
Boca BB1004 4-Port serial card (Modems NOT
supported)
Boca IOAT66 6-Port serial card (Modems supported)
Boca BB1008 8-Port serial card (Modems NOT
supported)
Boca BB2016 16-Port serial card (Modems supported)
Cyclades Cyclom-y Serial Board
Moxa SmartIO CI-104J 4-Port serial card
STB 4 port card using shared IRQ
SDL Communications RISCom/8 Serial Board
SDL Communications RISCom/N2 and N2pci high-speed sync
serial boards
Specialix SI/XIO/SX multiport serial cards, with both the
older SIHOST2.x and the new enhanced
(transputer based, aka JET) host cards; ISA, EISA and PCI are
supported
Stallion multiport serial boards: EasyIO, EasyConnection
8/32 & 8/64, ONboard 4/16 and Brumby
Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum,
Gravis UltraSound, and Roland MPU-401 sound cards
Connectix QuickCam
Matrox Meteor Video frame grabber
Creative Labs Video Spigot frame grabber
Cortex1 frame grabber
- Various frame grabbers based ont he the Brooktree Bt848
+ Various frame grabbers based on the Brooktree Bt848
and Bt878 chip
HP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R
drives
Bus mice
PS/2 mice
Standard PC Joystick
X-10 power controllers
GPIB and Transputer drives
Genius and Mustek hand scanners
Floppy tape drives (some rather old models only, driver is
rather stale)
Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA
standard speed (2Mbps) and turbo speed (6Mbps) wireless
network adapters and workalikes (NCR WaveLAN/IEEE 802.11,
Cabletron RoamAbout 802.11 DS)
The ISA versions of these adapters are actually PCMCIA
cards combined with an ISA to PCMCIA bridge card, so both
kinds of devices work with the same driver.
FreeBSD currently does NOT support IBM's microchannel (MCA)
bus.
Troubleshooting
The following section covers basic installation troubleshooting,
such as common problems people have reported. There are also a few
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.
What to do if something goes wrong...
Due to various limitations of the PC architecture, it is
impossible for probing to be 100% reliable, however, there are a
few things you can do if it fails.
Check the supported
hardware list to make sure your hardware is
supported.
If your hardware is supported and you still experience
lock-ups or other problems, reset your computer, and when the
visual kernel configuration option is given, choose it. This will
allow you to go through your hardware and supply information to the
system about it. The kernel on the boot disks is configured
assuming that most hardware devices are in their factory default
configuration in terms of IRQs, IO addresses, and DMA channels. If
your hardware has been reconfigured, you will most likely need to
use the configuration editor to tell FreeBSD where to find
things.
It is also possible that a probe for a device not present will
cause a later probe for another device that is present to fail. In
that case, the probes for the conflicting driver(s) should be
disabled.
Do not disable any drivers you will need during the
installation, such as your screen (sc0).
If the installation wedges or fails mysteriously after leaving
the configuration editor, you have probably removed or changed
something you should not have. Reboot and try again.
In configuration mode, you can:
List the device drivers installed in the kernel.
Change device drivers for hardware that is not present in
your system.
Change IRQs, DRQs, and IO port addresses used by a device
driver.
After adjusting the kernel to match your hardware
configuration, type Q to boot with the new
settings. Once the installation has completed, any changes you
made in the configuration mode will be permanent so you do not have
to reconfigure every time you boot. It is still highly likely that
you will eventually want to build a custom kernel.
MS-DOS User's Questions and Answers
Many users wish to install FreeBSD on PCs inhabited by MS-DOS.
Here are some commonly asked questions about installing FreeBSD on
such systems.
Help, I have no space! Do I need to delete everything
first?
If your machine is already running MS-DOS and has little
or no free space available for the FreeBSD installation, all
hope is not lost! You may find the FIPS utility, provided
in the tools directory on the FreeBSD
CDROM or various FreeBSD FTP sites to be quite
useful.
FIPS allows you to split an existing MS-DOS partition
into two pieces, preserving the original partition and
allowing you to install onto the second free piece. You
first defragment your MS-DOS partition using the Windows
DEFRAG utility (go into Explorer, right-click on the
hard drive, and choose to defrag your
hard drive), or Norton Disk Tools. You then must run FIPS. It
will prompt you for the rest of the information it needs.
Afterwards, you can reboot and install FreeBSD on the new
free slice. See the Distributions menu
for an estimate of how much free space you will need for the
kind of installation you want.
There is also a very useful
product from PowerQuest
called Partition Magic. This
application has far more functionality than FIPS, and is
highly recommended if you plan to often add/remove
operating systems (like me). However, it does cost
money, and if you plan to install FreeBSD once and then
leave it there, FIPS will probably be fine for you.
Can I use compressed MS-DOS filesystems from
FreeBSD?
No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use whatever
portion of the filesystem you leave uncompressed. The rest
of the filesystem will show up as one large file (the
stacked/double spaced file!). Do not remove that
file or you will probably regret it
greatly!
It is probably better to create another uncompressed
primary MS-DOS partition and use this for communications
between MS-DOS and FreeBSD.
Can I mount my extended MS-DOS partition?
Yes. DOS extended partitions are mapped in at the end
of the other slices
in FreeBSD, e.g., your
D: drive might be
/dev/da0s5, your
E: drive,
/dev/da0s6, and so on. This example
assumes, of course, that your extended partition is on SCSI
drive 0. For IDE drives, substitute ad
for da appropriately if installing
4.0-RELEASE or later, and substitute
wd for da if you
are installing a version of FreeBSD prior to 4.0. You otherwise
mount extended partitions exactly like you would any other
DOS drive, for example:
&prompt.root; mount -t msdos /dev/ad0s5 /dos_d
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index fef9dfd349..4490777632 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1133 +1,1133 @@
Configuring the FreeBSD Kernel
Synopsis
Updated and restructured by &a.jim;, March 2000.
Originally contributed by &a.jehamby;, 6 October
1995.
The following chapter of the handbook covers everything you will
need to know in order to build a custom kernel. If you are
wondering what the benefits of a custom kernel are, or would like to
know how to configure, compile, and install a custom kernel, this
chapter is for you.
Why Build a Custom Kernel?
Building a custom kernel is one of the most important rites of
passage nearly every UNIX user must endure. This process, while
time consuming, will provide many benefits to your FreeBSD system.
Unlike the GENERIC kernel, which must support a
wide range of hardware, a custom kernel only contains support for
your PC's hardware. This has a number of
benefits, such as:
Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot will decrease dramatically.
Less memory use. A custom kernel often uses less memory
than the GENERIC kernel, which is important
because the kernel is one process that must always be present in
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.
Additional hardware support. A custom kernel allows you to
add in support for devices such as sound cards, which are not
present in the GENERIC kernel.
Building and Installing a Custom Kernel
First, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
/usr/src/sys directory, which is also
accessible through /sys. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
arch/conf, where you
will edit your custom kernel configuration, and
compile, which is the staging area where your
kernel will be built. arch represents
either i386, alpha, or
pc98 (an alternative development branch of PC
hardware, popular in Japan). Everything inside a particular
architecture's directory deals with that architecture only; the rest
of the code is common to all platforms to which FreeBSD could
potentially be ported. Notice the logical organization of the
directory structure, with each supported device, filesystem, and
option in its own subdirectory.
If there is not a
/usr/src/sys directory on your system, then
the kernel source has not been been installed. The easiest way to
do this is by running /stand/sysinstall as
root, choosing Configure,
then Distributions, then
src, then sys.
Next, move to the
arch/conf directory
and copy the GENERIC configuration file to the
name you want to give your kernel. For example:
&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC MYKERNEL
Traditionally, this name is in all capital letters and, if you
are maintaining multiple FreeBSD machines with different hardware,
it is a good idea to name it after your machine's hostname. We will
call it MYKERNEL for the purpose of this
example.
You must execute these and all of the following commands under
the root account or you will get permission
denied errors.
Now, edit MYKERNEL with your favorite text
editor. If you are just starting out, the only editor available
will probably be vi, which is too complex to
explain here, but is covered well in many books in the bibliography. However, FreeBSD does
offer an easier editor called ee
which, if you are a
beginner, should be your editor of choice. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
GENERIC.
If you have build a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the GENERIC configuration file
might seem overwhelming to you, so follow the descriptions in the
Configuration File
section slowly and carefully.
If you are trying to upgrade your kernel from an older version
of FreeBSD, you will probably have to get a new version of
&man.config.8; from the same place you got the new kernel sources.
It is located in /usr/src/usr.sbin, so you
will need to download those sources as well. Re-build and install
it before running the next commands.
When you are finished, type the following to compile and install
your kernel:
&prompt.root; /usr/sbin/config MYKERNEL
&prompt.root; cd ../../compile/MYKERNEL
&prompt.root; make depend
&prompt.root; make
&prompt.root; make install
The new kernel will be copied to the root directory as
/kernel and the old kernel will be moved to
/kernel.old. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong, there are
some troubleshooting
instructions at the end of this document. Be sure to read the
section which explains how to recover in case your new kernel does not boot.
If you have added any new devices (such as sound cards) you
may have to add some device
nodes to your /dev directory before
you can use them.
The Configuration File
The general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a # is considered a comment and
ignored. The following sections describe each keyword, generally in
the order they are listed in GENERIC, although
some related keywords have been grouped together in a single section
(such as Networking) even though they are actually scattered
throughout the GENERIC file. An exhaustive list of options and more
detailed explanations of the device lines is present in the
LINT configuration file, located in the same
directory as GENERIC. If you are in doubt as
to the purpose or necessity of a line, check first in
LINT.
Quoting numbers
In all versions of FreeBSD up to and including 3.X,
&man.config.8; required that any strings in the configuration file
that contained numbers used as text had to be enclosed in double
quotes.
This requirement was removed in the 4.X branch, which this
book covers, so if you are on a pre-4.X system, see the
/usr/src/sys/i386/conf/LINT and
/usr/src/sys/i386/conf/GENERIC
files on your system for examples.
The following is an example GENERIC kernel
configuration file with various additional comments where needed for
clarity. This example should match your copy in
/usr/src/sys/i386/conf/GENERIC fairly
closely. For details of all the possible kernel options, see
/usr/src/sys/i386/conf/LINT.
#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.freebsd.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $
The following are the mandatory keywords required in
every kernel you build:
machine i386
This is the machine architecture. It must be either
i386, alpha, or
pc98.
cpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPU
The above specifies the type of CPU you have in your system.
You may have multiple instances of the CPU line (i.e., you are not
sure whether you should use I586_CPU or
I686_CPU), however, for a custom kernel, it is
best to specify only the CPU you have. If you are unsure which type
your CPU use, you can use the dmesg command to
view your boot up messages.
- The Alpha architechture has different values for
+ The Alpha architecture has different values for
cpu_type. They include:
cpu EV4
cpu EV5
If you are using an Alpha machine, you should be using one of
the above CPU types.
ident GENERIC
This is the identification of the kernel. You should change
this to whatever you named your kernel, in our previous example,
MYKERNEL. The value you put in the
ident string will print when you boot up the
kernel, so it is useful to give a kernel a different name if you
want to keep it separate from your usual kernel (i.e., you want to
build an experimental kernel).
maxusers 32
The maxusers option sets the size of a number
of important system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to have on your
machine. However, under normal circumstances, you will want to set
maxusers to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by maxusers is the
maximum number of processes, which is set to 20 + 16 *
maxusers, so if you set maxusers to 1,
then you can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15 or so you
will probably create when you start the X Window System. Even a
simple task like reading a man page will start up nine processes to
filter, decompress, and view it. Setting
maxusers to 64 will allow you to have up to 1044
simultaneous processes, which should be enough for nearly all uses.
If, however, you see the dreaded proc table
full error when trying to start another program, or are
running a server with a large number of simultaneous users (like
ftp.FreeBSD.org), you can always
increase the number and rebuild.
maxusers does not
limit the number of users which can log into your machine. It
simply sets various table sizes to reasonable values considering
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which does limit the number of simultaneous
remote logins is pseudo-device pty
16.
Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.
#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
options MATH_EMULATE #Support for x87 emulation
This line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line
out.
The normal math co-processor emulation routines that come with
FreeBSD are not very accurate. If you do not
have a math co-processor, and you need the best accuracy, it is
recommended that you change this option to
GPL_MATH_EMULATION to use the GNU math support,
which is not included by default for licensing reasons.
options INET #InterNETworking
Networking support. Leave this in, even if you do not plan to
be connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.
options INET6 #IPv6 communications protocols
This enables the IPv6 communication protocols.
options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]
This is the basic hard drive filesystem. Leave it in if you
boot from the hard disk.
options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root device
This is the memory-mapped filesystem. This is basically a RAM
disk for fast storage of temporary files, useful if you have a lot
of swap space that you want to take advantage of. A perfect place
to mount an MFS partition is on the /tmp
directory, since many programs store temporary data here. To mount
an MFS RAM disk on /tmp, add the following line
to /etc/fstab:
/dev/ad1s2b /tmp mfs rw 0 0
Now you simply need to either reboot, or run the command
mount /tmp.
options NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS required
The network filesystem. Unless you plan to mount partitions
from a UNIX file server over TCP/IP, you can comment these
out.
options MSDOSFS #MSDOS Filesystem
The MS-DOS filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this out.
It will be automatically loaded the first time you mount a DOS
partition, as described above. Also, the excellent
mtools software (in the ports collection)
allows you to access DOS floppies without having to mount and
unmount them (and does not require MSDOSFS at
all).
options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 required
The ISO 9660 filesystem for CDROMs. Comment it out if you do
not have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this filesystem.
options PROCFS #Process filesystem
The process filesystem. This is a pretend
filesystem mounted on /proc which allows
programs like &man.ps.1; to give you more information on what
processes are running.
options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]
Compatibility with 4.3BSD. Leave this in; some programs will
act strangely if you comment this out.
options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI
This causes the kernel to pause for 15 seconds before probing
each SCSI device in your system. If you only have IDE hard drives,
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
you will have to raise it back up.
options UCONSOLE #Allow users to grab the console
Allow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing xterm
-C, which will display any write,
talk, and any other messages you receive, as well
as any console messages sent by the kernel.
options USERCONFIG #boot -c editor
This option allows you to boot the configuration editor from the
boot menu.
options VISUAL_USERCONFIG #visual boot -c editor
This option allows you to boot the visual configuration editor
from the boot menu.
options KTRACE #ktrace(1) support
This enables kernel process tracing, which is useful in
debugging.
options SYSVSHM #SYSV-style shared memory
This option provides for System V shared memory. The most
common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of for
extra speed. If you use X, you'll definitely want to include
this.
options SYSVSEM #SYSV-style semaphores
Support for System V semaphores. Less commonly used but only
adds a few hundred bytes to the kernel.
options SYSVMSG #SYSV-style message queues
Support for System V messages. Again, only adds a few hundred
bytes to the kernel.
The &man.ipcs.1; command will list any processes using each of
these System V facilities.
options P1003_1B #Posix P1003_1B real-time extentions
options _KPOSIX_PRIORITY_SCHEDULING
Real-time extensions added in the 1993 POSIX. Certain
applications in the ports collection use these (such as Star
Office).
options ICMP_BANDLIM #Rate limit bad replies
This option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
denial of service packet attacks.
# To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/O
The above are both required for SMP support.
# Optionally these may need tweaked, (defaults shown):
#options NCPU=2 # number of CPUs
#options NBUS=4 # number of busses
#options NAPIC=1 # number of IO APICs
#options NINTR=24 # number of INTs
These are some additional SMP knobs.
device isa
All PCs supported by FreeBSD have one of these. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
this time (support is being worked on).
device eisa
Include this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the EISA
bus.
device pci
Include this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.
# Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1
This is the floppy drive controller. fd0 is
the A: floppy drive, and
fd1 is the B:
drive.
device ata
This driver supports all ATA and ATAPI devices. You only need
one device ata line for the kernel to detect all
PCI ATA/ATAPI devices on modern machines.
device atadisk # ATA disk drives
This is needed along with device ata for
ATAPI disk drives.
device atapicd # ATAPI CDROM drives
This is needed along with device ata for
ATAPI CDROM drives.
device atapifd # ATAPI floppy drives
This is needed along with device ata for
ATAPI floppy drives.
device atapist # ATAPI tape drives
This is needed along with device ata for
ATAPI tape drives.
options ATA_STATIC_ID #Static device numbering
This makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.
#options ATA_ENABLE_ATAPI_DMA #Enable DMA on ATAPI devices
This enables DMA on the ATAPI device. Since many ATAPI devices
claim to support DMA, but it does not actually work, this is turned
off by default.
# ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15
Use the above for older, non-PCI systems.
# SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?
SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether.
# SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)
SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.
# RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 family
Supported RAID controllers. If you do not have any of these,
you can comment them out or remove them.
# atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBD
The keyboard controller (atkbdc) provides I/O
services for the AT keyboard and PS/2 style pointing devices. This
controller is required by the keyboard driver
(atkbd) and the PS/2 pointing device driver
(psm).
device atkbd0 at atkbdc? irq 1
The atkbd driver, together with
atkbdc controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.
device psm0 at atkbdc? irq 12
Use this device if your mouse plugs into the PS/2 mouse
port.
device vga0 at isa?
The video card driver.
# splash screen/screen saver
pseudo-device splash
Splash screen at start up! Screen savers require this
too.
# syscons is the default console driver, resembling an SCO console
device sc0 at isa?
sc0 is the default console driver, which
resembles a SCO console. Since most full-screen programs access the
console through a terminal database library like
termcap, it should not matter whether you use
this or vt0, the VT220
compatible console driver. When you log in, set your
TERM variable to scoansi if
full-screen programs have trouble running under this console.
# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-std
This is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with sc0. Also set your
TERM variable to vt100 or
vt220 when you log in. This driver might also
prove useful when connecting to a large number of different machines
over the network, where termcap or
terminfo entries for the sc0
device are often not available — vt100
should be available on virtually any platform.
# Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13
npx0 is the interface to the floating point
math unit in FreeBSD, which is either the hardware co-processor or
the software math emulator. This is not
optional.
# Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power Management
Advanced Power Management support. Useful for laptops.
# PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
PCMCIA support. You need this if you are installing on a
laptop.
# Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9
These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.
If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
S3 chips) use IO addresses in the form of
0x*2e8, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
these cards making the COM4 port practically unavailable.
Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.
# Parallel port
device ppc0 at isa? irq 7
This is the ISA-bus parallel port interface.
device ppbus # Parallel port bus (required)
Provides support for the parallel port bus.
device lpt # Printer
Support for parallel port printers.
All three of the above are required to enable parallel printer
support.
device plip # TCP/IP over parallel
This is the driver for the parallel network interface.
device ppi # Parallel port interface device
The general-purpose I/O (geek port
) + IEEE1284
I/O.
#device vpo # Requires scbus and da
This is for an Iomega Zip drive. It requires
scbus and da support. Best
performance is achieved with ports in EPP 1.9 mode.
# PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (Tulip
)
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 EPIC
)
device vx # 3Com 3c590, 3c595 (Vortex
)
device wx # Intel Gigabit Ethernet Card (Wiseman
)
Various PCI network card drivers. Comment out or remove any of
these not present in your system.
# PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus support
MII bus support is required for some PCI 10/100 ethernet NICs,
namely those which use MII-compliant transceivers or implement
- transceiver control interfaces taht operate like an MII. Adding
+ transceiver control interfaces that operate like an MII. Adding
device miibus to the kernel config pulls in
support for the generic miibus API and all of the PHY drivers,
including a generic one for PHYs that are not specifically handled
by an individual driver
device dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (Starfire
)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (Boomerang
, Cyclone
)
Drivers that use the MII bus controller code.
# ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
-# exists only as a PCMCIA device, so there is no ISA attatement needed
+# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
-# those paremeters here.
+# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?
ISA ethernet drivers. See
/usr/src/sys/i386/conf/LINT for which cards are
supported by which driver.
# Pseudo devices - the number indicates how many units to allocated.
pseudo-device loop # Network loopback
This is the generic loopback device for TCP/IP. If you telnet
or FTP to localhost (a.k.a., 127.0.0.1 it will come back at you through
this pseudo-device. This is mandatory.
pseudo-device ether # Ethernet support
ether is only needed if you have an Ethernet
card. It includes generic Ethernet protocol code.
pseudo-device sl 1 # Kernel SLIP
sl is for SLIP support. This has been almost
entirely supplanted by PPP, which is easier to set up, better suited
for modem-to-modem connection, and more powerful. The
number after sl
specifies how many simultaneous SLIP sessions to support.
pseudo-device ppp 1 # Kernel PPP
This is for kernel PPP support for dial-up connections. There
is also a version of PPP implemented as a userland application that
uses tun and offers more flexibility and features
such as demand dialing. The number after
ppp specifies how many simultaneous PPP
connections to support.
pseudo-device tun # Packet tunnel.
This is used by the userland PPP software. The
number after tun
specifies the number of simultaneous PPP sessions to support. See
the PPP section of this book for more
information.
pseudo-device pty # Pseudo-ttys (telnet etc)
This is a pseudo-terminal
or simulated login port.
It is used by incoming telnet and
rlogin sessions,
xterm, and some other applications such
as emacs. The
number indicates the number of
ptys to create. If you need more than the
default of 16 simultaneous xterm windows
and/or remote logins, be sure to increase this number accordingly,
up to a maximum of 256.
pseudo-device md # Memory disks
Memory disk pseudo-devices.
pseudo-device gif 4 # IPv6 and IPv4 tunneling
This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
tunneling.
pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)
This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.
# The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filter
This is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an ethernet). These packets
can be captured to disk and or examined with the &man.tcpdump.1;
program.
# USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # Human Interface Devices
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernet
Support for various USB devices.
For more information and additional devices supported by
FreeBSD, see
/usr/src/sys/i386/conf/LINT.
Making Device Nodes
Almost every device in the kernel has a corresponding
node
entry in the /dev directory.
These nodes look like regular files, but are actually special
entries into the kernel which programs use to access the device.
The shell script /dev/MAKEDEV, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create all of them, so when you add support for
a new device, it pays to make sure that the appropriate entries are
in this directory, and if not, add them. Here is a simple
example:
Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:
device acd0
This means that you should look for some entries that start with
acd0 in the /dev
directory, possibly followed by a letter, such as
c, or preceded by the letter
r, which means a raw
device. It
turns out that those files are not there, so I must change to the
/dev directory and type:
&prompt.root; sh MAKEDEV acd0
When this script finishes, you will find that there are now
acd0c and racd0c entries
in /dev so you know that it executed
correctly.
For sound cards, the following command creates the appropriate
entries:
&prompt.root; sh MAKEDEV snd0
When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
/etc/fbtab file. See &man.fbtab.5; for more
information.
Follow this simple procedure for any other
non-GENERIC devices which do not have
entries.
All SCSI controllers use the same set of
/dev entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in /dev at all, so you do not
have to worry about these either.
If Something Goes Wrong
There are four categories of trouble that can occur when
building a custom kernel. They are:
config fails
If the config command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
config will print the line number that it
had trouble with, so you can quickly skip to it with
vi. For example, if you see:
config: line 17: syntax error
You can skip to the problem in vi by
typing 17G in command mode. Make sure the
keyword is typed correctly, by comparing it to the
GENERIC kernel or another
reference.
make fails
If the make command fails, it usually
signals an error in your kernel description, but not severe
enough for config to catch it. Again, look
over your configuration, and if you still cannot resolve the
problem, send mail to the &a.questions; with your kernel
configuration, and it should be diagnosed very quickly.
The kernel will not boot
If your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, BSD has an excellent
mechanism for recovering from incompatible kernels. Simply
choose the kernel you want to boot from at the FreeBSD boot
loader (i.e.,
boot kernel.old).
When reconfiguring a kernel, it is always a good idea to keep
a kernel that is known to work on hand.
After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the /var/log/messages file
which records, among other things, all of the kernel messages
from every successful boot. Also, the &man.dmesg.8; command
will print the kernel messages from the current boot.
If you are having trouble building a kernel, make sure
to keep a GENERIC, or some other kernel
that is known to work on hand as a different name that will
not get erased on the next build. You cannot rely on
kernel.old because when installing a
new kernel, kernel.old is overwritten
with the last installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel to the
proper kernel location or commands such
as &man.ps.1; will not work properly. The proper command to
unlock
the kernel file that
make installs (in order to move another
kernel back permanently) is:
&prompt.root; chflags noschg /kernel
And, if you want to lock
your new kernel
into place, or any file for that matter, so that it cannot
be moved or tampered with:
&prompt.root; chflags schg /kernel
The kernel works, but ps does not work
any more!
If you have installed a different version of the kernel
from the one that the system utilities have been built with,
for example, a 4.X kernel on a 3.X system, many system-status
commands like &man.ps.1; and &man.vmstat.8; will not work any
more. You must recompile the libkvm
library as well as these utilities. This is one reason it is
not normally a good idea to use a different version of the
kernel from the rest of the operating system.
diff --git a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
index c7bb721c09..12ce626731 100644
--- a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
@@ -1,597 +1,597 @@
Kernel Debugging
Contributed by &a.paul; and &a.joerg;
Debugging a Kernel Crash Dump with <command>kgdb</command>
Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the config kernel line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the dumpdev variable in
/etc/rc.conf. Typically you want to specify one of
the swap devices specified in /etc/fstab. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using config -g. See Kernel Configuration for details on
configuring the FreeBSD kernel.
Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via /etc/rc.conf and /etc/rc.
Alternatively, you can hard-code the dump device via the
dump clause in the config line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.
In the following, the term kgdb refers to
gdb run in kernel debug mode
. This
can be accomplished by either starting the gdb with
the option , or by linking and starting it under
the name kgdb. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.
When the kernel has been built make a copy of it, say
kernel.debug, and then run strip
-g on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.
If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the flag at the boot prompt, and
then perform the following steps:
&prompt.root; fsck -p
&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable
&prompt.root; savecore -N /kernel.panicked /var/crash
&prompt.root; exit # ...to multi-user
This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.
Now, after a crash dump, go to
/sys/compile/WHATEVER and run
kgdb. From kgdb do:
symbol-file kernel.debug
exec-file /var/crash/kernel.0
core-file /var/crash/vmcore.0
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.
Here is a script log of a kgdb session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.
1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; cd /sys/compile/URIAH
3:&prompt.root; kgdb kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb) where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb) up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&frame, FALSE);
36:(kgdb) frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb) list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb) print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb) print tp->t_line
56:$2 = 1767990816
57:(kgdb) up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb) up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb) up
64:#3 0xf012d014 in vn_open ()
65:(kgdb) up
66:#4 0xf012a183 in open ()
67:(kgdb) up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb) up
75:Initial frame selected; you cannot go up.
76:(kgdb) quit
77:&prompt.root; exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994
Comments to the above script:
line 6:
This is a dump taken from within DDB (see below), hence the
panic comment because you said to!
, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.
line 20:
This is the location of function trap()
in the stack trace.
line 36:
Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy <g>, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
tp
was messed up, or the array access was out of
bounds.
line 52:
The pointer looks suspicious, but happens to be a valid
address.
line 56:
However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
tp->t_line refers to the line discipline of
the console device here, which must be a rather small integer
number.)
Debugging a Crash Dump with DDD
Examining a kernel crash dump with a graphical debugger like
ddd is also possible. Add the
option to the ddd command line you would use
normally. For example;
&prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0
You should then be able to go about looking at the crash dump using
ddd's graphical interface.
Post-Mortem Analysis of a Dump
What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using config -g? Not
everything is lost here. Do not panic!
Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.
Go to your kernel config directory
(/usr/src/sys/arch/conf)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following line
makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
Rebuild the kernel. Due to the time stamp change on the Makefile,
there will be some other object files rebuild, for example
trap.o. With a bit of luck, the added
option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.
Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the kgdb
session until you know enough.
All this is not guaranteed to work, but it will do it fine in most
cases.
On-Line Kernel Debugging Using DDB
- While kgdb as an offline debugger provides a very
+ While kgdb as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.
If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like kgdb.
To configure your kernel to include DDB, add the option line
options DDB
to your config file, and rebuild. (See Kernel Configuration for details on
configuring the FreeBSD kernel.
Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)
Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.
The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (options BREAK_TO_DEBUGGER
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.
The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.
The DDB commands roughly resemble some gdb
commands. The first thing you probably need to do is to set a
breakpoint:
b function-name
b address
Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
a-f need to be preceded with 0x
(this is optional for other numbers). Simple expressions are allowed,
for example: function-name + 0x103.
To continue the operation of an interrupted kernel, simply
type:
c
To get a stack trace, use:
trace
Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.
If you want to remove a breakpoint, use
del
del address-expression
The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:
show b
To single-step the kernel, try:
s
This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:
n
This is different from gdb's
next statement; it is like gdb's
finish.
To examine data from memory, use (for example):
x/wx 0xf0133fe0,40
x/hd db_symtab_space
x/bc termbuf,10
x/s stringbuf
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:
x ,10
Similarly, use
x/ia foofunc,10
to disassemble the first 0x10 instructions of
foofunc, and display them along with their offset
from the beginning of foofunc.
To modify memory, use the write command:
w/b termbuf 0xa 0xb 0
w/w 0xf0010030 0 0
The command modifier
(b/h/w)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.
If you need to know the current registers, use:
show reg
Alternatively, you can display a single register value by e.g.
p $eax
and modify it by:
set $eax new-value
Should you need to call some kernel functions from DDB, simply
say:
call func(arg1, arg2, ...)
The return value will be printed.
For a &man.ps.1; style summary of all running processes, use:
ps
Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:
panic
This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another continue
statement.
call boot(0)
Which might be a good way to cleanly shut down the running system,
sync() all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.
call cpu_reset()
is the final way out of disaster and almost the same as hitting the
Big Red Button.
If you need a short command summary, simply type:
help
However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.
On-Line Kernel Debugging Using Remote GDB
This feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.
GDB has already supported remote debugging for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).
You should configure the kernel in question with config
-g, include into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with strip -x, and boot it
using the boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:
&prompt.user; gdb -k kernel
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
(kgdb)
Initialize the remote debugging session (assuming the first serial
port is being used) by:
(kgdb) target remote /dev/cuaa0
Now, on the target host (the one that entered DDB right before even
starting the device probe), type:
Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
db> gdb
DDB will respond with:
Next trap will enter GDB remote protocol mode
Every time you type gdb, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type s (step). Your hosting GDB
will now gain control over the target kernel:
Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
(kgdb)
You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.
Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:
&prompt.root; cd /usr/src/lkm/linux
&prompt.root; make clean; make COPTS=-g
Then install this version of the module on the target machine, load
it and use modstat to find out where it was
loaded:
&prompt.root; linux
&prompt.root; modstat
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod
Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module code
was relocated to. Use the add-symbol-file command in
GDB to tell the debugger about the module:
(kgdb) add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) y
(kgdb)
You now have access to all the symbols in the LKM.
Debugging a Console Driver
Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying at the Boot: prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.
diff --git a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
index 71e0e85ab3..28fcdb26ed 100644
--- a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
@@ -1,165 +1,165 @@
Adding New Kernel Configuration Options
Contributed by &a.joerg;
You should be familiar with the section about kernel configuration before reading
here.
What's a <emphasis>Kernel Option</emphasis>, Anyway?
The use of kernel options is basically described in the kernel configuration section.
There's also an explanation of historic
and
new-style
options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a make depend in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.
Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel .h file) must be written with the option
- concept in mind, i.e. the default must have been made overridable by the
+ concept in mind, i.e., the default can be overridden by the
config option. This is usually done with something like:
#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */
This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.
It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in
#ifdef THAT_OPTION
[your code here]
#endif
Simply mentioning THAT_OPTION in the config file
(with or without any value) will then turn on the corresponding piece of
code.
People familiar with the C language will immediately recognize that
everything could be counted as a config option
where there
is at least a single #ifdef referencing it...
However, it's unlikely that many people would put
options notyet,notdef
in their config file, and then wonder why the kernel compilation
falls over. :-)
Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the new-style option scheme, where
each option goes into a separate .h file in the
kernel compile directory, which is by convention named
opt_foo.h. This way,
the usual Makefile dependencies could be applied, and
make can determine what needs to be recompiled once
an option has been changed.
The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new #ifdef to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.
Now What Do I Have to Do for it?
First, edit sys/conf/options (or
sys/<arch>/conf/options.<arch>,
e. g. sys/i386/conf/options.i386), and select an
opt_foo.h file where
your new option would best go into.
If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
- behaviour of the SCSI subsystem can go into
+ behavior of the SCSI subsystem can go into
opt_scsi.h. By default, simply mentioning an
option in the appropriate option file, say FOO,
implies its value will go into the corresponding file
opt_foo.h. This can be overridden on the
right-hand side of a rule by specifying another filename.
If there is no
opt_foo.h already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
options[.<arch>]
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..
Packing too many options into a single
opt_foo.h will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.
Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet,
&prompt.user; find /usr/src/sys -type f | xargs fgrep NEW_OPTION
is your friend in finding them. Go and edit all those files, and add
#include "opt_foo.h" on
top before all the #include <xxx.h> stuff.
This sequence is most important as the options could override defaults
from the regular include files, if the defaults are of the form
#ifndef NEW_OPTION #define NEW_OPTION (something)
#endif in the regular header.
Adding an option that overrides something in a system header file
(i.e., a file sitting in /usr/include/sys/) is
almost always a mistake.
opt_foo.h cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.
diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
index f7d9341dd1..54770b0f3f 100644
--- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
@@ -1,920 +1,920 @@
Localization - I18N/L10N Usage and Setup
Contributed by &a.ache;
Rewritten by Michael Chin-Yuan Wu
keichii@mail.utexas.edu, 6 March 2000.
Synopsis
This section of the handbook discusses the internationalization
and localization of FreeBSD to different countries and different
settings. If the users wish to use languages other than the system
default English, he/she will have to setup the system accordingly.
Please note that language support for each language varies in level.
Hence, the user should contact the respective FreeBSD local group
that is responsible for each language.
The author realizes that he may have been incomplete in the
description of the i18n process in FreeBSD. Due to the various
- levels of i18n implementation in both the system and applicational
+ levels of i18n implementation in both the system and application
levels, we advise you to refer to individual documentation, man
pages, READMEs, and so forth.
Should you have any questions or suggestions regarding this
chapter, please email the author.
The Basics
What is i18n/l10n?
Developers shortened internationalization into the term i18n,
counting the number of letters between the first and the last
letters of internationalization. l10n uses the same naming
scheme, coming from "localization". Combined
together, i18n/l10n methods, protocols, and applications allow
users to use languages of their choice.
I18n applications are programmed using i18n kits under
libraries. It allows for developers to write a simple file and
translate displayed menus and texts to each language. We strongly
encourage programmers to follow this convention.
Why should I use i18n/l10n?
I18n/l10n is used whenever you wish to either view, input, or
process data in non-English languages.
What languages are supported in the i18n effort?
I18n and l10n are not FreeBSD specific. Currently, one can
choose from most of the major languages of the World, including
but not limited to: Chinese, German, Japanese, French, Russian,
and others.
Using Localization
In all its splendor, i18n is not FreeBSD-specific and is a
convention. We encourage you to help FreeBSD in following this
convention.
Localization settings are based on three main terms:
Language Code, Country Code, and Encoding. Locale names are
constructed from these parts as follows:
LanguageCode_CountryCode.Encoding
Language and Country Codes
In order to localize a FreeBSD system to a specific language
(or any other i18n-supporting UNIX's), the user needs to find out
the codes for the specify country and language (country
codes tell applications what variation of given
language to use). In addition, web
- browsers, SMTP/POP servers, HTTPd's, etc. make decisions based on
+ browsers, SMTP/POP servers, web servers, etc. make decisions based on
them. The following are examples of language/country codes:
Language/Country Code
Description
en_US
English - United States
ru_RU
Russian for Russia
zh_TW
Traditional Chinese for Taiwan
Encodings
Some languages use non-ASCII encodings that are 8-bit, wide
or multibyte characters, see &man.multibyte.3; for more
details. Older applications do not recognize them
and mistake them for control characters. Newer applications
usually do recognize 8-bit characters. Depending on the
implementation, users may be required to compile an application
with wide or multibyte characters support, or configure it correctly.
To be able to input and process wide or multibyte characters, the FreeBSD Ports collection has provided
each language with different programs. Refer to the i18n
documentation in the respective FreeBSD Port.
Specifically, the user needs to look at the application
documentation to decide on how to configure it correctly or to
pass correct values into the configure/Makefile/compiler.
Some things to keep in mind are:
Language specific single C chars character sets
(see &man.multibyte.3;), i.e.,
ISO_8859-1, KOI8-R, CP437.
Wide or multibyte encodings, f.e. EUC, Big5.
You can check the active list of character sets at the
IANA Registry.
I18n applications
In the FreeBSD Ports and Package system, i18n applications
have been named with i18n in their names for
easy identification. However, they do not always support the
language needed.
Setting Locale
Theoretically, one only needs to export the value of his/her
locale name as LANG in the login shell and is
usually done through the user's
~/.login_conf or the user login shell
configuration (~/.profile,
~/.bashrc, ~/.cshrc).
This should set all of the locale subsets (such as
LC_CTYPE, LC_CTIME, etc.). Please
refer to language-specific FreeBSD documentation for more
information.
You should set the following two values in your configuration
files:
LANG for POSIX &man.setlocale.3; family
functions
MM_CHARSET for applications' MIME character
set
This includes the user shell config, the specific application
config, and the X11 config.
Setting Locale Methods
There are two methods for setting locale, and both are
described below. The first (recommended one) is by assigning
the environment variables in login
class, and the second is by adding the environment
variable assignments to the system's shell startup file.
Login Classes Method
This method allows environment variables needed for locale
name and MIME character sets to be assigned once for every
possible shell instead of adding specific shell assignments to
each shell's startup file. User
Level Setup can be done by an user himself and Administrator Level Setup require
- superuser priviledges.
+ superuser privileges.
User Level Setup
Here is a minimal example of a
.login_conf file in user's home
directory which has both variables set for Latin-1
encoding:
me:My Account:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:
See Administrator Level
Setup and &man.login.conf.5; for more details.
Administrator Level Setup
Check that /etc/login.conf have the
correct language user's class. Make sure these settings
appear in /etc/login.conf:
language_name:accounts_title:\
:charset=MIME_charset:\
:lang=locale_name:\
:tc=default:
So sticking with our previous example using Latin-1, it
would look like this:
german:German Users Accounts:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:\
:tc=default:
Changing Login Classes with &man.vipw.8;
Use vipw to add new users, and make
the entry look like this:
user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh
Changing Login Classes with &man.adduser.8;
Use adduser to add new users, and do
the following:
Set defaultclass =
language in
/etc/adduser.conf. Keep in mind
you must enter a default class for
all users of other languages in this case.
An alternative variant is answering the specified
language each time that
Enter login class: default []:
appears from &man.adduser.8;
Another alternative is to use the following for each
user of a different language that you wish to
add:
&prompt.root; adduser -class language
Changing Login Classes with &man.pw.8;
If you use &man.pw.8; for adding new users, call it in
this form:
&prompt.root; pw useradd user_name -L language
Shell Startup File Method
This method is not recommended because it requires a
different setup for each possible login program chosen. Use
the Login Class Method
instead.
To add the locale name and MIME character set, just set
the two environment variables shown below in the
/etc/profile and/or
/etc/csh.login shell startup files. We
will use the German language as an example below:
In /etc/profile:
LANG=de_DE.ISO_8859-1; export LANG
MM_CHARSET=ISO-8859-1; export MM_CHARSET
Or in /etc/csh.login:
setenv LANG de_DE.ISO_8859-1
setenv MM_CHARSET ISO-8859-1
Alternatively, you can add the above instructions to
/usr/share/skel/dot.profile (similar to
what was used in /etc/profile above), or
/usr/share/skel/dot.login (similar to
what was used in /etc/csh.login
above).
For X11:
In $HOME/.xinitrc:
LANG=de_DE.ISO_8859-1; export LANG
Or:
setenv LANG de_DE.ISO_8859-1
Depending on your shell (see above).
Console Setup
For all single C chars character sets, set the correct
console fonts in /etc/rc.conf for the
language in question with:
font8x16=font_name
font8x14=font_name
font8x8=font_name
The font_name here is taken from
the /usr/share/syscons/fonts directory,
without the .fnt suffix.
Also be sure to set the correct keymap and screenmap for your
single C chars character set through
/stand/sysinstall.
Once inside sysinstall, choose Configure, then
Console. Alternatively, you can add the
following to /etc/rc.conf:
scrnmap=screenmap_name
keymap=keymap_name
keychange="fkey_number sequence"
The screenmap_name here is taken
from the /usr/share/syscons/scrnmaps
directory, without the .scm suffix. A
screenmap with a corresponding mapped font is usually needed as a
workaround for expanding bit 8 to bit 9 on a VGA adapter's font
character matrix in pseudographics area, i.e., to move letters out
of that area if screen font uses a bit 8 column.
If you have the following settings, insert the
kernel config specified in the paragraph after the list.
Console uses a screen font that utilizes 8-bit column font
character.
The moused daemon is enabled by setting the following in
your /etc/rc.conf:
moused_enable="YES"
A workaround for expanding 8-bit to 9-bit on a VGA adapter
is usually needed for the above settings. This workaround
disables 8-bit to 9-bit expansion of the font character with the
mouse cursor the sc0 console driver. To enable the workaround,
insert the following line into the kernel config.
options SC_MOUSE_CHAR=0x03
The keymap_name here is taken from
the /usr/share/syscons/keymaps directory,
without the .kbd suffix.
The keychange is usually needed to program
function keys to match the selected terminal type because
function key sequences can not be defined in the key map.
Also be sure to set the correct console terminal type in
/etc/ttys for all ttyv*
entries. Current pre-defined correspondences are:
Character Set
Terminal Type
ISO-8859-1 or ISO-8859-15
cons25l1
ISO-8859-2
cons25l2
KOI8-R
cons25r
CP437 (hardware default)
cons25
For wide or multibyte characters languages, use the correct
FreeBSD port in your
/usr/ports/language
directory. Some ports appear as console while the system sees it
as serial vtty's, hence you must reserve enough vtty's for both
X11 and the pseudo-serial console. Here is a partial list of
applications for using other languages in console:
Language
Location
Traditional Chinese (BIG-5)
/usr/ports/chinese/big5con
Japanese
/usr/ports/japanese/ja-kon2-* or
/usr/ports/japanese/Mule_Wnn
Korean
/usr/ports/korean/ko-han
X11 Setup
Although X11 is not part of the FreeBSD Project, we have
included some information here for FreeBSD users. For more
details, refer to the XFree86
- website or whichever X11 Server you use.
+ web site or whichever X11 Server you use.
In ~/.Xresources, you can additionally
tune application specific i18n settings (e.g., fonts, menus,
etc.).
Displaying Fonts
Install the X11 True Type-Common server (XTT-common) and
install the language truetype fonts. Setting the correct
locale should allow you to view your selected language in menus
and such.
Inputting Non-English Characters
The X11 Input Method (XIM) Protocol is a new standard for
all X11 clients. All X11 applications should be written as XIM
clients that take input from XIM Input servers. There are
several XIM servers available for different languages.
Printer Setup
Some single C chars character sets are usually hardware
coded into printers. Wide or multibyte
character sets require special setup and we recommend using
apsfilter. You may also convert the
document to Postscript or PDF formats using language specific
converters.
Kernel and File Systems
The FreeBSD FFS filesystem is 8-bit clean, so it can be used
with any single C chars character set (see &man.multibyte.3;),
but there is no character set
name stored in the filesystem; i.e., it is raw 8-bit and does not
know anything about encoding order. Officially, FFS does not
support any form of wide or multibyte character sets yet. However, some
wide or multibyte character sets have independent patches for FFS
enabling such support. They are only temporary unportable
solutions or hacks and we have decided to not include them in the
- source tree. Refer to respective languages' websites for more
+ source tree. Refer to respective languages' web sites for more
informations and the patch files.
- The FreeBSD MSDOS filesystem has the configurable ability to
- convert between MSDOS, Unicode character sets and chosen
+ The FreeBSD MS-DOS filesystem has the configurable ability to
+ convert between MS-DOS, Unicode character sets and chosen
FreeBSD filesystem character sets. See &man.mount.msdos.8; for
details.
Advanced Topics
If you wish to compile i18n applications or program i18n
compliant applications, please read this section.
Compiling i18n Programs
Many FreeBSD Ports have been ported with i18n support. Some
of them are marked with -i18n in the port name. These and many
other programs have built in support for i18n and need no special
consideration.
However, some applications such as MySQL need to be have the
Makefile configured with the specific
charset. This is usually done in the
Makefile or done by passing a value to
configure in the source.
Programming i18n Compliant Applications
To make your application more useful for speakers of other
languages, we hope that you will program i18n compliant. The GNU
gcc compiler, GUI Libraries like QT and GTK support i18n through
special handling of strings. Making a program i18n compliant is
very easy. It allows contributors to port your application to
other languages quickly. Refer to library specific i18n
documentation for more details.
To the contrary of common perception, i18n compliant code is
easy to write. Usually, it only involves wrapping your strings
with library specific functions. In addition, please be sure to
allow for wide or multibyte characters support.
A Call to Unify the i18n effort
It has come to our attention that the individual i18n/l10n
efforts for each country has been repeating each others'
efforts. Many of us have been reinventing the wheel repeatedly
and inefficiently. We hope that the various major groups in
- i18n could congregate into a group effort similiar to the Core
+ i18n could congregate into a group effort similar to the Core
Team's responsibility.
Currently, we hope that, when you write or port i18n
programs, you would send it out to each country's related
FreeBSD mailing lists for testing. In the future, we hope to
create applications that work in all the languages
out-of-the-box without dirty hacks.
Perl and Python
Perl and Python have i18n and wide characters handling
libraries. Please use them for i18n compliance.
In older FreeBSD versions,
Perl may gives warning about not having a wide characters locale
that is already installed in your system. You can set the
environmental variable LD_PRELOAD to
/usr/lib/libxpg4.so in your shell.
In sh-based shells:
LD_PRELOAD=/usr/lib/libxpg4.so
In C-based shells:
setenv LD_PRELOAD /usr/lib/libxpg4.so
Localizing FreeBSD to Specific Languages
Russian Language (KOI8-R encoding)
Originally contributed by
&a.ache;.
For more information about KOI8-R encoding, see the KOI8-R References
(Russian Net Character Set).
Locale Setup
Put the following lines into your
~/.login_conf file:
me:My Account:\
:charset=KOI8-R:\
:lang=ru_RU.KOI8-R:
See earlier in this chapter for examples of setting up the
locale.
Console Setup
Add the following to your kernel configuration
file:
options SC_MOUSE_CHAR=0x03
Use following settings in
/etc/rc.conf:
keymap="ru.koi8-r"
keychange="61 ^[[K"
scrnmap="koi8-r2cp866"
font8x16="cp866b-8x16"
font8x14="cp866-8x14"
font8x8="cp866-8x8"
Note that the ^[ here stands for a
real Escape character (\033) entered directly in
/etc/rc.conf, not for sequence of two
characters '^' and '['.
For each ttyv* entry in
/etc/ttys, use
cons25r as the terminal type.
See earlier in this chapter for examples of setting up the
console.
Printer Setup
Since most printers with Russian characters come with
hardware code page CP866, a special output filter is needed for
KOI8-R -> CP866 conversion. Such a filter is installed by
default as /usr/libexec/lpr/ru/koi2alt.
A Russian printer /etc/printcap entry
should look like:
lp|Russian local line printer:\
:sh:of=/usr/libexec/lpr/ru/koi2alt:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
See &man.printcap.5; for a detailed description.
- MSDOS FS and Russian Filenames
+ MS-DOS FS and Russian Filenames
The following example &man.fstab.5; entry enables support
- for Russian filenames in mounted MSDOS filesystems:
+ for Russian filenames in mounted MS-DOS filesystems:
/dev/ad0s2 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0
See &man.mount.msdos.8; for a detailed description of the
and options.
X11 Setup
Do non-X locale
setup first as described.
The Russian KOI8-R locale
may not work with old XFree86 releases (lower than 3.3).
The XFree86 port from
/usr/ports/x11/XFree86 already is the
most recent XFree86 version, so it will work if you
install XFree86 from the port. This should not be an
issue unless you are using an old version of
FreeBSD.
Go to the
/usr/ports/russian/X.language directory
and issue the following command:
&prompt.root; make install
The above port installs the latest version of the KOI8-R
fonts. XFree86 3.3 already has some KOI8-R fonts, but these
are scaled better.
Check the "Files" section
in your /etc/XF86Config file.
The following
lines must be added before any other
FontPath entries:
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"
If you use a high resolution video mode, swap the 75 dpi
and 100 dpi lines.
To activate a Russian keyboard, add the following to the
"Keyboard" section of your
XF86Config file:
XkbLayout "ru"
XkbOptions "grp:caps_toggle"
Also make sure that XkbDisable is
turned off (commented out) there.
The RUS/LAT switch will be CapsLock.
The old CapsLock function is still
available via Shift+CapsLock (in LAT mode
only).
If you have Windows
keys on your keyboard,
and notice that some non-alphabetical keys are mapped
incorrectly in RUS mode, add the following line in your
XF86Config file:
XkbVariant "winkeys"
The Russian XKB keyboard may not work with old XFree86
versions, see the above
note for more information. The Russian XKB
keyboard may also not work with non-localized
applications as well. Minimally localized applications
should call a XtSetLanguageProc (NULL, NULL,
NULL); function early in the program.
See
KOI8-R for X-Window for more instructions on
localizing X11 applications.
Traditional Chinese Localization for Taiwan
The FreeBSD-Taiwan Project has an i18n/l10n tutorial for
FreeBSD at http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html
using many /usr/ports/chinese/* applications.
The editor for the zh-l10n-tut is Clive Lin
Clive@CirX.org. You can also cvsup the following
collections at freebsd.sinica.edu.tw:
Collection
Description
outta-port tag=.
Beta-quality Ports Collection for Chinese
zh-l10n-tut tag=.
Localizing FreeBSD Tutorial in BIG-5 Traditional
Chinese
zh-doc tag=.
- FreeBSD Documenation Translation to BIG-5 Traditional
+ FreeBSD Documentation Translation to BIG-5 Traditional
Chinese
Chuan-Hsing Shen s874070@mail.yzu.edu.tw has
created the Chinese
FreeBSD Extension (CFE) using FreeBSD-Taiwan's
zh-l10n-tut. The packages and the script files
are available at ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/cfe.txt
and ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/.
German Language Localization (For All ISO 8859-1
Languages)
Slaven Rezic eserte@cs.tu-berlin.de wrote a
tutorial how to use umlauts on a FreeBSD machine. The tutorial
is written in German and available at http://www.de.FreeBSD.org/de/umlaute/.
Japanese and Korean Language Localization
For Japanese, refer to http://www.jp.FreeBSD.org/,
and for Korean, refer to http://www.kr.FreeBSD.org/.
Non-English FreeBSD Documentation
Some FreeBSD contributors have translated parts of FreeBSD to
other languages. They are available through links on the main site or in
/usr/share/doc.
diff --git a/en_US.ISO_8859-1/books/handbook/install/chapter.sgml b/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
index 8b3744d8a6..b7f3e22014 100644
--- a/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
@@ -1,1673 +1,1673 @@
Installing FreeBSD
Restructured, updated, and parts rewritten by &a.jim;,
January 2000.
Synopsis
The following chapter will attempt to guide you through the
install of FreeBSD on your system. It can be installed through a
variety of methods, including anonymous FTP (assuming you have
network connectivity via modem or local network), CDROM, floppy
disk, tape, an MS-DOS partition, or even NFS.
No matter which method you choose, you will need to get started
by creating the installation disks as described
in the next section. By
booting into the FreeBSD installer, even if you are not planning on
installing FreeBSD right away, will provide important information
about compatibility with your hardware. This information may
dictate which installation options are even possible for you. It
can also provide clues early-on in the process to potential problems
you may come across later.
If you plan to install FreeBSD via anonymous FTP, the only
things you will need are the installation floppies. The
install program itself will handle anything else that is
required.
For more information about obtaining FreeBSD, see the Obtaining FreeBSD section of the
Appendix.
By now, you are probably wondering what exactly it is you need
to do. Continue on to the installation guide.
Installation Guide
The following sections will guide you through preparing for and
actually installing FreeBSD. If you find something missing, please
let us know about it by sending email to the &a.doc;.
Preparing for the Installation
There are various things you should do in preparation for the
install. The following describes what needs to be done prior to
each type of installation.
The first thing you should do is make sure your hardware is
supported by FreeBSD. The list of supported hardware should
come in handy here. ;-) It would also be a good idea to make a
list of any special
cards you have installed,
such as SCSI controllers, ethernet cards, sound cards, etc..
The list should include their IRQs and IO port addresses.
Creating the Boot Floppies
Please read the installation
boot image information before proceeding. To make the
installation boot disks from the image files, do the
following:
The first thing you will need to do is download the image
files. These can be retrieved from the floppies directory
of the FreeBSD FTP site or your local mirror.
If you are installing from an MS-DOS partition,
download the fdimage.exe
program or get it from tools\fdimage.exe
on the CDROM and then run it like so:
E:\> tools\fdimage floppies\kern.flp a:
The fdimage program will format
the A: drive and then copy
kern.flp to it (assuming that you are
at the top level of a FreeBSD distribution and the floppy
images live in a floppies
subdirectory, which is typically the case).
If you are using a UNIX-based system to create the
boot floppies, do the following:
&prompt.root; dd if=kern.flp of=disk_device
disk_device is the
/dev entry for the floppy drive. On
FreeBSD, this is /dev/rfd0 for the
A: drive and
/dev/rfd1 for the
B: drive.
With the kern.flp disk in your floppy
drive, reboot your computer. After a couple of minutes
(while the kernel loads from the floppy), you
will be prompted to insert
the mfsroot.flp, after which the
installation will proceed normally.
Before Installing from CDROM
If your CDROM is of an unsupported type, please skip ahead
to the MS-DOS Preparation
section.
There is not a whole lot of preparation needed if you are
installing from one of Walnut Creek CDROM's
FreeBSD CDROMs (other CDROM distributions may work as well,
though we cannot say for certain as we have no hand or say in
how they created). You can either boot into the CD installation
directly from DOS using the install.bat or
you can make floppies with the makeflp.bat
command.
If the CD has El Torito boot support and your system
supports booting directly from the CDROM drive (many older
systems do NOT), simply insert the first
FreeBSD of the set into the drive and reboot your system. You
will be put into the install menu directly from the CD.
If you are installing from an MS-DOS partition and have
the proper drivers to access your CD, run the
install.bat script provided on the CDROM.
This will attempt to boot the FreeBSD installation directly
from DOS.
You must do this from actual DOS (i.e., boot in DOS
mode) and not from a DOS window under Windows.
For the easiest interface of all (from DOS), type
view. This will bring up a DOS menu utility
that leads you through all of the available options.
If you are creating the boot floppies from a UNIX machine,
see the Creating the Boot
Floppies section of this guide for examples.
Once you have booted from DOS or floppy, you should then be
able to select CDROM as the media type during the install
process and load the entire distribution from CDROM. No other
types of installation media should be required.
After your system is fully installed and you have rebooted
(from the hard disk), you can mount the CDROM at any time by
typing:
&prompt.root; mount /cdrom
Before removing the CD from the drive again, you must first
unmount it. This is done with the following command:
&prompt.root; umount /cdrom
Do not just remove it from the drive!
Before invoking the installation, be sure that the CDROM
is in the drive so that the install probe can find it. This
is also true if you wish the CDROM to be added to the default
system configuration automatically during the install (whether
or not you actually use it as the installation media).
Finally, if you would like people to be able to FTP install
FreeBSD directly from the CDROM in your machine, you will find
it quite easy. After the machine is fully installed, you simply
need to add the following line to the password file (using the
vipw command):
ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent
Anyone with network connectivity to your machine can now
chose a media type of FTP and type in
ftp://your machine
after picking Other
in the FTP sites menu during
the install.
If you choose to enable anonymous FTP during the
installation of your system, the installation program will do
the above procedure for you.
Before installing from Floppies
If you must install from floppy disk (which we suggest you
do NOT do), either due to unsupported
hardware or simply because you insist on doing things the hard
way, you must first prepare some floppies for the install.
At a minimum, you will need as many 1.44MB or 1.2MB floppies
as it takes to hold all the files in the
bin (binary distribution) directory. If
you are preparing the floppies from DOS, then they
MUST be formatted using the MS-DOS
FORMAT command. If you are using Windows,
use Explorer to format the disks (right-click on the
A: drive, and select "Format".
Do NOT trust factory pre-formatted
floppies! Format them again yourself, just to be sure. Many
problems reported by our users in the past have resulted from
the use of improperly formatted media, which is why we are
making a point of it now.
If you are creating the floppies on another FreeBSD machine,
a format is still not a bad idea, though you do not need to put
a DOS filesystem on each floppy. You can use the
disklabel and newfs
commands to put a UFS filesystem on them instead, as the
following sequence of commands (for a 3.5" 1.44MB floppy)
illustrate:
&prompt.root; fdformat -f 1440 fd0.1440
&prompt.root; disklabel -w -r fd0.1440 floppy3
&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0
Use fd0.1200 and
floppy5 for 5.25" 1.2MB disks.
Then you can mount and write to them like any other
filesystem.
After you have formatted the floppies, you will need to copy
the files to them. The distribution files are split into chunks
conveniently sized so that 5 of them will fit on a conventional
1.44MB floppy. Go through all your floppies, packing as many
files as will fit on each one, until you have all of the
distributions you want packed up in this fashion. Each
distribution should go into a subdirectory on the floppy, e.g.:
a:\bin\bin.aa,
a:\bin\bin.ab, and so on.
Once you come to the Media screen during the install
process, select Floppy
and you will be prompted
for the rest.
Before Installing from MS-DOS
To prepare for an installation from an MS-DOS partition,
copy the files from the distribution into a directory named,
for example, c:\FreeBSD. The directory
structure of the CDROM or FTP site must be partially reproduced
within this directory, so we suggest using the DOS
xcopy command if you are copying it from a
CD. For example, to prepare for a minimal installation of
FreeBSD:
C:\> md c:\FreeBSD
C:\> xcopy /s e:\bin c:\FreeBSD\bin\
C:\> xcopy /s e:\manpages c:\FreeBSD\manpages\
Assuming that C: is where you have
free space and E: is where your CDROM
is mounted.
If you do not have a CDROM drive, you can download the
distribution from
ftp.FreeBSD.org. Each distribution is in its own directory;
for example, the bin distribution can be
found in the &rel.current;/bin directory.
For as many distributions you wish to install from an MS-DOS
partition (and you have the free space for), install each one
under c:\FreeBSD — the
BIN distribution is the only one required for
a minimum installation.
Before Installing from QIC/SCSI Tape
Installing from tape is probably the easiest method, short
of an online FTP install or CDROM install. The installation
- program expects the files to be simply tar'ed onto the tape, so
+ program expects the files to be simply tarred onto the tape, so
after getting all of the distribution files you are interested
in, simply tar them onto the tape like so:
&prompt.root; cd /freebsd/distdir
&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2
When you go to do the installation, you should also make
sure that you leave enough room in some temporary directory
(which you will be allowed to choose) to accommodate the
full contents of the tape you have created.
Due to the non-random access nature of tapes, this method of
installation requires quite a bit of temporary storage. You
should expect to require as much temporary storage as you have
stuff written on tape.
When starting the installation, the tape must be in the
drive before booting from the boot
floppy. The installation probe may otherwise fail to find
it.
Before Installing over a Network
There are three types of network installations you can do.
Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
or Ethernet (a standard ethernet controller (includes some
PCMCIA)).
The SLIP support is rather primitive, and limited primarily
to hard-wired links, such as a serial cable running between a
laptop computer and another computer. The link should be
hard-wired as the SLIP installation does not currently offer a
dialing capability; that facility is provided with the PPP
utility, which should be used in preference to SLIP whenever
possible.
If you are using a modem, then PPP is almost certainly
your only choice. Make sure that you have your service
provider's information handy as you will need to know it fairly
early in the installation process.
If you use PAP or CHAP to connect your ISP (in other
words, if you can connect to the ISP in Windows without
using a script), then all you will need to do is type in
dial at the
ppp prompt. Otherwise,
you will need to know
how to dial your ISP using the AT commands
specific to your modem, as the PPP dialer provides only a very
simple terminal emulator. Please
to the user-ppp handbook and FAQ entries for further
information. If you have problems, logging can be directed to
the screen using the command set log local
....
If a hard-wired connection to another FreeBSD (2.0-R or
later) machine is available, you might also consider installing
over a laplink
parallel port cable. The data rate
over the parallel port is much higher than what is typically
possible over a serial line (up to 50kbytes/sec), thus resulting
in a quicker installation.
Finally, for the fastest possible network installation, an
ethernet adapter is always a good choice! FreeBSD supports most
common PC ethernet cards; a table of supported cards (and their
required settings) is provided in the Supported Hardware list. If you are
using one of the supported PCMCIA ethernet cards, also be sure
that it is plugged in before the laptop is
powered on! FreeBSD does not, unfortunately, currently support
hot insertion of PCMCIA cards during installation.
You will also need to know your IP address on the network,
the netmask value for your address class, and the name of your
machine. If you are installing over a PPP connection and do not
have a static IP, fear not, the IP address can be dynamically
assigned by your ISP. Your system administrator can tell you
which values to use for your particular network setup. If you
will be referring to other hosts by name rather than IP address,
you will also need a name server and possibly the address of a
gateway (if you are using PPP, it is your provider's IP address)
to use in talking to it. If you do not know the answers to all
or most of these questions, then you should really probably talk
to your system administrator or ISP before trying
this type of installation.
Before Installing via NFS
The NFS installation is fairly straight-forward. Simply
copy the FreeBSD distribution files you want onto a server
somewhere and then point the NFS media selection at it.
If this server supports only privileged port
(as is generally the default for Sun workstations), you will
need to set this option in the Options menu before
installation can proceed.
If you have a poor quality ethernet card which suffers
from very slow transfer rates, you may also wish to toggle the
appropriate Options flag.
In order for NFS installation to work, the server must
support subdir mounts, e.g., if your FreeBSD 3.4 distribution
directory lives
on:ziggy:/usr/archive/stuff/FreeBSD, then
ziggy will have to allow the direct mounting
of /usr/archive/stuff/FreeBSD, not just
/usr or
/usr/archive/stuff.
In FreeBSD's /etc/exports file, this
is controlled by the . Other NFS
servers may have different conventions. If you are getting
permission denied
messages from the server, then
it is likely that you do not have this enabled
properly.
Before Installing via FTP
FTP installation may be done from any FreeBSD mirror site
containing a reasonably up-to-date version of FreeBSD. A full
list of FTP mirrors located all over the world is provided
during the install process.
If you are installing from an FTP site not listed in this
menu, or are having trouble getting your name server
configured properly, you can also specify a URL to use by
selecting the choice labeled Other
in that menu.
You can also use the IP address of a machine you wish to
install from, so the following would work in the absence of a
name server:
ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASE
There are two FTP installation modes you can choose from,
active or passive FTP.
FTP Active
This option will make all FTP transfers
use Active
mode. This will not work through firewalls, but will
often work with older FTP servers that do not support
passive mode. If your connection hangs with passive
mode (the default), try active!
FTP Passive
This option instructs FreeBSD to use
Passive
mode for all FTP operations.
This allows the user to pass through firewalls
that do not allow incoming connections on random port
addresses.
Active and passive modes are not the same as a
proxy
connection, where a proxy FTP server is
listening and forwarding FTP requests!
For a proxy FTP server, you should usually give the name
of the server you really want as a part of the username, after
an @
sign. The proxy server then
fakes
the real server. For example, assuming
you want to install from ftp.FreeBSD.org, using the proxy FTP
server foo.bar.com, listening on
port 1024.
In this case, you go to the options menu, set the FTP
username to ftp@ftp.FreeBSD.org, and the password to your
email address. As your installation media, you specify FTP
(or passive FTP, if the proxy supports it), and the URL
ftp://foo.bar.com:1234/pub/FreeBSD.
Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, you are able to install from
that machine (which will fetch the files
from ftp.FreeBSD.org as your
installation requests them.
Check your BIOS drive numbering
If you have used features in your BIOS to renumber your disk
drives without recabling them then you should read first to ensure you do not
confused.
Installing FreeBSD
Once you have completed the pre-installation step relevant to
your situation, you are ready to install FreeBSD!
Although you should not experience any difficulties, there is
always the chance you might, no matter how slight it is. If this
is the case in your situation, then you may wish to go back and
re-read the relevant preparation section or sections. Perhaps you
will come across something you missed the first time. If you are
having hardware problems, or FreeBSD refuses to boot at all, read
the Hardware Guide on the boot floppy for a list of possible
solutions.
The FreeBSD boot floppies contain all of the online
documentation you should need to be able to navigate through an
installation. If it does not, please let us know what you found
to be the most confusing or most lacking. Send your comments to
the &a.doc;. It is the objective of the installation program
(sysinstall) to be self-documenting enough that painful
step-by-step
guides are no longer necessary. It may
take us a little while to reach that objective, but nonetheless,
it is still our objective :-)
Meanwhile, you may also find the following typical
installation sequence
to be helpful:
Boot the kern.flp floppy and when
asked, remove it and insert the
mfsroot.flp and hit return. After a
boot sequence which can take anywhere from 30 seconds to 3
minutes, depending on your hardware, you should be presented
with a menu of initial choices. If the
kern.flp floppy does not boot at all or
the boot hangs at some stage, read the Q&A section of the
Hardware Guide on the floppy for possible causes.
Press F1. You should see some basic usage instructions on
the menu screen and general navigation. If you have not used
this menu system before then please read
this thoroughly.
Select the Options item and set any special preferences
you may have.
Select a Standard, Express, or Custom install, depending on
whether or not you would like the installation to help you
through a typical installation, give you a high degree of
- control over each step, or simply whizz through it (using
+ control over each step, or simply whiz through it (using
reasonable defaults when possible) as fast as possible. If
you have never used FreeBSD before, the Standard installation
method is most recommended.
The final configuration menu choice allows you to further
configure your FreeBSD installation by giving you menu-driven
access to various system defaults. Some items, like
networking, may be especially important if you did a CDROM,
tape, or floppy install and have not yet configured your
network interfaces (assuming you have any). Properly
configuring such interfaces here will allow FreeBSD to come up
on the network when you first reboot from the hard
disk.
Supported Hardware
FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and
PCI bus based PCs, ranging from the 386SX to Pentium class machines
(though the 386SX is not recommended). Support for generic IDE or
ESDI drive configurations, various SCSI controllers, and network and
serial cards is also provided.
- In order to run FreeBSD, a recommmended minimum of eight
+ In order to run FreeBSD, a recommended minimum of eight
megabytes of RAM is suggested. Sixteen megabytes is the preferred
amount of RAM as you may have some trouble with anything less than
sixteen depending on your hardware.
What follows is a list of hardware currently known to work with
FreeBSD. There may be other hardware that works as well, but we
have simply not received any confirmation of it.
Disk Controllers
WD1003 (any generic MFM/RLL)
WD1007 (any generic IDE/ESDI)
IDE
ATA
Adaptec 1535 ISA SCSI controllers
Adaptec 154X series ISA SCSI controllers
Adaptec 174X series EISA SCSI controllers in standard and
enhanced mode
Adaptec 274X/284X/2920C/294X/2950/3940/3950
(Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers
Adaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI
controllers
Adaptec 1510 series ISA SCSI controllers (not for bootable
devices)
Adaptec 152X series ISA SCSI controllers
Adaptec AIC-6260 and AIC-6360 based boards, which include
the AHA-152X and SoundBlaster SCSI cards
AdvanSys SCSI controllers (all models)
BusLogic MultiMaster W
Series Host Adapters
including BT-948, BT-958, BT-9580
BusLogic MultiMaster C
Series Host Adapters
including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C,
BT-757C, BT-757CD, BT-545C, BT-540CF
BusLogic MultiMaster S
Series Host Adapters
including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D,
BT-545S, BT-542D, BT-742A, BT-542B
BusLogic MultiMaster A
Series Host Adapters
including BT-742A, BT-542B
AMI FastDisk controllers that are true BusLogic
MultiMaster clones are also supported.
BusLogic/Mylex Flashpoint
adapters are NOT
yet supported.
DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III,
SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The
DPT SmartRAID/CACHE V is not yet supported.
Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES,
SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and
Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES.
SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820,
53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI
controllers including ASUS SC-200, Data Technology DTC3130
(all variants), Diamond FirePort (all), NCR cards (all),
SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan
S1365
QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre
Channel Adapters
DTC 3290 EISA SCSI controller in 1542 evaluation
mode
With all supported SCSI controllers, full support is provided
for SCSI-I and SCSI-II peripherals, including hard disks, optical
disks, tape drives (including DAT and 8mm Exabyte), medium
changers, processor target devices, and CDROM drives. WORM
devices that support CDROM commands are supported for read-only
access by the CDROM driver. WORM/CD-R/CD-RW writing support is
provided by cdrecord, which is in the ports tree.
The following CD-ROM type systems are supported at this
time:
cd - SCSI interface (includes
ProAudio Spectrum and SoundBlaster SCSI)
matcd - Matsushita/Panasonic
(Creative Soundblaster) proprietary interface (562/563
models)
scd - Sony proprietary interface
(all models)
acd - ATAPI IDE interface
The following drivers were supported under the old SCSI
subsystem, but are NOT YET supported under the new CAM SCSI
subsystem:
NCR5380/NCR53400 (ProAudio Spectrum
) SCSI
controller
UltraStor 14F, 24F, and 34F SCSI controllers
Seagate ST01/02 SCSI controllers
Future Domain 8XX/950 series SCSI controllers
WD7000 SCSI controller
There is work-in-progress to port the UltraStor driver
to the new CAM framework, but no estimates on when or if it
will be completed.
Unmaintained drivers, they might or might not work for your
hardware:
Floppy tape interface (Colorado/Mountain/Insight)
mcd - Mitsumi proprietary CD-ROM
interface (all models)
Network Cards
Adaptec Duralink PCI fast ethernet adapters based on the
Adaptec AIC-6195 fast ethernet controller chip, including the
following:
ANA-62011 64-bit single port 10/100baseTX
adapter
ANA-62022 64-bit dual port 10/100baseTX adapter
ANA-62044 64-bit quad port 10/100baseTX adapter
ANA-69011 32-bit single port 10/100baseTX
adapter
ANA-62020 64-bit single port 100baseFX adapter
Allied-Telesyn AT1700 and RE2000 cards
Alteon Networks PCI gigabit ethernet NICs based on the
Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC
(Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620
(Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq
EtherWORKS 1000, NEC Gigabit Ethernet
AMD PCnet/PCI (79c970 and 53c974 or 79c974)
RealTek 8129/8139 fast ethernet NICs including the
following:
Allied-Telesyn AT2550
Allied-Telesyn AT2500TX
Genius GF100TXR (RTL8139)
NDC Communications NE100TX-E
OvisLink LEF-8129TX
OvisLink LEF-8139TX
Netronix Inc. EA-1210 NetEther 10/100
KTX-9130TX 10/100 Fast Ethernet
Accton Cheetah
EN1027D (MPX 5030/5038;
RealTek 8139 clone?)
SMC EZ Card 10/100 PCI 1211-TX
Lite-On 98713, 98713A, 98715, and 98725 fast ethernet
NICs, including the LinkSys EtherFast LNE100TX, NetGear
FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston
KNE110TX
Macronix 98713, 98713A, 98715, 98715A, and 98725 fast
ethernet NICs including the NDC Communications SFA100A
(98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B
(98715), SVEC PN102TX (98713)
Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs
including the LinkSys EtherFast LNE100TX version 2
- Winbond W89C840F fast ethernet nics including the
+ Winbond W89C840F fast ethernet NICs including the
Trendware TE100-PCIE
VIA Technologies VT3043 Rhine I
and
VT86C100A Rhine II
fast ethernet NICs including
the Hawking Technologies PN102TX and D-Link DFE-530TX
Silicon Integrated Systems SiS 900 and SiS 7016 PCI fast
ethernet NICs
Sundance Technologies ST201 PCI fast ethernet NICs
including the D-Link DFE-550TX
SysKonnect SK-984x PCI gigabit ethernet cards including
the SK-9841 1000baseLX (single mode fiber, single port),
the SK-9842 1000baseSX (multimode fiber, single port), the
SK-9843 1000baseLX (single mode fiber, dual port), and the
SK-9844 1000baseSX (multimode fiber, dual port).
Texas Instruments ThunderLAN PCI NICs, including the
Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100
Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and
10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P
w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX
UTP, and the Racore 8165 10/100baseTX and 8148
10baseT/100baseTX/100baseFX multi-personality cards
ADMtek AL981-based and AN985-based PCI fast ethernet
NICs
ASIX Electronics AX88140A PCI NICs including the Alfa Inc.
GFC2204 and CNet Pro110B
DEC EtherWORKS III NICs (DE203, DE204, and DE205)
DEC EtherWORKS II NICs (DE200, DE201, DE202, and
DE422)
DEC DC21040, DC21041, or DC21140 based NICs (SMC
Etherpower 8432T, DE245, etc.)
DEC FDDI (DEFPA/DEFEA) NICs
Efficient ENI-155p ATM PCI
FORE PCA-200E ATM PCI
Fujitsu MB86960A/MB86965A
HP PC Lan+ cards (model numbers: 27247B and 27252A)
Intel EtherExpress (not recommended due to driver
instability)
Intel EtherExpress Pro/10
Intel EtherExpress Pro/100B PCI Fast Ethernet
Isolan AT 4141-0 (16 bit)
Isolink 4110 (8 bit)
Novell NE1000, NE2000, and NE2100 Ethernet
interfaces
PCI network cards emulating the NE2000, including the
RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA
VT86C926
3Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507
Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA),
3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink
III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL
server adapter, 3CSOHO100-TX OfficeConnect adapter
Toshiba ethernet cards
PCMCIA ethernet cards from IBM and National Semiconductor
are also supported
USB Peripherals
A wide range of USB peripherals are supported. Owing to the
generic nature of most USB devices, with some exceptions any
device of a given class will be supported even if not explicitly
listed here.
USB keyboards
USB mice
USB printers and USB to parallel printer conversion
cables
USB hubs
Motherboard chipsets:
ALi Aladdin-V
Intel 82371SB (PIIX3) and 82371AB and EB (PIIX4)
chipsets
NEC uPD 9210 Host Controller
VIA 83C572 USB Host Controller
and any other UHCI or OHCI compliant motherboard chipset
(no exceptions known).
PCI plug-in USB host controllers
ADS Electronics PCI plug-in card (2 ports)
Entrega PCI plug-in card (4 ports)
Specific USB devices reported to be working:
Agiler Mouse 29UO
Andromeda hub
Apple iMac mouse and keyboard
ATen parallel printer adapter
Belkin F4U002 parallel printer adapter and Belkin
mouse
BTC BTC7935 keyboard with mouse port
Cherry G81-3504
Chic mouse
Cypress mouse
Entrega USB-to-parallel printer adapter
Genius Niche mouse
Iomega USB Zip 100 MB
Kensington Mouse-in-a-Box
Logitech M2452 keyboard
Logictech wheel mouse (3 buttons)
Logitech PS/2 / USB mouse (3 buttons)
MacAlly mouse (3 buttons)
MacAlly self-powered hub (4 ports)
Microsoft Intellimouse (3 buttons)
Microsoft keyboard
NEC hub
Trust Ami Mouse (3 buttons)
ISDN (European DSS1 [Q.921/Q.931] protocol)
Asuscom I-IN100-ST-DV (experimental, may work)
Asuscom ISDNlink 128K
AVM A1
AVM Fritz!Card classic
AVM Fritz!Card PCI
AVM Fritz!Card PCMCIA (currently FreeBSD 3.x only)
AVM Fritz!Card PnP (currently FreeBSD 3.x only)
Creatix ISDN-S0/8
Creatix ISDN-S0/16
Creatix ISDN-S0 PnP
Dr.Neuhaus Niccy 1008
Dr.Neuhaus Niccy 1016
Dr.Neuhaus Niccy GO@ (ISA PnP)
Dynalink IS64PH (no longer maintained)
ELSA 1000pro ISA
ELSA 1000pro PCI
ELSA PCC-16
ITK ix1 micro (currently FreeBSD 3.x only)
ITK ix1 micro V.3 (currently FreeBSD 3.x only)
Sagem Cybermod (ISA PnP, may work)
Sedlbauer Win Speed
Siemens I-Surf 2.0
Stollman Tina-pp (under development)
Teles S0/8
Teles S0/16
Teles S0/16.3 (the c
Versions - like 16.3c
- are unsupported!)
Teles S0 PnP (experimental, may work)
3Com/USRobotics Sportster ISDN TA intern (non-PnP
version)
Miscellaneous Devices
AST 4 port serial card using shared IRQ
ARNET 8 port serial card using shared IRQ
ARNET (now Digiboard) Sync 570/i high-speed serial
Boca BB1004 4-Port serial card (Modems NOT
supported)
Boca IOAT66 6-Port serial card (Modems supported)
Boca BB1008 8-Port serial card (Modems NOT
supported)
Boca BB2016 16-Port serial card (Modems supported)
Cyclades Cyclom-y Serial Board
Moxa SmartIO CI-104J 4-Port serial card
STB 4 port card using shared IRQ
SDL Communications RISCom/8 Serial Board
SDL Communications RISCom/N2 and N2pci high-speed sync
serial boards
Specialix SI/XIO/SX multiport serial cards, with both the
older SIHOST2.x and the new enhanced
(transputer based, aka JET) host cards; ISA, EISA and PCI are
supported
Stallion multiport serial boards: EasyIO, EasyConnection
8/32 & 8/64, ONboard 4/16 and Brumby
Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum,
Gravis UltraSound, and Roland MPU-401 sound cards
Connectix QuickCam
Matrox Meteor Video frame grabber
Creative Labs Video Spigot frame grabber
Cortex1 frame grabber
- Various frame grabbers based ont he the Brooktree Bt848
+ Various frame grabbers based on the Brooktree Bt848
and Bt878 chip
HP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R
drives
Bus mice
PS/2 mice
Standard PC Joystick
X-10 power controllers
GPIB and Transputer drives
Genius and Mustek hand scanners
Floppy tape drives (some rather old models only, driver is
rather stale)
Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA
standard speed (2Mbps) and turbo speed (6Mbps) wireless
network adapters and workalikes (NCR WaveLAN/IEEE 802.11,
Cabletron RoamAbout 802.11 DS)
The ISA versions of these adapters are actually PCMCIA
cards combined with an ISA to PCMCIA bridge card, so both
kinds of devices work with the same driver.
FreeBSD currently does NOT support IBM's microchannel (MCA)
bus.
Troubleshooting
The following section covers basic installation troubleshooting,
such as common problems people have reported. There are also a few
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.
What to do if something goes wrong...
Due to various limitations of the PC architecture, it is
impossible for probing to be 100% reliable, however, there are a
few things you can do if it fails.
Check the supported
hardware list to make sure your hardware is
supported.
If your hardware is supported and you still experience
lock-ups or other problems, reset your computer, and when the
visual kernel configuration option is given, choose it. This will
allow you to go through your hardware and supply information to the
system about it. The kernel on the boot disks is configured
assuming that most hardware devices are in their factory default
configuration in terms of IRQs, IO addresses, and DMA channels. If
your hardware has been reconfigured, you will most likely need to
use the configuration editor to tell FreeBSD where to find
things.
It is also possible that a probe for a device not present will
cause a later probe for another device that is present to fail. In
that case, the probes for the conflicting driver(s) should be
disabled.
Do not disable any drivers you will need during the
installation, such as your screen (sc0).
If the installation wedges or fails mysteriously after leaving
the configuration editor, you have probably removed or changed
something you should not have. Reboot and try again.
In configuration mode, you can:
List the device drivers installed in the kernel.
Change device drivers for hardware that is not present in
your system.
Change IRQs, DRQs, and IO port addresses used by a device
driver.
After adjusting the kernel to match your hardware
configuration, type Q to boot with the new
settings. Once the installation has completed, any changes you
made in the configuration mode will be permanent so you do not have
to reconfigure every time you boot. It is still highly likely that
you will eventually want to build a custom kernel.
MS-DOS User's Questions and Answers
Many users wish to install FreeBSD on PCs inhabited by MS-DOS.
Here are some commonly asked questions about installing FreeBSD on
such systems.
Help, I have no space! Do I need to delete everything
first?
If your machine is already running MS-DOS and has little
or no free space available for the FreeBSD installation, all
hope is not lost! You may find the FIPS utility, provided
in the tools directory on the FreeBSD
CDROM or various FreeBSD FTP sites to be quite
useful.
FIPS allows you to split an existing MS-DOS partition
into two pieces, preserving the original partition and
allowing you to install onto the second free piece. You
first defragment your MS-DOS partition using the Windows
DEFRAG utility (go into Explorer, right-click on the
hard drive, and choose to defrag your
hard drive), or Norton Disk Tools. You then must run FIPS. It
will prompt you for the rest of the information it needs.
Afterwards, you can reboot and install FreeBSD on the new
free slice. See the Distributions menu
for an estimate of how much free space you will need for the
kind of installation you want.
There is also a very useful
product from PowerQuest
called Partition Magic. This
application has far more functionality than FIPS, and is
highly recommended if you plan to often add/remove
operating systems (like me). However, it does cost
money, and if you plan to install FreeBSD once and then
leave it there, FIPS will probably be fine for you.
Can I use compressed MS-DOS filesystems from
FreeBSD?
No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use whatever
portion of the filesystem you leave uncompressed. The rest
of the filesystem will show up as one large file (the
stacked/double spaced file!). Do not remove that
file or you will probably regret it
greatly!
It is probably better to create another uncompressed
primary MS-DOS partition and use this for communications
between MS-DOS and FreeBSD.
Can I mount my extended MS-DOS partition?
Yes. DOS extended partitions are mapped in at the end
of the other slices
in FreeBSD, e.g., your
D: drive might be
/dev/da0s5, your
E: drive,
/dev/da0s6, and so on. This example
assumes, of course, that your extended partition is on SCSI
drive 0. For IDE drives, substitute ad
for da appropriately if installing
4.0-RELEASE or later, and substitute
wd for da if you
are installing a version of FreeBSD prior to 4.0. You otherwise
mount extended partitions exactly like you would any other
DOS drive, for example:
&prompt.root; mount -t msdos /dev/ad0s5 /dos_d
diff --git a/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml b/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
index feb3ee10b1..9578579ac9 100644
--- a/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
@@ -1,3222 +1,3222 @@
FreeBSD Internals
DMA: What it is and How it Works
Copyright © 1995,1997 &a.uhclem;, All Rights
Reserved. 10 December 1996. Last Update 8 October
1997.
Direct Memory Access (DMA) is a method of allowing data to be moved
from one location to another in a computer without intervention from the
central processor (CPU).
The way that the DMA function is implemented varies between computer
architectures, so this discussion will limit itself to the
implementation and workings of the DMA subsystem on the IBM Personal
Computer (PC), the IBM PC/AT and all of its successors and
clones.
The PC DMA subsystem is based on the Intel 8237 DMA controller. The
8237 contains four DMA channels that can be programmed independently and
any one of the channels may be active at any moment. These channels are
numbered 0, 1, 2 and 3. Starting with the PC/AT, IBM added a second
8237 chip, and numbered those channels 4, 5, 6 and 7.
The original DMA controller (0, 1, 2 and 3) moves one byte in each
transfer. The second DMA controller (4, 5, 6, and 7) moves 16-bits from
two adjacent memory locations in each transfer, with the first byte
always coming from an even-numbered address. The two controllers are
identical components and the difference in transfer size is caused by
the way the second controller is wired into the system.
The 8237 has two electrical signals for each channel, named DRQ and
-DACK. There are additional signals with the names HRQ (Hold Request),
HLDA (Hold Acknowledge), -EOP (End of Process), and the bus control
signals -MEMR (Memory Read), -MEMW (Memory Write), -IOR (I/O Read), and
-IOW (I/O Write).
The 8237 DMA is known as a fly-by
DMA controller.
This means that the data being moved from one location to another does
not pass through the DMA chip and is not stored in the DMA chip.
Subsequently, the DMA can only transfer data between an I/O port and a
memory address, but not between two I/O ports or two memory
locations.
The 8237 does allow two channels to be connected together to allow
memory-to-memory DMA operations in a non-fly-by
mode,
but nobody in the PC industry uses this scarce resource this way since
it is faster to move data between memory locations using the
CPU.
In the PC architecture, each DMA channel is normally activated only
when the hardware that uses a given DMA channel requests a transfer by
asserting the DRQ line for that channel.
A Sample DMA transfer
Here is an example of the steps that occur to cause and perform a
DMA transfer. In this example, the floppy disk controller (FDC) has
just read a byte from a diskette and wants the DMA to place it in
memory at location 0x00123456. The process begins by the FDC
asserting the DRQ2 signal (the DRQ line for DMA channel 2) to alert
the DMA controller.
The DMA controller will note that the DRQ2 signal is asserted. The
DMA controller will then make sure that DMA channel 2 has been
programmed and is unmasked (enabled). The DMA controller also makes
sure that none of the other DMA channels are active or want to be
active and have a higher priority. Once these checks are complete,
the DMA asks the CPU to release the bus so that the DMA may use the
bus. The DMA requests the bus by asserting the HRQ signal which goes
to the CPU.
The CPU detects the HRQ signal, and will complete executing the
current instruction. Once the processor has reached a state where it
can release the bus, it will. Now all of the signals normally
generated by the CPU (-MEMR, -MEMW, -IOR, -IOW and a few others) are
placed in a tri-stated condition (neither high or low) and then the
CPU asserts the HLDA signal which tells the DMA controller that it is
now in charge of the bus.
Depending on the processor, the CPU may be able to execute a few
additional instructions now that it no longer has the bus, but the CPU
will eventually have to wait when it reaches an instruction that must
read something from memory that is not in the internal processor cache
or pipeline.
Now that the DMA is in charge
, the DMA activates its
-MEMR, -MEMW, -IOR, -IOW output signals, and the address outputs from
the DMA are set to 0x3456, which will be used to direct the byte that
is about to transferred to a specific memory location.
The DMA will then let the device that requested the DMA transfer
know that the transfer is commencing. This is done by asserting the
-DACK signal, or in the case of the floppy disk controller, -DACK2 is
asserted.
The floppy disk controller is now responsible for placing the byte
to be transferred on the bus Data lines. Unless the floppy controller
needs more time to get the data byte on the bus (and if the peripheral
does need more time it alerts the DMA via the READY signal), the DMA
will wait one DMA clock, and then de-assert the -MEMW and -IOR signals
so that the memory will latch and store the byte that was on the bus,
and the FDC will know that the byte has been transferred.
Since the DMA cycle only transfers a single byte at a time, the
FDC now drops the DRQ2 signal, so the DMA knows that it is no longer
needed. The DMA will de-assert the -DACK2 signal, so that the FDC
knows it must stop placing data on the bus.
The DMA will now check to see if any of the other DMA channels
have any work to do. If none of the channels have their DRQ lines
asserted, the DMA controller has completed its work and will now
tri-state the -MEMR, -MEMW, -IOR, -IOW and address signals.
Finally, the DMA will de-assert the HRQ signal. The CPU sees
this, and de-asserts the HOLDA signal. Now the CPU activates its
-MEMR, -MEMW, -IOR, -IOW and address lines, and it resumes executing
instructions and accessing main memory and the peripherals.
For a typical floppy disk sector, the above process is repeated
512 times, once for each byte. Each time a byte is transferred, the
address register in the DMA is incremented and the counter in the DMA
that shows how many bytes are to be transferred is decremented.
When the counter reaches zero, the DMA asserts the EOP signal,
which indicates that the counter has reached zero and no more data
will be transferred until the DMA controller is reprogrammed by the
CPU. This event is also called the Terminal Count (TC). There is only
one EOP signal, and since only DMA channel can be active at any
instant, the DMA channel that is currently active must be the DMA
channel that just completed its task.
If a peripheral wants to generate an interrupt when the transfer
of a buffer is complete, it can test for its -DACKn signal and the EOP
signal both being asserted at the same time. When that happens, it
means the DMA will not transfer any more information for that
peripheral without intervention by the CPU. The peripheral can then
assert one of the interrupt signals to get the processors' attention.
In the PC architecture, the DMA chip itself is not capable of
generating an interrupt. The peripheral and its associated hardware
is responsible for generating any interrupt that occurs.
Subsequently, it is possible to have a peripheral that uses DMA but
does not use interrupts.
It is important to understand that although the CPU always
releases the bus to the DMA when the DMA makes the request, this
action is invisible to both applications and the operating systems,
except for slight changes in the amount of time the processor takes to
execute instructions when the DMA is active. Subsequently, the
processor must poll the peripheral, poll the registers in the DMA
chip, or receive an interrupt from the peripheral to know for certain
when a DMA transfer has completed.
DMA Page Registers and 16Meg address space limitations
You may have noticed earlier that instead of the DMA setting the
address lines to 0x00123456 as we said earlier, the DMA only set
0x3456. The reason for this takes a bit of explaining.
When the original IBM PC was designed, IBM elected to use both DMA
and interrupt controller chips that were designed for use with the
8085, an 8-bit processor with an address space of 16 bits (64K).
Since the IBM PC supported more than 64K of memory, something had to
be done to allow the DMA to read or write memory locations above the
64K mark. What IBM did to solve this problem was to add an external
data latch for each DMA channel that holds the upper bits of the
address to be read to or written from. Whenever a DMA channel is
active, the contents of that latch are written to the address bus and
kept there until the DMA operation for the channel ends. IBM called
these latches Page Registers
.
So for our example above, the DMA would put the 0x3456 part of the
address on the bus, and the Page Register for DMA channel 2 would put
0x0012xxxx on the bus. Together, these two values form the complete
address in memory that is to be accessed.
Because the Page Register latch is independent of the DMA chip,
the area of memory to be read or written must not span a 64K physical
boundary. For example, if the DMA accesses memory location 0xffff,
after that transfer the DMA will then increment the address register
and the DMA will access the next byte at location 0x0000, not 0x10000.
The results of letting this happen are probably not intended.
Physical
64K boundaries should not be confused
with 8086-mode 64K Segments
, which are created by
mathematically adding a segment register with an offset register.
Page Registers have no address overlap and are mathematically OR-ed
together.
To further complicate matters, the external DMA address latches on
the PC/AT hold only eight bits, so that gives us 8+16=24 bits, which
means that the DMA can only point at memory locations between 0 and
16Meg. For newer computers that allow more than 16Meg of memory, the
standard PC-compatible DMA cannot access memory locations above
16Meg.
To get around this restriction, operating systems will reserve a
RAM buffer in an area below 16Meg that also does not span a physical
64K boundary. Then the DMA will be programmed to transfer data from
the peripheral and into that buffer. Once the DMA has moved the data
into this buffer, the operating system will then copy the data from
the buffer to the address where the data is really supposed to be
stored.
When writing data from an address above 16Meg to a DMA-based
peripheral, the data must be first copied from where it resides into a
buffer located below 16Meg, and then the DMA can copy the data from
the buffer to the hardware. In FreeBSD, these reserved buffers are
called Bounce Buffers
. In the MS-DOS world, they are
sometimes called Smart Buffers
.
A new implementation of the 8237, called the 82374, allows 16
bits of page register to be specified, allows access to the entire
32 bit address space, without the use of bounce buffers.
DMA Operational Modes and Settings
The 8237 DMA can be operated in several modes. The main ones
are:
Single
A single byte (or word) is transferred. The DMA must
release and re-acquire the bus for each additional byte. This is
commonly-used by devices that cannot transfer the entire block
of data immediately. The peripheral will request the DMA each
time it is ready for another transfer.
The standard PC-compatible floppy disk controller (NEC 765)
only has a one-byte buffer, so it uses this mode.
Block/Demand
Once the DMA acquires the system bus, an entire block of
data is transferred, up to a maximum of 64K. If the peripheral
needs additional time, it can assert the READY signal to suspend
the transfer briefly. READY should not be used excessively, and
for slow peripheral transfers, the Single Transfer Mode should
be used instead.
The difference between Block and Demand is that once a Block
transfer is started, it runs until the transfer count reaches
zero. DRQ only needs to be asserted until -DACK is asserted.
Demand Mode will transfer one more bytes until DRQ is
de-asserted, at which point the DMA suspends the transfer and
releases the bus back to the CPU. When DRQ is asserted later,
the transfer resumes where it was suspended.
Older hard disk controllers used Demand Mode until CPU
speeds increased to the point that it was more efficient to
transfer the data using the CPU, particularly if the memory
locations used in the transfer were above the 16Meg mark.
Cascade
This mechanism allows a DMA channel to request the bus, but
then the attached peripheral device is responsible for placing
the addressing information on the bus instead of the DMA. This
is also used to implement a technique known as Bus
Mastering
.
When a DMA channel in Cascade Mode receives control of the
bus, the DMA does not place addresses and I/O control signals on
the bus like the DMA normally does when it is active. Instead,
the DMA only asserts the -DACK signal for the active DMA
channel.
At this point it is up to the peripheral connected to that
DMA channel to provide address and bus control signals. The
peripheral has complete control over the system bus, and can do
reads and/or writes to any address below 16Meg. When the
peripheral is finished with the bus, it de-asserts the DRQ line,
and the DMA controller can then return control to the CPU or to
some other DMA channel.
Cascade Mode can be used to chain multiple DMA controllers
together, and this is exactly what DMA Channel 4 is used for in
the PC architecture. When a peripheral requests the bus on DMA
channels 0, 1, 2 or 3, the slave DMA controller asserts HLDREQ,
but this wire is actually connected to DRQ4 on the primary DMA
controller instead of to the CPU. The primary DMA controller,
thinking it has work to do on Channel 4, requests the bus from
the CPU using HLDREQ signal. Once the CPU grants the bus to the
primary DMA controller, -DACK4 is asserted, and that wire is
actually connected to the HLDA signal on the slave DMA
controller. The slave DMA controller then transfers data for
the DMA channel that requested it (0, 1, 2 or 3), or the slave
DMA may grant the bus to a peripheral that wants to perform its
own bus-mastering, such as a SCSI controller.
Because of this wiring arrangement, only DMA channels 0, 1,
2, 3, 5, 6 and 7 are usable with peripherals on PC/AT
systems.
DMA channel 0 was reserved for refresh operations in early
IBM PC computers, but is generally available for use by
peripherals in modern systems.
When a peripheral is performing Bus Mastering, it is
important that the peripheral transmit data to or from memory
constantly while it holds the system bus. If the peripheral
cannot do this, it must release the bus frequently so that the
system can perform refresh operations on main memory.
The Dynamic RAM used in all PCs for main memory must be
accessed frequently to keep the bits stored in the components
charged
. Dynamic RAM essentially consists of
millions of capacitors with each one holding one bit of data.
These capacitors are charged with power to represent a
1 or drained to represent a
0. Because all capacitors leak, power must
be added at regular intervals to keep the 1
values intact. The RAM chips actually handle the task of
pumping power back into all of the appropriate locations in RAM,
but they must be told when to do it by the rest of the computer
so that the refresh activity won't interfere with the computer
wanting to access RAM normally. If the computer is unable to
refresh memory, the contents of memory will become corrupted in
just a few milliseconds.
Since memory read and write cycles count
as
refresh cycles (a dynamic RAM refresh cycle is actually an
incomplete memory read cycle), as long as the peripheral
controller continues reading or writing data to sequential
memory locations, that action will refresh all of memory.
Bus-mastering is found in some SCSI host interfaces and
other high-performance peripheral controllers.
Autoinitialize
This mode causes the DMA to perform Byte, Block or Demand
transfers, but when the DMA transfer counter reaches zero, the
counter and address are set back to where they were when the DMA
channel was originally programmed. This means that as long as
the peripheral requests transfers, they will be granted. It is
up to the CPU to move new data into the fixed buffer ahead of
where the DMA is about to transfer it when doing output
operations, and read new data out of the buffer behind where the
DMA is writing when doing input operations.
This technique is frequently used on audio devices that have
small or no hardware sample
buffers. There is
additional CPU overhead to manage this circular
buffer, but in some cases this may be the only way to eliminate
the latency that occurs when the DMA counter reaches zero and
the DMA stops transfers until it is reprogrammed.
Programming the DMA
The DMA channel that is to be programmed should always be
masked
before loading any settings. This is because the
hardware might unexpectedly assert the DRQ for that channel, and the
DMA might respond, even though not all of the parameters have been
loaded or updated.
Once masked, the host must specify the direction of the transfer
(memory-to-I/O or I/O-to-memory), what mode of DMA operation is to be
used for the transfer (Single, Block, Demand, Cascade, etc), and
finally the address and length of the transfer are loaded. The length
that is loaded is one less than the amount you expect the DMA to
transfer. The LSB and MSB of the address and length are written to
the same 8-bit I/O port, so another port must be written to first to
guarantee that the DMA accepts the first byte as the LSB and the
second byte as the MSB of the length and address.
Then, be sure to update the Page Register, which is external to
the DMA and is accessed through a different set of I/O ports.
Once all the settings are ready, the DMA channel can be un-masked.
That DMA channel is now considered to be armed
, and will
respond when the DRQ line for that channel is asserted.
Refer to a hardware data book for precise programming details for
the 8237. You will also need to refer to the I/O port map for the PC
system, which describes where the DMA and Page Register ports are
located. A complete port map table is located below.
DMA Port Map
All systems based on the IBM-PC and PC/AT have the DMA hardware
located at the same I/O ports. The complete list is provided below.
Ports assigned to DMA Controller #2 are undefined on non-AT
designs.
0x00–0x1f DMA Controller #1 (Channels 0, 1, 2 and
3)
DMA Address and Count Registers
0x00
write
Channel 0 starting address
0x00
read
Channel 0 current address
0x01
write
Channel 0 starting word count
0x01
read
Channel 0 remaining word count
0x02
write
Channel 1 starting address
0x02
read
Channel 1 current address
0x03
write
Channel 1 starting word count
0x03
read
Channel 1 remaining word count
0x04
write
Channel 2 starting address
0x04
read
Channel 2 current address
0x05
write
Channel 2 starting word count
0x05
read
Channel 2 remaining word count
0x06
write
Channel 3 starting address
0x06
read
Channel 3 current address
0x07
write
Channel 3 starting word count
0x07
read
Channel 3 remaining word count
DMA Command Registers
0x08
write
Command Register
0x08
read
Status Register
0x09
write
Request Register
0x09
read
-
0x0a
write
Single Mask Register Bit
0x0a
read
-
0x0b
write
Mode Register
0x0b
read
-
0x0c
write
Clear LSB/MSB Flip-Flop
0x0c
read
-
0x0d
write
Master Clear/Reset
0x0d
read
Temporary Register (not available on newer
versions)
0x0e
write
Clear Mask Register
0x0e
read
-
0x0f
write
Write All Mask Register Bits
0x0f
read
Read All Mask Register Bits (only in Intel
82374)
0xc0–0xdf DMA Controller #2 (Channels 4, 5, 6 and
7)
DMA Address and Count Registers
0xc0
write
Channel 4 starting address
0xc0
read
Channel 4 current address
0xc2
write
Channel 4 starting word count
0xc2
read
Channel 4 remaining word count
0xc4
write
Channel 5 starting address
0xc4
read
Channel 5 current address
0xc6
write
Channel 5 starting word count
0xc6
read
Channel 5 remaining word count
0xc8
write
Channel 6 starting address
0xc8
read
Channel 6 current address
0xca
write
Channel 6 starting word count
0xca
read
Channel 6 remaining word count
0xcc
write
Channel 7 starting address
0xcc
read
Channel 7 current address
0xce
write
Channel 7 starting word count
0xce
read
Channel 7 remaining word count
DMA Command Registers
0xd0
write
Command Register
0xd0
read
Status Register
0xd2
write
Request Register
0xd2
read
-
0xd4
write
Single Mask Register Bit
0xd4
read
-
0xd6
write
Mode Register
0xd6
read
-
0xd8
write
Clear LSB/MSB Flip-Flop
0xd8
read
-
0xda
write
Master Clear/Reset
0xda
read
Temporary Register (not present in Intel
82374)
0xdc
write
Clear Mask Register
0xdc
read
-
0xde
write
Write All Mask Register Bits
0xdf
read
Read All Mask Register Bits (only in Intel
82374)
0x80–0x9f DMA Page Registers
0x87
r/w
Channel 0 Low byte (23-16) page Register
0x83
r/w
Channel 1 Low byte (23-16) page Register
0x81
r/w
Channel 2 Low byte (23-16) page Register
0x82
r/w
Channel 3 Low byte (23-16) page Register
0x8b
r/w
Channel 5 Low byte (23-16) page Register
0x89
r/w
Channel 6 Low byte (23-16) page Register
0x8a
r/w
Channel 7 Low byte (23-16) page Register
0x8f
r/w
Low byte page Refresh
0x400–0x4ff 82374 Enhanced DMA Registers
The Intel 82374 EISA System Component (ESC) was introduced in
early 1996 and includes a DMA controller that provides a superset of
8237 functionality as well as other PC-compatible core peripheral
components in a single package. This chip is targeted at both EISA
and PCI platforms, and provides modern DMA features like
scatter-gather, ring buffers as well as direct access by the system
DMA to all 32 bits of address space.
If these features are used, code should also be included to
provide similar functionality in the previous 16 years worth of
PC-compatible computers. For compatibility reasons, some of the
82374 registers must be programmed after
programming the traditional 8237 registers for each transfer.
Writing to a traditional 8237 register forces the contents of some
of the 82374 enhanced registers to zero to provide backward software
compatibility.
0x401
r/w
Channel 0 High byte (bits 23-16) word count
0x403
r/w
Channel 1 High byte (bits 23-16) word count
0x405
r/w
Channel 2 High byte (bits 23-16) word count
0x407
r/w
Channel 3 High byte (bits 23-16) word count
0x4c6
r/w
Channel 5 High byte (bits 23-16) word count
0x4ca
r/w
Channel 6 High byte (bits 23-16) word count
0x4ce
r/w
Channel 7 High byte (bits 23-16) word count
0x487
r/w
Channel 0 High byte (bits 31-24) page Register
0x483
r/w
Channel 1 High byte (bits 31-24) page Register
0x481
r/w
Channel 2 High byte (bits 31-24) page Register
0x482
r/w
Channel 3 High byte (bits 31-24) page Register
0x48b
r/w
Channel 5 High byte (bits 31-24) page Register
0x489
r/w
Channel 6 High byte (bits 31-24) page Register
0x48a
r/w
Channel 6 High byte (bits 31-24) page Register
0x48f
r/w
High byte page Refresh
0x4e0
r/w
Channel 0 Stop Register (bits 7-2)
0x4e1
r/w
Channel 0 Stop Register (bits 15-8)
0x4e2
r/w
Channel 0 Stop Register (bits 23-16)
0x4e4
r/w
Channel 1 Stop Register (bits 7-2)
0x4e5
r/w
Channel 1 Stop Register (bits 15-8)
0x4e6
r/w
Channel 1 Stop Register (bits 23-16)
0x4e8
r/w
Channel 2 Stop Register (bits 7-2)
0x4e9
r/w
Channel 2 Stop Register (bits 15-8)
0x4ea
r/w
Channel 2 Stop Register (bits 23-16)
0x4ec
r/w
Channel 3 Stop Register (bits 7-2)
0x4ed
r/w
Channel 3 Stop Register (bits 15-8)
0x4ee
r/w
Channel 3 Stop Register (bits 23-16)
0x4f4
r/w
Channel 5 Stop Register (bits 7-2)
0x4f5
r/w
Channel 5 Stop Register (bits 15-8)
0x4f6
r/w
Channel 5 Stop Register (bits 23-16)
0x4f8
r/w
Channel 6 Stop Register (bits 7-2)
0x4f9
r/w
Channel 6 Stop Register (bits 15-8)
0x4fa
r/w
Channel 6 Stop Register (bits 23-16)
0x4fc
r/w
Channel 7 Stop Register (bits 7-2)
0x4fd
r/w
Channel 7 Stop Register (bits 15-8)
0x4fe
r/w
Channel 7 Stop Register (bits 23-16)
0x40a
write
Channels 0-3 Chaining Mode Register
0x40a
read
Channel Interrupt Status Register
0x4d4
write
Channels 4-7 Chaining Mode Register
0x4d4
read
Chaining Mode Status
0x40c
read
Chain Buffer Expiration Control Register
0x410
write
Channel 0 Scatter-Gather Command Register
0x411
write
Channel 1 Scatter-Gather Command Register
0x412
write
Channel 2 Scatter-Gather Command Register
0x413
write
Channel 3 Scatter-Gather Command Register
0x415
write
Channel 5 Scatter-Gather Command Register
0x416
write
Channel 6 Scatter-Gather Command Register
0x417
write
Channel 7 Scatter-Gather Command Register
0x418
read
Channel 0 Scatter-Gather Status Register
0x419
read
Channel 1 Scatter-Gather Status Register
0x41a
read
Channel 2 Scatter-Gather Status Register
0x41b
read
Channel 3 Scatter-Gather Status Register
0x41d
read
Channel 5 Scatter-Gather Status Register
0x41e
read
Channel 5 Scatter-Gather Status Register
0x41f
read
Channel 7 Scatter-Gather Status Register
0x420-0x423
r/w
Channel 0 Scatter-Gather Descriptor Table Pointer
Register
0x424-0x427
r/w
Channel 1 Scatter-Gather Descriptor Table Pointer
Register
0x428-0x42b
r/w
Channel 2 Scatter-Gather Descriptor Table Pointer
Register
0x42c-0x42f
r/w
Channel 3 Scatter-Gather Descriptor Table Pointer
Register
0x434-0x437
r/w
Channel 5 Scatter-Gather Descriptor Table Pointer
Register
0x438-0x43b
r/w
Channel 6 Scatter-Gather Descriptor Table Pointer
Register
0x43c-0x43f
r/w
Channel 7 Scatter-Gather Descriptor Table Pointer
Register
The FreeBSD VM System
Contributed by &a.dillon;. 6 Feb 1999
Management of physical
memory—<literal>vm_page_t</literal>
Physical memory is managed on a page-by-page basis through the
vm_page_t structure. Pages of physical memory are
categorized through the placement of their respective
vm_page_t structures on one of several paging
queues.
A page can be in a wired, active, inactive, cache, or free state.
Except for the wired state, the page is typically placed in a doubly
link list queue representing the state that it is in. Wired pages
are not placed on any queue.
FreeBSD implements a more involved paging queue for cached and
free pages in order to implement page coloring. Each of these states
involves multiple queues arranged according to the size of the
processor's L1 and L2 caches. When a new page needs to be allocated,
FreeBSD attempts to obtain one that is reasonably well aligned from
the point of view of the L1 and L2 caches relative to the VM object
the page is being allocated for.
Additionally, a page may be held with a reference count or locked
with a busy count. The VM system also implements an ultimate
locked
state for a page using the PG_BUSY bit in the page's
flags.
In general terms, each of the paging queues operates in a LRU
fashion. A page is typically placed in a wired or active state
initially. When wired, the page is usually associated with a page
table somewhere. The VM system ages the page by scanning pages in a
more active paging queue (LRU) in order to move them to a less-active
paging queue. Pages that get moved into the cache are still
associated with a VM object but are candidates for immediate reuse.
Pages in the free queue are truly free. FreeBSD attempts to minimize
the number of pages in the free queue, but a certain minimum number of
truly free pages must be maintained in order to accommodate page
allocation at interrupt time.
If a process attempts to access a page that does not exist in its
page table but does exist in one of the paging queues ( such as the
inactive or cache queues), a relatively inexpensive page reactivation
fault occurs which causes the page to be reactivated. If the page
does not exist in system memory at all, the process must block while
the page is brought in from disk.
FreeBSD dynamically tunes its paging queues and attempts to
maintain reasonable ratios of pages in the various queues as well as
- attempts to maintain a reasonable breakdown of clean vs dirty pages.
+ attempts to maintain a reasonable breakdown of clean v.s. dirty pages.
The amount of rebalancing that occurs depends on the system's memory
load. This rebalancing is implemented by the pageout daemon and
involves laundering dirty pages (syncing them with their backing
store), noticing when pages are activity referenced (resetting their
position in the LRU queues or moving them between queues), migrating
pages between queues when the queues are out of balance, and so forth.
FreeBSD's VM system is willing to take a reasonable number of
reactivation page faults to determine how active or how idle a page
actually is. This leads to better decisions being made as to when to
launder or swap-out a page.
The unified buffer
cache—<literal>vm_object_t</literal>
FreeBSD implements the idea of a generic VM object
.
VM objects can be associated with backing store of various
types—unbacked, swap-backed, physical device-backed, or
file-backed storage. Since the filesystem uses the same VM objects to
manage in-core data relating to files, the result is a unified buffer
cache.
VM objects can be shadowed. That is, they
can be stacked on top of each other. For example, you might have a
swap-backed VM object stacked on top of a file-backed VM object in
order to implement a MAP_PRIVATE mmap()ing. This stacking is also
used to implement various sharing properties, including,
copy-on-write, for forked address spaces.
It should be noted that a vm_page_t can only be
associated with one VM object at a time. The VM object shadowing
implements the perceived sharing of the same page across multiple
instances.
Filesystem I/O—<literal>struct buf</literal>
vnode-backed VM objects, such as file-backed objects, generally
need to maintain their own clean/dirty info independent from the VM
system's idea of clean/dirty. For example, when the VM system decides
to synchronize a physical page to its backing store, the VM system
needs to mark the page clean before the page is actually written to
its backing s tore. Additionally, filesystems need to be able to map
portions of a file or file metadata into KVM in order to operate on
it.
The entities used to manage this are known as filesystem buffers,
struct buf's, and also known as
bp's. When a filesystem needs to operate on a
portion of a VM object, it typically maps part of the object into a
struct buf and the maps the pages in the struct buf into KVM. In the
same manner, disk I/O is typically issued by mapping portions of
objects into buffer structures and then issuing the I/O on the buffer
structures. The underlying vm_page_t's are typically busied for the
duration of the I/O. Filesystem buffers also have their own notion of
being busy, which is useful to filesystem driver code which would
rather operate on filesystem buffers instead of hard VM pages.
FreeBSD reserves a limited amount of KVM to hold mappings from
struct bufs, but it should be made clear that this KVM is used solely
to hold mappings and does not limit the ability to cache data.
Physical data caching is strictly a function of
vm_page_t's, not filesystem buffers. However,
since filesystem buffers are used placehold I/O, they do inherently
limit the amount of concurrent I/O possible. As there are usually a
few thousand filesystem buffers available, this is not usually a
problem.
Mapping Page Tables - vm_map_t, vm_entry_t
FreeBSD separates the physical page table topology from the VM
system. All hard per-process page tables can be reconstructed on the
fly and are usually considered throwaway. Special page tables such as
those managing KVM are typically permanently preallocated. These page
tables are not throwaway.
FreeBSD associates portions of vm_objects with address ranges in
virtual memory through vm_map_t and
vm_entry_t structures. Page tables are directly
synthesized from the
vm_map_t/vm_entry_t/
vm_object_t hierarchy. Remember when I mentioned
that physical pages are only directly associated with a
vm_object. Well, that isn't quite true.
vm_page_t's are also linked into page tables that
they are actively associated with. One vm_page_t
can be linked into several pmaps, as page tables
are called. However, the hierarchical association holds so all
references to the same page in the same object reference the same
vm_page_t and thus give us buffer cache unification
across the board.
KVM Memory Mapping
FreeBSD uses KVM to hold various kernel structures. The single
largest entity held in KVM is the filesystem buffer cache. That is,
mappings relating to struct buf entities.
Unlike Linux, FreeBSD does NOT map all of physical memory into
KVM. This means that FreeBSD can handle memory configurations up to
4G on 32 bit platforms. In fact, if the mmu were capable of it,
FreeBSD could theoretically handle memory configurations up to 8TB on
a 32 bit platform. However, since most 32 bit platforms are only
capable of mapping 4GB of ram, this is a moot point.
KVM is managed through several mechanisms. The main mechanism
used to manage KVM is the zone allocator. The
zone allocator takes a chunk of KVM and splits it up into
constant-sized blocks of memory in order to allocate a specific type
of structure. You can use vmstat -m to get an
overview of current KVM utilization broken down by zone.
Tuning the FreeBSD VM system
A concerted effort has been made to make the FreeBSD kernel
dynamically tune itself. Typically you do not need to mess with
anything beyond the maxusers and
NMBCLUSTERS kernel config options. That is, kernel
compilation options specified in (typically)
/usr/src/sys/i386/conf/CONFIG_FILE.
A description of all available kernel configuration options can be
found in /usr/src/sys/i386/conf/LINT.
In a large system configuration you may wish to increase
maxusers. Values typically range from 10 to 128.
Note that raising maxusers too high can cause the
system to overflow available KVM resulting in unpredictable operation.
It is better to leave maxusers at some reasonable number and add other
options, such as NMBCLUSTERS, to increase specific
resources.
If your system is going to use the network heavily, you may want
to increase NMBCLUSTERS. Typical values range from
1024 to 4096.
The NBUF parameter is also traditionally used
to scale the system. This parameter determines the amount of KVA the
system can use to map filesystem buffers for I/O. Note that this
parameter has nothing whatsoever to do with the unified buffer cache!
This parameter is dynamically tuned in 3.0-CURRENT and later kernels
and should generally not be adjusted manually. We recommend that you
not try to specify an NBUF
parameter. Let the system pick it. Too small a value can result in
extremely inefficient filesystem operation while too large a value can
starve the page queues by causing too many pages to become wired
down.
By default, FreeBSD kernels are not optimized. You can set
debugging and optimization flags with the
makeoptions directive in the kernel configuration.
Note that you should not use unless you can
accommodate the large (typically 7 MB+) kernels that result.
makeoptions DEBUG="-g"
makeoptions COPTFLAGS="-O2 -pipe"
Sysctl provides a way to tune kernel parameters at run-time. You
typically do not need to mess with any of the sysctl variables,
especially the VM related ones.
Run time VM and system tuning is relatively straightforward.
First, use softupdates on your UFS/FFS filesystems whenever possible.
/usr/src/contrib/sys/softupdates/README contains
instructions (and restrictions) on how to configure it up.
Second, configure sufficient swap. You should have a swap
partition configured on each physical disk, up to four, even on your
work
disks. You should have at least 2x the swap space
as you have main memory, and possibly even more if you do not have a
lot of memory. You should also size your swap partition based on the
maximum memory configuration you ever intend to put on the machine so
you do not have to repartition your disks later on. If you want to be
able to accommodate a crash dump, your first swap partition must be at
least as large as main memory and /var/crash must
have sufficient free space to hold the dump.
NFS-based swap is perfectly acceptable on -4.x or later systems,
but you must be aware that the NFS server will take the brunt of the
paging load.
IPv6/IPsec Implementation
Contributed by &a.shin;, 5 March
2000.
This section should explain IPv6 and IPsec related implementation
internals. These functionalities are derived from KAME project
IPv6
Conformance
The IPv6 related functions conforms, or tries to conform to
the latest set of IPv6 specifications. For future reference we list
some of the relevant documents below (NOTE: this
is not a complete list - this is too hard to maintain...).
For details please refer to specific chapter in the document,
RFCs, manpages, or comments in the source code.
Conformance tests have been performed on the KAME STABLE kit
at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/
. We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) in the
past, with our past snapshots.
RFC1639: FTP Operation Over Big Address Records
(FOOBAR)
RFC2428 is preferred over RFC1639. FTP clients will
first try RFC2428, then RFC1639 if failed.
RFC1886: DNS Extensions to support IPv6
RFC1933: Transition Mechanisms for IPv6 Hosts and
Routers
IPv4 compatible address is not supported.
automatic tunneling (described in 4.3 of this RFC) is not
supported.
&man.gif.4; interface implements IPv[46]-over-IPv[46]
tunnel in a generic way, and it covers "configured tunnel"
described in the spec. See 23.5.1.5
in this document for details.
RFC1981: Path MTU Discovery for IPv6
RFC2080: RIPng for IPv6
usr.sbin/route6d support this.
RFC2292: Advanced Sockets API for IPv6
For supported library functions/kernel APIs, see
sys/netinet6/ADVAPI.
RFC2362: Protocol Independent Multicast-Sparse
Mode (PIM-SM)
RFC2362 defines packet formats for PIM-SM.
draft-ietf-pim-ipv6-01.txt is
written based on this.
RFC2373: IPv6 Addressing Architecture
supports node required addresses, and conforms to
the scope requirement.
RFC2374: An IPv6 Aggregatable Global Unicast Address
Format
supports 64-bit length of Interface ID.
RFC2375: IPv6 Multicast Address Assignments
Userland applications use the well-known addresses
assigned in the RFC.
RFC2428: FTP Extensions for IPv6 and NATs
- RFC2428 is preferred over RFC1639. ftp clients will
+ RFC2428 is preferred over RFC1639. FTP clients will
first try RFC2428, then RFC1639 if failed.
RFC2460: IPv6 specification
RFC2461: Neighbor discovery for IPv6
See 23.5.1.2
in this document for details.
RFC2462: IPv6 Stateless Address Autoconfiguration
See 23.5.1.4 in this
document for details.
RFC2463: ICMPv6 for IPv6 specification
See 23.5.1.9 in this
document for details.
RFC2464: Transmission of IPv6 Packets over Ethernet
Networks
RFC2465: MIB for IPv6: Textual Conventions and General
Group
Necessary statistics are gathered by the kernel. Actual
- IPv6 MIB support is provided as patchkit for ucd-snmp.
+ IPv6 MIB support is provided as a patchkit for ucd-snmp.
RFC2466: MIB for IPv6: ICMPv6 group
Necessary statistics are gathered by the kernel. Actual
IPv6 MIB support is provided as patchkit for ucd-snmp.
RFC2467: Transmission of IPv6 Packets over FDDI
Networks
RFC2497: Transmission of IPv6 packet over ARCnet
Networks
RFC2553: Basic Socket Interface Extensions for IPv6
IPv4 mapped address (3.7) and special behavior of IPv6
wildcard bind socket (3.8) are supported. See 23.5.1.12
in this document for details.
RFC2675: IPv6 Jumbograms
See 23.5.1.7 in
this document for details.
RFC2710: Multicast Listener Discovery for IPv6
RFC2711: IPv6 router alert option
draft-ietf-ipngwg-router-renum-08: Router
renumbering for IPv6
draft-ietf-ipngwg-icmp-namelookups-02:
IPv6 Name Lookups Through ICMP
draft-ietf-ipngwg-icmp-name-lookups-03:
IPv6 Name Lookups Through ICMP
draft-ietf-pim-ipv6-01.txt:
PIM for IPv6
&man.pim6dd.8; implements dense mode. &man.pim6sd.8;
implements sparse mode.
draft-itojun-ipv6-tcp-to-anycast-00:
Disconnecting TCP connection toward IPv6 anycast address
draft-yamamoto-wideipv6-comm-model-00
See 23.5.1.6 in this
document for details.
draft-ietf-ipngwg-scopedaddr-format-00.txt
: An Extension of Format for IPv6 Scoped
Addresses
Neighbor Discovery
Neighbor Discovery is fairly stable. Currently Address
Resolution, Duplicated Address Detection, and Neighbor Unreachability
Detection are supported. In the near future we will be adding Proxy
Neighbor Advertisement support in the kernel and Unsolicited Neighbor
Advertisement transmission command as admin tool.
If DAD fails, the address will be marked "duplicated" and
message will be generated to syslog (and usually to console). The
"duplicated" mark can be checked with &man.ifconfig.8;. It is
administrators' responsibility to check for and recover from DAD
failures. The behavior should be improved in the near future.
Some of the network driver loops multicast packets back to itself,
even if instructed not to do so (especially in promiscuous mode).
In such cases DAD may fail, because DAD engine sees inbound NS packet
(actually from the node itself) and considers it as a sign of duplicate.
You may want to look at #if condition marked "heuristics" in
sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
fragment in "heuristics" section is not spec conformant).
Neighbor Discovery specification (RFC2461) does not talk about
neighbor cache handling in the following cases:
when there was no neighbor cache entry, node
received unsolicited RS/NS/NA/redirect packet without
link-layer address
neighbor cache handling on medium without link-layer
address (we need a neighbor cache entry for IsRouter bit)
For first case, we implemented workaround based on discussions
on IETF ipngwg mailing list. For more details, see the comments in
the source code and email thread started from (IPng 7155), dated
Feb 6 1999.
IPv6 on-link determination rule (RFC2461) is quite different
from assumptions in BSD network code. At this moment, no on-link
determination rule is supported where default router list is empty
(RFC2461, section 5.2, last sentence in 2nd paragraph - note that
the spec misuse the word "host" and "node" in several places in
the section).
To avoid possible DoS attacks and infinite loops, only 10
options on ND packet is accepted now. Therefore, if you have 20
prefix options attached to RA, only the first 10 prefixes will be
recognized. If this troubles you, please ask it on FREEBSD-CURRENT
mailing list and/or modify nd6_maxndopt in
sys/netinet6/nd6.c. If there are high demands
we may provide sysctl knob for the variable.
Scope Index
IPv6 uses scoped addresses. Therefore, it is very important to
specify scope index (interface index for link-local address, or
site index for site-local address) with an IPv6 address. Without
scope index, scoped IPv6 address is ambiguous to the kernel, and
kernel will not be able to determine the outbound interface for a
packet.
Ordinary userland applications should use advanced API
(RFC2292) to specify scope index, or interface index. For similar
purpose, sin6_scope_id member in sockaddr_in6 structure is defined
in RFC2553. However, the semantics for sin6_scope_id is rather vague.
If you care about portability of your application, we suggest you to
use advanced API rather than sin6_scope_id.
In the kernel, an interface index for link-local scoped address is
embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For
example, you may see something like:
fe80:1::200:f8ff:fe01:6317
in the routing table and interface address structure (struct
in6_ifaddr). The address above is a link-local unicast address
which belongs to a network interface whose interface identifier is 1.
The embedded index enables us to identify IPv6 link local
addresses over multiple interfaces effectively and with only a
little code change.
Routing daemons and configuration programs, like &man.route6d.8;
and &man.ifconfig.8;, will need to manipulate the "embedded" scope
index. These programs use routing sockets and ioctls (like
SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with
2nd 16bit-word filled in. The APIs are for manipulating kernel
internal structure. Programs that use these APIs have to be prepared
about differences in kernels anyway.
When you specify scoped address to the command line, NEVER write
the embedded form (such as ff02:1::1 or fe80:2::fedc). This is not
supposed to work. Always use standard form, like ff02::1 or
fe80::fedc, with command line option for specifying interface (like
ping6 -I ne0 ff02::1). In general, if a command
does not have command line option to specify outgoing interface, that
command is not ready to accept scoped address. This may seem to be
opposite from IPv6's premise to support "dentist office" situation.
We believe that specifications need some improvements for this.
Some of the userland tools support extended numeric IPv6 syntax,
as documented in
draft-ietf-ipngwg-scopedaddr-format-00.txt. You
can specify outgoing link, by using name of the outgoing interface
like "fe80::1%ne0". This way you will be able to specify link-local
scoped address without much trouble.
To use this extension in your program, you'll need to use
&man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID.
The implementation currently assumes 1-to-1 relationship between a
link and an interface, which is stronger than what specs say.
Plug and Play
- Most of the IPv6 stateless address autoconfiguration is implemeted
+ Most of the IPv6 stateless address autoconfiguration is implemented
in the kernel. Neighbor Discovery functions are implemented in the
kernel as a whole. Router Advertisement (RA) input for hosts is
implemented in the kernel. Router Solicitation (RS) output for
endhosts, RS input for routers, and RA output for routers are
implemented in the userland.
Assignment of link-local, and special addresses
- IPv6 link-local address is generated from IEEE802 adddress
+ IPv6 link-local address is generated from IEEE802 address
(ethernet MAC address). Each of interface is assigned an IPv6
link-local address automatically, when the interface becomes up
(IFF_UP). Also, direct route for the link-local address is added
to routing table.
Here is an output of netstat command:
Internet6:
Destination Gateway Flags Netif Expire
fe80:1::%ed0/64 link#1 UC ed0
fe80:2::%ep0/64 link#2 UC ep0
Interfaces that has no IEEE802 address (pseudo interfaces
like tunnel interfaces, or ppp interfaces) will borrow IEEE802
address from other interfaces, such as ethernet interfaces,
whenever possible. If there is no IEEE802 hardware attached,
last-resort pseudorandom value, which is from MD5(hostname), will
be used as source of link-local address. If it is not suitable
for your usage, you will need to configure the link-local address
manually.
If an interface is not capable of handling IPv6 (such as
lack of multicast support), link-local address will not be
assigned to that interface. See section 2 for details.
Each interface joins the solicited multicast address and the
link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
and ff02::1, respectively, on the link the interface is attached).
In addition to a link-local address, the loopback address (::1)
will be assigned to the loopback interface. Also, ::1/128 and
ff01::/32 are automatically added to routing table, and loopback
interface joins node-local multicast group ff01::1.
Stateless address autoconfiguration on hosts
In IPv6 specification, nodes are separated into two categories:
routers and hosts. Routers
forward packets addressed to others, hosts does not forward the
packets. net.inet6.ip6.forwarding defines whether this node is
router or host (router if it is 1, host if it is 0).
When a host hears Router Advertisement from the router, a host
may autoconfigure itself by stateless address autoconfiguration.
This behavior can be controlled by net.inet6.ip6.accept_rtadv (host
autoconfigures itself if it is set to 1). By autoconfiguration,
network address prefix for the receiving interface (usually global
address prefix) is added. Default route is also configured.
Routers periodically generate Router Advertisement packets. To
request an adjacent router to generate RA packet, a host can
transmit Router Solicitation. To generate a RS packet at any time,
use the rtsol command. &man.rtsold.8; daemon is
also available. &man.rtsold.8; generates Router Solicitation whenever
necessary, and it works great for nomadic usage (notebooks/laptops).
If one wishes to ignore Router Advertisements, use sysctl to set
net.inet6.ip6.accept_rtadv to 0.
To generate Router Advertisement from a router, use the
&man.rtadvd.8 daemon.
Note that, IPv6 specification assumes the following items, and
nonconforming cases are left unspecified:
Only hosts will listen to router advertisements
Hosts have single network interface (except loopback)
Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv
on routers, or multi-interface host. A misconfigured node can
behave strange (nonconforming configuration allowed for those who
would like to do some experiments).
To summarize the sysctl knob:
accept_rtadv forwarding role of the node
--- --- ---
0 0 host (to be manually configured)
0 1 router
1 0 autoconfigured host
(spec assumes that host has single
interface only, autoconfigured host
with multiple interface is
out-of-scope)
1 1 invalid, or experimental
(out-of-scope of spec)
RFC2462 has validation rule against incoming RA prefix
information option, in 5.5.3 (e). This is to protect hosts from
malicious (or misconfigured) routers that advertise very short
prefix lifetime. There was an update from Jim Bound to ipngwg
mailing list (look for "(ipng 6712)" in the archive) and it is
implemented Jim's update.
See 23.5.1.2 in
the document for relationship between DAD and
autoconfiguration.
Generic tunnel interface
GIF (Generic InterFace) is a pseudo interface for configured
- tunnel. Details are described in &man.gif.4; manpage. Currently
+ tunnel. Details are described in &man.gif.4;. Currently
v6 in v6
v6 in v4
v4 in v6
v4 in v4
are available. Use &man.gifconfig.8; to assign physical (outer)
source and destination address to gif interfaces. Configuration that
uses same address family for inner and outer IP header (v4 in v4, or
v6 in v6) is dangerous. It is very easy to configure interfaces and
routing tables to perform infinite level of tunneling.
Please be warned.
gif can be configured to be ECN-friendly. See 23.5.4.5 for ECN-friendliness of
- tunnels, and &man.gif.4; manpage for how to configure.
+ tunnels, and &man.gif.4; for how to configure.
If you would like to configure an IPv4-in-IPv6 tunnel with gif
- interface, read &man.gif.4; manpage carefully. You will need to
+ interface, read &man.gif.4; carefully. You will need to
remove IPv6 link-local address automatically assigned to the gif
interface.
Source Address Selection
Current source selection rule is scope oriented (there are some
exceptions - see below). For a given destination, a source IPv6
address is selected by the following rule:
If the source address is explicitly specified by
the user (e.g. via the advanced API), the specified address
is used.
If there is an address assigned to the outgoing
interface (which is usually determined by looking up the
routing table) that has the same scope as the destination
address, the address is used.
This is the most typical case.
If there is no address that satisfies the above
condition, choose a global address assigned to one of
the interfaces on the sending node.
If there is no address that satisfies the above condition,
and destination address is site local scope, choose a site local
address assigned to one of the interfaces on the sending node.
If there is no address that satisfies the above condition,
choose the address associated with the routing table entry for the
destination. This is the last resort, which may cause scope
violation.
For instance, ::1 is selected for ff01::1,
fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note
that embedded interface index - described in 23.5.1.3 - helps us
choose the right source address. Those embedded indices will not
be on the wire). If the outgoing interface has multiple address for
the scope, a source is selected longest match basis (rule 3). Suppose
3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317
is chosen as the source for the destination 3ffe:501:800::1.
Note that the above rule is not documented in the IPv6 spec.
It is considered "up to implementation" item. There are some cases
where we do not use the above rule. One example is connected TCP
session, and we use the address kept in tcb as the source. Another
example is source address for Neighbor Advertisement. Under the spec
(RFC2461 7.2.2) NA's source should be the target address of the
corresponding NS's target. In this case we follow the spec rather
than the above longest-match rule.
For new connections (when rule 1 does not apply), deprecated
addresses (addresses with preferred lifetime = 0) will not be chosen
- as source address if other choises are available. If no other choices
+ as source address if other choices are available. If no other choices
are available, deprecated address will be used as a last resort. If
there are multiple choice of deprecated addresses, the above scope
- rule will be used to choose from those deprecated addreses. If you
+ rule will be used to choose from those deprecated addresses. If you
would like to prohibit the use of deprecated address for some reason,
configure net.inet6.ip6.use_deprecated to 0. The issue related to
deprecated address is described in RFC2462 5.5.4 (NOTE: there is
some debate underway in IETF ipngwg on how to use "deprecated"
address).
Jumbo Payload
The Jumbo Payload hop-by-hop option is implemented and can
be used to send IPv6 packets with payloads longer than 65,535 octets.
But currently no physical interface whose MTU is more than 65,535 is
supported, so such payloads can be seen only on the loopback
interface (i.e. lo0).
If you want to try jumbo payloads, you first have to reconfigure
the kernel so that the MTU of the loopback interface is more than
65,535 bytes; add the following to the kernel configuration file:
options "LARGE_LOMTU" #To test jumbo payload
and recompile the new kernel.
Then you can test jumbo payloads by the &man.ping6.8; command
with -b and -s options. The -b option must be specified to enlarge
the size of the socket buffer and the -s option specifies the length
of the packet, which should be more than 65,535. For example,
type as follows:
&prompt.user; ping6 -b 70000 -s 68000 ::1
The IPv6 specification requires that the Jumbo Payload option
must not be used in a packet that carries a fragment header. If
this condition is broken, an ICMPv6 Parameter Problem message must
be sent to the sender. specification is followed, but you cannot
usually see an ICMPv6 error caused by this requirement.
When an IPv6 packet is received, the frame length is checked and
compared to the length specified in the payload length field of the
IPv6 header or in the value of the Jumbo Payload option, if any. If
the former is shorter than the latter, the packet is discarded and
statistics are incremented. You can see the statistics as output of
&man.netstat.8; command with `-s -p ip6' option:
&prompt.user; netstat -s -p ip6
ip6:
(snip)
1 with data size < data length
So, kernel does not send an ICMPv6 error unless the erroneous
packet is an actual Jumbo Payload, that is, its packet size is more
than 65,535 bytes. As described above, currently no physical interface
with such a huge MTU is supported, so it rarely returns an
ICMPv6 error.
TCP/UDP over jumbogram is not supported at this moment. This
is because we have no medium (other than loopback) to test this.
Contact us if you need this.
IPsec does not work on jumbograms. This is due to some
specification twists in supporting AH with jumbograms (AH header
size influences payload length, and this makes it real hard to
authenticate inbound packet with jumbo payload option as well as AH).
There are fundamental issues in *BSD support for jumbograms.
We would like to address those, but we need more time to finalize
these. To name a few:
mbuf pkthdr.len field is typed as "int" in 4.4BSD, so
it will not hold jumbogram with len > 2G on 32bit architecture
CPUs. If we would like to support jumbogram properly, the field
must be expanded to hold 4G + IPv6 header + link-layer header.
Therefore, it must be expanded to at least int64_t
(u_int32_t is NOT enough).
We mistakingly use "int" to hold packet length in many
places. We need to convert them into larger integral type.
It needs a great care, as we may experience overflow during
packet length computation.
We mistakingly check for ip6_plen field of IPv6 header
for packet payload length in various places. We should be
checking mbuf pkthdr.len instead. ip6_input() will perform
sanity check on jumbo payload option on input, and we can
safely use mbuf pkthdr.len afterwards.
TCP code needs a careful update in bunch of places, of
course.
Loop prevention in header processing
IPv6 specification allows arbitrary number of extension headers
to be placed onto packets. If we implement IPv6 packet processing
code in the way BSD IPv4 code is implemented, kernel stack may
overflow due to long function call chain. sys/netinet6 code
is carefully designed to avoid kernel stack overflow. Because of
this, sys/netinet6 code defines its own protocol switch
structure, as "struct ip6protosw" (see
netinet6/ip6protosw.h). There is no such
update to IPv4 part (sys/netinet) for compatibility, but small
change is added to its pr_input() prototype. So "struct ipprotosw"
is also defined. Because of this, if you receive IPsec-over-IPv4
packet with massive number of IPsec headers, kernel stack may blow
up. IPsec-over-IPv6 is okay. (Off-course, for those all IPsec
headers to be processed, each such IPsec header must pass each
IPsec check. So an anonymous attacker won't be able to do such an
attack.)
ICMPv6
After RFC2463 was published, IETF ipngwg has decided to
disallow ICMPv6 error packet against ICMPv6 redirect, to prevent
ICMPv6 storm on a network medium. This is already implemented
into the kernel.
Applications
For userland programming, we support IPv6 socket API as
specified in RFC2553, RFC2292 and upcoming internet drafts.
TCP/UDP over IPv6 is available and quite stable. You can
enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;, &man.rsh.1;,
&man.ssh.1, etc. These applications are protocol independent.
That is, they automatically chooses IPv4 or IPv6 according to DNS.
Kernel Internals
While ip_forward() calls ip_output(), ip6_forward() directly
calls if_output() since routers must not divide IPv6 packets into
fragments.
ICMPv6 should contain the original packet as long as possible
up to 1280. UDP6/IP6 port unreach, for instance, should contain
all extension headers and the *unchanged* UDP6 and IP6 headers.
So, all IP6 functions except TCP never convert network byte
order into host byte order, to save the original packet.
tcp_input(), udp6_input() and icmp6_input() can't assume that
IP6 header is preceding the transport headers due to extension
headers. So, in6_cksum() was implemented to handle packets whose IP6
header and transport header is not continuous. TCP/IP6 nor UDP6/IP6
header structure don't exist for checksum calculation.
To process IP6 header, extension headers and transport headers
easily, network drivers are now required to store packets in one
internal mbuf or one or more external mbufs. A typical old driver
prepares two internal mbufs for 96 - 204 bytes data, however, now
such packet data is stored in one external mbuf.
netstat -s -p ip6 tells you whether or not
your driver conforms such requirement. In the following example,
"cce0" violates the requirement. (For more information, refer to
Section 2.)
Mbuf statistics:
317 one mbuf
two or more mbuf::
lo0 = 8
cce0 = 10
3282 one ext mbuf
0 two or more ext mbuf
Each input function calls IP6_EXTHDR_CHECK in the beginning to
check if the region between IP6 and its header is continuous.
IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag,
that is, the packet comes from the loopback interface. m_pullup()
is never called for packets coming from physical network interfaces.
Both IP and IP6 reassemble functions never call m_pullup().
IPv4 mapped address and IPv6 wildcard socket
RFC2553 describes IPv4 mapped address (3.7) and special behavior
of IPv6 wildcard bind socket (3.8). The spec allows you to:
Accept IPv4 connections by AF_INET6 wildcard bind
socket.
Transmit IPv4 packet over AF_INET6 socket by using
special form of the address like ::ffff:10.1.1.1.
but the spec itself is very complicated and does not specify
how the socket layer should behave. Here we call the former one
"listening side" and the latter one "initiating side", for
reference purposes.
- You can perform wildcard bind on both of the adderss families,
+ You can perform wildcard bind on both of the address families,
on the same port.
The following table show the behavior of FreeBSD 4.x.
listening side initiating side
- (AF_INET6 wildcard (connetion to ::ffff:10.1.1.1)
+ (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
socket gets IPv4 conn.)
--- ---
FreeBSD 4.x configurable supported
default: enabled
The following sections will give you more details, and how you can
configure the behavior.
Comments on listening side:
It looks that RFC2553 talks too little on wildcard bind issue,
especially on the port space issue, failure mode and relationship
between AF_INET/INET6 wildcard bind. There can be several separate
interpretation for this RFC which conform to it but behaves differently.
So, to implement portable application you should assume nothing
about the behavior in the kernel. Using &man.getaddrinfo.3; is the
safest way. Port number space and wildcard bind issues were discussed
in detail on ipv6imp mailing list, in mid March 1999 and it looks
that there's no concrete consensus (means, up to implementers).
You may want to check the mailing list archives.
If a server application would like to accept IPv4 and IPv6
connections, there will be two alternatives.
One is using AF_INET and AF_INET6 socket (you'll need two
sockets). Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags,
and &man.socket.2; and &man.bind.2; to all the addresses returned.
By opening multiple sockets, you can accept connections onto the
socket with proper address family. IPv4 connections will be
accepted by AF_INET socket, and IPv6 connections will be accepted
by AF_INET6 socket.
Another way is using one AF_INET6 wildcard bind socket. Use
&man.getaddrinfo.3; with AI_PASSIVE into ai_flags and with
AF_INET6 into ai_family, and set the 1st argument hostname to
NULL. And &man.socket.2; and &man.bind.2; to the address returned.
(should be IPv6 unspecified addr). You can accept either of IPv4
and IPv6 packet via this one socket.
To support only IPv6 traffic on AF_INET6 wildcard binded socket
portably, always check the peer address when a connection is made
toward AF_INET6 listening socket. If the address is IPv4 mapped
address, you may want to reject the connection. You can check the
condition by using IN6_IS_ADDR_V4MAPPED() macro.
To resolve this issue more easily, there is system dependent
&man.setsockopt.2; option, IPV6_BINDV6ONLY, used like below.
int on;
setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
(char *)&on, sizeof (on)) < 0));
When this call succeed, then this socket only receive IPv6
packets.
Comments on initiating side:
Advise to application implementers: to implement a portable
IPv6 application (which works on multiple IPv6 kernels), we believe
that the following is the key to the success:
NEVER hardcode AF_INET nor AF_INET6.
Use &man.getaddrinfo.3; and &man.getnameinfo.3;
throughout the system. Never use gethostby*(), getaddrby*(),
inet_*() or getipnodeby*(). (To update existing applications
to be IPv6 aware easily, sometime getipnodeby*() will be
useful. But if possible, try to rewrite the code to use
&man.getaddrinfo.3; and &man.getnameinfo.3;.)
If you would like to connect to destination, use
&man.getaddrinfo.3; and try all the destination returned,
like &man.telnet.1; does.
Some of the IPv6 stack is shipped with buggy
&man.getaddrinfo.3;. Ship a minimal working version with
your application and use that as last resort.
If you would like to use AF_INET6 socket for both IPv4 and
IPv6 outgoing connection, you will need to use &man.getipnodebyname.3;.
- When you would like to update your existing appication to be IPv6
- aware with minimal effort, this approach might be choosed. But please
+ When you would like to update your existing application to be IPv6
+ aware with minimal effort, this approach might be chosen. But please
note that it is a temporal solution, because &man.getipnodebyname.3;
itself is not recommended as it does not handle scoped IPv6 addresses
at all. For IPv6 name resolution, &man.getaddrinfo.3; is the
preferred API. So you should rewrite your application to use
&man.getaddrinfo.3;, when you get the time to do it.
When writing applications that make outgoing connections,
story goes much simpler if you treat AF_INET and AF_INET6 as totally
- seaprate address family. {set,get}sockopt issue goes simpler,
+ separate address family. {set,get}sockopt issue goes simpler,
DNS issue will be made simpler. We do not recommend you to rely
upon IPv4 mapped address.
unified tcp and inpcb code
FreeBSD 4.x uses shared tcp code between IPv4 and IPv6
- (from sys/netinet/tcp*) and separete udp4/6 code. It uses
+ (from sys/netinet/tcp*) and separate udp4/6 code. It uses
unified inpcb structure.
The platform can be configured to support IPv4 mapped address.
Kernel configuration is summarized as follows:
By default, AF_INET6 socket will grab IPv4
connections in certain condition, and can initiate
connection to IPv4 destination embedded in IPv4 mapped
IPv6 address.
You can disable it on entire system with sysctl like
below.
sysctl -w net.inet6.ip6.mapped_addr=0
listening side
Each socket can be configured to support special AF_INET6
wildcard bind (enabled by default). You can disable it on
each socket basis with &man.setsockopt.2; like below.
int on;
setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
(char *)&on, sizeof (on)) < 0));
Wildcard AF_INET6 socket grabs IPv4 connection if and only
if the following conditions are satisfied:
there's no AF_INET socket that matches the IPv4
connection
the AF_INET6 socket is configured to accept IPv4
traffic, i.e. getsockopt(IPV6_BINDV6ONLY) returns 0.
There's no problem with open/close ordering.
initiating side
- FreeBSD 4.x supports outgoing connetion to IPv4 mapped
+ FreeBSD 4.x supports outgoing connection to IPv4 mapped
address (::ffff:10.1.1.1), if the node is configured to support
IPv4 mapped address.
sockaddr_storage
- When RFC2553 was about to be finalized, there was discusson on
+ When RFC2553 was about to be finalized, there was discussion on
how struct sockaddr_storage members are named. One proposal is to
prepend "__" to the members (like "__ss_len") as they should not be
touched. The other proposal was that don't prepend it (like "ss_len")
as we need to touch those members directly. There was no clear
consensus on it.
As a result, RFC2553 defines struct sockaddr_storage as
follows:
struct sockaddr_storage {
u_char __ss_len; /* address length */
u_char __ss_family; /* address family */
/* and bunch of padding */
};
On the contrary, XNET draft defines as follows:
struct sockaddr_storage {
u_char ss_len; /* address length */
u_char ss_family; /* address family */
/* and bunch of padding */
};
In December 1999, it was agreed that RFC2553bis should pick
the latter (XNET) definition.
Current implementation conforms to XNET definition, based on
- RFC2553bis discusson.
+ RFC2553bis discussion.
If you look at multiple IPv6 implementations, you will be able
to see both definitions. As an userland programmer, the most
portable way of dealing with it is to:
ensure ss_family and/or ss_len are available on the
platform, by using GNU autoconf,
- have -Dss_family=__ss_family to unify all occurences
+ have -Dss_family=__ss_family to unify all occurrences
(including header file) into __ss_family, or
never touch __ss_family. cast to sockaddr * and use sa_family
like:
struct sockaddr_storage ss;
family = ((struct sockaddr *)&ss)->sa_family
Network Drivers
Now following two items are required to be supported by standard
drivers:
mbuf clustering requirement. In this stable release, we
changed MINCLSIZE into MHLEN+1 for all the operating systems
in order to make all the drivers behave as we expect.
multicast. If &man.ifmcstat.8; yields no multicast group for
a interface, that interface has to be patched.
If any of the driver don't support the requirements, then
the driver can't be used for IPv6 and/or IPsec communication. If
you find any problem with your card using IPv6/IPsec, then, please
report it to freebsd-bugs@FreeBSD.org.
- (NOTE: In the past we required all pcmcia drivers to have a
+ (NOTE: In the past we required all PCMCIA drivers to have a
call to in6_ifattach(). We have no such requirement any more)
Translator
We categorize IPv4/IPv6 translator into 4 types:
Translator A --- It is used in the early
stage of transition to make it possible to establish a
connection from an IPv6 host in an IPv6 island to an IPv4 host
in the IPv4 ocean.
Translator B --- It is used in the early
stage of transition to make it possible to establish a connection
from an IPv4 host in the IPv4 ocean to an IPv6 host in an
IPv6 island.
Translator C --- It is used in the late
stage of transition to make it possible to establish a
connection from an IPv4 host in an IPv4 island to an IPv6 host
in the IPv6 ocean.
Translator D --- It is used in the late
stage of transition to make it possible to establish a
connection from an IPv6 host in the IPv6 ocean to an IPv4 host
in an IPv4 island.
TCP relay translator for category A is supported. This is called
"FAITH". We also provide IP header translator for category A.
(The latter is not yet put into FreeBSD 4.x yet.)
FAITH TCP relay translator
FAITH system uses TCP relay daemon called &man.faithd.8; helped
by the kernel. FAITH will reserve an IPv6 address prefix, and relay
TCP connection toward that prefix to IPv4 destination.
For example, if the reserved IPv6 prefix is
3ffe:0501:0200:ffff::, and the IPv6 destination for TCP connection
is 3ffe:0501:0200:ffff::163.221.202.12, the connection will be
relayed toward IPv4 destination 163.221.202.12.
destination IPv4 node (163.221.202.12)
^
| IPv4 tcp toward 163.221.202.12
FAITH-relay dual stack node
^
| IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
source IPv6 node
&man.faithd.8; must be invoked on FAITH-relay dual stack
node.
For more details, consult
src/usr.sbin/faithd/README
IPsec
IPsec is mainly organized by three components.
Policy Management
Key Management
AH and ESP handling
Policy Management
The kernel implements experimental policy management code.
There are two way to manage security policy. One is to configure
per-socket policy using &man.setsockopt.2;. In this cases, policy
configuration is described in &man.ipsec.set.policy.3;. The other
is to configure kernel packet filter-based policy using PF_KEY
interface, via &man.setkey.8;.
The policy entry is not re-ordered with its
indexes, so the order of entry when you add is very significant.
Key Management
The key management code implemented in this kit (sys/netkey)
is a home-brew PFKEY v2 implementation. This conforms to RFC2367.
The home-brew IKE daemon, "racoon" is included in the
kit (kame/kame/racoon). Basically you'll need to run racoon as
daemon, then setup a policy to require keys (like
ping -P 'out ipsec esp/transport//use').
The kernel will contact racoon daemon as necessary to exchange
keys.
AH and ESP handling
IPsec module is implemented as "hooks" to the standard IPv4/IPv6
processing. When sending a packet, ip{,6}_output() checks if ESP/AH
processing is required by checking if a matching SPD (Security
Policy Database) is found. If ESP/AH is needed,
{esp,ah}{4,6}_output() will be called and mbuf will be updated
accordingly. When a packet is received, {esp,ah}4_input() will be
called based on protocol number, i.e. (*inetsw[proto])().
{esp,ah}4_input() will decrypt/check authenticity of the packet,
and strips off daisy-chained header and padding for ESP/AH. It is
safe to strip off the ESP/AH header on packet reception, since we
will never use the received packet in "as is" form.
By using ESP/AH, TCP4/6 effective data segment size will be
affected by extra daisy-chained headers inserted by ESP/AH. Our
code takes care of the case.
Basic crypto functions can be found in directory "sys/crypto".
ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions.
If you wish to add some algorithm, add wrapper function in
{esp,ah}_core.c, and add your crypto algorithm code into
sys/crypto.
Tunnel mode is partially supported in this release, with the
following restrictions:
IPsec tunnel is not combined with GIF generic tunneling
interface. It needs a great care because we may create an
infinite loop between ip_output() and tunnelifp->if_output().
Opinion varies if it is better to unify them, or not.
MTU and Don't Fragment bit (IPv4) considerations need more
checking, but basically works fine.
Authentication model for AH tunnel must be revisited.
We'll need to improve the policy management engine,
eventually.
Conformance to RFCs and IDs
The IPsec code in the kernel conforms (or, tries to conform)
to the following standards:
"old IPsec" specification documented in
rfc182[5-9].txt
"new IPsec" specification documented in
rfc240[1-6].txt,
rfc241[01].txt, rfc2451.txt
and draft-mcdonald-simple-ipsec-api-01.txt
(draft expired, but you can take from
ftp://ftp.kame.net/pub/internet-drafts/).
(NOTE: IKE specifications, rfc241[7-9].txt are
implemented in userland, as "racoon" IKE daemon)
Currently supported algorithms are:
old IPsec AH
null crypto checksum (no document, just for
debugging)
keyed MD5 with 128bit crypto checksum
(rfc1828.txt)
keyed SHA1 with 128bit crypto checksum
(no document)
HMAC MD5 with 128bit crypto checksum
(rfc2085.txt)
HMAC SHA1 with 128bit crypto checksum
(no document)
old IPsec ESP
null encryption (no document, similar to
rfc2410.txt)
DES-CBC mode (rfc1829.txt)
new IPsec AH
null crypto checksum (no document,
just for debugging)
keyed MD5 with 96bit crypto checksum
(no document)
keyed SHA1 with 96bit crypto checksum
(no document)
HMAC MD5 with 96bit crypto checksum
(rfc2403.txt)
HMAC SHA1 with 96bit crypto checksum
(rfc2404.txt)
new IPsec ESP
null encryption
(rfc2410.txt)
DES-CBC with derived IV
(draft-ietf-ipsec-ciph-des-derived-01.txt,
draft expired)
DES-CBC with explicit IV
(rfc2405.txt)
3DES-CBC with explicit IV
(rfc2451.txt)
BLOWFISH CBC
(rfc2451.txt)
CAST128 CBC
(rfc2451.txt)
RC5 CBC
(rfc2451.txt)
each of the above can be combined with:
ESP authentication with HMAC-MD5(96bit)
ESP authentication with HMAC-SHA1(96bit)
The following algorithms are NOT supported:
old IPsec AH
HMAC MD5 with 128bit crypto checksum + 64bit
replay prevention (rfc2085.txt)
keyed SHA1 with 160bit crypto checksum + 32bit padding
(rfc1852.txt)
IPsec (in kernel) and IKE (in userland as "racoon") has been
tested at several interoperability test events, and it is known to
interoperate with many other implementations well. Also, current
IPsec implementation as quite wide coverage for IPsec crypto
algorithms documented in RFC (we cover algorithms without intellectual
property issues only).
ECN consideration on IPsec tunnels
ECN-friendly IPsec tunnel is supported as described in
draft-ipsec-ecn-00.txt.
Normal IPsec tunnel is described in RFC2401. On encapsulation,
IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
IP header to outer IP header. On decapsulation outer IP header
will be simply dropped. The decapsulation rule is not compatible
with ECN, since ECN bit on the outer IP TOS/traffic class field will be
lost.
To make IPsec tunnel ECN-friendly, we should modify encapsulation
and decapsulation procedure. This is described in
http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt,
chapter 3.
IPsec tunnel implementation can give you three behaviors, by
setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some
value:
RFC2401: no consideration for ECN (sysctl value -1)
ECN forbidden (sysctl value 0)
ECN allowed (sysctl value 1)
Note that the behavior is configurable in per-node manner,
not per-SA manner (draft-ipsec-ecn-00 wants per-SA configuration,
but it looks too much for me).
The behavior is summarized as follows (see source code for
more detail):
encapsulate decapsulate
--- ---
RFC2401 copy all TOS bits drop TOS bits on outer
from inner to outer. (use inner TOS bits as is)
ECN forbidden copy TOS bits except for ECN drop TOS bits on outer
(masked with 0xfc) from inner (use inner TOS bits as is)
to outer. set ECN bits to 0.
ECN allowed copy TOS bits except for ECN use inner TOS bits with some
CE (masked with 0xfe) from change. if outer ECN CE bit
inner to outer. is 1, enable ECN CE bit on
set ECN CE bit to 0. the inner.
General strategy for configuration is as follows:
if both IPsec tunnel endpoint are capable of ECN-friendly
behavior, you'd better configure both end to "ECN allowed"
(sysctl value 1).
if the other end is very strict about TOS bit, use "RFC2401"
(sysctl value -1).
in other cases, use "ECN forbidden" (sysctl value 0).
The default behavior is "ECN forbidden" (sysctl value 0).
For more information, please refer to:
http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt,
RFC2481 (Explicit Congestion Notification),
src/sys/netinet6/{ah,esp}_input.c
(Thanks goes to Kenjiro Cho kjc@csl.sony.co.jp
for detailed analysis)
Interoperability
Here are (some of) platforms that KAME code have tested
IPsec/IKE interoperability in the past. Note that both ends may
have modified their implementation, so use the following list just
for reference purposes.
Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel,
Microsoft WinNT, NIST (linux IPsec + plutoplus), Netscreen, OpenBSD,
RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
VPNet, Yamaha RT100i
diff --git a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
index fef9dfd349..4490777632 100644
--- a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1133 +1,1133 @@
Configuring the FreeBSD Kernel
Synopsis
Updated and restructured by &a.jim;, March 2000.
Originally contributed by &a.jehamby;, 6 October
1995.
The following chapter of the handbook covers everything you will
need to know in order to build a custom kernel. If you are
wondering what the benefits of a custom kernel are, or would like to
know how to configure, compile, and install a custom kernel, this
chapter is for you.
Why Build a Custom Kernel?
Building a custom kernel is one of the most important rites of
passage nearly every UNIX user must endure. This process, while
time consuming, will provide many benefits to your FreeBSD system.
Unlike the GENERIC kernel, which must support a
wide range of hardware, a custom kernel only contains support for
your PC's hardware. This has a number of
benefits, such as:
Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot will decrease dramatically.
Less memory use. A custom kernel often uses less memory
than the GENERIC kernel, which is important
because the kernel is one process that must always be present in
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.
Additional hardware support. A custom kernel allows you to
add in support for devices such as sound cards, which are not
present in the GENERIC kernel.
Building and Installing a Custom Kernel
First, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
/usr/src/sys directory, which is also
accessible through /sys. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
arch/conf, where you
will edit your custom kernel configuration, and
compile, which is the staging area where your
kernel will be built. arch represents
either i386, alpha, or
pc98 (an alternative development branch of PC
hardware, popular in Japan). Everything inside a particular
architecture's directory deals with that architecture only; the rest
of the code is common to all platforms to which FreeBSD could
potentially be ported. Notice the logical organization of the
directory structure, with each supported device, filesystem, and
option in its own subdirectory.
If there is not a
/usr/src/sys directory on your system, then
the kernel source has not been been installed. The easiest way to
do this is by running /stand/sysinstall as
root, choosing Configure,
then Distributions, then
src, then sys.
Next, move to the
arch/conf directory
and copy the GENERIC configuration file to the
name you want to give your kernel. For example:
&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC MYKERNEL
Traditionally, this name is in all capital letters and, if you
are maintaining multiple FreeBSD machines with different hardware,
it is a good idea to name it after your machine's hostname. We will
call it MYKERNEL for the purpose of this
example.
You must execute these and all of the following commands under
the root account or you will get permission
denied errors.
Now, edit MYKERNEL with your favorite text
editor. If you are just starting out, the only editor available
will probably be vi, which is too complex to
explain here, but is covered well in many books in the bibliography. However, FreeBSD does
offer an easier editor called ee
which, if you are a
beginner, should be your editor of choice. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
GENERIC.
If you have build a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the GENERIC configuration file
might seem overwhelming to you, so follow the descriptions in the
Configuration File
section slowly and carefully.
If you are trying to upgrade your kernel from an older version
of FreeBSD, you will probably have to get a new version of
&man.config.8; from the same place you got the new kernel sources.
It is located in /usr/src/usr.sbin, so you
will need to download those sources as well. Re-build and install
it before running the next commands.
When you are finished, type the following to compile and install
your kernel:
&prompt.root; /usr/sbin/config MYKERNEL
&prompt.root; cd ../../compile/MYKERNEL
&prompt.root; make depend
&prompt.root; make
&prompt.root; make install
The new kernel will be copied to the root directory as
/kernel and the old kernel will be moved to
/kernel.old. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong, there are
some troubleshooting
instructions at the end of this document. Be sure to read the
section which explains how to recover in case your new kernel does not boot.
If you have added any new devices (such as sound cards) you
may have to add some device
nodes to your /dev directory before
you can use them.
The Configuration File
The general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a # is considered a comment and
ignored. The following sections describe each keyword, generally in
the order they are listed in GENERIC, although
some related keywords have been grouped together in a single section
(such as Networking) even though they are actually scattered
throughout the GENERIC file. An exhaustive list of options and more
detailed explanations of the device lines is present in the
LINT configuration file, located in the same
directory as GENERIC. If you are in doubt as
to the purpose or necessity of a line, check first in
LINT.
Quoting numbers
In all versions of FreeBSD up to and including 3.X,
&man.config.8; required that any strings in the configuration file
that contained numbers used as text had to be enclosed in double
quotes.
This requirement was removed in the 4.X branch, which this
book covers, so if you are on a pre-4.X system, see the
/usr/src/sys/i386/conf/LINT and
/usr/src/sys/i386/conf/GENERIC
files on your system for examples.
The following is an example GENERIC kernel
configuration file with various additional comments where needed for
clarity. This example should match your copy in
/usr/src/sys/i386/conf/GENERIC fairly
closely. For details of all the possible kernel options, see
/usr/src/sys/i386/conf/LINT.
#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.freebsd.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $
The following are the mandatory keywords required in
every kernel you build:
machine i386
This is the machine architecture. It must be either
i386, alpha, or
pc98.
cpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPU
The above specifies the type of CPU you have in your system.
You may have multiple instances of the CPU line (i.e., you are not
sure whether you should use I586_CPU or
I686_CPU), however, for a custom kernel, it is
best to specify only the CPU you have. If you are unsure which type
your CPU use, you can use the dmesg command to
view your boot up messages.
- The Alpha architechture has different values for
+ The Alpha architecture has different values for
cpu_type. They include:
cpu EV4
cpu EV5
If you are using an Alpha machine, you should be using one of
the above CPU types.
ident GENERIC
This is the identification of the kernel. You should change
this to whatever you named your kernel, in our previous example,
MYKERNEL. The value you put in the
ident string will print when you boot up the
kernel, so it is useful to give a kernel a different name if you
want to keep it separate from your usual kernel (i.e., you want to
build an experimental kernel).
maxusers 32
The maxusers option sets the size of a number
of important system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to have on your
machine. However, under normal circumstances, you will want to set
maxusers to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by maxusers is the
maximum number of processes, which is set to 20 + 16 *
maxusers, so if you set maxusers to 1,
then you can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15 or so you
will probably create when you start the X Window System. Even a
simple task like reading a man page will start up nine processes to
filter, decompress, and view it. Setting
maxusers to 64 will allow you to have up to 1044
simultaneous processes, which should be enough for nearly all uses.
If, however, you see the dreaded proc table
full error when trying to start another program, or are
running a server with a large number of simultaneous users (like
ftp.FreeBSD.org), you can always
increase the number and rebuild.
maxusers does not
limit the number of users which can log into your machine. It
simply sets various table sizes to reasonable values considering
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which does limit the number of simultaneous
remote logins is pseudo-device pty
16.
Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.
#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
options MATH_EMULATE #Support for x87 emulation
This line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line
out.
The normal math co-processor emulation routines that come with
FreeBSD are not very accurate. If you do not
have a math co-processor, and you need the best accuracy, it is
recommended that you change this option to
GPL_MATH_EMULATION to use the GNU math support,
which is not included by default for licensing reasons.
options INET #InterNETworking
Networking support. Leave this in, even if you do not plan to
be connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.
options INET6 #IPv6 communications protocols
This enables the IPv6 communication protocols.
options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]
This is the basic hard drive filesystem. Leave it in if you
boot from the hard disk.
options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root device
This is the memory-mapped filesystem. This is basically a RAM
disk for fast storage of temporary files, useful if you have a lot
of swap space that you want to take advantage of. A perfect place
to mount an MFS partition is on the /tmp
directory, since many programs store temporary data here. To mount
an MFS RAM disk on /tmp, add the following line
to /etc/fstab:
/dev/ad1s2b /tmp mfs rw 0 0
Now you simply need to either reboot, or run the command
mount /tmp.
options NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS required
The network filesystem. Unless you plan to mount partitions
from a UNIX file server over TCP/IP, you can comment these
out.
options MSDOSFS #MSDOS Filesystem
The MS-DOS filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this out.
It will be automatically loaded the first time you mount a DOS
partition, as described above. Also, the excellent
mtools software (in the ports collection)
allows you to access DOS floppies without having to mount and
unmount them (and does not require MSDOSFS at
all).
options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 required
The ISO 9660 filesystem for CDROMs. Comment it out if you do
not have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this filesystem.
options PROCFS #Process filesystem
The process filesystem. This is a pretend
filesystem mounted on /proc which allows
programs like &man.ps.1; to give you more information on what
processes are running.
options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]
Compatibility with 4.3BSD. Leave this in; some programs will
act strangely if you comment this out.
options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI
This causes the kernel to pause for 15 seconds before probing
each SCSI device in your system. If you only have IDE hard drives,
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
you will have to raise it back up.
options UCONSOLE #Allow users to grab the console
Allow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing xterm
-C, which will display any write,
talk, and any other messages you receive, as well
as any console messages sent by the kernel.
options USERCONFIG #boot -c editor
This option allows you to boot the configuration editor from the
boot menu.
options VISUAL_USERCONFIG #visual boot -c editor
This option allows you to boot the visual configuration editor
from the boot menu.
options KTRACE #ktrace(1) support
This enables kernel process tracing, which is useful in
debugging.
options SYSVSHM #SYSV-style shared memory
This option provides for System V shared memory. The most
common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of for
extra speed. If you use X, you'll definitely want to include
this.
options SYSVSEM #SYSV-style semaphores
Support for System V semaphores. Less commonly used but only
adds a few hundred bytes to the kernel.
options SYSVMSG #SYSV-style message queues
Support for System V messages. Again, only adds a few hundred
bytes to the kernel.
The &man.ipcs.1; command will list any processes using each of
these System V facilities.
options P1003_1B #Posix P1003_1B real-time extentions
options _KPOSIX_PRIORITY_SCHEDULING
Real-time extensions added in the 1993 POSIX. Certain
applications in the ports collection use these (such as Star
Office).
options ICMP_BANDLIM #Rate limit bad replies
This option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
denial of service packet attacks.
# To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/O
The above are both required for SMP support.
# Optionally these may need tweaked, (defaults shown):
#options NCPU=2 # number of CPUs
#options NBUS=4 # number of busses
#options NAPIC=1 # number of IO APICs
#options NINTR=24 # number of INTs
These are some additional SMP knobs.
device isa
All PCs supported by FreeBSD have one of these. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
this time (support is being worked on).
device eisa
Include this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the EISA
bus.
device pci
Include this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.
# Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1
This is the floppy drive controller. fd0 is
the A: floppy drive, and
fd1 is the B:
drive.
device ata
This driver supports all ATA and ATAPI devices. You only need
one device ata line for the kernel to detect all
PCI ATA/ATAPI devices on modern machines.
device atadisk # ATA disk drives
This is needed along with device ata for
ATAPI disk drives.
device atapicd # ATAPI CDROM drives
This is needed along with device ata for
ATAPI CDROM drives.
device atapifd # ATAPI floppy drives
This is needed along with device ata for
ATAPI floppy drives.
device atapist # ATAPI tape drives
This is needed along with device ata for
ATAPI tape drives.
options ATA_STATIC_ID #Static device numbering
This makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.
#options ATA_ENABLE_ATAPI_DMA #Enable DMA on ATAPI devices
This enables DMA on the ATAPI device. Since many ATAPI devices
claim to support DMA, but it does not actually work, this is turned
off by default.
# ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15
Use the above for older, non-PCI systems.
# SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?
SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether.
# SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)
SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.
# RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 family
Supported RAID controllers. If you do not have any of these,
you can comment them out or remove them.
# atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBD
The keyboard controller (atkbdc) provides I/O
services for the AT keyboard and PS/2 style pointing devices. This
controller is required by the keyboard driver
(atkbd) and the PS/2 pointing device driver
(psm).
device atkbd0 at atkbdc? irq 1
The atkbd driver, together with
atkbdc controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.
device psm0 at atkbdc? irq 12
Use this device if your mouse plugs into the PS/2 mouse
port.
device vga0 at isa?
The video card driver.
# splash screen/screen saver
pseudo-device splash
Splash screen at start up! Screen savers require this
too.
# syscons is the default console driver, resembling an SCO console
device sc0 at isa?
sc0 is the default console driver, which
resembles a SCO console. Since most full-screen programs access the
console through a terminal database library like
termcap, it should not matter whether you use
this or vt0, the VT220
compatible console driver. When you log in, set your
TERM variable to scoansi if
full-screen programs have trouble running under this console.
# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-std
This is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with sc0. Also set your
TERM variable to vt100 or
vt220 when you log in. This driver might also
prove useful when connecting to a large number of different machines
over the network, where termcap or
terminfo entries for the sc0
device are often not available — vt100
should be available on virtually any platform.
# Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13
npx0 is the interface to the floating point
math unit in FreeBSD, which is either the hardware co-processor or
the software math emulator. This is not
optional.
# Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power Management
Advanced Power Management support. Useful for laptops.
# PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
PCMCIA support. You need this if you are installing on a
laptop.
# Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9
These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.
If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
S3 chips) use IO addresses in the form of
0x*2e8, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
these cards making the COM4 port practically unavailable.
Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.
# Parallel port
device ppc0 at isa? irq 7
This is the ISA-bus parallel port interface.
device ppbus # Parallel port bus (required)
Provides support for the parallel port bus.
device lpt # Printer
Support for parallel port printers.
All three of the above are required to enable parallel printer
support.
device plip # TCP/IP over parallel
This is the driver for the parallel network interface.
device ppi # Parallel port interface device
The general-purpose I/O (geek port
) + IEEE1284
I/O.
#device vpo # Requires scbus and da
This is for an Iomega Zip drive. It requires
scbus and da support. Best
performance is achieved with ports in EPP 1.9 mode.
# PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (Tulip
)
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 EPIC
)
device vx # 3Com 3c590, 3c595 (Vortex
)
device wx # Intel Gigabit Ethernet Card (Wiseman
)
Various PCI network card drivers. Comment out or remove any of
these not present in your system.
# PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus support
MII bus support is required for some PCI 10/100 ethernet NICs,
namely those which use MII-compliant transceivers or implement
- transceiver control interfaces taht operate like an MII. Adding
+ transceiver control interfaces that operate like an MII. Adding
device miibus to the kernel config pulls in
support for the generic miibus API and all of the PHY drivers,
including a generic one for PHYs that are not specifically handled
by an individual driver
device dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (Starfire
)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (Boomerang
, Cyclone
)
Drivers that use the MII bus controller code.
# ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
-# exists only as a PCMCIA device, so there is no ISA attatement needed
+# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
-# those paremeters here.
+# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?
ISA ethernet drivers. See
/usr/src/sys/i386/conf/LINT for which cards are
supported by which driver.
# Pseudo devices - the number indicates how many units to allocated.
pseudo-device loop # Network loopback
This is the generic loopback device for TCP/IP. If you telnet
or FTP to localhost (a.k.a., 127.0.0.1 it will come back at you through
this pseudo-device. This is mandatory.
pseudo-device ether # Ethernet support
ether is only needed if you have an Ethernet
card. It includes generic Ethernet protocol code.
pseudo-device sl 1 # Kernel SLIP
sl is for SLIP support. This has been almost
entirely supplanted by PPP, which is easier to set up, better suited
for modem-to-modem connection, and more powerful. The
number after sl
specifies how many simultaneous SLIP sessions to support.
pseudo-device ppp 1 # Kernel PPP
This is for kernel PPP support for dial-up connections. There
is also a version of PPP implemented as a userland application that
uses tun and offers more flexibility and features
such as demand dialing. The number after
ppp specifies how many simultaneous PPP
connections to support.
pseudo-device tun # Packet tunnel.
This is used by the userland PPP software. The
number after tun
specifies the number of simultaneous PPP sessions to support. See
the PPP section of this book for more
information.
pseudo-device pty # Pseudo-ttys (telnet etc)
This is a pseudo-terminal
or simulated login port.
It is used by incoming telnet and
rlogin sessions,
xterm, and some other applications such
as emacs. The
number indicates the number of
ptys to create. If you need more than the
default of 16 simultaneous xterm windows
and/or remote logins, be sure to increase this number accordingly,
up to a maximum of 256.
pseudo-device md # Memory disks
Memory disk pseudo-devices.
pseudo-device gif 4 # IPv6 and IPv4 tunneling
This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
tunneling.
pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)
This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.
# The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filter
This is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an ethernet). These packets
can be captured to disk and or examined with the &man.tcpdump.1;
program.
# USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # Human Interface Devices
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernet
Support for various USB devices.
For more information and additional devices supported by
FreeBSD, see
/usr/src/sys/i386/conf/LINT.
Making Device Nodes
Almost every device in the kernel has a corresponding
node
entry in the /dev directory.
These nodes look like regular files, but are actually special
entries into the kernel which programs use to access the device.
The shell script /dev/MAKEDEV, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create all of them, so when you add support for
a new device, it pays to make sure that the appropriate entries are
in this directory, and if not, add them. Here is a simple
example:
Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:
device acd0
This means that you should look for some entries that start with
acd0 in the /dev
directory, possibly followed by a letter, such as
c, or preceded by the letter
r, which means a raw
device. It
turns out that those files are not there, so I must change to the
/dev directory and type:
&prompt.root; sh MAKEDEV acd0
When this script finishes, you will find that there are now
acd0c and racd0c entries
in /dev so you know that it executed
correctly.
For sound cards, the following command creates the appropriate
entries:
&prompt.root; sh MAKEDEV snd0
When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
/etc/fbtab file. See &man.fbtab.5; for more
information.
Follow this simple procedure for any other
non-GENERIC devices which do not have
entries.
All SCSI controllers use the same set of
/dev entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in /dev at all, so you do not
have to worry about these either.
If Something Goes Wrong
There are four categories of trouble that can occur when
building a custom kernel. They are:
config fails
If the config command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
config will print the line number that it
had trouble with, so you can quickly skip to it with
vi. For example, if you see:
config: line 17: syntax error
You can skip to the problem in vi by
typing 17G in command mode. Make sure the
keyword is typed correctly, by comparing it to the
GENERIC kernel or another
reference.
make fails
If the make command fails, it usually
signals an error in your kernel description, but not severe
enough for config to catch it. Again, look
over your configuration, and if you still cannot resolve the
problem, send mail to the &a.questions; with your kernel
configuration, and it should be diagnosed very quickly.
The kernel will not boot
If your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, BSD has an excellent
mechanism for recovering from incompatible kernels. Simply
choose the kernel you want to boot from at the FreeBSD boot
loader (i.e.,
boot kernel.old).
When reconfiguring a kernel, it is always a good idea to keep
a kernel that is known to work on hand.
After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the /var/log/messages file
which records, among other things, all of the kernel messages
from every successful boot. Also, the &man.dmesg.8; command
will print the kernel messages from the current boot.
If you are having trouble building a kernel, make sure
to keep a GENERIC, or some other kernel
that is known to work on hand as a different name that will
not get erased on the next build. You cannot rely on
kernel.old because when installing a
new kernel, kernel.old is overwritten
with the last installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel to the
proper kernel location or commands such
as &man.ps.1; will not work properly. The proper command to
unlock
the kernel file that
make installs (in order to move another
kernel back permanently) is:
&prompt.root; chflags noschg /kernel
And, if you want to lock
your new kernel
into place, or any file for that matter, so that it cannot
be moved or tampered with:
&prompt.root; chflags schg /kernel
The kernel works, but ps does not work
any more!
If you have installed a different version of the kernel
from the one that the system utilities have been built with,
for example, a 4.X kernel on a 3.X system, many system-status
commands like &man.ps.1; and &man.vmstat.8; will not work any
more. You must recompile the libkvm
library as well as these utilities. This is one reason it is
not normally a good idea to use a different version of the
kernel from the rest of the operating system.
diff --git a/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
index c7bb721c09..12ce626731 100644
--- a/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
@@ -1,597 +1,597 @@
Kernel Debugging
Contributed by &a.paul; and &a.joerg;
Debugging a Kernel Crash Dump with <command>kgdb</command>
Here are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the config kernel line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the dumpdev variable in
/etc/rc.conf. Typically you want to specify one of
the swap devices specified in /etc/fstab. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using config -g. See Kernel Configuration for details on
configuring the FreeBSD kernel.
Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via /etc/rc.conf and /etc/rc.
Alternatively, you can hard-code the dump device via the
dump clause in the config line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.
In the following, the term kgdb refers to
gdb run in kernel debug mode
. This
can be accomplished by either starting the gdb with
the option , or by linking and starting it under
the name kgdb. This is not being done by default,
however, and the idea is basically deprecated since the GNU folks do
not like their tools to behave differently when called by another
name. This feature may well be discontinued in further
releases.
When the kernel has been built make a copy of it, say
kernel.debug, and then run strip
-g on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time for
some programs will drastically increase, and since the whole kernel is
loaded entirely at boot time and cannot be swapped out later, several
megabytes of physical memory will be wasted.
If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the flag at the boot prompt, and
then perform the following steps:
&prompt.root; fsck -p
&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable
&prompt.root; savecore -N /kernel.panicked /var/crash
&prompt.root; exit # ...to multi-user
This instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.
Now, after a crash dump, go to
/sys/compile/WHATEVER and run
kgdb. From kgdb do:
symbol-file kernel.debug
exec-file /var/crash/kernel.0
core-file /var/crash/vmcore.0
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.
Here is a script log of a kgdb session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver.
1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; cd /sys/compile/URIAH
3:&prompt.root; kgdb kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb) where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb) up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&frame, FALSE);
36:(kgdb) frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb) list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb) print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb) print tp->t_line
56:$2 = 1767990816
57:(kgdb) up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb) up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb) up
64:#3 0xf012d014 in vn_open ()
65:(kgdb) up
66:#4 0xf012a183 in open ()
67:(kgdb) up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb) up
75:Initial frame selected; you cannot go up.
76:(kgdb) quit
77:&prompt.root; exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994
Comments to the above script:
line 6:
This is a dump taken from within DDB (see below), hence the
panic comment because you said to!
, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.
line 20:
This is the location of function trap()
in the stack trace.
line 36:
Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap. (I do not have a new core
dump handy <g>, my kernel has not panicked for a rather long
time.) From looking at the code in source line 403, there is a
high probability that either the pointer access for
tp
was messed up, or the array access was out of
bounds.
line 52:
The pointer looks suspicious, but happens to be a valid
address.
line 56:
However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
tp->t_line refers to the line discipline of
the console device here, which must be a rather small integer
number.)
Debugging a Crash Dump with DDD
Examining a kernel crash dump with a graphical debugger like
ddd is also possible. Add the
option to the ddd command line you would use
normally. For example;
&prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0
You should then be able to go about looking at the crash dump using
ddd's graphical interface.
Post-Mortem Analysis of a Dump
What do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using config -g? Not
everything is lost here. Do not panic!
Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.
Go to your kernel config directory
(/usr/src/sys/arch/conf)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following line
makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
Rebuild the kernel. Due to the time stamp change on the Makefile,
there will be some other object files rebuild, for example
trap.o. With a bit of luck, the added
option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.
Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the kgdb
session until you know enough.
All this is not guaranteed to work, but it will do it fine in most
cases.
On-Line Kernel Debugging Using DDB
- While kgdb as an offline debugger provides a very
+ While kgdb as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.
If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like kgdb.
To configure your kernel to include DDB, add the option line
options DDB
to your config file, and rebuild. (See Kernel Configuration for details on
configuring the FreeBSD kernel.
Note that if you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)
Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.
The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (options BREAK_TO_DEBUGGER
in the kernel config file). It is not the default since there are a lot
of crappy serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.
The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.
The DDB commands roughly resemble some gdb
commands. The first thing you probably need to do is to set a
breakpoint:
b function-name
b address
Numbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
a-f need to be preceded with 0x
(this is optional for other numbers). Simple expressions are allowed,
for example: function-name + 0x103.
To continue the operation of an interrupted kernel, simply
type:
c
To get a stack trace, use:
trace
Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.
If you want to remove a breakpoint, use
del
del address-expression
The first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:
show b
To single-step the kernel, try:
s
This will step into functions, but you can make DDB trace them until
the matching return statement is reached by:
n
This is different from gdb's
next statement; it is like gdb's
finish.
To examine data from memory, use (for example):
x/wx 0xf0133fe0,40
x/hd db_symtab_space
x/bc termbuf,10
x/s stringbuf
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:
x ,10
Similarly, use
x/ia foofunc,10
to disassemble the first 0x10 instructions of
foofunc, and display them along with their offset
from the beginning of foofunc.
To modify memory, use the write command:
w/b termbuf 0xa 0xb 0
w/w 0xf0010030 0 0
The command modifier
(b/h/w)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.
If you need to know the current registers, use:
show reg
Alternatively, you can display a single register value by e.g.
p $eax
and modify it by:
set $eax new-value
Should you need to call some kernel functions from DDB, simply
say:
call func(arg1, arg2, ...)
The return value will be printed.
For a &man.ps.1; style summary of all running processes, use:
ps
Now you have now examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:
panic
This will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with kgdb. This command
usually must be followed by another continue
statement.
call boot(0)
Which might be a good way to cleanly shut down the running system,
sync() all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.
call cpu_reset()
is the final way out of disaster and almost the same as hitting the
Big Red Button.
If you need a short command summary, simply type:
help
However, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.
On-Line Kernel Debugging Using Remote GDB
This feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.
GDB has already supported remote debugging for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).
You should configure the kernel in question with config
-g, include into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with strip -x, and boot it
using the boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:
&prompt.user; gdb -k kernel
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
(kgdb)
Initialize the remote debugging session (assuming the first serial
port is being used) by:
(kgdb) target remote /dev/cuaa0
Now, on the target host (the one that entered DDB right before even
starting the device probe), type:
Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
db> gdb
DDB will respond with:
Next trap will enter GDB remote protocol mode
Every time you type gdb, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type s (step). Your hosting GDB
will now gain control over the target kernel:
Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
(kgdb)
You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.
Remote GDB can also be used to debug LKMs. First build the LKM with
debugging symbols:
&prompt.root; cd /usr/src/lkm/linux
&prompt.root; make clean; make COPTS=-g
Then install this version of the module on the target machine, load
it and use modstat to find out where it was
loaded:
&prompt.root; linux
&prompt.root; modstat
Type Id Off Loadaddr Size Info Rev Module Name
EXEC 0 4 f5109000 001c f510f010 1 linux_mod
Take the load address of the module and add 0x20 (probably to
account for the a.out header). This is the address that the module code
was relocated to. Use the add-symbol-file command in
GDB to tell the debugger about the module:
(kgdb) add-symbol-file /usr/src/lkm/linux/linux_mod.o 0xf5109020
add symbol table from file "/usr/src/lkm/linux/linux_mod.o" at
text_addr = 0xf5109020? (y or n) y
(kgdb)
You now have access to all the symbols in the LKM.
Debugging a Console Driver
Since you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying at the Boot: prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.
diff --git a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
index 71e0e85ab3..28fcdb26ed 100644
--- a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
@@ -1,165 +1,165 @@
Adding New Kernel Configuration Options
Contributed by &a.joerg;
You should be familiar with the section about kernel configuration before reading
here.
What's a <emphasis>Kernel Option</emphasis>, Anyway?
The use of kernel options is basically described in the kernel configuration section.
There's also an explanation of historic
and
new-style
options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a make depend in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.
Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel .h file) must be written with the option
- concept in mind, i.e. the default must have been made overridable by the
+ concept in mind, i.e., the default can be overridden by the
config option. This is usually done with something like:
#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */
This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.
It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in
#ifdef THAT_OPTION
[your code here]
#endif
Simply mentioning THAT_OPTION in the config file
(with or without any value) will then turn on the corresponding piece of
code.
People familiar with the C language will immediately recognize that
everything could be counted as a config option
where there
is at least a single #ifdef referencing it...
However, it's unlikely that many people would put
options notyet,notdef
in their config file, and then wonder why the kernel compilation
falls over. :-)
Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the new-style option scheme, where
each option goes into a separate .h file in the
kernel compile directory, which is by convention named
opt_foo.h. This way,
the usual Makefile dependencies could be applied, and
make can determine what needs to be recompiled once
an option has been changed.
The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new #ifdef to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.
Now What Do I Have to Do for it?
First, edit sys/conf/options (or
sys/<arch>/conf/options.<arch>,
e. g. sys/i386/conf/options.i386), and select an
opt_foo.h file where
your new option would best go into.
If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
- behaviour of the SCSI subsystem can go into
+ behavior of the SCSI subsystem can go into
opt_scsi.h. By default, simply mentioning an
option in the appropriate option file, say FOO,
implies its value will go into the corresponding file
opt_foo.h. This can be overridden on the
right-hand side of a rule by specifying another filename.
If there is no
opt_foo.h already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
options[.<arch>]
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..
Packing too many options into a single
opt_foo.h will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.
Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet,
&prompt.user; find /usr/src/sys -type f | xargs fgrep NEW_OPTION
is your friend in finding them. Go and edit all those files, and add
#include "opt_foo.h" on
top before all the #include <xxx.h> stuff.
This sequence is most important as the options could override defaults
from the regular include files, if the defaults are of the form
#ifndef NEW_OPTION #define NEW_OPTION (something)
#endif in the regular header.
Adding an option that overrides something in a system header file
(i.e., a file sitting in /usr/include/sys/) is
almost always a mistake.
opt_foo.h cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.
diff --git a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
index f7d9341dd1..54770b0f3f 100644
--- a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
@@ -1,920 +1,920 @@
Localization - I18N/L10N Usage and Setup
Contributed by &a.ache;
Rewritten by Michael Chin-Yuan Wu
keichii@mail.utexas.edu, 6 March 2000.
Synopsis
This section of the handbook discusses the internationalization
and localization of FreeBSD to different countries and different
settings. If the users wish to use languages other than the system
default English, he/she will have to setup the system accordingly.
Please note that language support for each language varies in level.
Hence, the user should contact the respective FreeBSD local group
that is responsible for each language.
The author realizes that he may have been incomplete in the
description of the i18n process in FreeBSD. Due to the various
- levels of i18n implementation in both the system and applicational
+ levels of i18n implementation in both the system and application
levels, we advise you to refer to individual documentation, man
pages, READMEs, and so forth.
Should you have any questions or suggestions regarding this
chapter, please email the author.
The Basics
What is i18n/l10n?
Developers shortened internationalization into the term i18n,
counting the number of letters between the first and the last
letters of internationalization. l10n uses the same naming
scheme, coming from "localization". Combined
together, i18n/l10n methods, protocols, and applications allow
users to use languages of their choice.
I18n applications are programmed using i18n kits under
libraries. It allows for developers to write a simple file and
translate displayed menus and texts to each language. We strongly
encourage programmers to follow this convention.
Why should I use i18n/l10n?
I18n/l10n is used whenever you wish to either view, input, or
process data in non-English languages.
What languages are supported in the i18n effort?
I18n and l10n are not FreeBSD specific. Currently, one can
choose from most of the major languages of the World, including
but not limited to: Chinese, German, Japanese, French, Russian,
and others.
Using Localization
In all its splendor, i18n is not FreeBSD-specific and is a
convention. We encourage you to help FreeBSD in following this
convention.
Localization settings are based on three main terms:
Language Code, Country Code, and Encoding. Locale names are
constructed from these parts as follows:
LanguageCode_CountryCode.Encoding
Language and Country Codes
In order to localize a FreeBSD system to a specific language
(or any other i18n-supporting UNIX's), the user needs to find out
the codes for the specify country and language (country
codes tell applications what variation of given
language to use). In addition, web
- browsers, SMTP/POP servers, HTTPd's, etc. make decisions based on
+ browsers, SMTP/POP servers, web servers, etc. make decisions based on
them. The following are examples of language/country codes:
Language/Country Code
Description
en_US
English - United States
ru_RU
Russian for Russia
zh_TW
Traditional Chinese for Taiwan
Encodings
Some languages use non-ASCII encodings that are 8-bit, wide
or multibyte characters, see &man.multibyte.3; for more
details. Older applications do not recognize them
and mistake them for control characters. Newer applications
usually do recognize 8-bit characters. Depending on the
implementation, users may be required to compile an application
with wide or multibyte characters support, or configure it correctly.
To be able to input and process wide or multibyte characters, the FreeBSD Ports collection has provided
each language with different programs. Refer to the i18n
documentation in the respective FreeBSD Port.
Specifically, the user needs to look at the application
documentation to decide on how to configure it correctly or to
pass correct values into the configure/Makefile/compiler.
Some things to keep in mind are:
Language specific single C chars character sets
(see &man.multibyte.3;), i.e.,
ISO_8859-1, KOI8-R, CP437.
Wide or multibyte encodings, f.e. EUC, Big5.
You can check the active list of character sets at the
IANA Registry.
I18n applications
In the FreeBSD Ports and Package system, i18n applications
have been named with i18n in their names for
easy identification. However, they do not always support the
language needed.
Setting Locale
Theoretically, one only needs to export the value of his/her
locale name as LANG in the login shell and is
usually done through the user's
~/.login_conf or the user login shell
configuration (~/.profile,
~/.bashrc, ~/.cshrc).
This should set all of the locale subsets (such as
LC_CTYPE, LC_CTIME, etc.). Please
refer to language-specific FreeBSD documentation for more
information.
You should set the following two values in your configuration
files:
LANG for POSIX &man.setlocale.3; family
functions
MM_CHARSET for applications' MIME character
set
This includes the user shell config, the specific application
config, and the X11 config.
Setting Locale Methods
There are two methods for setting locale, and both are
described below. The first (recommended one) is by assigning
the environment variables in login
class, and the second is by adding the environment
variable assignments to the system's shell startup file.
Login Classes Method
This method allows environment variables needed for locale
name and MIME character sets to be assigned once for every
possible shell instead of adding specific shell assignments to
each shell's startup file. User
Level Setup can be done by an user himself and Administrator Level Setup require
- superuser priviledges.
+ superuser privileges.
User Level Setup
Here is a minimal example of a
.login_conf file in user's home
directory which has both variables set for Latin-1
encoding:
me:My Account:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:
See Administrator Level
Setup and &man.login.conf.5; for more details.
Administrator Level Setup
Check that /etc/login.conf have the
correct language user's class. Make sure these settings
appear in /etc/login.conf:
language_name:accounts_title:\
:charset=MIME_charset:\
:lang=locale_name:\
:tc=default:
So sticking with our previous example using Latin-1, it
would look like this:
german:German Users Accounts:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:\
:tc=default:
Changing Login Classes with &man.vipw.8;
Use vipw to add new users, and make
the entry look like this:
user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh
Changing Login Classes with &man.adduser.8;
Use adduser to add new users, and do
the following:
Set defaultclass =
language in
/etc/adduser.conf. Keep in mind
you must enter a default class for
all users of other languages in this case.
An alternative variant is answering the specified
language each time that
Enter login class: default []:
appears from &man.adduser.8;
Another alternative is to use the following for each
user of a different language that you wish to
add:
&prompt.root; adduser -class language
Changing Login Classes with &man.pw.8;
If you use &man.pw.8; for adding new users, call it in
this form:
&prompt.root; pw useradd user_name -L language
Shell Startup File Method
This method is not recommended because it requires a
different setup for each possible login program chosen. Use
the Login Class Method
instead.
To add the locale name and MIME character set, just set
the two environment variables shown below in the
/etc/profile and/or
/etc/csh.login shell startup files. We
will use the German language as an example below:
In /etc/profile:
LANG=de_DE.ISO_8859-1; export LANG
MM_CHARSET=ISO-8859-1; export MM_CHARSET
Or in /etc/csh.login:
setenv LANG de_DE.ISO_8859-1
setenv MM_CHARSET ISO-8859-1
Alternatively, you can add the above instructions to
/usr/share/skel/dot.profile (similar to
what was used in /etc/profile above), or
/usr/share/skel/dot.login (similar to
what was used in /etc/csh.login
above).
For X11:
In $HOME/.xinitrc:
LANG=de_DE.ISO_8859-1; export LANG
Or:
setenv LANG de_DE.ISO_8859-1
Depending on your shell (see above).
Console Setup
For all single C chars character sets, set the correct
console fonts in /etc/rc.conf for the
language in question with:
font8x16=font_name
font8x14=font_name
font8x8=font_name
The font_name here is taken from
the /usr/share/syscons/fonts directory,
without the .fnt suffix.
Also be sure to set the correct keymap and screenmap for your
single C chars character set through
/stand/sysinstall.
Once inside sysinstall, choose Configure, then
Console. Alternatively, you can add the
following to /etc/rc.conf:
scrnmap=screenmap_name
keymap=keymap_name
keychange="fkey_number sequence"
The screenmap_name here is taken
from the /usr/share/syscons/scrnmaps
directory, without the .scm suffix. A
screenmap with a corresponding mapped font is usually needed as a
workaround for expanding bit 8 to bit 9 on a VGA adapter's font
character matrix in pseudographics area, i.e., to move letters out
of that area if screen font uses a bit 8 column.
If you have the following settings, insert the
kernel config specified in the paragraph after the list.
Console uses a screen font that utilizes 8-bit column font
character.
The moused daemon is enabled by setting the following in
your /etc/rc.conf:
moused_enable="YES"
A workaround for expanding 8-bit to 9-bit on a VGA adapter
is usually needed for the above settings. This workaround
disables 8-bit to 9-bit expansion of the font character with the
mouse cursor the sc0 console driver. To enable the workaround,
insert the following line into the kernel config.
options SC_MOUSE_CHAR=0x03
The keymap_name here is taken from
the /usr/share/syscons/keymaps directory,
without the .kbd suffix.
The keychange is usually needed to program
function keys to match the selected terminal type because
function key sequences can not be defined in the key map.
Also be sure to set the correct console terminal type in
/etc/ttys for all ttyv*
entries. Current pre-defined correspondences are:
Character Set
Terminal Type
ISO-8859-1 or ISO-8859-15
cons25l1
ISO-8859-2
cons25l2
KOI8-R
cons25r
CP437 (hardware default)
cons25
For wide or multibyte characters languages, use the correct
FreeBSD port in your
/usr/ports/language
directory. Some ports appear as console while the system sees it
as serial vtty's, hence you must reserve enough vtty's for both
X11 and the pseudo-serial console. Here is a partial list of
applications for using other languages in console:
Language
Location
Traditional Chinese (BIG-5)
/usr/ports/chinese/big5con
Japanese
/usr/ports/japanese/ja-kon2-* or
/usr/ports/japanese/Mule_Wnn
Korean
/usr/ports/korean/ko-han
X11 Setup
Although X11 is not part of the FreeBSD Project, we have
included some information here for FreeBSD users. For more
details, refer to the XFree86
- website or whichever X11 Server you use.
+ web site or whichever X11 Server you use.
In ~/.Xresources, you can additionally
tune application specific i18n settings (e.g., fonts, menus,
etc.).
Displaying Fonts
Install the X11 True Type-Common server (XTT-common) and
install the language truetype fonts. Setting the correct
locale should allow you to view your selected language in menus
and such.
Inputting Non-English Characters
The X11 Input Method (XIM) Protocol is a new standard for
all X11 clients. All X11 applications should be written as XIM
clients that take input from XIM Input servers. There are
several XIM servers available for different languages.
Printer Setup
Some single C chars character sets are usually hardware
coded into printers. Wide or multibyte
character sets require special setup and we recommend using
apsfilter. You may also convert the
document to Postscript or PDF formats using language specific
converters.
Kernel and File Systems
The FreeBSD FFS filesystem is 8-bit clean, so it can be used
with any single C chars character set (see &man.multibyte.3;),
but there is no character set
name stored in the filesystem; i.e., it is raw 8-bit and does not
know anything about encoding order. Officially, FFS does not
support any form of wide or multibyte character sets yet. However, some
wide or multibyte character sets have independent patches for FFS
enabling such support. They are only temporary unportable
solutions or hacks and we have decided to not include them in the
- source tree. Refer to respective languages' websites for more
+ source tree. Refer to respective languages' web sites for more
informations and the patch files.
- The FreeBSD MSDOS filesystem has the configurable ability to
- convert between MSDOS, Unicode character sets and chosen
+ The FreeBSD MS-DOS filesystem has the configurable ability to
+ convert between MS-DOS, Unicode character sets and chosen
FreeBSD filesystem character sets. See &man.mount.msdos.8; for
details.
Advanced Topics
If you wish to compile i18n applications or program i18n
compliant applications, please read this section.
Compiling i18n Programs
Many FreeBSD Ports have been ported with i18n support. Some
of them are marked with -i18n in the port name. These and many
other programs have built in support for i18n and need no special
consideration.
However, some applications such as MySQL need to be have the
Makefile configured with the specific
charset. This is usually done in the
Makefile or done by passing a value to
configure in the source.
Programming i18n Compliant Applications
To make your application more useful for speakers of other
languages, we hope that you will program i18n compliant. The GNU
gcc compiler, GUI Libraries like QT and GTK support i18n through
special handling of strings. Making a program i18n compliant is
very easy. It allows contributors to port your application to
other languages quickly. Refer to library specific i18n
documentation for more details.
To the contrary of common perception, i18n compliant code is
easy to write. Usually, it only involves wrapping your strings
with library specific functions. In addition, please be sure to
allow for wide or multibyte characters support.
A Call to Unify the i18n effort
It has come to our attention that the individual i18n/l10n
efforts for each country has been repeating each others'
efforts. Many of us have been reinventing the wheel repeatedly
and inefficiently. We hope that the various major groups in
- i18n could congregate into a group effort similiar to the Core
+ i18n could congregate into a group effort similar to the Core
Team's responsibility.
Currently, we hope that, when you write or port i18n
programs, you would send it out to each country's related
FreeBSD mailing lists for testing. In the future, we hope to
create applications that work in all the languages
out-of-the-box without dirty hacks.
Perl and Python
Perl and Python have i18n and wide characters handling
libraries. Please use them for i18n compliance.
In older FreeBSD versions,
Perl may gives warning about not having a wide characters locale
that is already installed in your system. You can set the
environmental variable LD_PRELOAD to
/usr/lib/libxpg4.so in your shell.
In sh-based shells:
LD_PRELOAD=/usr/lib/libxpg4.so
In C-based shells:
setenv LD_PRELOAD /usr/lib/libxpg4.so
Localizing FreeBSD to Specific Languages
Russian Language (KOI8-R encoding)
Originally contributed by
&a.ache;.
For more information about KOI8-R encoding, see the KOI8-R References
(Russian Net Character Set).
Locale Setup
Put the following lines into your
~/.login_conf file:
me:My Account:\
:charset=KOI8-R:\
:lang=ru_RU.KOI8-R:
See earlier in this chapter for examples of setting up the
locale.
Console Setup
Add the following to your kernel configuration
file:
options SC_MOUSE_CHAR=0x03
Use following settings in
/etc/rc.conf:
keymap="ru.koi8-r"
keychange="61 ^[[K"
scrnmap="koi8-r2cp866"
font8x16="cp866b-8x16"
font8x14="cp866-8x14"
font8x8="cp866-8x8"
Note that the ^[ here stands for a
real Escape character (\033) entered directly in
/etc/rc.conf, not for sequence of two
characters '^' and '['.
For each ttyv* entry in
/etc/ttys, use
cons25r as the terminal type.
See earlier in this chapter for examples of setting up the
console.
Printer Setup
Since most printers with Russian characters come with
hardware code page CP866, a special output filter is needed for
KOI8-R -> CP866 conversion. Such a filter is installed by
default as /usr/libexec/lpr/ru/koi2alt.
A Russian printer /etc/printcap entry
should look like:
lp|Russian local line printer:\
:sh:of=/usr/libexec/lpr/ru/koi2alt:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
See &man.printcap.5; for a detailed description.
- MSDOS FS and Russian Filenames
+ MS-DOS FS and Russian Filenames
The following example &man.fstab.5; entry enables support
- for Russian filenames in mounted MSDOS filesystems:
+ for Russian filenames in mounted MS-DOS filesystems:
/dev/ad0s2 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0
See &man.mount.msdos.8; for a detailed description of the
and options.
X11 Setup
Do non-X locale
setup first as described.
The Russian KOI8-R locale
may not work with old XFree86 releases (lower than 3.3).
The XFree86 port from
/usr/ports/x11/XFree86 already is the
most recent XFree86 version, so it will work if you
install XFree86 from the port. This should not be an
issue unless you are using an old version of
FreeBSD.
Go to the
/usr/ports/russian/X.language directory
and issue the following command:
&prompt.root; make install
The above port installs the latest version of the KOI8-R
fonts. XFree86 3.3 already has some KOI8-R fonts, but these
are scaled better.
Check the "Files" section
in your /etc/XF86Config file.
The following
lines must be added before any other
FontPath entries:
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"
If you use a high resolution video mode, swap the 75 dpi
and 100 dpi lines.
To activate a Russian keyboard, add the following to the
"Keyboard" section of your
XF86Config file:
XkbLayout "ru"
XkbOptions "grp:caps_toggle"
Also make sure that XkbDisable is
turned off (commented out) there.
The RUS/LAT switch will be CapsLock.
The old CapsLock function is still
available via Shift+CapsLock (in LAT mode
only).
If you have Windows
keys on your keyboard,
and notice that some non-alphabetical keys are mapped
incorrectly in RUS mode, add the following line in your
XF86Config file:
XkbVariant "winkeys"
The Russian XKB keyboard may not work with old XFree86
versions, see the above
note for more information. The Russian XKB
keyboard may also not work with non-localized
applications as well. Minimally localized applications
should call a XtSetLanguageProc (NULL, NULL,
NULL); function early in the program.
See
KOI8-R for X-Window for more instructions on
localizing X11 applications.
Traditional Chinese Localization for Taiwan
The FreeBSD-Taiwan Project has an i18n/l10n tutorial for
FreeBSD at http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html
using many /usr/ports/chinese/* applications.
The editor for the zh-l10n-tut is Clive Lin
Clive@CirX.org. You can also cvsup the following
collections at freebsd.sinica.edu.tw:
Collection
Description
outta-port tag=.
Beta-quality Ports Collection for Chinese
zh-l10n-tut tag=.
Localizing FreeBSD Tutorial in BIG-5 Traditional
Chinese
zh-doc tag=.
- FreeBSD Documenation Translation to BIG-5 Traditional
+ FreeBSD Documentation Translation to BIG-5 Traditional
Chinese
Chuan-Hsing Shen s874070@mail.yzu.edu.tw has
created the Chinese
FreeBSD Extension (CFE) using FreeBSD-Taiwan's
zh-l10n-tut. The packages and the script files
are available at ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/cfe.txt
and ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/.
German Language Localization (For All ISO 8859-1
Languages)
Slaven Rezic eserte@cs.tu-berlin.de wrote a
tutorial how to use umlauts on a FreeBSD machine. The tutorial
is written in German and available at http://www.de.FreeBSD.org/de/umlaute/.
Japanese and Korean Language Localization
For Japanese, refer to http://www.jp.FreeBSD.org/,
and for Korean, refer to http://www.kr.FreeBSD.org/.
Non-English FreeBSD Documentation
Some FreeBSD contributors have translated parts of FreeBSD to
other languages. They are available through links on the main site or in
/usr/share/doc.