This document details how to build oskit-mach.

Copyright © 2001 Kevin Kreamer

This document is licensed under the GNU Free Documentation License.

This document details how to build oskit-mach.

Introduction
************

Mach is the microkernel currently used by the HURD.  Mach was a research project of Carnegie Mellon University from 1985 to 1994.  After CMU concluded work on Mach 3, the University of Utah's Flux Group took over and produced version 4 of Mach.  The GNU Project of the Free Software Foundation then took up maintainership, in the form of GNUmach.  This is the variant that HURD uses today.

OSKit is a collection of components along with a framework to lower the barrier of entry to operating system research.  Instead of spending months or years writing the boring infrastructure for your Really Cool OS Idea(tm), you simply use the parts you need from oskit and leave the rest.  OSKit currently runs on the StrongArm and Intel x86 platforms.

Roland McGrath, a HURD hacker and member of the Flux Group, decided to combine these two software packages to make oskit-mach as a personal project.  It has since become the primary development branch for HURD microkernel features (and bugfixes).  Once it stabilizes, it may well become the primary microkernel for the HURD project.

Audience
********

This document assumes you have just heard about oskit-mach on a HURD mailing list or elsewhere, and want to help debug it.  It assumes that you are building on a Linux system (primarily because building it there is faster than building on Hurd), with HURD mounted at /gnu.  While this document has a few Debian-specific commands, the majority of it should be useful for other systems as well.

This document should take you from only having the Hurd sources (no oskit or oskit-mach sources at all) to the point where oskit-mach begins to boot.  As far as getting it to successfully boot and run stable, that is why you are helping debug it :-)

Differences between GNUmach and OSKit-Mach
******************************************

This section is ripped pretty much verbatim from Roland's oskit-mach announcement (http://mail.gnu.org/pipermail/bug-hurd/1999-November/003554.html).

What you get vs. GNUmach
========================

All the benefits of an oskit kernel:

  * Device drivers from Linux 2.2.12 (IDE, SCSI, floppy, and Ethernet) (GNUmach has Linux 2.0.36 drivers with a few fixes.)

  * Serial-port console support with a very simple minimal serial driver

  * OSKit-style Multiboot support, including return address hack for extra-speedy soft reboot when using oskit's Netboot

  * Serial-port GDB support for debugging the microkernel in style

  * The University of Utah might maintain the device drivers for you

A much smaller source tree!  The unpacked oskit-mach sources total about a quarter of the GNUmach sources (though the oskit itself is much larger of course).  The gzip'd tar file of the source tree is about 700k, vs 3.6MB for gnumach.  This is because Roland wiped out a bunch of the old cruft, as well as all the old device drivers and the Linux code.

What you lose vs. GNUmach
=========================

All the old device drivers are gone, so you only get what oskit has.  It would not be very hard to support some of the old drivers alongside the oskit drivers, but Roland is more interested in adding good new drivers to the oskit.

  * The PC screen/keyboard console driver is very minimal, and not compatible with the old Mach driver's terminal emulation.  The oskit's PC console emulates an adm3a terminal, and the keyboard input support is very simple.

  * No real serial drivers at all.  The serial drivers that provide the serial console and serial GDB are very minimal and not really generally usable serial drivers at all.  The oskit's freebsd serial driver might work, but the interface glue for features to serial ports (baud rate, modem control, etc) are not there.

  * No parallel (printer) port driver.  The oskit's freebsd printer driver might work, though.

  * No real drivers for PC keyboard or PS/2 mouse at all.  The oskit needs a good clean driver for the low-level keyboard access.

No DDB.  Roland ripped that out rather than making it work.  Serial GDB is much better anyway, but it may be useful at some point to resurrect some of DDB's code that prints out kernel data structures in comprehensible form.

Getting the source
******************

You can download the oskit from the University of Utah at ftp://flux.cs.utah.edu/flux/oskit/. If you want networking to work, get the 20000505 snapshot.  However, to be on the real bleeding edge, get the latest snapshot.

The newest oskit snapshot (20010214) requires a patch (ftp://flux.cs.utah.edu/flux/oskit/mail/html/oskit-users/msg01253.html) for oskit-mach to compile (your line numbers won't match):

Index: configure.in
===================================================================
RCS file: /usr/lsrc/flux/CVS/oskit/configure.in,v
retrieving revision 1.149
diff -b -u -r1.149 configure.in
--- configure.in   2001/03/09 19:17:58  1.149
+++ configure.in   2001/08/26 22:05:12
@@ -638,6 +638,12 @@
 [if test $enableval = yes; then enableval=300; fi]
 [OSKIT_DEFS="$OSKIT_DEFS -DLINUX_BOGOMIPS=$enableval"]
 [oskit_options="linux-bogomips=$enableval $oskit_options"])
+
+flux_ARG_ENABLE(indirect-osenv,
+[  --enable-indirect-osenv internal debugging features and sanity checks],
+[OSKIT_DEFS="$OSKIT_DEFS -DINDIRECT_OSENV=1"]
+[oskit_options="indirect_osenv $oskit_options"])
+

outfiles="$outfiles Makeconf GNUmakefile
unsupported/scripts/gcc-driver-script"
outfiles="$outfiles unsupported/scripts/sym-trace"

After applying this patch, be sure to make clean (or selectively remove the proper object files) before building oskit, because the automatic dependencies don't notice that this flag has changed.

You want to use CVS to get the latest oskit-mach sources.  To do so, issue the command cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/hurd co -d oskit-mach -r oskit-branch -P gnumach which puts the sources in a subdirectory of your current directory named oskit-mach.

OSKit-Mach also needs a couple patches (http://mail.gnu.org/pipermail/bug-hurd/2001-July/004654.html) for it to work optimally (again, your line numbers will not match):

Index: ds_osenv.c
===================================================================
RCS file: /cvsroot/hurd/gnumach/oskit/Attic/ds_osenv.c,v
retrieving revision 1.1.2.1
diff -u -r1.1.2.1 ds_osenv.c
--- ds_osenv.c  1999/11/25 23:27:06     1.1.2.1
+++ ds_osenv.c  2001/06/05 19:56:44
@@ -52,7 +52,6 @@
                                   oskit_create_osenv_intr (),
                                   oskit_create_osenv_sleep (),
                                   &ds_console_stream);
-      direct_cons_set_flags (DC_NO_ONLCR);
     }
   if (rc)
     panic ("cannot create interrupt-driven console stream: %x\n", rc);
Index: trap.c
===================================================================
RCS file: /cvsroot/hurd/gnumach/i386/i386/trap.c,v
retrieving revision 1.4.2.3
diff -u -r1.4.2.3 trap.c
--- trap.c      2001/04/05 06:52:46     1.4.2.3
+++ trap.c      2001/07/09 19:36:15
@@ -219,9 +219,7 @@
 #if 0
                printf("now %08x\n", subcode);
 #endif
-                       if (trunc_page(subcode) == 0
-                           || (subcode >= (int)_start
-                               && subcode < (int)etext)) {
+                       if (subcode >= (int)_start && subcode < (int)etext) {
                                printf("Kernel page fault at address 0x%x, "
                                       "eip = 0x%x\n",
                                       subcode, regs->eip);

The first one fixes some display problems and allows you to get a readable register dump if oskit-mach crashes.  The second avoids a panic in an oskit function when it tries to access address 0x104.  Also, if you get an error message saying undefined reference to cli you need to change cli(); to asm("cli"); on line 70 of i386/i386/pic.c in the oskit-mach sources.

MiG is required to build oskit-mach.  To get it (assuming a Debian system), issue apt-get install mig-1386-gnu.

At the moment, oskit-mach only builds successfully if your hurd source tree is ../hurd relative to oskit-mach's source tree.  Either move the sources into the correct place, or use a symlink to make it look as if you did.  In any case, this limitation will be removed in the near future.

Building OSKit
**************

To prevent the error message multiple definition of __libc_multiple_libcs, edit modules.x86.pc and comment out (put a # in front of) all the lines which start with unix or start with examples/unix.  This disables oskit-on-Unix functionality, but allows oskit compilation.

It is also highly recommended that you go through all the other options in modules.x86.pc to choose which items you want compiled into oskit.  If you are not sure what you want included, include just these items:

     boot/multiboot
     clientos
     com
     crt
     dev
     diskpart
     exec
     flask
     kern
     libc
     linux/dev
     lmm
     oskit
     posix/sys
     smp
     startup
     unsupported

These additional modules compile all the example kernels, which you may use to test oskit on your machine:

     bootp
     memdebug
     freebsd/dev
     netbsd/fs
     fsnamespace/fsn
     fsread
     memfs
     examples/x86

After getting the source in order, run ./configure --enable-debug --enable-indirect-osenv.  Enabling debugging support is recommended if you plan on debugging oskit-mach.  On the other hand, if you want it to Just Work(tm), perhaps you should wait a while before trying oskit-mach.

A simple make followed by a make install (as root, of course) builds and installs oskit.  By default, it is installed into /usr/local, but that can be changed via configure switches.

Building OSKit-Mach
*******************

Be sure to build oskit-mach in a different directory than the sources. A safe way to go is to mkdir build in the oskit-mach directory, and build there.  These instructions assume that you do.

The build system needs to be told where you installed oskit.  To do this, specify that value using the OSKIT_LIBDIR environment variable on the configure command line.  It also needs to know where MiG is located, which can be passed via the MIG environment variable.  For instance, if you took the defaults so far (i.e. oskit is installed into /usr/local, mig is installed via apt-get, and HURD is mounted under /gnu), you would want to issue MIG=i386-gnu-mig OSKIT_LIBDIR=/usr/local/lib/oskit CFLAGS=-g ../configure --prefix=/gnu to configure oskit-mach.  If OSKIT_LIBDIR is not set correctly, you will receive No rule to make target `kernel', needed by `all'.  If you are planning on skipping the make install step and just directly copying the kernel to its final location, you may leave off the --prefix=/gnu part of the configure line.

To build it, issue make.  make install installs it (again, as root).  The oskit-mach kernel should now be /boot/oskit-mach on your Hurd partition.  However, if you are interested only in the kernel and don't care about installing header files as well, you make skip the make install step as the kernel is in your build directory named kernel.  You may simply copy it to a bootable location, and boot it from there.

Booting OSKit-Mach
******************

To boot oskit-mach, you need a multiboot-compliant bootloader.  GRUB works fine.  To configure grub, simply add something like

     # For booting the GNU Hurd (experimental)
     title  GNU/Hurd Testing
     root   (hd0,4)
     kernel /boot/oskit-mach root=hd0s5
     module /boot/serverboot.gz

to your menu.lst, or type it into the grub command prompt after rebooting.  Either way, you should see Welcome to OSKit-Mach! scroll by when you boot that kernel.  The rest of the boot messages will be scattered across the screen; that is a known problem.

Assuming all of this worked successfully for you, you should be able to start debugging oskit-mach.  If you have a second machine with a couple of serial cables, the preferred method is remote debugging using GDB. That is outside the scope of this document, though; see http://www.multiverse.ca/hurd/oskit-boot.txt for a treatment of that topic.

Frequently Asked Questions
**************************

How do I make sure oskit supports my machine?
=============================================

Try the oskit example kernels.  After building the example kernels, move them to a bootable location, like /boot/oskit_example/.  You can then boot them using grub's command prompt.  Read grub's documentation for more details.

What's with oskit-mach's crazy build system?
============================================

Roland came up with it.  No, we don't know what he was thinking either :-)