Date: Sat, 21 Oct 1995 20:29:51 +0100 (MET) From: J Wunsch <j@uriah.heep.sax.de> To: doc@freebsd.org Subject: Some update Message-ID: <199510211929.UAA18548@uriah.heep.sax.de>
next in thread | raw e-mail | index | archive | help
Hi Doc :-)
Well, after i finally figured out how to convert all these funny SGML
files into something human-readable, and it turned out that even a
simple "make" would do <g></g>, i've took the time to update some of
the portions, mainly those that originated from me.
Guys, GREAT work that you've done here!
Here's the updates. Everything is against the 2.1.0 branch, in hope
that this wouldn't be too late yet for 2.1. -- Jörg
Index: handbook/authors.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/authors.sgml,v
retrieving revision 1.3.4.2
diff -u -r1.3.4.2 authors.sgml
--- 1.3.4.2 1995/10/12 03:15:42
+++ authors.sgml 1995/10/21 18:03:13
@@ -55,7 +55,7 @@
<tt><htmlurl url='mailto:jkh@FreeBSD.org'
name='<jkh@FreeBSD.org>'></tt>">
-<!ENTITY a.joerg "Joerg Wunsch
+<!ENTITY a.joerg "Jörg Wunsch
<tt><htmlurl url='mailto:joerg_wunsch@uriah.heep.sax.de'
name='<joerg_wunsch@uriah.heep.sax.de>'></tt>">
Index: handbook/basics.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/basics.sgml,v
retrieving revision 1.1.1.1.4.2
diff -u -r1.1.1.1.4.2 basics.sgml
--- 1.1.1.1.4.2 1995/10/12 03:15:43
+++ basics.sgml 1995/10/21 13:06:35
@@ -45,7 +45,12 @@
% <bf>man 1 chmod</bf>
</tscreen>
which will display the manual page for the user command
- <tt><bf>chmod</bf></tt>.
+ <tt><bf>chmod</bf></tt>. References to a particular
+ section of the on-line manual are traditionally placed
+ in paranthesis in written documentation; so
+ <tt><bf>chmod(1)</bf></tt> refers to the <tt><bf>chmod
+ </bf></tt> user command, while <tt><bf>chmod(2)</bf></tt>
+ means the system call.
<p>This is fine if you know the name of the command and
forgot how to use it, but what if you cannot recall the
@@ -57,7 +62,21 @@
</tscreen>
With this command you will be presented with a list of
commands that have the keyword `mail' in their
- descriptions.
+ descriptions. This is the same as the separate command
+ <tt><bf>apropos</bf></tt>.
+
+ <p>You are seeing all those fancy commands in <tt>
+ /usr/bin</tt>, but don't even have the silliest idea
+ what most of the names do actually stand for? Simply
+ do a
+ <tscreen>
+ % <bf>cd /usr/bin; man -f *</bf>
+ </tscreen>
+ or
+ <tscreen>
+ % <bf>cd /usr/bin; whatis *</bf>
+ </tscreen>
+ which is the same.
<sect>
<heading>GNU Info files<label id="basics:info"></heading>
Index: handbook/booting.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/booting.sgml,v
retrieving revision 1.2.4.2
diff -u -r1.2.4.2 booting.sgml
--- 1.2.4.2 1995/10/12 03:15:47
+++ booting.sgml 1995/10/21 18:56:43
@@ -107,7 +107,7 @@
<sect1><heading>Initialize user-land things</heading>
<p>
To get the user-land going, when the kernel has finished
- initialization, it will create a with ``<tt/pid == 1/'' and execute
+ initialization, it will create a process with ``<tt/pid == 1/'' and execute
a program on the rootfilesystem, this program is normally
``<tt>/sbin/init</tt>''.
@@ -115,8 +115,11 @@
in mind that:
there is no stdin/out/err unless you open it yourself, if you exit,
- the machine panics signal handling is special for ``<tt/pid ==
+ the machine panics, signal handling is special for ``<tt/pid ==
1/''.
+
+ An example of this is the ``<tt>/stand/sysinstall</tt>''
+ program on the installation floppy.
<sect1><heading>Interesting combinations</heading>
Index: handbook/contrib.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/contrib.sgml,v
retrieving revision 1.15.2.2
diff -u -r1.15.2.2 contrib.sgml
--- 1.15.2.2 1995/10/12 03:15:48
+++ contrib.sgml 1995/10/21 18:04:57
@@ -254,7 +254,7 @@
<item>James da Silva <jds@cs.umd.edu> et al
<item>Jay Fenlason <hack@datacube.com>
<item>Jim Wilson <wilson@moria.cygnus.com>
- <item>Joerg Lohse <lohse@tech7.informatik.uni-hamburg.de>
+ <item>Jörg Lohse <lohse@tech7.informatik.uni-hamburg.de>
<item>Jörg Wunsch <joerg_wunsch@uriah.heep.sax.de>
<item>John Dyson - <formerly dyson@ref.tfs.com>
<item>John Polstra <jdp@polstra.com>
Index: handbook/install.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/install.sgml,v
retrieving revision 1.9.2.2
diff -u -r1.9.2.2 install.sgml
--- 1.9.2.2 1995/10/18 04:36:28
+++ install.sgml 1995/10/21 12:48:59
@@ -202,11 +202,16 @@
Not yet! We'd like to add support for this someday, but
are still lacking anyone to actually do the work.
- Ongoing work with Linux's PCEMU utility may bring this
+ Ongoing work with Linux's DOSEMU utility may bring this
much closer to being a reality sometime soon. Send mail
to hackers@freebsd.org if you're interested in joining
this effort!
+ However, there's a nice application available in the
+ <ref id="ports" name="The Ports Collection"> called pcemu,
+ that allows you to run many basic MS-DOS text-mode binaries
+ by entirely emulating an 8088 CPU.
+
<sect><heading>Supported Configurations<label id="install:hw"></heading>
@@ -244,7 +249,9 @@
<item>Adaptec 274X/284X/2940 <!-- 3940 (in 2.1) -->
(Narrow/Wide/Twin)
series EISA/VLB/PCI SCSI controllers
- <item>Adaptec AIC-6260 and AIC-6360 based boards,
+ <item>Adaptec
+ <!-- AIC-6260 and - actually not working, joerg -->
+ AIC-6360 based boards,
which includes the AHA-152x and SoundBlaster SCSI
cards.
@@ -366,6 +373,8 @@
<item>BOCA IOAT66 6 port serial card using shared IRQ.
+ <item>BOCA 2016 16 port serial card using shared IRQ.
+
<item>Cyclades Cyclom-y Serial Board.
<item>STB 4 port card using shared IRQ.
@@ -453,12 +462,14 @@
You will also need, at minimum, as many 1.44MB or 1.2MB
floppies as it takes to hold all files in the bin
- (binary distribution) directory. THESE floppies *must*
+ (binary distribution) directory. THESE floppies <bf>must</bf>
be formatted using MS-DOS, using with the FORMAT
command in MS-DOS or the File Manager format command in
Microsoft Windows(tm). Factory preformatted floppies
will also work well, provided that they haven't been
- previously used for something else.
+ previously used for something else. Note that only media
+ without any defects are usable for these floppies; there
+ is no kind of bad sector remapping available for them.
Many problems reported by our users in the past have
resulted from the use of improperly formatted media, so
Index: handbook/kernelconfig.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/kernelconfig.sgml,v
retrieving revision 1.1
diff -u -r1.1 kernelconfig.sgml
--- 1.1 1995/10/07 04:31:31
+++ kernelconfig.sgml 1995/10/21 13:44:48
@@ -192,6 +192,11 @@
your kernel's name in quotation marks if it
contains any numbers.
+ Since this name is passed to the C compiler as a
+ <tt>-D</tt> switch, don't use names like <tt>
+ DEBUG</tt>, or something that could be confused
+ with another machine or CPU name, like <tt>vax</tt>.
+
<tag>maxusers <em>number</em></tag>
<p>This file sets the size of a number of important
@@ -294,7 +299,8 @@
Windows. For example, you can create a console
xterm by typing <tt>xterm -C</tt>, which will
display any `write', `talk', and other messages you
- receive.
+ receive, as well as any console messages sent by the
+ kernel.
<tag>options SYSVSHM</tag>
@@ -381,6 +387,7 @@
is a pretend filesystem mounted on /proc which
allows programs like <tt>ps(1)</tt> to give you
more information on what processes are running.
+ <-- XXX why? it's perfectly working as LKM. joerg -->
Leave it in.
<tag>options MFS</tag>
@@ -624,6 +631,16 @@
<p>Support for SCSI CD-ROM
drives.
+ <p>Note that the number <bf>0</bf> in the above entries
+ is slightly misleading: all these devices are
+ automatically configured as they are found, regardless
+ of how many of them are hooked up to the SCSI bus(es),
+ and which target IDs they have.
+
+ If you want to ``wire down'' specific target IDs to
+ particular devices, refer to the appropriate section
+ of the LINT kernel config file.
+
</descrip>
<sect1><heading>Console, Bus Mouse, and X Server Support</heading>
@@ -652,9 +669,13 @@
console driver, backwards compatible to VT100/102.
It works well on some laptops which have hardware
incompatibilities with <tt>sc0</tt>. Also, set
- your TERM variable to ``vt220'' when you log in if
- full-screen programs do not run correctly on this
- console.
+ 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 the <em>termcap</em>
+ or <em>terminfo</em> entries for the <tt>sc0</tt>
+ device are often not available -- ``vt100'' should be
+ available on virtually any platform.
<descrip>
@@ -712,7 +733,17 @@
it from FreeBSD. If you have a multiport serial
card, check the manual page for <tt>sio(4)</tt> for
more information on the proper values for these
- lines.
+ lines. Some video cards (notably
+ those based on S3 chips) use IO addresses of the
+ form <tt>0x*2e8</tt>, 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!
<tag>device lpt0 at isa? port? tty irq 7 vector lptintr</tag>
@@ -958,7 +989,7 @@
<p>Stand-alone 6850 UART for MIDI.
- <tag>device pca0 at isa? port ``IO_TIMER1'' tty</tag>
+ <tag>device pca0 at isa? port ``IO_TIMER1'' tty<label id="kernelconfig:pcaudio"></tag>
<p>Digital audio through PC speaker. This is going to
be very poor sound quality and quite CPU-intensive,
@@ -1060,6 +1091,9 @@
game NetHack (in the ports collection) can be
configured to use this device to play songs when
you play musical instruments in the game.
+
+ <p>See also the <ref id="kernelconfig:pcaudio"
+ name="pca0"> device.
</descrip>
Index: handbook/kerneldebug.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/kerneldebug.sgml,v
retrieving revision 1.3.2.1
diff -u -r1.3.2.1 kerneldebug.sgml
--- 1.3.2.1 1995/10/12 03:16:09
+++ kerneldebug.sgml 1995/10/21 18:55:51
@@ -26,10 +26,8 @@
normally arranged via <tt>/etc/sysconfig</tt> and <tt>/etc/rc</tt>.
Alternatively, you can
hard-code the dump device via the `dump' clause in the `config' line
- of your kernel config file. This is deprecated, but might be the
- only chance to get a crash dump from a kernel that's not booting at
- all, so that you didn't had the ability to run any command before it
- used to crash.
+ of your kernel config file. This is deprecated, use only if you
+ want a crash dump from a kernel that crashes during booting.
<em><bf>Note:</bf> In the following, the term `<tt>kgdb</tt>' refers
to <tt>gdb</tt> run in `kernel debug mode'. This can be accomplished by
@@ -44,7 +42,7 @@
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 RAM will be wasted.
+ 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
@@ -58,7 +56,9 @@
exit # ...to multi-user
</verb></tscreen>
This instructs <tt>savecore(8)</tt> to use another kernel for symbol name
- extraction. It would otherwise default to the currently running kernel.
+ 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 <tt>/sys/compile/WHATEVER</tt> and run
<tt>kgdb</tt>. From <tt>kgdb</tt> do:
@@ -70,22 +70,8 @@
and voila, you can debug the crash dump using the kernel sources
just like you can for any other program.
- If your kernel panicked due to a trap, perhaps the most common
- case for getting a core dump, the following trick might help
- you. Examine the stack using <tt>kgdb</tt>'s `where' command,
- and look for the stack frame in the function <tt>trap()</tt>. Go `up'
- to that frame, and then type:
-<tscreen><verb>
- frame frame->tf_ebp frame->tf_eip
-</verb></tscreen>
- This will tell <tt>kgdb</tt> to go to the stack frame explicitly named by a
- frame pointer and instruction pointer, which is the location where
- the trap occured. There are still some bugs in <tt>kgdb</tt> (you can go
- `up' from there, but not `down'; the stack trace will still remain
- as it was before going to here), but generally this method will lead
- you much closer to the failing piece of code.
-
- Here's a script log of a <tt>kgdb</tt> session illustrating the above. Long
+ Here's a script log of a <tt>kgdb</tt> session illustrating the
+ procedure. Long
lines have been folded to improve readability, and the lines are
numbered for reference. Despite of this, it's a real-world error
trace taken during the development of the pcvt console driver.
@@ -180,9 +166,13 @@
a page fault trap though.
<tag/line 20:/ This is the location of function <tt>trap()</tt>
in the stack trace.
-<tag/line 36:/ Force usage of a new stack frame, kgdb responds and displays
- the source line where the trap happened; from looking at the
- code, there's a high probability that either the pointer
+<tag/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 don't have a new core dump handy <g>, my kernel
+ didn't panic for rather long.)
+ From looking at the code in source line 403,
+ there's a high probability that either the pointer
access for ``tp'' was messed up, or the array access was
out of bounds.
<tag/line 52:/ The pointer looks suspicious, but happens to be a valid
@@ -202,11 +192,7 @@
Not everything is lost here. Don't panic!
Of course, you still need to enable crash dumps. See above
- on the options you've got to do this.
- (This is for safety reasons in the default kernels, to avoid them
- trying to dump e.g. during system installation where there's no
- FreeBSD partition at all and valuable data on the disk could be
- destroyed.)
+ on the options you've got in order to do this.
Go to your kernel compile directory, and edit the line
containing <tt>COPTFLAGS?=-O</tt>. Add the <tt>-g</tt> option
@@ -270,14 +256,17 @@
Ctrl-Alt-ESC. For syscons, this can be remapped, and some of
the distributed maps do this, so watch out.
There's an option
- available for a COMCONSOLE kernel (``options BREAK_TO_DEBUGGER'')
+ available for serial consoles
that allows the use of a serial line BREAK on the console line to
- enter DDB.
+ enter DDB (``<tt>options BREAK_TO_DEBUGGER</tt>''
+ 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. It is not wise to
- configure a kernel with DDB for a machine running unattended
- for this reason.
+ 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 <tt>gdb</tt> commands. The first you
probably need is to set a breakpoint:
@@ -325,7 +314,7 @@
<tscreen><verb>
n
</verb></tscreen>
- Note: this is different from <tt>gdb</tt>'s `next' statement, it's like
+ <bf>Note:</bf> this is different from <tt>gdb</tt>'s `next' statement, it's like
<tt>gdb</tt>'s `finish'.
To examine data from memory, use (for example):
@@ -364,7 +353,7 @@
</verb></tscreen>
Alternatively, you can display a single register value by e.g.
<tscreen><verb>
- print $eax
+ p $eax
</verb></tscreen>
and modify it by
<tscreen><verb>
@@ -412,14 +401,24 @@
is the final way out of disaster and almost the same as hitting
the Big Red Button.
+ If you nead a short command summary, simply type
+<tscreen><verb>
+ help
+</verb></tscreen>
+ However, it's highly recommended to have a printed copy of the
+ <tt>ddb(4)</tt> manual page ready for a debugging session.
+ Remember that it's hard to read the on-line manual while
+ single-stepping the kernel.
<sect><heading>Debugging a console driver</heading>
<p>Since you need a console driver to run DDB on, things are more
- complicated if the console driver itself is flakey. You might
- remember the <tt>options COMCONSOLE</tt> line, and hook up a standard
+ 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 <tt><bf>-h</bf></tt> at the <tt>Boot:</tt>
+ prompt), and hook up a standard
terminal onto your first serial port. DDB works on any configured
- console driver, of course it also works on a <tt>COMCONSOLE</tt>.
+ console driver, of course also on a serial console.
Index: handbook/memoryuse.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/memoryuse.sgml,v
retrieving revision 1.1.4.2
diff -u -r1.1.4.2 memoryuse.sgml
--- 1.1.4.2 1995/10/12 03:16:13
+++ memoryuse.sgml 1995/10/21 19:05:24
@@ -11,26 +11,26 @@
what 0-640K gets used for, does the kernel load there or higher,
is the kernel relocated, etc. Is there a paper on this?</em>
-The boot sector will be loaded at 0:0x7c00, and relocates itself
-immediately to 0x7c0:0. (This is nothing magic, just an adjustment
-for the %cs selector, done by an ljmp.)
+The boot sector will be loaded at <tt>0:0x7c00</tt>, and relocates itself
+immediately to <tt>0x7c0:0</tt>. (This is nothing magic, just an adjustment
+for the <tt>%cs</tt> selector, done by an <tt>ljmp</tt>.)
-It then loads the first 15 sectors at 0x10000 (segment BOOTSEG in the
-biosboot Makefile), and sets up the stack to work below 0x1fff0.
+It then loads the first 15 sectors at <tt>0x10000</tt> (segment BOOTSEG in the
+biosboot Makefile), and sets up the stack to work below <tt>0x1fff0</tt>.
After this, it jumps to the entry of boot2 within that code. I.e., it
jumps over itself and the (dummy) partition table, and it's going to
adjust the %cs selector---we are still in 16-bit mode there.
-boot2 asks for the boot file, and examines the a.out header. It masks
-the file entry point (usually 0xf0100000) by 0x00ffffff, and loads the
-file there. Hence the usual load point is 1 MB (0x00100000). During
+boot2 asks for the boot file, and examines the <tt>a.out</tt> header. It masks
+the file entry point (usually <tt>0xf0100000</tt>) by <tt>0x00ffffff</tt>, and loads the
+file there. Hence the usual load point is 1 MB (<tt>0x00100000</tt>). During
load, the boot code toggles back and forth between real and protected
mode, to use the BIOS in real mode.
-The boot code itself uses segment selectors 0x18 and 0x20 for %cs and
-%ds/%es in protected mode, and 0x28 to jump back into real mode. The
-kernel is finally started with %cs 0x08 and %ds/%es/%ss 0x10, which
-refer to dummy descriptors covering the whole address space.
+The boot code itself uses segment selectors <tt>0x18</tt> and <tt>0x20</tt> for <tt>%cs</tt> and
+<tt>%ds/%es</tt> in protected mode, and <tt>0x28</tt> to jump back into real mode. The
+kernel is finally started with <tt>%cs</tt> <tt>0x08</tt> and <tt>%ds/%es/%ss</tt> <tt>0x10</tt>, which
+refer to dummy descriptors covering the entire address space.
The kernel will be started at its load point. Since it's been linked
for another (high) address, it will have to execute PIC until the page
@@ -38,9 +38,6 @@
paging will be enabled and the kernel will finally run at the address
for which it was linked.
-The kernel still skips over the first 0x500 bytes of code, in the
-assumption this were valuable BIOS data space (back from old days
-where it has been loaded low).
<em>Contributed by &a.davidg;.<newline>
16 Apr 1995.</em>
@@ -48,7 +45,7 @@
The physical pages immediately following the kernel BSS contain
proc0's page directory, page tables, and upages. Some time later
when the VM system is initialized, the physical memory between
-0x1000-0x9ffff and the physical memory after the kernel
+<tt>0x1000-0x9ffff</tt> and the physical memory after the kernel
(text+data+bss+proc0 stuff+other misc) is made available in the
form of general VM pages and added to the global free page list.
Index: handbook/relnotes.sgml
===================================================================
RCS file: /home/cvs/src/share/doc/handbook/relnotes.sgml,v
retrieving revision 1.4.2.1
diff -u -r1.4.2.1 relnotes.sgml
--- 1.4.2.1 1995/10/12 03:16:30
+++ relnotes.sgml 1995/10/21 12:25:56
@@ -383,7 +383,7 @@
<tag>WD7000 driver</tag> Owner: Olof Johansson
(offe@ludd.luth.se)
- <tag>Pcvt Console driver</tag> Owner: Joerg Wunsch
+ <tag>Pcvt Console driver</tag> Owner: Jörg Wunsch
(joerg@FreeBSD.org)
Submitted by: Hellmuth Michaelis
--
cheers, J"org
joerg_wunsch@uriah.heep.sax.de -- http://www.sax.de/~joerg/ -- NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199510211929.UAA18548>