Booting Pintos on your laptop - Spring 2009

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 laptops do). A serial port is useful, but not necessary.

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

• You may need to apply some minor patches to the version of Pintos we distributed at the beginning of this semester. (To apply patches, use the 'patch' command. patch --dry-run tests if a patch could be applied, without actually applying it, if you're unsure what patch would do. Note that patch reads patch files from stdin, so you must use the shell's < I/O redirection.)

  1. (Possibly necessary): 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 should try that if you get stuck during bootup. This patch (console-serial-disable.c.patch) will do it:
     patch -p0 < /home/courses/cs3204/public_html/fall2008/pintos-vt-local/console-serial-disable.c.patch
     (You may need to adjust the -p0 option if you're in a different directory, read 'man patch' for details.) If you do want to reenable serial output - for instance, if your computer does have a serial COM1 port and you've attached a second computer with a terminal program such as minicom via a null modem cable ($6.95 at PC Land) to it, set the define MIRROR_CONSOLE_TO_SERIAL_PORT in your userprog/Make.var files, as shown in userprog.Make.var.patch. It is also useful to use CRLF instead of LF as a line terminator to simplify the terminal emulator's job. The serial console patch does that.

• Build your P2 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:

      cd examples
      make
      

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

• Build a bootable disk. I wrote a shell script, makedemodisk.sh, located in /home/courses/cs3204/bin/makedemodisk.sh, you may find helpful. You can run the script directly via makedemodisk.sh, but you may find it useful to make your own copy of the script (so you can change it):

      cd src
      cp /home/courses/cs3204/bin/makedemodisk.sh makedemodisk.sh
      

  Run this script from your src directory:

      ./makedemodisk.sh
      

  You should see output similar to the output shown 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, that is, whereby MIRROR_CONSOLE_TO_SERIAL_PORT is *not* defined, you should see this output instead. It's normal for the kernel to not output anything after the bootloader finishes in this version.

  The script is commented; edit the script to use a P3 or P4 kernel and to place other programs on the disk.

• Warning: please be very careful before issuing the following commands so that you don't wipe out your harddrive. In particular, be careful with writing to /dev/sda, unless you're certain the stick is at this address.

  Copy usbdisk.img onto a USB stick. You could use the command 'dd' to that end, like so

      dd if=usbdisk.img of=DISKDEVICE
      

  dd will overwrite everything that's on the USB stick, so make sure that's ok. Target has 32MB USB sticks for $4.99 that are large enough.

  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 an Apple G5 desktop with 1 internal disk, DISKDEVICE for the front USB port would likely be /dev/disk1.

  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.

  But 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 may need to use the command 'sudo' to force the execution of these commands with superuser privileges.

  On Windows, Cygwin's dd command should work as well. The syntax would be as above, with DISKDEVICE, for instance, /dev/sdb or /dev/sdc (again, be very careful to not overwrite an existing disk, which Cygwin may place at /dev/sda). cat /proc/partitions should work on recent Cygwin's as well. Be doubly careful on Cygwin because you're running with administrator privileges and so dd may not fail even if the device is in use and assigned to an internal disk.

  Other programs may work as well on Windows, such as this version of dd, which however uses a different scheme of enumerating devices.

• Try booting from the stick. You may need to set your BIOS to set to boot from USB harddisk, or you may need to press a key during startup (such as F2 or F12). Some laptops do not support booting from all USB ports, only from some. If all goes well, you should see this:

  

• Tips for when things go wrong:

  1. I'm getting all the way to where it says:

     Shell starting...
     --
     

     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.

  2. 'dd' gives a permission denied error.

     a) 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.

     b) you may need to use 'sudo' for the dd command if your /dev file requires root access.

     c), make sure you're running dd on your own machine, not on the lab cluster.

  3. 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. Try a different machine, and send us a URL with your boot image so we can try it on a machine that should work. If you do, please disable MIRROR_CONSOLE_TO_SERIAL_PORT as discussed above, then make clean and rebuild a new image.

  4. 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 disabling MIRROR_CONSOLE_TO_SERIAL_PORT as discussed above.