lguest: update comments
authorRusty Russell <rusty@rustcorp.com.au>
Fri, 22 Jul 2011 05:09:50 +0000 (14:39 +0930)
committerRusty Russell <rusty@rustcorp.com.au>
Fri, 22 Jul 2011 05:09:50 +0000 (14:39 +0930)
Also removes a long-unused #define and an extraneous semicolon.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Documentation/virtual/lguest/lguest.c
arch/x86/include/asm/lguest_hcall.h
arch/x86/lguest/boot.c
arch/x86/lguest/i386_head.S
drivers/lguest/core.c
drivers/lguest/interrupts_and_traps.c
drivers/lguest/lguest_user.c
drivers/lguest/page_tables.c
drivers/lguest/x86/core.c

index 80261d34da3de8dfbbefb3e5169e8e2ac633b128..043bd7df31399a6a02c770393eb6d7f083e331e3 100644 (file)
@@ -51,7 +51,7 @@
 #include <asm/bootparam.h>
 #include "../../../include/linux/lguest_launcher.h"
 /*L:110
- * We can ignore the 42 include files we need for this program, but I do want
+ * We can ignore the 43 include files we need for this program, but I do want
  * to draw attention to the use of kernel-style types.
  *
  * As Linus said, "C is a Spartan language, and so should your naming be."  I
@@ -65,7 +65,6 @@ typedef uint16_t u16;
 typedef uint8_t u8;
 /*:*/
 
-#define PAGE_PRESENT 0x7       /* Present, RW, Execute */
 #define BRIDGE_PFX "bridge:"
 #ifndef SIOCBRADDIF
 #define SIOCBRADDIF    0x89a2          /* add interface to bridge      */
@@ -1359,7 +1358,7 @@ static void setup_console(void)
  * --sharenet=<name> option which opens or creates a named pipe.  This can be
  * used to send packets to another guest in a 1:1 manner.
  *
- * More sopisticated is to use one of the tools developed for project like UML
+ * More sophisticated is to use one of the tools developed for project like UML
  * to do networking.
  *
  * Faster is to do virtio bonding in kernel.  Doing this 1:1 would be
@@ -1369,7 +1368,7 @@ static void setup_console(void)
  * multiple inter-guest channels behind one interface, although it would
  * require some manner of hotplugging new virtio channels.
  *
- * Finally, we could implement a virtio network switch in the kernel.
+ * Finally, we could use a virtio network switch in the kernel, ie. vhost.
 :*/
 
 static u32 str2ip(const char *ipaddr)
@@ -2006,10 +2005,7 @@ int main(int argc, char *argv[])
        /* Tell the entry path not to try to reload segment registers. */
        boot->hdr.loadflags |= KEEP_SEGMENTS;
 
-       /*
-        * We tell the kernel to initialize the Guest: this returns the open
-        * /dev/lguest file descriptor.
-        */
+       /* We tell the kernel to initialize the Guest. */
        tell_kernel(start);
 
        /* Ensure that we terminate if a device-servicing child dies. */
index b60f2924c41314468d5c9b2df3fcea77fdc0c063..879fd7d33877516fd13d6eb06fc0fc8354350e98 100644 (file)
@@ -61,6 +61,7 @@ hcall(unsigned long call,
                     : "memory");
        return call;
 }
+/*:*/
 
 /* Can't use our min() macro here: needs to be a constant */
 #define LGUEST_IRQS (NR_IRQS < 32 ? NR_IRQS: 32)
index 719a32c60516cd9b6c715dfed3acd68d5e1aa58b..74279907bc1abf40ae09b788b078f1545bb095c3 100644 (file)
@@ -71,7 +71,8 @@
 #include <asm/stackprotector.h>
 #include <asm/reboot.h>                /* for struct machine_ops */
 
-/*G:010 Welcome to the Guest!
+/*G:010
+ * Welcome to the Guest!
  *
  * The Guest in our tale is a simple creature: identical to the Host but
  * behaving in simplified but equivalent ways.  In particular, the Guest is the
@@ -190,15 +191,23 @@ static void lazy_hcall4(unsigned long call,
 #endif
 
 /*G:036
- * When lazy mode is turned off reset the per-cpu lazy mode variable and then
- * issue the do-nothing hypercall to flush any stored calls.
-:*/
+ * When lazy mode is turned off, we issue the do-nothing hypercall to
+ * flush any stored calls, and call the generic helper to reset the
+ * per-cpu lazy mode variable.
+ */
 static void lguest_leave_lazy_mmu_mode(void)
 {
        hcall(LHCALL_FLUSH_ASYNC, 0, 0, 0, 0);
        paravirt_leave_lazy_mmu();
 }
 
+/*
+ * We also catch the end of context switch; we enter lazy mode for much of
+ * that too, so again we need to flush here.
+ *
+ * (Technically, this is lazy CPU mode, and normally we're in lazy MMU
+ * mode, but unlike Xen, lguest doesn't care about the difference).
+ */
 static void lguest_end_context_switch(struct task_struct *next)
 {
        hcall(LHCALL_FLUSH_ASYNC, 0, 0, 0, 0);
@@ -640,7 +649,7 @@ static void lguest_write_cr4(unsigned long val)
 
 /*
  * The Guest calls this after it has set a second-level entry (pte), ie. to map
- * a page into a process' address space.  Wetell the Host the toplevel and
+ * a page into a process' address space.  We tell the Host the toplevel and
  * address this corresponds to.  The Guest uses one pagetable per process, so
  * we need to tell the Host which one we're changing (mm->pgd).
  */
@@ -1139,7 +1148,7 @@ static struct notifier_block paniced = {
 static __init char *lguest_memory_setup(void)
 {
        /*
-        *The Linux bootloader header contains an "e820" memory map: the
+        * The Linux bootloader header contains an "e820" memory map: the
         * Launcher populated the first entry with our memory limit.
         */
        e820_add_region(boot_params.e820_map[0].addr,
index c8c95e575c1e2fd2719653418d366f70de747001..cfa23e37ec5ce24a3df7c12a420d28c71bd89009 100644 (file)
@@ -6,18 +6,22 @@
 #include <asm/processor-flags.h>
 
 /*G:020
- * Our story starts with the kernel booting into startup_32 in
- * arch/x86/kernel/head_32.S.  It expects a boot header, which is created by
- * the bootloader (the Launcher in our case).
+
+ * Our story starts with the bzImage: booting starts at startup_32 in
+ * arch/x86/boot/compressed/head_32.S.  This merely uncompresses the real
+ * kernel in place and then jumps into it: startup_32 in
+ * arch/x86/kernel/head_32.S.  Both routines expects a boot header in the %esi
+ * register, which is created by the bootloader (the Launcher in our case).
  *
  * The startup_32 function does very little: it clears the uninitialized global
  * C variables which we expect to be zero (ie. BSS) and then copies the boot
- * header and kernel command line somewhere safe.  Finally it checks the
- * 'hardware_subarch' field.  This was introduced in 2.6.24 for lguest and Xen:
- * if it's set to '1' (lguest's assigned number), then it calls us here.
+ * header and kernel command line somewhere safe, and populates some initial
+ * page tables.  Finally it checks the 'hardware_subarch' field.  This was
+ * introduced in 2.6.24 for lguest and Xen: if it's set to '1' (lguest's
+ * assigned number), then it calls us here.
  *
  * WARNING: be very careful here!  We're running at addresses equal to physical
- * addesses (around 0), not above PAGE_OFFSET as most code expectes
+ * addesses (around 0), not above PAGE_OFFSET as most code expects
  * (eg. 0xC0000000).  Jumps are relative, so they're OK, but we can't touch any
  * data without remembering to subtract __PAGE_OFFSET!
  *
index efa202499e37f792eb808188bf80652ce3cd07fc..2535933c49f83cb9fa8b7488caddf6a20dd8db09 100644 (file)
@@ -117,7 +117,7 @@ static __init int map_switcher(void)
 
        /*
         * Now the Switcher is mapped at the right address, we can't fail!
-        * Copy in the compiled-in Switcher code (from <arch>_switcher.S).
+        * Copy in the compiled-in Switcher code (from x86/switcher_32.S).
         */
        memcpy(switcher_vma->addr, start_switcher_text,
               end_switcher_text - start_switcher_text);
index f0c17150637122f5735fcfeddeb9a2c2edbd1e83..28433a155d67da1599dd2b63c852737d7ab9c67f 100644 (file)
@@ -427,8 +427,8 @@ void pin_stack_pages(struct lg_cpu *cpu)
 
 /*
  * Direct traps also mean that we need to know whenever the Guest wants to use
- * a different kernel stack, so we can change the IDT entries to use that
- * stack.  The IDT entries expect a virtual address, so unlike most addresses
+ * a different kernel stack, so we can change the guest TSS to use that
+ * stack.  The TSS entries expect a virtual address, so unlike most addresses
  * the Guest gives us, the "esp" (stack pointer) value here is virtual, not
  * physical.
  *
index 948c547b8e9e0d721bb440a5a3e4cc3bf3521067..f97e625241ad792ea935a77cd3a50afbc165416a 100644 (file)
@@ -1,8 +1,10 @@
-/*P:200 This contains all the /dev/lguest code, whereby the userspace launcher
- * controls and communicates with the Guest.  For example, the first write will
- * tell us the Guest's memory layout and entry point.  A read will run the
- * Guest until something happens, such as a signal or the Guest doing a NOTIFY
- * out to the Launcher.
+/*P:200 This contains all the /dev/lguest code, whereby the userspace
+ * launcher controls and communicates with the Guest.  For example,
+ * the first write will tell us the Guest's memory layout and entry
+ * point.  A read will run the Guest until something happens, such as
+ * a signal or the Guest doing a NOTIFY out to the Launcher.  There is
+ * also a way for the Launcher to attach eventfds to particular NOTIFY
+ * values instead of returning from the read() call.
 :*/
 #include <linux/uaccess.h>
 #include <linux/miscdevice.h>
@@ -357,8 +359,8 @@ static int initialize(struct file *file, const unsigned long __user *input)
                goto free_eventfds;
 
        /*
-        * Initialize the Guest's shadow page tables, using the toplevel
-        * address the Launcher gave us.  This allocates memory, so can fail.
+        * Initialize the Guest's shadow page tables.  This allocates
+        * memory, so can fail.
         */
        err = init_guest_pagetable(lg);
        if (err)
@@ -516,6 +518,7 @@ static const struct file_operations lguest_fops = {
        .read    = read,
        .llseek  = default_llseek,
 };
+/*:*/
 
 /*
  * This is a textbook example of a "misc" character device.  Populate a "struct
index 00026222bde816a0250aea633452617e0ec943db..3b62be160a6ebca5b11f9f4a0126268386b32580 100644 (file)
@@ -155,7 +155,7 @@ static pte_t *spte_addr(struct lg_cpu *cpu, pgd_t spgd, unsigned long vaddr)
 }
 
 /*
- * These functions are just like the above two, except they access the Guest
+ * These functions are just like the above, except they access the Guest
  * page tables.  Hence they return a Guest address.
  */
 static unsigned long gpgd_addr(struct lg_cpu *cpu, unsigned long vaddr)
@@ -195,7 +195,7 @@ static unsigned long gpte_addr(struct lg_cpu *cpu,
 #endif
 /*:*/
 
-/*M:014
+/*M:007
  * get_pfn is slow: we could probably try to grab batches of pages here as
  * an optimization (ie. pre-faulting).
 :*/
index ec0cdfc04e781f36649210f839a891aeaa1e3ec3..3b9b810cbf2801fc2725430f2376f7d7329abb10 100644 (file)
@@ -272,7 +272,7 @@ static int emulate_insn(struct lg_cpu *cpu)
        unsigned int insnlen = 0, in = 0, shift = 0;
        /*
         * The eip contains the *virtual* address of the Guest's instruction:
-        * guest_pa just subtracts the Guest's page_offset.
+        * walk the Guest's page tables to find the "physical" address.
         */
        unsigned long physaddr = guest_pa(cpu, cpu->regs->eip);
 
@@ -409,7 +409,7 @@ void lguest_arch_handle_trap(struct lg_cpu *cpu)
                 * These values mean a real interrupt occurred, in which case
                 * the Host handler has already been run. We just do a
                 * friendly check if another process should now be run, then
-                * return to run the Guest again
+                * return to run the Guest again.
                 */
                cond_resched();
                return;
@@ -459,7 +459,7 @@ void __init lguest_arch_host_init(void)
        int i;
 
        /*
-        * Most of the i386/switcher.S doesn't care that it's been moved; on
+        * Most of the x86/switcher_32.S doesn't care that it's been moved; on
         * Intel, jumps are relative, and it doesn't access any references to
         * external code or data.
         *
@@ -587,7 +587,7 @@ void __init lguest_arch_host_init(void)
                clear_cpu_cap(&boot_cpu_data, X86_FEATURE_PGE);
        }
        put_online_cpus();
-};
+}
 /*:*/
 
 void __exit lguest_arch_host_fini(void)
@@ -670,8 +670,6 @@ int lguest_arch_init_hypercalls(struct lg_cpu *cpu)
 /*:*/
 
 /*L:030
- * lguest_arch_setup_regs()
- *
  * Most of the Guest's registers are left alone: we used get_zeroed_page() to
  * allocate the structure, so they will be 0.
  */