CompSci 143A: Principles of Operating System

Instructor: Ardalan Amiri Sani

Pintos Project Setup

To develop the Pintos projects, you'll need two essential sets of tools:

Your Openlab accounts have all the tools needed to build Pintos and the Bochs emulator. Here are the instructions to do this

1. Create “Pintos” directory in home directory:

  
$ mkdir Pintos

2. Get pintos from git in this directory:

  
$ cd Pintos
$ git clone https://github.com/trusslab/pintos.git

3. Create “bochs” directory in “Pintos” directory:

  
$ mkdir bochs

4. Go into pintos/src/misc/:

  
$ cd pintos/src/misc/

5. To build and install bochs, execute::

  
$ ./bochs-2.6.2-build.sh ~/Pintos/bochs

6. Create “bin” and “misc” directories inside “pintos” directory::

  
$ cd ~/Pintos/pintos/
$ mkdir bin
$ mkdir misc

7. Build utils:

  
$ cd ~/Pintos/pintos/src/utils/
$ make

8. Copy/install files:

  
$ cp backtrace pintos Pintos.pm pintos-gdb pintos-set-cmdline pintos-mkdisk setitimer-helper squish-pty squish-unix ~/Pintos/pintos/bin/
$ cp ~/Pintos/pintos/src/misc/gdb-macros ~/Pintos/pintos/misc/

9. Update path. add the following lines to the ~/.bashrc file, e.g., using the vim text editor ($ vim ~/.bashrc):

  
export PATH=$PATH:~/Pintos/pintos/bin/
export PATH=$PATH:~/Pintos/bochs/bin/

10. Reload ~/.bashrc:

  
$ source ~/.bashrc

Besides the lab machines, you may want to work on the projects on your own machines to be more productive. If you have a Linux distrobution OS (e.g., Ubuntu), you can use the instructions above for your own machine too. If you have successfully followed the instructions so far, you do not need to continue.

The rest of this page contains more instructions to help you with the setup of the core development environment needed for Pintos on your own machines. They are intended for Unix and Mac OS machines. If you are running Windows, we recommend you to run a virtual machine with Linux or you will have to setup Cygwin first. This guide, and the course in general, assumes you are familiar with Unix commands.

Compiler toolchain

The compiler toolchain are a collection of tools that turns source code into executable binaries for a target architecture. Pintos is written in C and x86 assembly, and runs on 32-bit 80x86 machines. So we will need the C compiler (gcc), assembler (as), linker (ld) and debugger (gdb).

If you are using a Linux machine, it is likely equipped with the compiler toolchain already. But it should support 32-bit x86 architecture. A quick test of the support is to run objdump -i | grep elf32-i386 in the terminal. If it returns matching lines, your system’s default tool chain supports the target so you can skip this section. Otherwise, you will need to build the toolchain from source. If you are using MacOS, you have to build the toolchain from source because MacOS’s object file format is not ELF that we need (and the objdump -i test won’t work).

When you are building the toolchain from source, to distinguish the new toolchain from your system’s default one, you should add a i386-elf- prefix to the build target, e.g., i386-elf-gcc, i386-elf-as.

Note
We've provided a script (pintos/src/misc/toolchain-build.sh) that automates the following building instructions. So you can just run the script and modify your PATH setting after the build finishes. The script has been tested on recent version of Ubuntu, Mac OS and Fedora.
Note
After building and installing the toolchain, you need to make sure they are in the PATH. Put export PATH=/path/to/swd/x86_64/bin:$PATH to the end of your terminal config file (e.g., .bash_profile) so that they are set automatically when you login. Remember to replace /path/to/swd/x86_64/bin with the actual path, e.g., ~/318/toolchain/x86_64/bin. You may also want to delete the source and build directories in /path/to/swd/{src,build} to save space.

x86 Emulator

Pintos Utility Tools

The Pintos source distribution comes with a few handy scripts that you will be using frequently. They are located within src/utils/. The most important one is the pintos Perl script, which you will be using to start and run tests in pintos. You need to make sure it can be found in your PATH environment variable. In addition, the src/misc/gdb-macros is provided with a number of GDB macros that you will find useful when you are debugging Pintos. The pintos-gdb is a wrapper around the i386-elf-gdb that reads this macro file at start. It assumes the macro file resides in ../misc.

The example commands to do the above setup for the Pintos utilities are: (replace /path/to/swd/x86_64 with the actual directory path) 

$ cd pintos/src/utils && make
$ cp backtrace pintos Pintos.pm pintos-gdb pintos-set-cmdline pintos-mkdisk setitimer-helper squish-pty squish-unix /path/to/swd/x86_64/bin
$ mkdir /path/to/swd/x86_64/misc
$ cp pintos/src/misc/gdb-macros /path/to/swd/x86_64/misc

Others

Mac Users

The original Pintos was mainly developed and tested for Linux (Debian and Ubuntu in particular) and Solaris. It has some issues to run on Mac OS. We have fixed a number of issues and provided scripts to make it run more smoothly with Mac OS. They should be working mostly. But one caveat that you should be aware of is that the setitimer system call (used by the pintos script to control runtime of tests) in Mac OS seems to have some bug, which may trigger premature timeout when using pintos with --qemu. To work around this, you can either use the Bochs simulator --bochs instead (modify the src/{threads,userprog,vm,filesys}/Make.vars) or increase the timeout passed to pintos (e.g., change TIMEOUT in src/tests/Make.tests to 400).

Pintos Infinite Loop Issue

Currently, the Openlab's compiler toolchain is not compatible with our Pintos. That results in an infinte loop when you run the command pintos --bochs -- run alarm-zero.

For that, we are distributing the compatible toolchain. Below are the instructions for installation.