lguest: documentation I: Preparation

The netfilter code had very good documentation: the Netfilter Hacking HOWTO.
Noone ever read it.

So this time I'm trying something different, using a bit of Knuthiness.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

2 files changed, 65 insertions, 2 deletions

diff --git a/Documentation/lguest/extract b/Documentation/lguest/extract
new file mode 100644
index 000000000000..7730bb6e4b94
--- /dev/null
+++ b/Documentation/lguest/extract
@@ -0,0 +1,58 @@
+#! /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
+
diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c
index 62a8133393e1..fc1bf70abfb1 100644
--- a/Documentation/lguest/lguest.c
+++ b/Documentation/lguest/lguest.c
@@ -1,5 +1,10 @@
-/* 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>