Subject: RFC: /kern/summary
To: None <>
From: Brian C. Grayson <>
List: tech-kern
Date: 03/09/1999 14:18:21
  I got no negative responses to my query regarding /kern files,
so I plan on adding a new file to /kern.  I've got some ideas,
but before I do too much work, I'd appreciate any helpful
opinions or suggestions.  I'm new to kernel stuff, so if I've
said something blatantly wrong here, please let me know.
Here's what I've thought up so far:

  /kern/summary (any better name ideas?)

  Purpose:  Provide numerous system statistics in a single file,
    allowing programs like top, systat, and xosview to grab an
    atomic snapshot of the state.  Hopefully, this will help
    reduce the number of recompiles of these programs when struct
    proc changes slightly.

  Format:  ASCII, and human-parseable without a man page.  In
    particular, each line will contain a single string like:


    with no whitespace around the '='.  This will allow one to
    write sh scripts like:

    source /kern/summary
    printf "%.2f%% of memory is free\n" \
      `echo $MemFreeBytes / $MemTotalBytes \* 100 | bc -l`

    C programs (top, systat, xosview) will need to parse these
    ``assignments.''  A function similar to a hashed getenv() may be
    provided to abstract this functionality away.  If desired, a
    raw version of this file could also be provided, with the
    possible lack of backwards compatibility whenever the format

    1.  The file should be meaningful without requiring a man
      page or other reference.  As an example of what I _don't_
      want to create, cat /proc/1/status, and tell me how many CPU
      seconds init has accumulated -- without peaking at the man
      page for mount_procfs and without using your finger to
      locate the nth number on the line.  :)

    2.  When possible, the kernel will provide values in bytes
      (unlike swapctl or vmmeter, which do blocks or pages, which
      then requires gunk to portably figure out the block->byte

    3.  The first five lines of this and any similarly-designed
      file will always provide the following variables (better
      variable name suggestions will be gladly accepted!):

      InfoMaxBytes:  an upper limit on the number of bytes
	contained in this file (valid until a new kernel is
	recompiled, that is, this will be conservative, and not
	just a strlen of the _current_ file contents).  This
	allows one to do a read() of this amount, and hopefully
	grab an atomic snapshot in a single syscall, rather
	than reading the first 1024 bytes of the file, then
	later reading the second 1024 bytes, leading to bogus
	values at the buffer boundary due to the change in stats
	between the two calls.
      MajorVersionNumber:  this format version number will only
	be changed when a variable is deleted from the file, or the
	interface changes in a substantial way.
      MinorVersionNumber:  whenever a new variable is added
	(preferrably to the end of the file, but not guaranteed),
	the minor version is bumped.  This allows a high degree
	of backward compatibility, and early detection in the
	case that things aren't going to work (i.e. newer program
	requires a variable that an older kernel doesn't export).
      SnapTimeSecs and SnapTimeNanoSecs:  the time at which the
	kernel started to compile this information.

  My immediate goal is to get an experimental version of this
in the kernel (hopefully for 1.4) such that xosview can grab
all of its data through /kern/summary.  Longer-term goals
include adding a similar verbosely-formatted file to the /proc
file system so that ps and top can reconstruct all the
important information in a kinfo_proc from a single file
(currently, /proc does not provide enough information for full
ps functionality).  I have no idea on the timescale here.  If
things go swell and I have the free time, it could take only a

  At the end, we should have a ps, top, and xosview that, as an
option, use only /proc and /kern, and thus no longer need
recompilation very often at all.

  If you strongly believe that this is a Really Really Bad Idea,
please speak now, or forever hold your peace.  :)

  Happy hacking!
  Brian Grayson