KevinKreamer 2001Kevin Kreamer This document is licensed under the GNU Free Documentation License. $Id: oskit-mach.sgml,v 1.10 2001/09/01 20:47:01 kkreamer Exp $ This document details how to build oskit-mach. 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, 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. 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 systemprimarily 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 :-) This section is ripped pretty much verbatim from Roland's oskit-mach announcement . 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. 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. It might be useful at some point to resurrect some of DDB's code that prints out kernel data structures in comprehensible form. You can download the oskit from the University of Utah at . 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 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 cleanor 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. MiG is required to build oskit-mach. To get itassuming 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. 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. Unless you know what you are doing, include just these modules: boot/multiboot clientos com crt dev diskpart exec flask kern libc linux/dev lmm oskit posix/sys smp unsupported After getting the source in order, run ./configure --enable-debug. Enabling debugging support is recommended if you plan on debugging oskit-mach. On the other hand, if you want it to Just Work, perhaps you should wait a while before trying oskit-mach. A simple make followed by a make installas root, of course builds and installs oskit. By default, it is installed into /usr/local, but that can be changed via configure switches. 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'. 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. 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 for a treatment of that topic. How do I make sure oskit supports my machine? Use the oskit example kernels. The instructions above do not compile them, due to a conflict between the startup module (which the example kernels need) and oskit-mach. Realize that you'll need to build oskit twice in this case, once for the example kernels, and again for oskit-mach if the example kernels work. To build and try these kernels, follow these instructions. (FIXME: test these instructions) When building oskit, edit modules.x86.pc as shown above, but also include: startup examples/x86 examples/x86/extended examples/x86/smp Follow the rest of the instructions, and then move the compiled kernels to /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 :-)