lguest: comment documentation update.
Took some cycles to re-read the Lguest Journey end-to-end, fix some
rot and tighten some phrases.
Only comments change. No new jokes, but a couple of recycled old jokes.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
diff --git a/drivers/lguest/x86/core.c b/drivers/lguest/x86/core.c
index 6351878..5126d5d 100644
--- a/drivers/lguest/x86/core.c
+++ b/drivers/lguest/x86/core.c
@@ -17,6 +17,13 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
+/*P:450 This file contains the x86-specific lguest code. It used to be all
+ * mixed in with drivers/lguest/core.c but several foolhardy code slashers
+ * wrestled most of the dependencies out to here in preparation for porting
+ * lguest to other architectures (see what I mean by foolhardy?).
+ *
+ * This also contains a couple of non-obvious setup and teardown pieces which
+ * were implemented after days of debugging pain. :*/
#include <linux/kernel.h>
#include <linux/start_kernel.h>
#include <linux/string.h>
@@ -157,6 +164,8 @@
* also simplify copy_in_guest_info(). Note that we'd still need to restore
* things when we exit to Launcher userspace, but that's fairly easy.
*
+ * We could also try using this hooks for PGE, but that might be too expensive.
+ *
* The hooks were designed for KVM, but we can also put them to good use. :*/
/*H:040 This is the i386-specific code to setup and run the Guest. Interrupts
@@ -182,7 +191,7 @@
* was doing. */
run_guest_once(cpu, lguest_pages(raw_smp_processor_id()));
- /* Note that the "regs" pointer contains two extra entries which are
+ /* Note that the "regs" structure contains two extra entries which are
* not really registers: a trap number which says what interrupt or
* trap made the switcher code come back, and an error code which some
* traps set. */
@@ -293,11 +302,10 @@
break;
case 14: /* We've intercepted a Page Fault. */
/* The Guest accessed a virtual address that wasn't mapped.
- * This happens a lot: we don't actually set up most of the
- * page tables for the Guest at all when we start: as it runs
- * it asks for more and more, and we set them up as
- * required. In this case, we don't even tell the Guest that
- * the fault happened.
+ * This happens a lot: we don't actually set up most of the page
+ * tables for the Guest at all when we start: as it runs it asks
+ * for more and more, and we set them up as required. In this
+ * case, we don't even tell the Guest that the fault happened.
*
* The errcode tells whether this was a read or a write, and
* whether kernel or userspace code. */
@@ -342,7 +350,7 @@
if (!deliver_trap(cpu, cpu->regs->trapnum))
/* If the Guest doesn't have a handler (either it hasn't
* registered any yet, or it's one of the faults we don't let
- * it handle), it dies with a cryptic error message. */
+ * it handle), it dies with this cryptic error message. */
kill_guest(cpu, "unhandled trap %li at %#lx (%#lx)",
cpu->regs->trapnum, cpu->regs->eip,
cpu->regs->trapnum == 14 ? cpu->arch.last_pagefault
@@ -375,8 +383,8 @@
* The only exception is the interrupt handlers in switcher.S: their
* addresses are placed in a table (default_idt_entries), so we need to
* update the table with the new addresses. switcher_offset() is a
- * convenience function which returns the distance between the builtin
- * switcher code and the high-mapped copy we just made. */
+ * convenience function which returns the distance between the
+ * compiled-in switcher code and the high-mapped copy we just made. */
for (i = 0; i < IDT_ENTRIES; i++)
default_idt_entries[i] += switcher_offset();
@@ -416,7 +424,7 @@
state->guest_gdt_desc.address = (long)&state->guest_gdt;
/* We know where we want the stack to be when the Guest enters
- * the switcher: in pages->regs. The stack grows upwards, so
+ * the Switcher: in pages->regs. The stack grows upwards, so
* we start it at the end of that structure. */
state->guest_tss.sp0 = (long)(&pages->regs + 1);
/* And this is the GDT entry to use for the stack: we keep a
@@ -513,8 +521,8 @@
{
u32 tsc_speed;
- /* The pointer to the Guest's "struct lguest_data" is the only
- * argument. We check that address now. */
+ /* The pointer to the Guest's "struct lguest_data" is the only argument.
+ * We check that address now. */
if (!lguest_address_ok(cpu->lg, cpu->hcall->arg1,
sizeof(*cpu->lg->lguest_data)))
return -EFAULT;
@@ -546,6 +554,7 @@
return 0;
}
+/*:*/
/*L:030 lguest_arch_setup_regs()
*
diff --git a/drivers/lguest/x86/switcher_32.S b/drivers/lguest/x86/switcher_32.S
index 0af8baa..3fc1531 100644
--- a/drivers/lguest/x86/switcher_32.S
+++ b/drivers/lguest/x86/switcher_32.S
@@ -1,6 +1,6 @@
-/*P:900 This is the Switcher: code which sits at 0xFFC00000 to do the low-level
- * Guest<->Host switch. It is as simple as it can be made, but it's naturally
- * very specific to x86.
+/*P:900 This is the Switcher: code which sits at 0xFFC00000 astride both the
+ * Host and Guest to do the low-level Guest<->Host switch. It is as simple as
+ * it can be made, but it's naturally very specific to x86.
*
* You have now completed Preparation. If this has whet your appetite; if you
* are feeling invigorated and refreshed then the next, more challenging stage
@@ -189,7 +189,7 @@
// Interrupts are turned back on: we are Guest.
iret
-// We treat two paths to switch back to the Host
+// We tread two paths to switch back to the Host
// Yet both must save Guest state and restore Host
// So we put the routine in a macro.
#define SWITCH_TO_HOST \