Site Home Page
The UML Wiki
UML Community Site
The UML roadmap
What it's good for
Case Studies
Kernel Capabilities
Downloading it
Running it
Compiling
Installation
Skas Mode
Incremental Patches
Test Suite
Host memory use
Building filesystems
Troubles
User Contributions
Related Links
The ToDo list
Projects
Diary
Thanks
Contacts
Tutorials
The HOWTO (html)
The HOWTO (text)
Host file access
Device inputs
Sharing filesystems
Creating filesystems
Resizing filesystems
Virtual Networking
Management Console
Kernel Debugging
UML Honeypots
gprof and gcov
Running X
Diagnosing problems
Configuration
Installing Slackware
Porting UML
IO memory emulation
UML on 2G/2G hosts
Adding a UML system call
Running nested UMLs
How you can help
Overview
Documentation
Utilities
Kernel bugs
Kernel projects
Screenshots
A virtual network
An X session
Transcripts
A login session
A debugging session
Slackware installation
Reference
Kernel switches
Slackware README
Papers
ALS 2000 paper (html)
ALS 2000 paper (TeX)
ALS 2000 slides
LCA 2001 slides
OLS 2001 paper (html)
OLS 2001 paper (TeX)
ALS 2001 paper (html)
ALS 2001 paper (TeX)
UML security (html)
LCA 2002 (html)
WVU 2002 (html)
Security Roundtable (html)
OLS 2002 slides
LWE 2005 slides
Fun and Games
Kernel Hangman
Disaster of the Month

The UML test suite

The UML test suite is a set of Perl scripts which I use as a regression test on new UML patches. It comprises a test harness, which organizes and runs the suite, and the suite itself, which is a directory hierarchy which groups similar tests.

The tests to be done during a particular test run are specified by the parent directory, if you want all of the tests in that directory to run, an individual test, or any combination of directories and files.

The tests are able to specify the properties of the UML in which they are to run. The test harness compiles and runs UMLs according to the test requirements, trying to minimize the number of builds and boots required to satisfy all of the tests' requirements.

The tests vary widely in what they test and how they work. The simplest ones run a command (which they may have compiled themselves) and check the return value. Others run gdb and make it step through a test program to check that breakpoints work correctly. These use an already-booted UML, and don't need any special setup of the UML.

In contrast, there are tests which have requirements of the UML. For example, the boot_filesystems test checks that a user-specified set of filesystems boots correctly. So, it requests an unbooted UML for its use, but puts no more requirements on it. Others test various configurable options, and request a UML with certain options enabled, which they boot.

Finally, there are tests which stress the kernel generally in order to make sure that it is stable under a hard workload. The kbuild test, which runs a kernel build, is an example of this.
Why you should run it

The main reason would be to do a sanity-check on UML when compiled locally, with whatever unusual config options you favor, and run on your hardware. UML is somewhat sensitive to toolchain changes, and, to a less extent, to the host hardware. Users regularly shake out bugs that don't appear during development, and these are often exposed by different toolchains and hardware.

Secondly, if UML fails mysteriously somehow, a test may exercise the same bug. In this case, the test is likely to be much more specific than your workload, and the search for the bug much more constrained.

It would also be a help to the UML project in general to have the tests run as often as possible, and on as a great a variety of hosts as possible. This will expose bugs, and get them fixed, more quickly.

How to run it
First, download the latest version from the test suite section of the UML download page.
host% wget http://www.user-mode-linux.org/mirror/uml_tests_20040726.tar.bz2
Uncompress and extract it
host% bunzip2 uml_tests_20040726.tar.bz2
host% tar xf uml_tests_20040726.tar
Set up a ~/.umltest, which is the config file needed to tell the harness about the external resources, such as filesystems, and other information it will need in order to run. The file contains a perl hash, with different types of information under different keys. If you don't know perl, don't panic, because the syntax is simple enough. Mine looks like this:
                
{
    kernel_pool => "/home/jdike/linux/2.4/um",
    uml => {
        ubd => { 0 => "/home/jdike/roots/debian_22" },
        mem => "64M",
        cow_ubds => 1,
        prompts => { "/home/jdike/roots/debian_22" => "usermode:.*#" },
    },
    tests => { "filesystems/boot_filesystems" => 
               { filesystems => [ "/home/jdike/roots/debian_22" ],
                 time => 0
               },
               "stress/kbuild" => 
               { kernel_pool => "/home/jdike/roots/kernel",
                 time => 0 },
    },
}

              
The kernel_pool tells the harness the location of a UML source pool. This will be where it builds whatever UMLs it needs.

The uml section specifies the default UML command. This will be used for any tests which don't have special requirements. The ubd hash within that is a mapping of device numbers to files, and this one will turn into "ubd0=/home/jdike/roots/debian_22" on the command line. The prompts hash specifies a regular expression which matches the shell prompts for the filesystems that will be booted.

The tests section provides test-specific information. The keys here are the filenames of the tests under the tests/ directory, and without the ".pl" extension. They can ask for arbitrary information here. I specify one filesystem for the boot_filesystems test to boot, and an image of a filesystem containing a kernel source tree for the kernel build test.

Now, the tests can be run as follows

host% perl test.pl
This will run the full test suite, reporting an overall status when it's done. A full log of the run will appear in tests.log. This will contain all output from the UMLs, including boot logs and anything the tests do.

Specific tests can be run by adding them to the command line

perl test.pl stress/kbuild
Adding a directory to the command line will cause all of the tests within the that directory to be run. So,
perl test.pl functional
will run all the tests under functional/, but nothing else.
How to add tests
The tests are all under the "tests" directory, each in a separate perl file. Here is a very simple test, commented:
                
# Virtually all tests will need these two modules.  The first defines
# the Test object, an instance of which is returned from here.  The
# second is a library of useful utilities which essentially all of the
# tests use.
use UML::Test;
use UML::Testlib;

# strict is good
use strict;

# This function is the actual test.  It will be run inside a booted
# UML, at the shell.  run_exit_0 is from TestLib.  It runs the dd
# command within the UML object given to the test, returning if the
# command had an exit status of 0, and dying if not.  In this case,
# the harness will trap that and report the failure.
sub run {
    my $test = shift;
    my $uml = shift;

    run_exit_0($uml, "dd if=/dev/mem of=/dev/null");
}

# This constructs the Test object and returns it.  This specifies that
# this test be run in a booted UML (state => "up") and that the test
# is contained in the 'run' function.
UML::Test->new(state => "up", run => \&run);

              
This illustrates the two essential features of a test
  • The function which executes the actual test
  • The construction of the test object, which specifies the test function and any requirements that the test makes on the UML.
The test can also request an unbooted UML with 'state => "up"', if the purpose of the test is to check that UML boots. It can also request a UML with special configuration options. The initrd test does this like so:
                
UML::Test->new(state => "up", 
               run => \&run, 
               kconfig => { MMAPPER => "y" },
               config => { "uml/iomem" => "mmapper,$file" } );

              
The kconfig option requests that it be given a UML with CONFIG_MMAPPER set to "y", and the config option adds 'iomem=mmapper,$file' to the UML command line.
Hosted at SourceForge Logo