Quick Start
============
    make config  (or make menuconfig, choosing all defaults will work)
    make isoimage
    qemu-system-x86_64 -cdrom arch/x86_64/boot/image.iso -serial stdio -smp 4

    What you should see:
        A bunch of kernel initialization messages print to the console,
        followed by:

            <6>Loading initial user-level task (init_task)...
            <8>(init_task) Hello, world!
            <8>(init_task) Arguments:
            <8>(init_task)   argv[0] = init_task
            <8>(init_task)   argv[1] = one
            <8>(init_task)   argv[2] = two
            <8>(init_task)   argv[3] = three
            <8>(init_task) Environment Variables:
            <8>(init_task)   envp[0] = one=1
            <8>(init_task)   envp[1] = two=2
            <8>(init_task)   envp[2] = three=3
            [... A bunch of test messages, omitted here]
            <8>(init_task) Spinning forever...
            <8>(init_task) main: Meow 0!
            <8>(init_task) main: Meow 1!
            <8>(init_task) main: Meow 2!
            <8>(init_task) main: Meow 3!
            <8>(init_task) main: Meow 4!
            <8>(init_task) main: Meow 5!
            <8>(init_task) main: Meow 6!
            <8>(init_task) main: Meow 7!
            <8>(init_task) main: Meow 8!
            <8>(init_task) main: Meow 9!
            <8>(init_task)    That's all, folks!

        The source code for the hello world init_task is at
        user/hello_world/hello_world.c
 
NOTE:
    If the hello_world output includes a bunch of errors like:

        [c0-0c1s7n2][init_task.thread_16] SYS_MMAP: ENOMEM (len=134217728, heap_brk=6f5000, mmap_brk=2650000)
        [c0-0c1s7n2][init_task.thread_16] SYS_MMAP: ENOMEM (len=67108864, heap_brk=6f5000, mmap_brk=2650000)

    It is likely due to Glibc's malloc implementation using per-thread
    arenas. This works fine on an OS that uses an allocate on first-touch
    memory allocation policy. On Kitten this is very wasteful because
    Kitten allocates all memory up-front at allocation time, even if
    it is never used/touched. To disable Glibc's per-thread arenas,
    set the following environment variable:

        MALLOC_ARENA_MAX=1

    This can be passed to the init_task via the Kitten boot command line:

        init_envp="MALLOC_ARENA_MAX=1"


Overview
========
    Kitten is a lightweight kernel (LWK) compute node operating system, 
    similar to previous LWKs such as SUNMOS, Puma, Cougar, and Catamount.
    Kitten distinguishes itself from these prior LWKs by providing a
    Linux-compatible user environment, a more modern and extendable codebase,
    and a virtual machine monitor capability via Palacios that allows
    full-featured guest operating systems to be loaded on-demand.


Supported Host (Build) Platforms
================================
    The Kitten kernel and user applications are compiled on a standard
    x86_64 (64-bit only, no 32-bit support) Linux host. The following
    distributions have been verified to work:

      * RedHat Enterprise Linux 7 (RHEL 7)
          Must install glibc-static and syslinux packages
      * Fedora Core 15
          Must install glibc-static and syslinux packages
          Known Issue: The "mktemp is dangerous" link warnings can be ignored
      * RedHat Enterprise Linux 6 (RHEL 6)
          Must install glibc-static, syslinux, and syslinux-devel packages
          Known Issue: The "mktemp is dangerous" link warnings can be ignored
      * Ubuntu 10.10
      * RedHat Enterprise Linux 5 (RHEL 5)


Supported Target (Execution) Platforms
======================================
    The Kitten kernel should boot on any x86_64 PC-compatible system.
    By default, console output is to both the VGA device and COM1 serial port.
    The following platforms have been verified to work:

      Emulators:
        * qemu-system-x86_64
        * kvm (running on a 64-bit x86 system)
        * virtualbox (with a bit of configuration, be sure to enable IO APIC)

      Real Hardware:
        * HP ProLiant BL460c G6 BladeSystem with dual-socket quad-core
          Intel Xeon X5570, 24 GB RAM, no disk
        * HP ProLiant BL465c G7 BladeSystem with dual-socket 12-core
          AMD Opteron 6172, 32 GB RAM, no disk
        * Cray XT4 compute nodes with single-socket quad-core AMD Opteron 1354,
          8 GB RAM, SeaStar 2.1 network interface, no disk


Instructions for Booting on Real Hardware
=========================================
    PC-compatible hardware:
        Do 'make config' and choose:
            System Architecture ---> PC-compatible (the default)
        Rebuild, and use the following files:
            kernel image: ./arch/x86_64/boot/bzImage
            initrd:       ./init_task
        In order to see any output a console must be specified via the
        console parameter on the kernel boot command line.  Examples:
            console=vga
            console=serial
            console=vga,serial
            console=serial serial.port=0x2f8 serial.baud=9600

    Cray XE and XK hardware:
        Do 'make config' and choose:
            System Architecture ---> Cray XE and XK systems
        Rebuild, and then use the following files:
            kernel image: ./vmlwk.bin
            initrd:       ./init_task
        Pass the following kernel command line to setup the console:
            console=serial serial.baud=115200


Instructions for Building with Palacios VMM Support
===================================================
    Palacios is a virtual machine monitor (VMM) being developed by the V3VEE
    project (http://v3vee.org). Palacios is distributed and built separately
    from Kitten, but can be linked with Kitten as part of the normal Kitten
    build process. The Kitten+Palacios combination allows full guest operating
    system images to be launched and managed similarly to native Kitten tasks.

    Installation Steps:

    1. Download the latest Kitten and Palacios releases:
           http://software.sandia.gov/trac/kitten
           http://www.v3vee.org/download

    2. Unpack them into the same directory:
           > cd where-id-like-to-build
           > tar xzvf downloaded-file-location/palacios.tar.gz
           > tar xzvf downloaded-file-locaiton/kitten.tar.gz

    3. Build Palacios:
           > cd palacios
           > make config (or make menuconfig, choosing all defaults will work)
           > make
           > cd ..

    4. Configure Kitten to link with Palacios:
           > cd kitten
           > make config (or make menuconfig, choosing all defaults will work)

             Answer 'Y' when prompted for:
               "Include Palacios virtual machine monitor:"

             Specify "../palacios" when prompted for:
               "Path to pre-built Palacios tree: "

             Specify the path to the guest image to boot when prompted for:
               "Path to guest OS image:"

             NOTE: Palacios previously booted an ISO image directly. It now
                   boots a custom image format that consists of an XML header
                   describing the virtual hardware environment, followed by
                   an ISO image of the guest OS to boot. Instructions for
                   building this image are provided in the Palacios Deverloper
                   Manual available at http://www.v3vee.org/palacios. After an
                   image has been built, the Kitten "Path to guest OS image: "
                   config option should be set to the path of the image.

    5. Build Kitten
           > make isoimage

             If successful, a bootable ISO image will be located at:
                kitten/arch/x86_64/boot/image.iso

             This requires the "syslinux" package to create a bootable ISO
             image. Most Linux distributions include a syslinux package, but
             it is usually not part of the standard install.

    6. Boot the resulting image:
           > qemu-system-x86_64 -cdrom kitten/arch/x86_64/boot/image.iso -m 1024 -serial stdio -smp 4

             By default the guest OS's console is output to the VGA device and
             Kitten's console is output to the serial port.

             If booting Puppy Linux, type "puppy acpi=off pfix=nox" at the
             boot prompt. This turns ACPI off and disables X windows.

             Instructions for booting on real hardware are given above.