CMPS 111, Spring 2007

Projects

Here, you'll find information that applies across all of the projects. Project-specific information can be found in each project's home page. There will be four projects assigned this quarter, each one due about 2 weeks after it is assigned. Due dates are listed on the schedule and each individual project description:

Design & documentation

The assignments in this class do not typically require you to write large quantities of code. For most assignments, you need only write several hundred lines of code, if not fewer. However, the concepts covered in class and in the operating system are quite difficult for most people. As a result, deciding which lines of code to write is very difficult. This means that a good design is crucial to getting your code to work, and well-written documentation is necessary to help you and your group to understand what your code is doing. A sample design document is available online.

The most important thing to do is write your design first and do it early! Each assignment is about two weeks long; your design should be complete by the end of the first week. Doing the design first has many advantages:

Doing your design early is the single most important factor for success in completing your programming projects!

Using the MINIX 3.0 kernel

This quarter, we will be using the MINIX 3.0 kernel for our programming assignments. This is a complete (and working) operating system, and is well documented in the textbook Operating Systems Design and Implementation (3rd edition). There's also lots of documentation at the MINIX web site.

The MINIX operating system comes with a complete set of tools, including C compiler and linker as well as debugger. MINIX can run on raw x86 hardware, but we recommend using an x86 emulator such as Qemu or Bochs (both open source and freely available) instead. Sure, they're not as fast as raw hardware, but they're plenty fast for running MINIX. Besides, you can also run MINIX under VMware, which is commercial software, if you want additional speed. Below, you'll find instructions on how to run MINIX on Mac OS X, Windows XP, Linux, and the unix.ic Solaris system. If you use unix.ic, the simulator has been downloaded and installed for you. Otherwise, you'll need to download a copy for yourself.

Installing the emulator and MINIX

MacOS X instructions

  1. Download the MINIX boot CD from the UC Santa Cruz site. Please make sure you use this image (not the original) in case we need to make bug fixes.
  2. Download Qemu for the Mac. You can get it from its original site, or get the copy we've got here at UC Santa Cruz.
  3. Unpack Qemu and drag it to your Applications folder. Double click Qemu to run it.
  4. Create a new compressed disk image (Tools -> Create new DiskImage). The image should be at least 200 MB. You may store it wherever you like; just make sure you remember where you put it!
  5. Create a new Guest PC (Guest PC -> New Guest PC). The options you should use are shown in these panels:
    Please note that you should pick the boot CD image file and compressed disk image you created in steps 1 and 4. When you're done, click "Create PC" and you'll see the new PC in the window that lists PC images.
  6. You can start the PC using the "play" button and stop it using the power button on the window that the guest PC brings up. You must click "Save PC" when you shut down the PC window if you want to resume where you "left off".

Windows XP instructions

Thanks to Jeff Hagen, our TA, for these instructions.

  1. Download Bochs for Windows from either the "official" site or from UC Santa Cruz.
  2. Execute the installer, and perform a normal installation.
  3. Download the MINIX boot CD from the UC Santa Cruz site. Please make sure you use this image (not the original) in case we need to make bug fixes. Place that image in the same directory that Bochs is installed to.
  4. Create a new disk image. The image should be at least 200 MB. Run the "bximage" program and create a "flat" disk image. Do not close the program after it creates the disk image.
  5. Now, run the simulator to edit the options. Add the new disk image to the simulator. Use options 3->8->4. Enable the image by saying "yes". Then select a type of "disk". Type in the filename of the new disk image you created. Now, we want the same information from the image program to be entered into the simulator. The model name, detection type, and translation type can be left default.
  6. Next we need to mount the CD image so that we can install Minix. From the disk image menu, use option 5. Enable the device, then choose type "cdrom". Now enter the filename of the Minix installer ISO that you downloaded. Don't forget the .iso at the end.
  7. Next change the boot order so that the simulator will boot the CDrom first, then the disk. Use options 15 (cdrom) and 16 (disk).
  8. Now, go back to the main menu 0->0 and save the options in a file called "bochsrc". This file will be automatically loaded each time the simulator starts up. If you name the file something else you will have to load it manually.
  9. You can now start the simulator.
  10. You can download my log files to see the installation steps I used. The install log and the disk creation log are both available.
  11. After installing, go back into the options menu and remove the CDrom image. From the main screen, options 3->8->5 "no". Then save the configuration file again.

Linux instructions

Thanks to Jeff Hagen, our TA, for these instructions.

  1. Pick a linux that hasd bochs in its package manager. I'm partial to Mandriva.
  2. Install bochs. In mandriva, as root: urpmi bochs && urpmi -a bochs-
  3. Create a new directory to run bochs in.... Put my bochs configuration file in it. Rename this file to "bochsrc.txt"
  4. Download both the CD Image and floppy image, and put them in your new bochs directory.
  5. Make a new disk image in the same way that it is made under Windows. Use the bximage program to create it. It must be at least 200 MB. I have a log of how to create it.
  6. Start bochs and install Minix. Then exit the simulator.

At this point you should be able to run the simulator.

To transfer stuff on and off your virtual floppy, mount it under linux with the following command: 

mount -o loop -t msdos minuxfloppy.img /mnt/floppy

Solaris (unix.ic) instructions

If you plan to use unix.ic as your development platform, you'll need a lot of extra space to keep the hard disk image that contains your files. 160 MB extra should be enough; please ask the course staff early to ensure that the space is there when you need it. You won't need to do any work on unix.ic (other than submitting your assignment) if you have a computer running Mac OS X, Windows XP, or Linux at home because all of the code you'll be writing and modifying runs (and is compiled) in Minix itself, which runs the same regardless of which system is running the simulator.

Having said that, both Qemu and Bochs are installed on unix.ic, as is the MINIX boot CD image (in /afs/cats/courses/cmps111-elm/minix/minix-IDE-3.1.1.iso) You shouldn't copy any of these files to your home directory; instead, link to them or make references in the appropriate configuration files.

We recommend that you use Qemu on unix.ic. The binaries for it are located in /opt/csw/bin. Follow these steps:

  1. Get an increased quota for your unix.ic account. You must do this step first!
  2. Create a disk image to use for your emulator using this command (or something like it):
    qemu-img create -f qcow minixdisk.qcow 160M
    This will create a 160MB disk image in the compressed copy-on-write (qcow) format. The disk image will be called minixdisk.qcow.
  3. Run Qemu with the qemu-launcher-gui command. Note that Qemu uses the X11 windowing system, so you'll need an X11-based system to do this. If you're running on a Mac or PC, use the instructions above to run locally.
  4. Click "Add" to add a new virtual machine. Modify its name to whatever you want to call it ("Minix VM" might be a good choice).
  5. Type the full pathname of the file you created in step 2 on the line labeled "HDA".
  6. Type the full pathname to the MINIX CD-ROM image on the line labeled "CD-ROM".
  7. Set the memory size to 64 or 128 MB.
  8. Set the boot device to "Cd-Rom".
  9. Check the "Local Time" box.
  10. Click the "Save" button to save the configuration.
  11. To run the system, use the "Launch" button.
  12. Once you've installed Minix on your hard disk image, you should change the boot device to "Hard-disk" and click "Save" to save the configuration.

If you want to use Bochs, you'll need to follow instructions similar to those for Windows XP. You won't need to download the Bochs executable (it's in /afs/cats/courses/cmps111-elm/bin), and you can use the Minix disk image directly from its location listed above. However, you'll need to configure Bochs before you can use it. When you start Bochs (by typing bochs on the command line), you get a text menu that lets you edit your configuration file. This configuration file is named .bochsrc, and is stored in your home directory. Follow the Windows XP instructions (except for using a 160 MB disk) to get Bochs running.

Moving stuff between host OS and MINIX

The easiest way to move things between your host OS and MINIX is probably to create a floppy disk and make it available to your emulator. Mac OS X can mount a floppy disk directly, or you can use mtools to copy files to or from the image file. You may need a blank floppy image to get started; one is available from the software section . Once you have one, you can copy files to or from it in the host OS, unmount it from the host OS, and mount the floppy image in your emulator (Bochs or Qemu). Then, you can use dosdir, dosread, and doswrite in MINIX to move files between MINIX and the floppy image.

Debugging & testing

More to come.

Handing in the project

Each project must be handed in using the submit system on unix.ic. For each project, hand in documentation, code, and any test files you created (scripts or data).

Design documentation

Your design documentation should describe the design of your project. This includes the data structures you're going to use, as well as the high-level pseudo-code for each high-level function. You must document functions that are "visible" to code you didn't write. You may also have "internal" functions; you don't have to document them. However, we suggest that you document major functions that aren't visible—it makes design simpler—but you don't have to include every single function you're going to implement in your design document. A sample design document is available online.

Documentation must be in one of two file formats: plain ASCII text, or Adobe Portable Document Format (PDF). However, you don't have to purchase Adobe Acrobat to generate PDF. Instead, print your document to a file (this works on Macs, PCs, and Unix) and then use the Unix command ps2pdf on the Instructional Computing cluster to convert PostScript to PDF. Regardless of how you generate your PDF file, please stick to the basic fonts—Times, Helvetica, Courier, and Symbol—to ensure that it'll display correctly on most computers and printers.

Your final design document will be turned in as part of your full project, and will be the basis for the design grade for your project. Your design document should be called either design.txt (if the document is in ASCII) or design.pdf (if it's in PDF).

Project code

Please turn in all of the files you modified to build your project: source code, Makefiles, and any other scripts you may have used. In addition, please include a README file to explain anything unusual to the TA—testing procedures, etc. Your code should unpack properly in a "clean" MINIX distribution so it can be built. You can select individual files to include in your tar file by executing commands like this at the "root" of your source tree:

tar cf proj1.tar design.pdf fs/file1.c mem/file2.c

This will include file1.c from the fs directory and file2.c from the mem directory along with design.pdf in the "main" directory. When the tar file is unpacked, the files will go back to their original locations.

Turning in files

Please turn in exactly one file for each project: a compressed tar file containing your design document and all of your source code, test files, Makefiles, and anything else you need to run the code.

You can turn in the files by running this Unix command in your project directory:

submit cmps111-dl.s07 projn  projn.tar.gz

Note that you can compress a file by using a command like gzip projn.tar.

Grading the projects

The intent of the grading for the project is not to differentiate among those students who do a careful design and implementation of the assignments. Rather, the grading helps us identify those students who (i) don't do the assignments or (ii) don't think carefully about the design, and therefore end up with a messy and over-complicated solution. Remember that you can't pass this course without at least making a serious attempt at each of the assignments. Further, the grading is skewed so that you will get substantial credit for a clean, logical, easy-to-understand design, even if your implementation doesn't completely work. This means that you should first strive to come up with a clean design of your project on paper. Also, don't try to add fancy features just because someone is!

The grade for each project will be 40% for design and 60% implementation. We've structured the grading in this way to encourage you to think through your solution before you start coding. If all you do is to work out a detailed design for what you would do to address the assignment (and if the design would work!), but you write no code, you'll still get almost half of the credit for the assignment. The implementation portion of the grade considers whether you implemented your design, ran reasonable test cases, and provided documentation that the TA could understand. Part of being a good computer scientist is coming up with simple designs and easy-to-understand code; a solution that works isn't necessarily the best that you can do. Thus, part of the design and implementation grade will be based on whether your solution is elegant, simple, and easy to understand.

Software

This a list of software that might be useful for CMPS 111 projects

MINIX / general

Mac OS X

Windows XP

Source code

Additional Resources

Last updated 10 Apr 2007 by Ethan L. Miller