lguest: documentation I: Preparation

#! /bin/sh

set -e

PREFIX=$1

shift

trap 'rm -r $TMPDIR' 0

TMPDIR=`mktemp -d`

exec 3>/dev/null

for f; do

    while IFS="

" read -r LINE; do

	case "$LINE" in

	    *$PREFIX:[0-9]*:\**)

		NUM=`echo "$LINE" | sed "s/.*$PREFIX:\([0-9]*\).*/\1/"`

		if [ -f $TMPDIR/$NUM ]; then

		    echo "$TMPDIR/$NUM already exits prior to $f"

		    exit 1

		fi

		exec 3>>$TMPDIR/$NUM

		echo $f | sed 's,\.\./,,g' > $TMPDIR/.$NUM

		/bin/echo "$LINE" | sed -e "s/$PREFIX:[0-9]*//" -e "s/:\*/*/" >&3

		;;

	    *$PREFIX:[0-9]*)

		NUM=`echo "$LINE" | sed "s/.*$PREFIX:\([0-9]*\).*/\1/"`

		if [ -f $TMPDIR/$NUM ]; then

		    echo "$TMPDIR/$NUM already exits prior to $f"

		    exit 1

		fi

		exec 3>>$TMPDIR/$NUM

		echo $f | sed 's,\.\./,,g' > $TMPDIR/.$NUM

		/bin/echo "$LINE" | sed "s/$PREFIX:[0-9]*//" >&3

		;;

	    *:\**)

		/bin/echo "$LINE" | sed -e "s/:\*/*/" -e "s,/\*\*/,," >&3

		echo >&3

		exec 3>/dev/null

		;;

	    *)

		/bin/echo "$LINE" >&3

		;;

	esac

    done < $f

    echo >&3

    exec 3>/dev/null

done

LASTFILE=""

for f in $TMPDIR/*; do

    if [ "$LASTFILE" != $(cat $TMPDIR/.$(basename $f) ) ]; then

	LASTFILE=$(cat $TMPDIR/.$(basename $f) )

	echo "[ $LASTFILE ]"

    fi

    cat $f

done

/* Simple program to layout "physical" memory for new lguest guest.

 * Linked high to avoid likely physical memory.  */

/*P:100 This is the Launcher code, a simple program which lays out the

 * "physical" memory for the new Guest by mapping the kernel image and the

 * virtual devices, then reads repeatedly from /dev/lguest to run the Guest.

 *

 * The only trick: the Makefile links it at a high address so it will be clear

 * of the guest memory region.  It means that each Guest cannot have more than

 * about 2.5G of memory on a normally configured Host. :*/

#define _LARGEFILE64_SOURCE

#define _GNU_SOURCE

#include <stdio.h>

obj-$(CONFIG_LGUEST)	+= lg.o

lg-y := core.o hypercalls.o page_tables.o interrupts_and_traps.o \

	segments.o io.o lguest_user.o switcher.o

Preparation Preparation!: PREFIX=P

Guest: PREFIX=G

Drivers: PREFIX=D

Launcher: PREFIX=L

Host: PREFIX=H

Switcher: PREFIX=S

Mastery: PREFIX=M

Beer:

	@for f in Preparation Guest Drivers Launcher Host Switcher Mastery; do echo "{==- $$f -==}"; make -s $$f; done; echo "{==-==}"

Preparation Preparation! Guest Drivers Launcher Host Switcher Mastery:

	@sh ../../Documentation/lguest/extract $(PREFIX) `find ../../* -name '*.[chS]' -wholename '*lguest*'`

Welcome, friend reader, to lguest.

Lguest is an adventure, with you, the reader, as Hero.  I can't think of many

5000-line projects which offer both such capability and glimpses of future

potential; it is an exciting time to be delving into the source!

But be warned; this is an arduous journey of several hours or more!  And as we

know, all true Heroes are driven by a Noble Goal.  Thus I offer a Beer (or

equivalent) to anyone I meet who has completed this documentation.

So get comfortable and keep your wits about you (both quick and humorous).

Along your way to the Noble Goal, you will also gain masterly insight into

lguest, and hypervisors and x86 virtualization in general.

Our Quest is in seven parts: (best read with C highlighting turned on)

I) Preparation

	- In which our potential hero is flown quickly over the landscape for a

	  taste of its scope.  Suitable for the armchair coders and other such

	  persons of faint constitution.

II) Guest

	- Where we encounter the first tantalising wisps of code, and come to

	  understand the details of the life of a Guest kernel.

III) Drivers

	- Whereby the Guest finds its voice and become useful, and our

	  understanding of the Guest is completed.

IV) Launcher

	- Where we trace back to the creation of the Guest, and thus begin our

	  understanding of the Host.

V) Host

	- Where we master the Host code, through a long and tortuous journey.

	  Indeed, it is here that our hero is tested in the Bit of Despair.

VI) Switcher

	- Where our understanding of the intertwined nature of Guests and Hosts

	  is completed.

VII) Mastery

	- Where our fully fledged hero grapples with the Great Question:

	  "What next?"

make Preparation!

Rusty Russell.

/* World's simplest hypervisor, to test paravirt_ops and show

 * unbelievers that virtualization is the future.  Plus, it's fun! */

/*P:400 This contains run_guest() which actually calls into the Host<->Guest

 * Switcher and analyzes the return, such as determining if the Guest wants the

 * Host to do something.  This file also contains useful helper routines, and a

 * couple of non-obvious setup and teardown pieces which were implemented after

 * days of debugging pain. :*/

#include <linux/module.h>

#include <linux/stringify.h>

#include <linux/stddef.h>