From b2b47c214f4e85ce3968120d42e8b18eccb4f4e3 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 26 Jul 2007 10:41:02 -0700 Subject: lguest: documentation II: Guest Documentation: The Guest Signed-off-by: Rusty Russell Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- include/linux/lguest.h | 47 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) (limited to 'include/linux/lguest.h') diff --git a/include/linux/lguest.h b/include/linux/lguest.h index 500aace..e76c151 100644 --- a/include/linux/lguest.h +++ b/include/linux/lguest.h @@ -27,18 +27,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 +72,40 @@ 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. */ + /* 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; }; -- cgit v1.1