1 /*P:200 This contains all the /dev/lguest code, whereby the userspace launcher
2 * controls and communicates with the Guest. For example, the first write will
3 * tell us the Guest's memory layout, pagetable, entry point and kernel address
4 * offset. A read will run the Guest until something happens, such as a signal
5 * or the Guest doing a DMA out to the Launcher. Writes are also used to get a
6 * DMA buffer registered by the Guest and to send the Guest an interrupt. :*/
7 #include <linux/uaccess.h>
8 #include <linux/miscdevice.h>
12 /*L:310 To send DMA into the Guest, the Launcher needs to be able to ask for a
13 * DMA buffer. This is done by writing LHREQ_GETDMA and the key to
15 static long user_get_dma(struct lguest
*lg
, const unsigned long __user
*input
)
17 unsigned long key
, udma
, irq
;
19 /* Fetch the key they wrote to us. */
20 if (get_user(key
, input
) != 0)
22 /* Look for a free Guest DMA buffer bound to that key. */
23 udma
= get_dma_buffer(lg
, key
, &irq
);
27 /* We need to tell the Launcher what interrupt the Guest expects after
28 * the buffer is filled. We stash it in udma->used_len. */
29 lgwrite_u32(lg
, udma
+ offsetof(struct lguest_dma
, used_len
), irq
);
31 /* The (guest-physical) address of the DMA buffer is returned from
36 /*L:315 To force the Guest to stop running and return to the Launcher, the
37 * Waker sets writes LHREQ_BREAK and the value "1" to /dev/lguest. The
38 * Launcher then writes LHREQ_BREAK and "0" to release the Waker. */
39 static int break_guest_out(struct lguest
*lg
, const unsigned long __user
*input
)
43 /* Fetch whether they're turning break on or off.. */
44 if (get_user(on
, input
) != 0)
49 /* Pop it out (may be running on different CPU) */
50 wake_up_process(lg
->tsk
);
51 /* Wait for them to reset it */
52 return wait_event_interruptible(lg
->break_wq
, !lg
->break_out
);
55 wake_up(&lg
->break_wq
);
60 /*L:050 Sending an interrupt is done by writing LHREQ_IRQ and an interrupt
61 * number to /dev/lguest. */
62 static int user_send_irq(struct lguest
*lg
, const unsigned long __user
*input
)
66 if (get_user(irq
, input
) != 0)
68 if (irq
>= LGUEST_IRQS
)
70 /* Next time the Guest runs, the core code will see if it can deliver
72 set_bit(irq
, lg
->irqs_pending
);
76 /*L:040 Once our Guest is initialized, the Launcher makes it run by reading
77 * from /dev/lguest. */
78 static ssize_t
read(struct file
*file
, char __user
*user
, size_t size
,loff_t
*o
)
80 struct lguest
*lg
= file
->private_data
;
82 /* You must write LHREQ_INITIALIZE first! */
86 /* If you're not the task which owns the guest, go away. */
87 if (current
!= lg
->tsk
)
90 /* If the guest is already dead, we indicate why */
94 /* lg->dead either contains an error code, or a string. */
96 return PTR_ERR(lg
->dead
);
98 /* We can only return as much as the buffer they read with. */
99 len
= min(size
, strlen(lg
->dead
)+1);
100 if (copy_to_user(user
, lg
->dead
, len
) != 0)
105 /* If we returned from read() last time because the Guest sent DMA,
107 if (lg
->dma_is_pending
)
108 lg
->dma_is_pending
= 0;
110 /* Run the Guest until something interesting happens. */
111 return run_guest(lg
, (unsigned long __user
*)user
);
114 /*L:020 The initialization write supplies 5 pointer sized (32 or 64 bit)
115 * values (in addition to the LHREQ_INITIALIZE value). These are:
117 * base: The start of the Guest-physical memory inside the Launcher memory.
119 * pfnlimit: The highest (Guest-physical) page number the Guest should be
120 * allowed to access. The Launcher has to live in Guest memory, so it sets
121 * this to ensure the Guest can't reach it.
123 * pgdir: The (Guest-physical) address of the top of the initial Guest
124 * pagetables (which are set up by the Launcher).
126 * start: The first instruction to execute ("eip" in x86-speak).
128 * page_offset: The PAGE_OFFSET constant in the Guest kernel. We should
129 * probably wean the code off this, but it's a very useful constant! Any
130 * address above this is within the Guest kernel, and any kernel address can
131 * quickly converted from physical to virtual by adding PAGE_OFFSET. It's
132 * 0xC0000000 (3G) by default, but it's configurable at kernel build time.
134 static int initialize(struct file
*file
, const unsigned long __user
*input
)
136 /* "struct lguest" contains everything we (the Host) know about a
140 unsigned long args
[5];
142 /* We grab the Big Lguest lock, which protects against multiple
143 * simultaneous initializations. */
144 mutex_lock(&lguest_lock
);
145 /* You can't initialize twice! Close the device and start again... */
146 if (file
->private_data
) {
151 if (copy_from_user(args
, input
, sizeof(args
)) != 0) {
156 lg
= kzalloc(sizeof(*lg
), GFP_KERNEL
);
162 /* Populate the easy fields of our "struct lguest" */
163 lg
->mem_base
= (void __user
*)(long)args
[0];
164 lg
->pfn_limit
= args
[1];
165 lg
->page_offset
= args
[4];
167 /* We need a complete page for the Guest registers: they are accessible
168 * to the Guest and we can only grant it access to whole pages. */
169 lg
->regs_page
= get_zeroed_page(GFP_KERNEL
);
170 if (!lg
->regs_page
) {
174 /* We actually put the registers at the bottom of the page. */
175 lg
->regs
= (void *)lg
->regs_page
+ PAGE_SIZE
- sizeof(*lg
->regs
);
177 /* Initialize the Guest's shadow page tables, using the toplevel
178 * address the Launcher gave us. This allocates memory, so can
180 err
= init_guest_pagetable(lg
, args
[2]);
184 /* Now we initialize the Guest's registers, handing it the start
186 lguest_arch_setup_regs(lg
, args
[3]);
188 /* The timer for lguest's clock needs initialization. */
191 /* We keep a pointer to the Launcher task (ie. current task) for when
192 * other Guests want to wake this one (inter-Guest I/O). */
194 /* We need to keep a pointer to the Launcher's memory map, because if
195 * the Launcher dies we need to clean it up. If we don't keep a
196 * reference, it is destroyed before close() is called. */
197 lg
->mm
= get_task_mm(lg
->tsk
);
199 /* Initialize the queue for the waker to wait on */
200 init_waitqueue_head(&lg
->break_wq
);
202 /* We remember which CPU's pages this Guest used last, for optimization
203 * when the same Guest runs on the same CPU twice. */
204 lg
->last_pages
= NULL
;
206 /* We keep our "struct lguest" in the file's private_data. */
207 file
->private_data
= lg
;
209 mutex_unlock(&lguest_lock
);
211 /* And because this is a write() call, we return the length used. */
215 free_page(lg
->regs_page
);
217 memset(lg
, 0, sizeof(*lg
));
219 mutex_unlock(&lguest_lock
);
223 /*L:010 The first operation the Launcher does must be a write. All writes
224 * start with a 32 bit number: for the first write this must be
225 * LHREQ_INITIALIZE to set up the Guest. After that the Launcher can use
226 * writes of other values to get DMA buffers and send interrupts. */
227 static ssize_t
write(struct file
*file
, const char __user
*in
,
228 size_t size
, loff_t
*off
)
230 /* Once the guest is initialized, we hold the "struct lguest" in the
231 * file private data. */
232 struct lguest
*lg
= file
->private_data
;
233 const unsigned long __user
*input
= (const unsigned long __user
*)in
;
236 if (get_user(req
, input
) != 0)
240 /* If you haven't initialized, you must do that first. */
241 if (req
!= LHREQ_INITIALIZE
&& !lg
)
244 /* Once the Guest is dead, all you can do is read() why it died. */
248 /* If you're not the task which owns the Guest, you can only break */
249 if (lg
&& current
!= lg
->tsk
&& req
!= LHREQ_BREAK
)
253 case LHREQ_INITIALIZE
:
254 return initialize(file
, input
);
256 return user_get_dma(lg
, input
);
258 return user_send_irq(lg
, input
);
260 return break_guest_out(lg
, input
);
266 /*L:060 The final piece of interface code is the close() routine. It reverses
267 * everything done in initialize(). This is usually called because the
270 * Note that the close routine returns 0 or a negative error number: it can't
271 * really fail, but it can whine. I blame Sun for this wart, and K&R C for
272 * letting them do it. :*/
273 static int close(struct inode
*inode
, struct file
*file
)
275 struct lguest
*lg
= file
->private_data
;
277 /* If we never successfully initialized, there's nothing to clean up */
281 /* We need the big lock, to protect from inter-guest I/O and other
282 * Launchers initializing guests. */
283 mutex_lock(&lguest_lock
);
284 /* Cancels the hrtimer set via LHCALL_SET_CLOCKEVENT. */
285 hrtimer_cancel(&lg
->hrt
);
286 /* Free any DMA buffers the Guest had bound. */
288 /* Free up the shadow page tables for the Guest. */
289 free_guest_pagetable(lg
);
290 /* Now all the memory cleanups are done, it's safe to release the
291 * Launcher's memory management structure. */
293 /* If lg->dead doesn't contain an error code it will be NULL or a
294 * kmalloc()ed string, either of which is ok to hand to kfree(). */
295 if (!IS_ERR(lg
->dead
))
297 /* We can free up the register page we allocated. */
298 free_page(lg
->regs_page
);
299 /* We clear the entire structure, which also marks it as free for the
301 memset(lg
, 0, sizeof(*lg
));
302 /* Release lock and exit. */
303 mutex_unlock(&lguest_lock
);
309 * Welcome to our journey through the Launcher!
311 * The Launcher is the Host userspace program which sets up, runs and services
312 * the Guest. In fact, many comments in the Drivers which refer to "the Host"
313 * doing things are inaccurate: the Launcher does all the device handling for
314 * the Guest. The Guest can't tell what's done by the the Launcher and what by
317 * Just to confuse you: to the Host kernel, the Launcher *is* the Guest and we
318 * shall see more of that later.
320 * We begin our understanding with the Host kernel interface which the Launcher
321 * uses: reading and writing a character device called /dev/lguest. All the
322 * work happens in the read(), write() and close() routines: */
323 static struct file_operations lguest_fops
= {
324 .owner
= THIS_MODULE
,
330 /* This is a textbook example of a "misc" character device. Populate a "struct
331 * miscdevice" and register it with misc_register(). */
332 static struct miscdevice lguest_dev
= {
333 .minor
= MISC_DYNAMIC_MINOR
,
335 .fops
= &lguest_fops
,
338 int __init
lguest_device_init(void)
340 return misc_register(&lguest_dev
);
343 void __exit
lguest_device_remove(void)
345 misc_deregister(&lguest_dev
);