A Tour through the NetBSD Documentation, Part III

This document was written for Daemonnews.

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.

Runoff Documentation

What Is Available

/usr/src/share/doc/papers/beyond4.3:: 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.
/usr/src/share/doc/papers/bus_dma:: 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! 12 pages.
/usr/src/share/doc/papers/diskperf:: 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.
/usr/src/share/doc/papers/fsinterface:: 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.
/usr/src/share/doc/papers/kernmalloc:: 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.
/usr/src/share/doc/papers/kerntune:: 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.
/usr/src/share/doc/papers/memfs:: 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.
/usr/src/share/doc/papers/newvm:: 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.
/usr/src/share/doc/papers/nqnfs:: 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.
/usr/src/share/doc/papers/px:: 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.
/usr/src/share/doc/papers/relengr:: 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.
/usr/src/share/doc/papers/sysperf:: 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.
/usr/share/doc/psd/05.sysman:: 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.
/usr/share/doc/psd/20.ipctut:: 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. 25 pages.
/usr/share/doc/psd/21.ipc:: 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.
/usr/share/doc/smm/01.setup:: 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! 60 pages.
/usr/share/doc/smm/04.quotas:: 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.
/usr/share/doc/smm/05.fastfs:: 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.
/usr/share/doc/smm/06.nfs:: 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.
/usr/share/doc/smm/18.net:: 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!