Pintos (UChicago edition)

h1. Booting Pintos from a USB drive

_These instructions are adapted from this document: http://courses.cs.vt.edu/~cs3204/fall2009/pintos-vt-local/bootingpintos.html_

The current version of Pintos is able to boot from USB on selected hardware. To be able to boot, your PC or laptop must support booting from a USB harddisk and it must contain a UHCI controller (most recent computers do).

You should be able to create a bootable image from a fully working Project 2 solution as follows (for Project 3 or Project 4 solutions, adjust the instructions accordingly):

# (Necessary on the Maclab machines, possibly necessary on some systems) On some systems, especially laptops that have a built-in serial port that is not connected to the outside, you may need to disable Pintos's serial port output. You can do this by defining DISABLE_CONSOLE_TO_SERIAL_PORT in your userprog/Make.var files. For example:

<pre>

kernel.bin: DEFINES = -DUSERPROG -DFILESYS -DDISABLE_CONSOLE_TO_SERIAL_PORT

</pre>

# Build your Project 2 kernel via make in userprog/build. This should leave a bootable kernel image in kernel.bin.

# Build the programs in your examples directory. Running @make@ in @examples@ will do it:

<pre>

cd examples

make

</pre>

You may wish to customize the @examples/shell@ program to output a customized "Welcome" message.

# Build a bootable disk. You can use the makedemodisk.sh script provided in the @src/@ directory. Run this script from your @src@ directory:

<pre>

./makedemodisk.sh

</pre>

You should see output similar to the output shown [[BootingPintosUSB_makebootdiskoutput|here]]. This will leave a disk image called @usbdisk.img@ in the @src@ directory. If you are running a kernel with serial console output disabled (where DISABLE_CONSOLE_TO_SERIAL_PORT is defined) you should see a different output (also shown [[BootingPintosUSB_makebootdiskoutput|here]]). It's normal for the kernel to not output anything after the bootloader finishes in this version.

# By default, the bootable disk will build a Project 2 kernel, and will run the @shell@ program on boot. The script is commented; edit the script to use a Project 3 or Project 4 kernel and to place other programs on the disk. 

# Copy @usbdisk.img@ onto a USB stick with the @dd@ command:

<pre>

dd if=usbdisk.img of=DISKDEVICE

</pre>

*Warning: please be very careful before running this command so that you don't wipe out your hard drive*. On most OSs, disks are numbered 'sda', 'sdb', 'sdc' or 'disk0', 'disk1', etc. in the order in which the OS detects them. The internal disks are detected first, so they will receive lower numbers. Disks that are added later (by plugging in a USB device, for instance), will receive the next available number.

On a Linux machine, it would be one of /dev/sda, /dev/sdb, /dev/sdc, etc. (After you plug in the USB stick, use the 'dmesg' command to find out which device was assigned to the new USB device. Use the command cat /proc/partitions to see which partitions exist. On Linux, the internal hard drive, if it's a IDE drive, may be assigned /dev/hda, in which case the USB stick may be at /dev/sda.

On a Mac with 1 internal disk, DISKDEVICE for a USB port would likely be /dev/disk1.

*WARNING: dd will overwrite everything that's on the USB drive.* Be careful to not use a device that's currently in use in your system, such as a different USB device or a SCSI disk. Running 'dd' would overwrite whatever is on that device; you do not want that if the device holds the filesystem of your host OS. The consequence of getting this wrong is loss of all data on the hard drive with no way to recover. Use the 'mount' command to verify that there's no filesystem mounted at the device you think the USB stick is at. Hint: it's most likely /dev/sdb or beyond, less likely /dev/sda.

On both Mac OSX and Linux, you will probably need to use the command 'sudo' to force the execution of these commands with superuser privileges.

# Try booting from the stick. You may need to set your BIOS to set to boot from a USB drive, or you may need to press a key during startup (such as F2 or F12). The Maclab machine reserved for OS are already set up to boot up _only_ from USB (in fact, they don't even have hard drives)

h2. FAQ

# _I'm getting all the way to where it says:

<pre>

Shell starting...

--

</pre>

but when I type something, nothing (or garbage) appears._

This indicates a problem with your kernel. The shell tries to read characters via the read() system call from the console. It uses file descriptor 0. The read(0,...) system call is, unfortunately, not exercised by any other test. You need to implement read(0,...) using the input_getc() function as described in the specification. Make sure that you read() as many characters as the user program asks you to.

# _dd gives a permission denied error_

#* Ensure that the USB stick isn't accidentally mounted (if you buy a new one, it has a FAT file system on it, and many OS - including Mac OSX, Linux, and Windows are set up to automatically mount it.) If so, unmount it using 'sudo umount /dev/....', then try dd.

#* You may need to use 'sudo' for the dd command if your /dev file requires root access.

#* Make sure you're running dd on your own machine, not on the lab cluster.

# _It correctly finds the USB stick during USB device detection, but gets stuck when trying to load the shell executable here: @Executing 'shell':@_

This likely means your USB controller is not correctly supported. This should not happen on the Maclab machines.

# _It gets stuck very early on, maybe around here: Initializing EHCI_

This may be an indication that your machine may have issues with its serial port. Try defining DISABLE_CONSOLE_TO_SERIAL_PORT as discussed above.