This document was written for
A Tour through the NetBSD Documentation
Part III: Runoff Documentation
Hubert Feyrer, March 2001
In the first two parts on our tour through the documentation
that is available with NetBSD 1.5, we concentrated on the information
that is intended for online consumption, manual and info pages.
Besides that, there is also a number of papers and
introductions that are more suited for printing on paper.
The traditional format for documentation on Unix is the various
derivates processed by a "runoff" derived processor like nroff or
groff. There's a large collection of historic and current
documentation available in NetBSD. This section wants to give an
overview of the available documents and papers. To read any of them,
change to the named directory on your NetBSD 1.5 system, and type
"make paper.ps" to get a PostScript version that can either be
printed, or viewed online via Ghostscript or one of it's frontends
like ghostview or gv.
What Is Available
- Current Research by The Computer Systems Research Group of
Berkeley. After 4.3BSD was released in April 1986, this paper
documents work intended to be done for the next release.
Mostly of historical value. 6 pages.
- A machine-independent DMA framework for NetBSD. Describes why
a machine-independent DMA mapping abstraction is needed, what
design considerations one must make for these abstractions,
and how they were implemented on the i386 and alpha
port. Highly recommended for portable driver works!
- Performance effects of disk subsystem choices for VAX systems
running 4.2BSD Unix. Some benchmark methods and results from
the times when BSD Unix was in competition with DEC's VMS,
with some side notes on buffer caching and filesystem
parameters. 12 pages.
- Toward a compatible filesystem interface. How the BSD VFS
layer used today came to live, what predecessors it had and
what their properties were that went into the final proposal.
Documents the state at post-4.3BSD, but very interesting to
read not only for historic reasons. 15 pages.
- Design of a general purpose memory allocator for the 4.3BSD
Unix kernel. How many allocators were replaced with one that
was fast for small allocations and space efficient for big
ones. The allocator described in here is not in use any longer
in NetBSD, yet this paper gives some some interesting numbers
for anyone interested in operating system details. 11 pages.
- Using gprof to tune the 4.2BSD kernel. Shows how to build a
profiling kernel, how to obtain profiling data, and how to
interpret it using various gprof profiles. A tuning example
shows how to speed up name lookup by introducing the namei
cache which is still used in NetBSD today. 6 pages.
- A pageable memory based filesystem. Describes the mfs still
used in NetBSD today, and the ideas behind it's
implementation. Great reading if you are interested in
filesystem implementations and don't want to buy the 4.4BSD
book. 8 pages.
- A new virtual memory implementation for Berkeley
Unix. Describes the way virtual memory was handled in 4.3BSD,
it's drawbacks and the requirements for a replacement given
decreasing costs for disks and memory. This is superseded by
UVM now in NetBSD, it still makes an interesting reading to
see the areas that have impact on VM. 8 pages.
- Not quite NFS, soft cache consistency for NFS. Describes
and measures problems of NFS (v2) that lead to performance
problems, and how to solve them by using caching on the client
side, while still assuring consistency from the server
side. This is still available in mount_nfs(8) in NetBSD
today; the 4.4BSD book covers this, too. 18 pages.
- Berkeley Pascal PX implementation notes. Describes the
organisation of the 'px' interpreter that runs the Pascal
binaries generated by the 'pi' translator. Neither of these is
shipped in NetBSD, and interested Pascal users are
recommended to use more modern tools like p2c, available in
pkgsrc/lang/p2c. 25 pages.
- The release engineering of 4.3BSD. A description of an
approach how a small group of people can develop and integrate
a large software system like an operating system. Very
interesting reading even for today's Open Source
development. 5 pages.
- Measuring and improving the performance of Berkeley Unix.
This April 1991 goes into finding out the problems that the
4.2BSD release had, with identifying areas where things can be
improved or tuned through functional extensions. Also
addresses some security issues. 36 pages.
- Berkeley software architecture manual, 4.4BSD
edition. This text summarizes the interfaces provided by
4.4BSD. It starts with the process related interfaces, then
moves over to the file and filesystem and communication area.
A very interesting introduction for the advanced user and any
programmer that's interested in generic BSD APIs. Not
intended as introduction for beginners, though. 44 pages.
- An introduction to 4.4BSD interprocess communication
tutorial. This paper provides an introduction to IPC using
pipes, socketpairs, sockets as well as TCP and UDP based
communication that's based on small examples. Ideal if you
know a bit of C, and want to get into network programming.
- An advanced 4.4BSD interprocess communication tutorial. After
the previous tutorial showed how to do many things in small
examples, this text goes into more depth, covering all the
traps and pitfalls there are in the wide area of interprocess
communication and network programming. Covered topics are
client server architectures, handling of out of band data,
non-blocking sockets, and IP multicasting. 44 pages.
- Installing and operating 4.4BSD Unix. Superseded massively by
what's in /usr/distrib/notes on NetBSD today, this text still
gives a nice reading on how to install or upgrade to
4.4BSD. After describing how to setup the basic system, it
goes into user management, setting up terminals and backing up
filesystems and other administrative tasks. Interesting to
see that the architectures supported by 4.4BSD - m68k powered
hp300s, sparc workstations, MIPS based DECstations were
available in binary, and more machines were supported in
source in 4.4BSD. All of them are available today in NetBSD!
- Disc quotas in a Unix environment. This short text gives an
overview of how quotas work from the user and admin side, it
also contains a few words about the
implementation. Recommended reading for new Unix users that
are often found not to know about the various limits that
quotas provide in Unix. 3 pages.
- A fast file system for Unix. This paper gives an overview of
the FFS still in use on NetBSD today; it addresses the
physical layout with the two block sizes that allow high
throughput while not wasting disk space through
fragments. After more details on the physical disk layout
policies, performance is compared against the 'old' Unix File
System. The text then goes into the filesystem's API,
describing long file names, symlinks, quotas etc. 14 pages.
- The 4.4BSD NFS implementation. With the Network File System
being derived from BSD Unix by Sun in their (then) SunOS
operating system, this text describes the implementation of
NFS that conforms to the original Sun specs, plus the NQNFS
extensions to increase performance. 15 pages.
- Networking implementation notes. If you want to get a detailed
description of the internal structure of the networking code
in 4.4BSD, have a look at this. Addressed topics are internal
address representation, the various internal software layers
and their interfaces, routing issues, buffering and congestion
control. Many of the details were changed since the TCP/IP
protocol suite became popular, but the basic concepts are
still present in NetBSD. 26 pages.
- /usr/share/doc/psd/18.gprof (src/usr.bin/gprof/PSD.doc):
- gprof: A call graph execution profiler, documents the ideas
behind gathering data from a running program or kernel, and
the various ways to evaluate it, using call graphs and various
types of profiles. Gives lots of background to profiling.
- /usr/share/doc/psd/19.curses (src/lib/libcurses/PSD.doc):
- Screen updating and cursor movement optimizations: shows how
to use the curses library, documents all the calls and
variables available for users. Read this if you want to use
the Curses library!
(c) Copyright 20000110 Hubert Feyrer
$Id: nbdocsIII.html,v 1.2 2001/03/16 11:04:09 feyrer Exp $