freebsd-skq/sys/ufs/lfs
dg c8b0a7332c NOTE: libkvm, w, ps, 'top', and any other utility which depends on struct
proc or any VM system structure will have to be rebuilt!!!

Much needed overhaul of the VM system. Included in this first round of
changes:

1) Improved pager interfaces: init, alloc, dealloc, getpages, putpages,
   haspage, and sync operations are supported. The haspage interface now
   provides information about clusterability. All pager routines now take
   struct vm_object's instead of "pagers".

2) Improved data structures. In the previous paradigm, there is constant
   confusion caused by pagers being both a data structure ("allocate a
   pager") and a collection of routines. The idea of a pager structure has
   escentially been eliminated. Objects now have types, and this type is
   used to index the appropriate pager. In most cases, items in the pager
   structure were duplicated in the object data structure and thus were
   unnecessary. In the few cases that remained, a un_pager structure union
   was created in the object to contain these items.

3) Because of the cleanup of #1 & #2, a lot of unnecessary layering can now
   be removed. For instance, vm_object_enter(), vm_object_lookup(),
   vm_object_remove(), and the associated object hash list were some of the
   things that were removed.

4) simple_lock's removed. Discussion with several people reveals that the
   SMP locking primitives used in the VM system aren't likely the mechanism
   that we'll be adopting. Even if it were, the locking that was in the code
   was very inadequate and would have to be mostly re-done anyway. The
   locking in a uni-processor kernel was a no-op but went a long way toward
   making the code difficult to read and debug.

5) Places that attempted to kludge-up the fact that we don't have kernel
   thread support have been fixed to reflect the reality that we are really
   dealing with processes, not threads. The VM system didn't have complete
   thread support, so the comments and mis-named routines were just wrong.
   We now use tsleep and wakeup directly in the lock routines, for instance.

6) Where appropriate, the pagers have been improved, especially in the
   pager_alloc routines. Most of the pager_allocs have been rewritten and
   are now faster and easier to maintain.

7) The pagedaemon pageout clustering algorithm has been rewritten and
   now tries harder to output an even number of pages before and after
   the requested page. This is sort of the reverse of the ideal pagein
   algorithm and should provide better overall performance.

8) Unnecessary (incorrect) casts to caddr_t in calls to tsleep & wakeup
   have been removed. Some other unnecessary casts have also been removed.

9) Some almost useless debugging code removed.

10) Terminology of shadow objects vs. backing objects straightened out.
    The fact that the vm_object data structure escentially had this
    backwards really confused things. The use of "shadow" and "backing
    object" throughout the code is now internally consistent and correct
    in the Mach terminology.

11) Several minor bug fixes, including one in the vm daemon that caused
    0 RSS objects to not get purged as intended.

12) A "default pager" has now been created which cleans up the transition
    of objects to the "swap" type. The previous checks throughout the code
    for swp->pg_data != NULL were really ugly. This change also provides
    the rudiments for future backing of "anonymous" memory by something
    other than the swap pager (via the vnode pager, for example), and it
    allows the decision about which of these pagers to use to be made
    dynamically (although will need some additional decision code to do
    this, of course).

13) (dyson) MAP_COPY has been deprecated and the corresponding "copy
    object" code has been removed. MAP_COPY was undocumented and non-
    standard. It was furthermore broken in several ways which caused its
    behavior to degrade to MAP_PRIVATE. Binaries that use MAP_COPY will
    continue to work correctly, but via the slightly different semantics
    of MAP_PRIVATE.

14) (dyson) Sharing maps have been removed. It's marginal usefulness in a
    threads design can be worked around in other ways. Both #12 and #13
    were done to simplify the code and improve readability and maintain-
    ability. (As were most all of these changes)

TODO:

1) Rewrite most of the vnode pager to use VOP_GETPAGES/PUTPAGES. Doing
   this will reduce the vnode pager to a mere fraction of its current size.

2) Rewrite vm_fault and the swap/vnode pagers to use the clustering
   information provided by the new haspage pager interface. This will
   substantially reduce the overhead by eliminating a large number of
   VOP_BMAP() calls. The VOP_BMAP() filesystem interface should be
   improved to provide both a "behind" and "ahead" indication of
   contiguousness.

3) Implement the extended features of pager_haspage in swap_pager_haspage().
   It currently just says 0 pages ahead/behind.

4) Re-implement the swap device (swstrategy) in a more elegant way, perhaps
   via a much more general mechanism that could also be used for disk
   striping of regular filesystems.

5) Do something to improve the architecture of vm_object_collapse(). The
   fact that it makes calls into the swap pager and knows too much about
   how the swap pager operates really bothers me. It also doesn't allow
   for collapsing of non-swap pager objects ("unnamed" objects backed by
   other pagers).
1995-07-13 08:48:48 +00:00
..
lfs_alloc.c Make vegetarian and animal rights people happy and use 0xdeadc0de instead 1995-04-16 11:25:47 +00:00
lfs_balloc.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_bio.c Cosmetics. make gcc less noisy. Still some way to go here. 1994-10-10 01:04:55 +00:00
lfs_cksum.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_debug.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_extern.h Add and move declarations to fix all of the warnings from `gcc -Wimplicit' 1995-03-28 07:58:53 +00:00
lfs_inode.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_segment.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_subr.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_syscalls.c Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
lfs_vfsops.c Removed redundant newlines that were in some panic strings. 1995-03-19 14:29:26 +00:00
lfs_vnops.c NOTE: libkvm, w, ps, 'top', and any other utility which depends on struct 1995-07-13 08:48:48 +00:00
lfs.h Remove trailing whitespace. 1995-05-30 08:16:23 +00:00
README
TODO

#	@(#)README	8.1 (Berkeley) 6/11/93

The file system is reasonably stable, but incomplete.  There are
places where cleaning performance can be improved dramatically (see
comments in lfs_syscalls.c).  For details on the implementation,
performance and why garbage collection always wins, see Dr. Margo
Seltzer's thesis available for anonymous ftp from toe.cs.berkeley.edu,
in the directory pub/personal/margo/thesis.ps.Z, or the January 1993
USENIX paper.

Missing Functionality:
	Multiple block sizes and/or fragments are not yet implemented.

----------
The disk is laid out in segments.  The first segment starts 8K into the
disk (the first 8K is used for boot information).  Each segment is composed
of the following:

	An optional super block
	One or more groups of:
		segment summary
		0 or more data blocks
		0 or more inode blocks

The segment summary and inode/data blocks start after the super block (if
present), and grow toward the end of the segment.

	_______________________________________________
	|         |            |         |            |
	| summary | data/inode | summary | data/inode |
	|  block  |   blocks   |  block  |   blocks   | ...
	|_________|____________|_________|____________|

The data/inode blocks following a summary block are described by the
summary block.  In order to permit the segment to be written in any order
and in a forward direction only, a checksum is calculated across the
blocks described by the summary.  Additionally, the summary is checksummed
and timestamped.  Both of these are intended for recovery; the former is
to make it easy to determine that it *is* a summary block and the latter
is to make it easy to determine when recovery is finished for partially
written segments.  These checksums are also used by the cleaner.

	Summary block (detail)
	________________
	| sum cksum    |
	| data cksum   |
	| next segment |
	| timestamp    |
	| FINFO count  |
	| inode count  |
	| flags        |
	|______________|
	|   FINFO-1    | 0 or more file info structures, identifying the
	|     .        | blocks in the segment.
	|     .        |
	|     .        |
	|   FINFO-N    |
	|   inode-N    |
	|     .        |
	|     .        |
	|     .        | 0 or more inode daddr_t's, identifying the inode
	|   inode-1    | blocks in the segment.
	|______________|

Inode blocks are blocks of on-disk inodes in the same format as those in
the FFS.  However, spare[0] contains the inode number of the inode so we
can find a particular inode on a page.  They are packed page_size /
sizeof(inode) to a block.  Data blocks are exactly as in the FFS.  Both
inodes and data blocks move around the file system at will.

The file system is described by a super-block which is replicated and
occurs as the first block of the first and other segments.  (The maximum
number of super-blocks is MAXNUMSB).  Each super-block maintains a list
of the disk addresses of all the super-blocks.  The super-block maintains
a small amount of checkpoint information, essentially just enough to find
the inode for the IFILE (fs->lfs_idaddr).

The IFILE is visible in the file system, as inode number IFILE_INUM.  It
contains information shared between the kernel and various user processes.

	Ifile (detail)
	________________
	| cleaner info | Cleaner information per file system.  (Page
	|              | granularity.)
	|______________|
	| segment      | Space available and last modified times per
	| usage table  | segment.  (Page granularity.)
	|______________|
	|   IFILE-1    | Per inode status information: current version #,
	|     .        | if currently allocated, last access time and
	|     .        | current disk address of containing inode block.
	|     .        | If current disk address is LFS_UNUSED_DADDR, the
	|   IFILE-N    | inode is not in use, and it's on the free list.
	|______________|


First Segment at Creation Time:
_____________________________________________________________
|        |       |         |       |       |       |       |
| 8K pad | Super | summary | inode | ifile | root  | l + f |
|        | block |         | block |       | dir   | dir   |
|________|_______|_________|_______|_______|_______|_______|
	  ^
           Segment starts here.

Some differences from the Sprite LFS implementation.

1. The LFS implementation placed the ifile metadata and the super block
   at fixed locations.  This implementation replicates the super block
   and puts each at a fixed location.  The checkpoint data is divided into
   two parts -- just enough information to find the IFILE is stored in
   two of the super blocks, although it is not toggled between them as in
   the Sprite implementation.  (This was deliberate, to avoid a single
   point of failure.)  The remaining checkpoint information is treated as
   a regular file, which means that the cleaner info, the segment usage
   table and the ifile meta-data are stored in normal log segments.
   (Tastes great, less filling...)

2. The segment layout is radically different in Sprite; this implementation
   uses something a lot like network framing, where data/inode blocks are
   written asynchronously, and a checksum is used to validate any set of
   summary and data/inode blocks.  Sprite writes summary blocks synchronously
   after the data/inode blocks have been written and the existence of the
   summary block validates the data/inode blocks.  This permits us to write
   everything contiguously, even partial segments and their summaries, whereas
   Sprite is forced to seek (from the end of the data inode to the summary
   which lives at the end of the segment).  Additionally, writing the summary
   synchronously should cost about 1/2 a rotation per summary.

3. Sprite LFS distinguishes between different types of blocks in the segment.
   Other than inode blocks and data blocks, we don't.

4. Sprite LFS traverses the IFILE looking for free blocks.  We maintain a
   free list threaded through the IFILE entries.

5. The cleaner runs in user space, as opposed to kernel space.  It shares
   information with the kernel by reading/writing the IFILE and through
   cleaner specific system calls.