lguest: documentation update

}

/*L:140 Loading the kernel is easy when it's a "vmlinux", but most kernels

 * come wrapped up in the self-decompressing "bzImage" format.  With some funky

 * coding, we can load those, too. */

 * come wrapped up in the self-decompressing "bzImage" format.  With a little

 * work, we can load those, too. */

static unsigned long load_kernel(int fd)

{

	Elf32_Ehdr hdr;

	 * to know where it is. */

	return to_guest_phys(pgdir);

}

/*:*/

/* Simple routine to roll all the commandline arguments together with spaces

 * between them. */

	dst[len] = '\0';

}

/* This is where we actually tell the kernel to initialize the Guest.  We saw

 * the arguments it expects when we looked at initialize() in lguest_user.c:

 * the base of guest "physical" memory, the top physical page to allow, the

/*L:185 This is where we actually tell the kernel to initialize the Guest.  We

 * saw the arguments it expects when we looked at initialize() in lguest_user.c:

 * the base of Guest "physical" memory, the top physical page to allow, the

 * top level pagetable and the entry point for the Guest. */

static int tell_kernel(unsigned long pgdir, unsigned long start)

{

/*L:200

 * The Waker.

 *

 * With a console and network devices, we can have lots of input which we need

 * to process.  We could try to tell the kernel what file descriptors to watch,

 * but handing a file descriptor mask through to the kernel is fairly icky.

 * With console, block and network devices, we can have lots of input which we

 * need to process.  We could try to tell the kernel what file descriptors to

 * watch, but handing a file descriptor mask through to the kernel is fairly

 * icky.

 *

 * Instead, we fork off a process which watches the file descriptors and writes

 * the LHREQ_BREAK command to the /dev/lguest file descriptor to tell the Host

 * loop to stop running the Guest.  This causes it to return from the

 * stop running the Guest.  This causes the Launcher to return from the

 * /dev/lguest read with -EAGAIN, where it will write to /dev/lguest to reset

 * the LHREQ_BREAK and wake us up again.

 *

			if (read(pipefd, &fd, sizeof(fd)) == 0)

				exit(0);

			/* Otherwise it's telling us to change what file

			 * descriptors we're to listen to. */

			 * descriptors we're to listen to.  Positive means

			 * listen to a new one, negative means stop

			 * listening. */

			if (fd >= 0)

				FD_SET(fd, &devices.infds);

			else

{

	int pipefd[2], child;

	/* We create a pipe to talk to the waker, and also so it knows when the

	/* We create a pipe to talk to the Waker, and also so it knows when the

	 * Launcher dies (and closes pipe). */

	pipe(pipefd);

	child = fork();

		err(1, "forking");

	if (child == 0) {

		/* Close the "writing" end of our copy of the pipe */

		/* We are the Waker: close the "writing" end of our copy of the

		 * pipe and start waiting for input. */

		close(pipefd[1]);

		wake_parent(pipefd[0], lguest_fd);

	}

	return pipefd[1];

}

/*L:210

/*

 * Device Handling.

 *

 * When the Guest sends DMA to us, it sends us an array of addresses and sizes.

 * When the Guest gives us a buffer, it sends an array of addresses and sizes.

 * We need to make sure it's not trying to reach into the Launcher itself, so

 * we have a convenient routine which check it and exits with an error message

 * we have a convenient routine which checks it and exits with an error message

 * if something funny is going on:

 */

static void *_check_pointer(unsigned long addr, unsigned int size,

/* A macro which transparently hands the line number to the real function. */

#define check_pointer(addr,size) _check_pointer(addr, size, __LINE__)

/* This function returns the next descriptor in the chain, or vq->vring.num. */

/* Each buffer in the virtqueues is actually a chain of descriptors.  This

 * function returns the next descriptor in the chain, or vq->vring.num if we're

 * at the end. */

static unsigned next_desc(struct virtqueue *vq, unsigned int i)

{

	unsigned int next;

	return head;

}

/* Once we've used one of their buffers, we tell them about it.  We'll then

/* After we've used one of their buffers, we tell them about it.  We'll then

 * want to send them an interrupt, using trigger_irq(). */

static void add_used(struct virtqueue *vq, unsigned int head, int len)

{

	struct vring_used_elem *used;

	/* Get a pointer to the next entry in the used ring. */

	/* The virtqueue contains a ring of used buffers.  Get a pointer to the

	 * next entry in that used ring. */

	used = &vq->vring.used->ring[vq->vring.used->idx % vq->vring.num];

	used->id = head;

	used->len = len;

{

	unsigned long buf[] = { LHREQ_IRQ, vq->config.irq };

	/* If they don't want an interrupt, don't send one. */

	if (vq->vring.avail->flags & VRING_AVAIL_F_NO_INTERRUPT)

		return;

	trigger_irq(fd, vq);

}

/* Here is the input terminal setting we save, and the routine to restore them

 * on exit so the user can see what they type next. */

/*

 * The Console

 *

 * Here is the input terminal setting we save, and the routine to restore them

 * on exit so the user gets their terminal back. */

static struct termios orig_term;

static void restore_term(void)

{

	}

}

/* Handling output for network is also simple: we get all the output buffers

/*

 * The Network

 *

 * Handling output for network is also simple: we get all the output buffers

 * and write them (ignoring the first element) to this device's file descriptor

 * (stdout). */

static void handle_net_output(int fd, struct virtqueue *vq)

	while ((head = get_vq_desc(vq, iov, &out, &in)) != vq->vring.num) {

		if (in)

			errx(1, "Input buffers in output queue?");

		/* Check header, but otherwise ignore it (we said we supported

		 * no features). */

		/* Check header, but otherwise ignore it (we told the Guest we

		 * supported no features, so it shouldn't have anything

		 * interesting). */

		(void)convert(&iov[0], struct virtio_net_hdr);

		len = writev(vq->dev->fd, iov+1, out-1);

		add_used_and_trigger(fd, vq, head, len);

	return true;

}

/* This callback ensures we try again, in case we stopped console or net

/*L:215 This is the callback attached to the network and console input

 * virtqueues: it ensures we try again, in case we stopped console or net

 * delivery because Guest didn't have any buffers. */

static void enable_fd(int fd, struct virtqueue *vq)

{

	      strnlen(from_guest_phys(addr), guest_limit - addr));

}

/* This is called when the waker wakes us up: check for incoming file

/* This is called when the Waker wakes us up: check for incoming file

 * descriptors. */

static void handle_input(int fd)

{

}

/* Each device descriptor is followed by some configuration information.

 * The first byte is a "status" byte for the Guest to report what's happening.

 * After that are fields: u8 type, u8 len, [... len bytes...].

 * Each configuration field looks like: u8 type, u8 len, [... len bytes...].

 *

 * This routine adds a new field to an existing device's descriptor.  It only

 * works for the last device, but that's OK because that's how we use it. */

	/* Link virtqueue back to device. */

	vq->dev = dev;

	/* Set up handler. */

	/* Set the routine to call when the Guest does something to this

	 * virtqueue. */

	vq->handle_output = handle_output;

	/* Set the "Don't Notify Me" flag if we don't have a handler */

	if (!handle_output)

		vq->vring.used->flags = VRING_USED_F_NO_NOTIFY;

}

/* This routine does all the creation and setup of a new device, including

 * caling new_dev_desc() to allocate the descriptor and device memory. */

 * calling new_dev_desc() to allocate the descriptor and device memory. */

static struct device *new_device(const char *name, u16 type, int fd,

				 bool (*handle_input)(int, struct device *))

{

	/* Append to device list.  Prepending to a single-linked list is

	 * easier, but the user expects the devices to be arranged on the bus

	 * in command-line order.  The first network device on the command line

	 * is eth0, the first block device /dev/lgba, etc. */

	 * is eth0, the first block device /dev/vda, etc. */

	*devices.lastdev = dev;

	dev->next = NULL;

	devices.lastdev = &dev->next;

		verbose("attached to bridge: %s\n", br_name);

}

/*

 * Block device.

/* Our block (disk) device should be really simple: the Guest asks for a block

 * number and we read or write that position in the file.  Unfortunately, that

 * was amazingly slow: the Guest waits until the read is finished before

 * running anything else, even if it could have been doing useful work.

 *

 * Serving a block device is really easy: the Guest asks for a block number and

 * we read or write that position in the file.

 *

 * Unfortunately, this is amazingly slow: the Guest waits until the read is

 * finished before running anything else, even if it could be doing useful

 * work.  We could use async I/O, except it's reputed to suck so hard that

 * characters actually go missing from your code when you try to use it.

 * We could use async I/O, except it's reputed to suck so hard that characters

 * actually go missing from your code when you try to use it.

 *

 * So we farm the I/O out to thread, and communicate with it via a pipe. */

/* This hangs off device->priv, with the data. */

/* This hangs off device->priv. */

struct vblk_info

{

	/* The size of the file. */

	 * Launcher triggers interrupt to Guest. */

	int done_fd;

};

/*:*/

/* This is the core of the I/O thread.  It returns true if it did something. */

/*L:210

 * The Disk

 *

 * Remember that the block device is handled by a separate I/O thread.  We head

 * straight into the core of that thread here:

 */

static bool service_io(struct device *dev)

{

	struct vblk_info *vblk = dev->priv;

	struct iovec iov[dev->vq->vring.num];

	off64_t off;

	/* See if there's a request waiting.  If not, nothing to do. */

	head = get_vq_desc(dev->vq, iov, &out_num, &in_num);

	if (head == dev->vq->vring.num)

		return false;

	/* Every block request should contain at least one output buffer

	 * (detailing the location on disk and the type of request) and one

	 * input buffer (to hold the result). */

	if (out_num == 0 || in_num == 0)

		errx(1, "Bad virtblk cmd %u out=%u in=%u",

		     head, out_num, in_num);

	in = convert(&iov[out_num+in_num-1], struct virtio_blk_inhdr);

	off = out->sector * 512;

	/* This is how we implement barriers.  Pretty poor, no? */

	/* The block device implements "barriers", where the Guest indicates

	 * that it wants all previous writes to occur before this write.  We

	 * don't have a way of asking our kernel to do a barrier, so we just

	 * synchronize all the data in the file.  Pretty poor, no? */

	if (out->type & VIRTIO_BLK_T_BARRIER)

		fdatasync(vblk->fd);

	/* In general the virtio block driver is allowed to try SCSI commands.

	 * It'd be nice if we supported eject, for example, but we don't. */

	if (out->type & VIRTIO_BLK_T_SCSI_CMD) {

		fprintf(stderr, "Scsi commands unsupported\n");

		in->status = VIRTIO_BLK_S_UNSUPP;

	/* When this read fails, it means Launcher died, so we follow. */

	while (read(vblk->workpipe[0], &c, 1) == 1) {

		/* We acknowledge each request immediately, to reduce latency,

		/* We acknowledge each request immediately to reduce latency,

		 * rather than waiting until we've done them all.  I haven't

		 * measured to see if it makes any difference. */

		while (service_io(dev))

	return 0;

}

/* When the thread says some I/O is done, we interrupt the Guest. */

/* Now we've seen the I/O thread, we return to the Launcher to see what happens

 * when the thread tells us it's completed some I/O. */

static bool handle_io_finish(int fd, struct device *dev)

{

	char c;

	/* If child died, presumably it printed message. */

	/* If the I/O thread died, presumably it printed the error, so we

	 * simply exit. */

	if (read(dev->fd, &c, 1) != 1)

		exit(1);

	return true;

}

/* When the Guest submits some I/O, we wake the I/O thread. */

/* When the Guest submits some I/O, we just need to wake the I/O thread. */

static void handle_virtblk_output(int fd, struct virtqueue *vq)

{

	struct vblk_info *vblk = vq->dev->priv;

		exit(1);

}

/* This creates a virtual block device. */

/*L:198 This actually sets up a virtual block device. */

static void setup_block_file(const char *filename)

{

	int p[2];

	/* The device responds to return from I/O thread. */

	dev = new_device("block", VIRTIO_ID_BLOCK, p[0], handle_io_finish);

	/* The device has a virtqueue. */

	/* The device has one virtqueue, where the Guest places requests. */

	add_virtqueue(dev, VIRTQUEUE_NUM, handle_virtblk_output);

	/* Allocate the room for our own bookkeeping */

	/* The I/O thread writes to this end of the pipe when done. */

	vblk->done_fd = p[1];

	/* This is how we tell the I/O thread about more work. */

	/* This is the second pipe, which is how we tell the I/O thread about

	 * more work. */

	pipe(vblk->workpipe);

	/* Create stack for thread and run it */

			char reason[1024] = { 0 };

			read(lguest_fd, reason, sizeof(reason)-1);

			errx(1, "%s", reason);

		/* EAGAIN means the waker wanted us to look at some input.

		/* EAGAIN means the Waker wanted us to look at some input.

		 * Anything else means a bug or incompatible change. */

		} else if (errno != EAGAIN)

			err(1, "Running guest failed");

		/* Service input, then unset the BREAK which releases

		 * the Waker. */

		/* Service input, then unset the BREAK to release the Waker. */

		handle_input(lguest_fd);

		if (write(lguest_fd, args, sizeof(args)) < 0)

			err(1, "Resetting break");

	}

}

/*

 * This is the end of the Launcher.

 * This is the end of the Launcher.  The good news: we are over halfway

 * through!  The bad news: the most fiendish part of the code still lies ahead

 * of us.

 *

 * But wait!  We've seen I/O from the Launcher, and we've seen I/O from the

 * Drivers.  If we were to see the Host kernel I/O code, our understanding

 * would be complete... :*/

 * Are you ready?  Take a deep breath and join me in the core of the Host, in

 * "make Host".

 :*/

static struct option opts[] = {

	{ "verbose", 0, NULL, 'v' },

	/* Memory, top-level pagetable, code startpoint and size of the

	 * (optional) initrd. */

	unsigned long mem = 0, pgdir, start, initrd_size = 0;

	/* A temporary and the /dev/lguest file descriptor. */

	/* Two temporaries and the /dev/lguest file descriptor. */

	int i, c, lguest_fd;

	/* The boot information for the Guest. */

	struct boot_params *boot;

	/* The boot header contains a command line pointer: we put the command

	 * line after the boot header. */

	boot->hdr.cmd_line_ptr = to_guest_phys(boot + 1);

	/* We use a simple helper to copy the arguments separated by spaces. */

	concat((char *)(boot + 1), argv+optind+2);

	/* Boot protocol version: 2.07 supports the fields for lguest. */

 * When lazy_mode is set, it means we're allowed to defer all hypercalls and do

 * them as a batch when lazy_mode is eventually turned off.  Because hypercalls

 * are reasonably expensive, batching them up makes sense.  For example, a

 * large mmap might update dozens of page table entries: that code calls

 * large munmap might update dozens of page table entries: that code calls

 * paravirt_enter_lazy_mmu(), does the dozen updates, then calls

 * lguest_leave_lazy_mode().

 *

/*:*/

/*G:033

 * Here are our first native-instruction replacements: four functions for

 * interrupt control.

 * After that diversion we return to our first native-instruction

 * replacements: four functions for interrupt control.

 *

 * The simplest way of implementing these would be to have "turn interrupts

 * off" and "turn interrupts on" hypercalls.  Unfortunately, this is too slow:

	return lguest_data.irq_enabled;

}

/* "restore_flags" just sets the flags back to the value given. */

/* restore_flags() just sets the flags back to the value given. */

static void restore_fl(unsigned long flags)

{

	lguest_data.irq_enabled = flags;

 * it.  The Host needs to know when the Guest wants to change them, so we have

 * a whole series of functions like read_cr0() and write_cr0().

 *

 * We start with CR0.  CR0 allows you to turn on and off all kinds of basic

 * We start with cr0.  cr0 allows you to turn on and off all kinds of basic

 * features, but Linux only really cares about one: the horrifically-named Task

 * Switched (TS) bit at bit 3 (ie. 8)

 *

	current_cr0 &= ~X86_CR0_TS;

}

/* CR2 is the virtual address of the last page fault, which the Guest only ever

/* cr2 is the virtual address of the last page fault, which the Guest only ever

 * reads.  The Host kindly writes this into our "struct lguest_data", so we

 * just read it out of there. */

static unsigned long lguest_read_cr2(void)

	return lguest_data.cr2;

}

/* CR3 is the current toplevel pagetable page: the principle is the same as

/* cr3 is the current toplevel pagetable page: the principle is the same as

 * cr0.  Keep a local copy, and tell the Host when it changes. */

static void lguest_write_cr3(unsigned long cr3)

{

	return current_cr3;

}

/* CR4 is used to enable and disable PGE, but we don't care. */

/* cr4 is used to enable and disable PGE, but we don't care. */

static unsigned long lguest_read_cr4(void)

{

	return 0;

 * maps virtual addresses to physical addresses using "page tables".  We could

 * use one huge index of 1 million entries: each address is 4 bytes, so that's

 * 1024 pages just to hold the page tables.   But since most virtual addresses

 * are unused, we use a two level index which saves space.  The CR3 register

 * are unused, we use a two level index which saves space.  The cr3 register

 * contains the physical address of the top level "page directory" page, which

 * contains physical addresses of up to 1024 second-level pages.  Each of these

 * second level pages contains up to 1024 physical addresses of actual pages,

 *

 * Here's a diagram, where arrows indicate physical addresses:

 *

 * CR3 ---> +---------+

 * cr3 ---> +---------+

 *	    |  	   --------->+---------+

 *	    |	      |	     | PADDR1  |

 *	  Top-level   |	     | PADDR2  |

 *

 * ... except in early boot when the kernel sets up the initial pagetables,

 * which makes booting astonishingly slow.  So we don't even tell the Host

 * anything changed until we've done the first page table switch.

 */

 * anything changed until we've done the first page table switch. */

static void lguest_set_pte(pte_t *ptep, pte_t pteval)

{

	*ptep = pteval;

	/* Set up the timer interrupt (0) to go to our simple timer routine */

	set_irq_handler(0, lguest_time_irq);

	/* Our clock structure look like arch/i386/kernel/tsc.c if we can use

	 * the TSC, otherwise it's a dumb nanosecond-resolution clock.  Either

	 * way, the "rating" is initialized so high that it's always chosen

	 * over any other clocksource. */

	/* Our clock structure looks like arch/x86/kernel/tsc_32.c if we can

	 * use the TSC, otherwise it's a dumb nanosecond-resolution clock.

	 * Either way, the "rating" is set so high that it's always chosen over

	 * any other clocksource. */

	if (lguest_data.tsc_khz)

		lguest_clock.mult = clocksource_khz2mult(lguest_data.tsc_khz,

							 lguest_clock.shift);

 * to work.  They're pretty simple.

 */

/* The Guest needs to tell the host what stack it expects traps to use.  For

/* The Guest needs to tell the Host what stack it expects traps to use.  For

 * native hardware, this is part of the Task State Segment mentioned above in

 * lguest_load_tr_desc(), but to help hypervisors there's this special call.

 *

	return "LGUEST";

}

/* Before virtqueues are set up, we use LHCALL_NOTIFY on normal memory to

 * produce console output. */

/* We will eventually use the virtio console device to produce console output,

 * but before that is set up we use LHCALL_NOTIFY on normal memory to produce

 * console output. */

static __init int early_put_chars(u32 vtermno, const char *buf, int count)

{

	char scratch[17];

	unsigned int len = count;

	/* We use a nul-terminated string, so we have to make a copy.  Icky,

	 * huh? */

	if (len > sizeof(scratch) - 1)

		len = sizeof(scratch) - 1;

	scratch[len] = '\0';

 * Our current solution is to allow the paravirt back end to optionally patch

 * over the indirect calls to replace them with something more efficient.  We

 * patch the four most commonly called functions: disable interrupts, enable

 * interrupts, restore interrupts and save interrupts.  We usually have 10

 * interrupts, restore interrupts and save interrupts.  We usually have 6 or 10

 * bytes to patch into: the Guest versions of these operations are small enough

 * that we can fit comfortably.

 *

	asm volatile ("mov %0, %%fs" : : "r" (__KERNEL_DS) : "memory");

	/* The Host uses the top of the Guest's virtual address space for the

	 * Host<->Guest Switcher, and it tells us how much it needs in

	 * Host<->Guest Switcher, and it tells us how big that is in

	 * lguest_data.reserve_mem, set up on the LGUEST_INIT hypercall. */

	reserve_top_address(lguest_data.reserve_mem);

/*

 * This marks the end of stage II of our journey, The Guest.

 *

 * It is now time for us to explore the nooks and crannies of the three Guest

 * devices and complete our understanding of the Guest in "make Drivers".

 * It is now time for us to explore the layer of virtual drivers and complete

 * our understanding of the Guest in "make Drivers".

 */

#include <asm/processor-flags.h>

/*G:020 This is where we begin: head.S notes that the boot header's platform

 * type field is "1" (lguest), so calls us here.  The boot header is in %esi.

 * type field is "1" (lguest), so 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

 * boot. */

.section .init.text, "ax", @progbits

ENTRY(lguest_entry)

	/* Make initial hypercall now, so we can set up the pagetables. */

	/* We make the "initialization" hypercall now to tell the Host about

	 * us, and also find out where it put our page tables. */

	movl $LHCALL_LGUEST_INIT, %eax

	movl $lguest_data - __PAGE_OFFSET, %edx

	int $LGUEST_TRAP_ENTRY

	/* The Host put the toplevel pagetable in lguest_data.pgdir.  The movsl

	 * instruction uses %esi implicitly. */

	 * instruction uses %esi implicitly as the source for the copy we'

	 * about to do. */

	movl lguest_data - __PAGE_OFFSET + LGUEST_DATA_pgdir, %esi

	/* Copy first 32 entries of page directory to __PAGE_OFFSET entries.

		__free_pages(switcher_page[i], 0);

}

/*L:305

/*H:032

 * Dealing With Guest Memory.

 *

 * Before we go too much further into the Host, we need to grok the routines

 * we use to deal with Guest memory.

 *

 * When the Guest gives us (what it thinks is) a physical address, we can use

 * the normal copy_from_user() & copy_to_user() on the corresponding place in

 * the memory region allocated by the Launcher.

		lg->pending_notify = args->arg1;

		break;

	default:

		/* It should be an architecture-specific hypercall. */

		if (lguest_arch_do_hcall(lg, args))

			kill_guest(lg, "Bad hypercall %li\n", args->arg0);

	}

 * Guest makes a hypercall, we end up here to set things up: */

static void initialize(struct lguest *lg)

{

	/* You can't do anything until you're initialized.  The Guest knows the

	 * rules, so we're unforgiving here. */

	if (lg->hcall->arg0 != LHCALL_LGUEST_INIT) {

	    || get_user(lg->noirq_end, &lg->lguest_data->noirq_end))

		kill_guest(lg, "bad guest page %p", lg->lguest_data);

	/* We write the current time into the Guest's data page once now. */

	/* We write the current time into the Guest's data page once so it can

	 * set its clock. */

	write_timestamp(lg);

	/* page_tables.c will also do some setup. */

	/* This is the one case where the above accesses might have been the

	 * first write to a Guest page.  This may have caused a copy-on-write

	 * fault, but the Guest might be referring to the old (read-only)

	 * page. */

	 * fault, but the old page might be (read-only) in the Guest

	 * pagetable. */

	guest_pagetable_clear_all(lg);

}

		 * Normally it doesn't matter: the Guest will run again and

		 * update the trap number before we come back here.

		 *

		 * However, if we are signalled or the Guest sends DMA to the

		 * However, if we are signalled or the Guest sends I/O to the

		 * Launcher, the run_guest() loop will exit without running the

		 * Guest.  When it comes back it would try to re-run the

		 * hypercall. */