sched: speed up and simplify vslice calculations

[linux-2.6-omap-h63xx.git] / include / linux / lguest.h

diff --git a/include/linux/lguest.h b/include/linux/lguest.h
index 500aace21ca7be6ad96e3455166c21fa4db94617..157ad64aa7ce8e020759db4498a7288d31345662 100644 (file)
--- a/include/linux/lguest.h
+++ b/include/linux/lguest.h
@@ -17,7 +17,6 @@
 #define LHCALL_TS              8
 #define LHCALL_SET_CLOCKEVENT  9
 #define LHCALL_HALT            10
-#define LHCALL_GET_WALLCLOCK   11
 #define LHCALL_BIND_DMA                12
 #define LHCALL_SEND_DMA                13
 #define LHCALL_SET_PTE         14
@@ -27,18 +26,38 @@
 #define LG_CLOCK_MIN_DELTA     100UL
 #define LG_CLOCK_MAX_DELTA     ULONG_MAX
 
+/*G:031 First, how does our Guest contact the Host to ask for privileged
+ * operations?  There are two ways: the direct way is to make a "hypercall",
+ * to make requests of the Host Itself.
+ *
+ * Our hypercall mechanism uses the highest unused trap code (traps 32 and
+ * above are used by real hardware interrupts).  Seventeen hypercalls are
+ * available: the hypercall number is put in the %eax register, and the
+ * arguments (when required) are placed in %edx, %ebx and %ecx.  If a return
+ * value makes sense, it's returned in %eax.
+ *
+ * Grossly invalid calls result in Sudden Death at the hands of the vengeful
+ * Host, rather than returning failure.  This reflects Winston Churchill's
+ * definition of a gentleman: "someone who is only rude intentionally". */
 #define LGUEST_TRAP_ENTRY 0x1F
 
 static inline unsigned long
 hcall(unsigned long call,
       unsigned long arg1, unsigned long arg2, unsigned long arg3)
 {
+       /* "int" is the Intel instruction to trigger a trap. */
        asm volatile("int $" __stringify(LGUEST_TRAP_ENTRY)
+                      /* The call is in %eax (aka "a"), and can be replaced */
                     : "=a"(call)
+                      /* The other arguments are in %eax, %edx, %ebx & %ecx */
                     : "a"(call), "d"(arg1), "b"(arg2), "c"(arg3)
+                      /* "memory" means this might write somewhere in memory.
+                       * This isn't true for all calls, but it's safe to tell
+                       * gcc that it might happen so it doesn't get clever. */
                     : "memory");
        return call;
 }
+/*:*/
 
 void async_hcall(unsigned long call,
                 unsigned long arg1, unsigned long arg2, unsigned long arg3);
@@ -52,31 +71,43 @@ struct hcall_ring
        u32 eax, edx, ebx, ecx;
 };
 
-/* All the good stuff happens here: guest registers it with LGUEST_INIT */
+/*G:032 The second method of communicating with the Host is to via "struct
+ * lguest_data".  The Guest's very first hypercall is to tell the Host where
+ * this is, and then the Guest and Host both publish information in it. :*/
 struct lguest_data
 {
-/* Fields which change during running: */
-       /* 512 == enabled (same as eflags) */
+       /* 512 == enabled (same as eflags in normal hardware).  The Guest
+        * changes interrupts so often that a hypercall is too slow. */
        unsigned int irq_enabled;
-       /* Interrupts blocked by guest. */
+       /* Fine-grained interrupt disabling by the Guest */
        DECLARE_BITMAP(blocked_interrupts, LGUEST_IRQS);
 
-       /* Virtual address of page fault. */
+       /* The Host writes the virtual address of the last page fault here,
+        * which saves the Guest a hypercall.  CR2 is the native register where
+        * this address would normally be found. */
        unsigned long cr2;
 
-       /* Async hypercall ring.  0xFF == done, 0 == pending. */
+       /* Wallclock time set by the Host. */
+       struct timespec time;
+
+       /* Async hypercall ring.  Instead of directly making hypercalls, we can
+        * place them in here for processing the next time the Host wants.
+        * This batching can be quite efficient. */
+
+       /* 0xFF == done (set by Host), 0 == pending (set by Guest). */
        u8 hcall_status[LHCALL_RING_SIZE];
+       /* The actual registers for the hypercalls. */
        struct hcall_ring hcalls[LHCALL_RING_SIZE];
 
-/* Fields initialized by the hypervisor at boot: */
+/* Fields initialized by the Host at boot: */
        /* Memory not to try to access */
        unsigned long reserve_mem;
-       /* ID of this guest (used by network driver to set ethernet address) */
+       /* ID of this Guest (used by network driver to set ethernet address) */
        u16 guestid;
        /* KHz for the TSC clock. */
        u32 tsc_khz;
 
-/* Fields initialized by the guest at boot: */
+/* Fields initialized by the Guest at boot: */
        /* Instruction range to suppress interrupts even if enabled */
        unsigned long noirq_start, noirq_end;
 };