User Mode Linux (2.6)

User Model Linux (UML) is a project that aims to run a linux machine as an executable inside a real linux machine. The project home page is at http://user-mode-linux.sourceforge.net, where aboundant documentation and software can be found.
This page describes how to setup a UML and how to use it to test your drivers, and kernel code.
Step by step build
  1. The User Mode Linux kernel is included in the official kernel sources (at least as of 2.6). Download the kernel, uncompress it, and rename the directory to avoid messing up with the other source trees. I named it "linux-2.6.3-um" ("um" stands for User Mode).
  2. Check the UML website if you need to download and apply patches to your kernel.
  3. From the UML homepage download one or more root files. I got that based on Debian-3.0r0 (type ext2) and that of Slackware 8.1 (also type ext2).
  4. Still from the UML homepage get the UML utility applications
  5. cd to the kernel source directory and do the usual "make menuconfig", or whatever is your favourite configuration process.
  6. Build the kernel, > make ARCH=um linux
  7. Build the modules, > make ARCH=um modules Do not install them: you need a root file where to put them
  8. Mount your root file, for example > mount -t ext2 -o loop Debian-3.0r0.ext2 /mnt/uml and install the modules there, > make ARCH=um INSTALL_MOD_PATH=/mnt/uml modules_install. Unmount the root file and "e2fsck" it.
  9. Now you can start the user-mode linux, > ./linux ubd0=Debian-3.0r0.ext2 mem=48M. The console will remain on the xterm where you issued the command. Two additional virtual consoles will be fired up in two new xterms. You can log in the system in any of them (user "root", no password).

Creating your drivers
  1. First a little bit of planning: i created a directory drivers that contains the drivers' subdirectory. In the top drivers directory i have a master Makefile. A few things are necessary in the makefile. It must say to the compiler to include the kernel header files as system headers before the usual ones. The compilation must use the kernel makefiles. A samples makefiles are provided in exercise [1] below.
  2. Write your driver. For example "hello world", the ancestor of all programs. The makefile in the driver subdirectory is very simple. It must contain the list of objects that make the module and the instruction to clean up everything.
  3. Compile the driver and put it in the root file. To compile go to the drivers directory and type > make. Then mount the root file, copy the driver hello.ko somewhere there, and umount the root file.
  4. Now start User-Mode linux, login as "root" and try to > insmod hello.ho and > rmmod hello.ko.

N.B. If you use the kernel 2.6 the root file downloaded from UML website might have the wrong module util programs. Dowmload the module-init-tools from the kernel website, compile them and install them in the root file. To do this mount the root file, and configure the module-init-tools with --prefix set to the mount point.

Debugging User Mode Linux is great because it lets you run a linux kernel as a user program. It lets you experiment several features of the kernel. From a coder point of view, it let you easily debug the kernel and your modules.

  1. Start a User-Mode linux. One of the first lines it writes is tracing thread pid = 21865.
  2. Send a usr1 signal to the tracing thread, > kill -USR1 21865. This will start a new xterm with gdb in it.
  3. Now you can set breakpoints, continue until the code reaches one of them, examine variables, stepping through the code, and so on.

Exercise

The purpose of this exercise is to familiarize with the setup of UML and how to write modules for it.
  1. Create a drivers directory and the hello subdirectory in it.
  2. Create the master makefile, in drivers and the makefile in hello. Here are the two, drivers/Makefile, hello/Makefile.
  3. Create the famous "hello world" module. Here is it, hello.c.
  4. Now compile the module, put it in the root file, and try it in the User-Mode linux.


Marco Corvi - 2004