kernel -- Technical Information

Master program of the COHERENT system

The kernel  is the master program  of the COHERENT system.   It manages the
file systems, processes, devices, and users.

When you boot COHERENT on your system, the COHERENT bootstrap automatically
loads and  runs the program /autoboot.  This file usually is  linked to the
kernel that you build when you installed COHERENT onto your computer.

Your system may have multiple kernels  on it.  For example, when you update
COHERENT, often the old kernel is  saved; and you can also build customized
versions  of  the  kernel.  The  COHERENT  bootstrap  lets  you boot  other
versions of  the kernel besides the  one that is linked  to file /autoboot.
For details on how to do this, see the Lexicon article booting.

For  information on  the  file system  that  the kernel  supports, see  the
Lexicon entry for file.

The Lexicon  entry coff.h describes the format of  programs that the kernel
can execute.

The COHERENT  system comes with a  set of system calls,  which you can call
from within  user application to  obtain kernel services.   See the Lexicon
entry libc summarizes the calls that the kernel offers.

The function ulimit() returns and sets some limits for the current process.
For details, see its entry in the Lexicon.

The Lexicon article device drivers describes the suite of drivers that come
with the  COHERENT system.  It gives  the major and minor  numbers of each,
plus information on how to access and manipulate each driver.

Modifying the Kernel

Beginning with  release 4.2, COHERENT  contains a System  V-style mechanism
for modifying the kernel and building a new bootable kernel.

File /etc/conf/mtune  defines the suite of  ``tunable variables'' available
within  the kernel  and its  drivers.  These variables  define many  of the
kernel's default  behaviors.  For  a complete  list of these  variables and
notes on what each does, see /etc/conf/mtune.

File /etc/conf/stune sets the values of the variables actually used in your
kernel.  To  modify the  values of  these variable, you  can edit  stune by
hand,   or   you   can   use   the   commands   /etc/conf/bin/cohtune   and
/etc/conf/bin/idtune. The former command  lets you set or modify the values
of variables  used by device  drivers; the latter  command lets you  set or
modify variables used in the kernel itself.

File /etc/conf/mdevice  names the drivers that  are available for inclusion
in your kernel.  File /etc/conf/sdevice names the drivers that actually are
included in  your kernel.  To include  or exclude a driver,  you can modify
sdevice by hand; or you can use the command /etc/conf/bin/idenable.

Command   /etc/conf/bin/idmkcoh   builds  a   new   bootable  kernel   that
incorporates  any  changes  you have  made.   For  your  changes to  become
effective, you must build a  new kernel that incorporates your changes, and
then boot it.

Finally, command  /etc/conf/bin/idbld walks you the  configuration of every
device drivers  in the kernel, then  invokes idmkcoh to link  a new kernel.
In effect, this command lets you reconfigure the entire kernel.

Each of the above commands and files is described in its own Lexicon entry.

Two other files are of interest if you wish to modify the kernel.

-> Header  file <sys/devices.h>  gives the  major-device  numbers for
   every driver in your kernel.  It  is read when drivers are compiled.  If
   you are  adding a  new driver,  you must add  its name  and major-device
   number to this header file.

-> Normally, when you build a new kernel, the symbol table is stripped from
   it and kept in file /kernel_name.sym.  The symbols in this file are used
   to  decipher kernel  tracebacks, and  can  be read  by the  debugger db.
   However, if  you wish  to hot-patch  a kernel variable,  that variable's
   symbol   (or  name)   must  be   kept  in   the  binary   itself.   File
   /etc/conf/install_conf/keeplist names the  variables (or, more properly,
   the symbols)  that are left in  the binary after it  is linked.  You can
   then  use the  command  /conf/patch to  hot-patch  these variables.   We
   discourage you from doing this unless it is absolutely necessary.

Example

The  Lexicon entry  device drivers  gives an  example of how  to add  a new
driver to the kernel.  The  following example walks you through the process
of changing the size of the buffer cache on your system.

The buffer cache is a reserved portion of memory in which the kernel stores
data recently  read from the disk  or to be written to  the disk.  When you
invoke  a command  from your  command  line, the  kernel checks  its buffer
cache.  If you had invoked the  command recently, the kernel should find it
within the  buffer cache; and it  can then call up  the command from memory
rather  than  reading  it  from  the  disk.  This  speeds  up  your  system
noticeably.

Like everything  else in  life, the buffer  cache involves a  tradeoff: the
larger the  buffer cache,  the faster  your system will  run, but  the less
memory will  be available for running your  programs.  By default, COHERENT
sets aside  a portion of memory  for the buffer cache;  the more memory you
have, the more  is set aside for the cache.   However, you can set the size
of  the cache by  hand.  Usually,  this is  done to limit  the size  of the
cache, which is necessary if your  system has limited amounts of memory and
you want to run large user programs (e.g., the X Window System).

The  following walks  you through  the process of  modifying the  kernel to
reduce the size of the buffer cache.

1. Log in as the superuser root. cd to directory /etc/conf.

2. Edit file /etc/conf/stune and add the following lines:

       NBUF_SPEC   100
       NHASH_SPEC  97

   NBUF_SPEC sets  the size of the buffer, in  blocks.  Here, we're setting
   it to  100 blocks (50  kilobytes), which is very  small.  NASH_SPEC sets
   the number  of hash lists  in the kernel;  this must be  the first prime
   number smaller  than the number  of blocks in  the cache (in  this case,
   97).  This, too, is very small.

3. Build a new kernel with the following command:

       /etc/conf/bin/idmkcoh -o /cohtest

   This builds a new kernel named cohtest, which incorporates your changes.

4. Shut down your  system and boot the new kernel.   For information on how
   to shut the system down, see the Lexicon entry for shutdown. For details
   on how to  boot a kernel other than the  default kernel, see the Lexicon
   entry for booting.

That's all there is to it.   If you wish to make these variables patchable,
so  you can  change them  without  going to  the bother  of building  a new
kernel, do the following:

1. In the file /etc/conf/install_conf/keeplist, change

       echo '-I SHMMNI:SEMMNI:NMSQID'
   to

       echo '-I SHMMNI:SEMMNI:NMSQID:NBUF:NHASH'

2. Build a new kernel as described above.

Then, to change limit the size of the buffer cache to 50 kilobytes, use the
command:

    /conf/patch /testcoh NBUF=100 NHASH=97

Then,  boot  the  patched kernel.   As  noted  above,  you  should not  use
/conf/patch unless you absolutely must.

Files

/autoboot -- The default kernel
/etc/conf -- Directory that holds configuration files
/etc/conf/mdevices -- Suite of available device drivers
/etc/conf/mtune -- Suite of legal patchable variables
/etc/conf/sdevices -- Drivers included in kernel
/etc/conf/stune -- Patchable variables included in kernel
/etc/conf/install_conf/keeplist -- Symbols kept in kernel

See Also

Administering COHERENT,
booting,
coff.h,
COHERENT,
device drivers,
file,
idmkcoh,
libc,
mtune,
stune,
ulimit()

Diagnostics

The kernel  can produce the following error  messages.  Most are meaningful
only to Mark Williams Company.   If you encounter these errors, contact MWC
and describe the circumstances during which you saw the error.  MWC Support
will try to solve this problem for you.

Arena number too small (hardware)

Bad block number (alloc) (hardware)
     The kernel attempted to allocate a  block of memory, only to find that
     there was something physically wrong with it.

Bad block number (free) (hardware)
     The kernel  attempted to  free a  block of memory,  only to  find that
     there was something physically wrong with it.

Bad free number (hardware)

Bad freelist (halt)
     The  freelist is  a list  of free  blocks on  the disk.   The COHERENT
     system maintains  this list so it  can see where it  can write data on
     the disk.  This message indicates that the freelist has been corrupted
     somehow.  To fix this  problem, run /etc/shutdown to return to single-
     use mode;  use sync to  flush the buffers;  use umount to  unmount the
     affected file system; and then run fsck to repair the file system.

Bad segment count (hardware)
Bus error at number (hardware)
Cannot allocate stack (hardware)
Cannot create process (hardware)
Corrupt arena (hardware)
Illegal instruction at number (hardware)
Inode number busy (hardware)
Inode table overflow (hardware)
Not a separate I/D machine (hardware)

Out of i-nodes (halt)
     A COHERENT file system has one i-node for each file it maintains.  The
     number of i-nodes is set when the file system is created.  If you have
     numerous small files on a file  system, it is possible to exhaust that
     file system's  resources even though  the command df  shows that space
     remains  on the  file system.   To get around  this problem,  you must
     delete files, one  file for each i-node needed; or  you must use ar to
     archive  a mass  of files.   To  do this,  first use  /etc/shutdown to
     return  the system  to single-user mode,  as described  above.  Delete
     files,  or use  ar as  described above.   Then use  sync to  flush all
     buffers,  and use  the  command umount  to unmount  the affected  file
     system.  Then  run fsck on the affected  file system before rebooting.
     fsck  checks  COHERENT  file  systems  and  fixes them  if  necessary.
     Consult the Lexicon entry on fsck  before you use this program for the
     first time.

Out of space (m,n) (halt)
     When this  error message appears,  your file system  still has i-nodes
     but the alloted disk space has  been exhausted; perhaps you have a few
     large  files  that are  eating  up  disk space.   To  get around  this
     problem, you  must delete  or compress files  to clear up  disk space.
     First, use  /etc/shutdown to return to  single-user mode, as described
     above; then  delete files  or compress  them as described  above until
     enough space has been cleared to allow you to continue your work.  Use
     sync to flush buffer, use  umount to unmount the affected file system,
     and run fsck on the affected file system.  Then reboot.

Random trap (hardware)
Raw I/O from non user (hardware)
System too large (hardware)

© 2012 by Stephen A. Ness