lguest: documentation V: Host
[linux-3.10.git] / drivers / lguest / hypercalls.c
1 /*P:500 Just as userspace programs request kernel operations through a system
2  * call, the Guest requests Host operations through a "hypercall".  You might
3  * notice this nomenclature doesn't really follow any logic, but the name has
4  * been around for long enough that we're stuck with it.  As you'd expect, this
5  * code is basically a one big switch statement. :*/
6
7 /*  Copyright (C) 2006 Rusty Russell IBM Corporation
8
9     This program is free software; you can redistribute it and/or modify
10     it under the terms of the GNU General Public License as published by
11     the Free Software Foundation; either version 2 of the License, or
12     (at your option) any later version.
13
14     This program is distributed in the hope that it will be useful,
15     but WITHOUT ANY WARRANTY; without even the implied warranty of
16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17     GNU General Public License for more details.
18
19     You should have received a copy of the GNU General Public License
20     along with this program; if not, write to the Free Software
21     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
22 */
23 #include <linux/uaccess.h>
24 #include <linux/syscalls.h>
25 #include <linux/mm.h>
26 #include <asm/page.h>
27 #include <asm/pgtable.h>
28 #include <irq_vectors.h>
29 #include "lg.h"
30
31 /*H:120 This is the core hypercall routine: where the Guest gets what it
32  * wants.  Or gets killed.  Or, in the case of LHCALL_CRASH, both.
33  *
34  * Remember from the Guest: %eax == which call to make, and the arguments are
35  * packed into %edx, %ebx and %ecx if needed. */
36 static void do_hcall(struct lguest *lg, struct lguest_regs *regs)
37 {
38         switch (regs->eax) {
39         case LHCALL_FLUSH_ASYNC:
40                 /* This call does nothing, except by breaking out of the Guest
41                  * it makes us process all the asynchronous hypercalls. */
42                 break;
43         case LHCALL_LGUEST_INIT:
44                 /* You can't get here unless you're already initialized.  Don't
45                  * do that. */
46                 kill_guest(lg, "already have lguest_data");
47                 break;
48         case LHCALL_CRASH: {
49                 /* Crash is such a trivial hypercall that we do it in four
50                  * lines right here. */
51                 char msg[128];
52                 /* If the lgread fails, it will call kill_guest() itself; the
53                  * kill_guest() with the message will be ignored. */
54                 lgread(lg, msg, regs->edx, sizeof(msg));
55                 msg[sizeof(msg)-1] = '\0';
56                 kill_guest(lg, "CRASH: %s", msg);
57                 break;
58         }
59         case LHCALL_FLUSH_TLB:
60                 /* FLUSH_TLB comes in two flavors, depending on the
61                  * argument: */
62                 if (regs->edx)
63                         guest_pagetable_clear_all(lg);
64                 else
65                         guest_pagetable_flush_user(lg);
66                 break;
67         case LHCALL_GET_WALLCLOCK: {
68                 /* The Guest wants to know the real time in seconds since 1970,
69                  * in good Unix tradition. */
70                 struct timespec ts;
71                 ktime_get_real_ts(&ts);
72                 regs->eax = ts.tv_sec;
73                 break;
74         }
75         case LHCALL_BIND_DMA:
76                 /* BIND_DMA really wants four arguments, but it's the only call
77                  * which does.  So the Guest packs the number of buffers and
78                  * the interrupt number into the final argument, and we decode
79                  * it here.  This can legitimately fail, since we currently
80                  * place a limit on the number of DMA pools a Guest can have.
81                  * So we return true or false from this call. */
82                 regs->eax = bind_dma(lg, regs->edx, regs->ebx,
83                                      regs->ecx >> 8, regs->ecx & 0xFF);
84                 break;
85
86         /* All these calls simply pass the arguments through to the right
87          * routines. */
88         case LHCALL_SEND_DMA:
89                 send_dma(lg, regs->edx, regs->ebx);
90                 break;
91         case LHCALL_LOAD_GDT:
92                 load_guest_gdt(lg, regs->edx, regs->ebx);
93                 break;
94         case LHCALL_LOAD_IDT_ENTRY:
95                 load_guest_idt_entry(lg, regs->edx, regs->ebx, regs->ecx);
96                 break;
97         case LHCALL_NEW_PGTABLE:
98                 guest_new_pagetable(lg, regs->edx);
99                 break;
100         case LHCALL_SET_STACK:
101                 guest_set_stack(lg, regs->edx, regs->ebx, regs->ecx);
102                 break;
103         case LHCALL_SET_PTE:
104                 guest_set_pte(lg, regs->edx, regs->ebx, mkgpte(regs->ecx));
105                 break;
106         case LHCALL_SET_PMD:
107                 guest_set_pmd(lg, regs->edx, regs->ebx);
108                 break;
109         case LHCALL_LOAD_TLS:
110                 guest_load_tls(lg, regs->edx);
111                 break;
112         case LHCALL_SET_CLOCKEVENT:
113                 guest_set_clockevent(lg, regs->edx);
114                 break;
115
116         case LHCALL_TS:
117                 /* This sets the TS flag, as we saw used in run_guest(). */
118                 lg->ts = regs->edx;
119                 break;
120         case LHCALL_HALT:
121                 /* Similarly, this sets the halted flag for run_guest(). */
122                 lg->halted = 1;
123                 break;
124         default:
125                 kill_guest(lg, "Bad hypercall %li\n", regs->eax);
126         }
127 }
128
129 /* Asynchronous hypercalls are easy: we just look in the array in the Guest's
130  * "struct lguest_data" and see if there are any new ones marked "ready".
131  *
132  * We are careful to do these in order: obviously we respect the order the
133  * Guest put them in the ring, but we also promise the Guest that they will
134  * happen before any normal hypercall (which is why we check this before
135  * checking for a normal hcall). */
136 static void do_async_hcalls(struct lguest *lg)
137 {
138         unsigned int i;
139         u8 st[LHCALL_RING_SIZE];
140
141         /* For simplicity, we copy the entire call status array in at once. */
142         if (copy_from_user(&st, &lg->lguest_data->hcall_status, sizeof(st)))
143                 return;
144
145
146         /* We process "struct lguest_data"s hcalls[] ring once. */
147         for (i = 0; i < ARRAY_SIZE(st); i++) {
148                 struct lguest_regs regs;
149                 /* We remember where we were up to from last time.  This makes
150                  * sure that the hypercalls are done in the order the Guest
151                  * places them in the ring. */
152                 unsigned int n = lg->next_hcall;
153
154                 /* 0xFF means there's no call here (yet). */
155                 if (st[n] == 0xFF)
156                         break;
157
158                 /* OK, we have hypercall.  Increment the "next_hcall" cursor,
159                  * and wrap back to 0 if we reach the end. */
160                 if (++lg->next_hcall == LHCALL_RING_SIZE)
161                         lg->next_hcall = 0;
162
163                 /* We copy the hypercall arguments into a fake register
164                  * structure.  This makes life simple for do_hcall(). */
165                 if (get_user(regs.eax, &lg->lguest_data->hcalls[n].eax)
166                     || get_user(regs.edx, &lg->lguest_data->hcalls[n].edx)
167                     || get_user(regs.ecx, &lg->lguest_data->hcalls[n].ecx)
168                     || get_user(regs.ebx, &lg->lguest_data->hcalls[n].ebx)) {
169                         kill_guest(lg, "Fetching async hypercalls");
170                         break;
171                 }
172
173                 /* Do the hypercall, same as a normal one. */
174                 do_hcall(lg, &regs);
175
176                 /* Mark the hypercall done. */
177                 if (put_user(0xFF, &lg->lguest_data->hcall_status[n])) {
178                         kill_guest(lg, "Writing result for async hypercall");
179                         break;
180                 }
181
182                 /* Stop doing hypercalls if we've just done a DMA to the
183                  * Launcher: it needs to service this first. */
184                 if (lg->dma_is_pending)
185                         break;
186         }
187 }
188
189 /* Last of all, we look at what happens first of all.  The very first time the
190  * Guest makes a hypercall, we end up here to set things up: */
191 static void initialize(struct lguest *lg)
192 {
193         u32 tsc_speed;
194
195         /* You can't do anything until you're initialized.  The Guest knows the
196          * rules, so we're unforgiving here. */
197         if (lg->regs->eax != LHCALL_LGUEST_INIT) {
198                 kill_guest(lg, "hypercall %li before LGUEST_INIT",
199                            lg->regs->eax);
200                 return;
201         }
202
203         /* We insist that the Time Stamp Counter exist and doesn't change with
204          * cpu frequency.  Some devious chip manufacturers decided that TSC
205          * changes could be handled in software.  I decided that time going
206          * backwards might be good for benchmarks, but it's bad for users.
207          *
208          * We also insist that the TSC be stable: the kernel detects unreliable
209          * TSCs for its own purposes, and we use that here. */
210         if (boot_cpu_has(X86_FEATURE_CONSTANT_TSC) && !check_tsc_unstable())
211                 tsc_speed = tsc_khz;
212         else
213                 tsc_speed = 0;
214
215         /* The pointer to the Guest's "struct lguest_data" is the only
216          * argument. */
217         lg->lguest_data = (struct lguest_data __user *)lg->regs->edx;
218         /* If we check the address they gave is OK now, we can simply
219          * copy_to_user/from_user from now on rather than using lgread/lgwrite.
220          * I put this in to show that I'm not immune to writing stupid
221          * optimizations. */
222         if (!lguest_address_ok(lg, lg->regs->edx, sizeof(*lg->lguest_data))) {
223                 kill_guest(lg, "bad guest page %p", lg->lguest_data);
224                 return;
225         }
226         /* The Guest tells us where we're not to deliver interrupts by putting
227          * the range of addresses into "struct lguest_data". */
228         if (get_user(lg->noirq_start, &lg->lguest_data->noirq_start)
229             || get_user(lg->noirq_end, &lg->lguest_data->noirq_end)
230             /* We tell the Guest that it can't use the top 4MB of virtual
231              * addresses used by the Switcher. */
232             || put_user(4U*1024*1024, &lg->lguest_data->reserve_mem)
233             || put_user(tsc_speed, &lg->lguest_data->tsc_khz)
234             /* We also give the Guest a unique id, as used in lguest_net.c. */
235             || put_user(lg->guestid, &lg->lguest_data->guestid))
236                 kill_guest(lg, "bad guest page %p", lg->lguest_data);
237
238         /* This is the one case where the above accesses might have been the
239          * first write to a Guest page.  This may have caused a copy-on-write
240          * fault, but the Guest might be referring to the old (read-only)
241          * page. */
242         guest_pagetable_clear_all(lg);
243 }
244 /* Now we've examined the hypercall code; our Guest can make requests.  There
245  * is one other way we can do things for the Guest, as we see in
246  * emulate_insn(). */
247
248 /*H:110 Tricky point: we mark the hypercall as "done" once we've done it.
249  * Normally we don't need to do this: the Guest will run again and update the
250  * trap number before we come back around the run_guest() loop to
251  * do_hypercalls().
252  *
253  * However, if we are signalled or the Guest sends DMA to the Launcher, that
254  * loop will exit without running the Guest.  When it comes back it would try
255  * to re-run the hypercall. */
256 static void clear_hcall(struct lguest *lg)
257 {
258         lg->regs->trapnum = 255;
259 }
260
261 /*H:100
262  * Hypercalls
263  *
264  * Remember from the Guest, hypercalls come in two flavors: normal and
265  * asynchronous.  This file handles both of types.
266  */
267 void do_hypercalls(struct lguest *lg)
268 {
269         /* Not initialized yet? */
270         if (unlikely(!lg->lguest_data)) {
271                 /* Did the Guest make a hypercall?  We might have come back for
272                  * some other reason (an interrupt, a different trap). */
273                 if (lg->regs->trapnum == LGUEST_TRAP_ENTRY) {
274                         /* Set up the "struct lguest_data" */
275                         initialize(lg);
276                         /* The hypercall is done. */
277                         clear_hcall(lg);
278                 }
279                 return;
280         }
281
282         /* The Guest has initialized.
283          *
284          * Look in the hypercall ring for the async hypercalls: */
285         do_async_hcalls(lg);
286
287         /* If we stopped reading the hypercall ring because the Guest did a
288          * SEND_DMA to the Launcher, we want to return now.  Otherwise if the
289          * Guest asked us to do a hypercall, we do it. */
290         if (!lg->dma_is_pending && lg->regs->trapnum == LGUEST_TRAP_ENTRY) {
291                 do_hcall(lg, lg->regs);
292                 /* The hypercall is done. */
293                 clear_hcall(lg);
294         }
295 }