Booting PintOS

Before going ahead with the instructions on this page, please make sure that you have installed all the prerequisites for this project as outlined in this document. We also assume that you have successfully accepted the project assignment.

Now click on the blue “Open in Visual Studio Code” on the home page of your github repository (e.g. https://github.com/hkaiserteaching/csc4103-spring2025-project0-your-name), you should see VSCode open a window on your local machine with the repository cloned.

The starter repository has been set up in a way that allows to seamlessly run the project in an docker environment after you opened VSCode connected to the Docker image. Now, when you ls, you will find there are new directories called results and src under your home directory in the container, those are shared by the container and your host laptop.

Now here comes the exciting part, type the following commands in a VSCode terminal window that is opened.

cd /pintos/src/userprog/
make
cd build
pintos -- -q

The last command will trigger Bochs (the emulation system used by default) to simulate a 32-bit x86 machine and boot your PintOS on it. You should see something like:

========================================================================
                       Bochs x86 Emulator 2.6.11
              Built from SVN snapshot on January 5, 2020
                Timestamp: Sun Jan  5 08:36:00 CET 2020
========================================================================
00000000000i[      ] BXSHARE not set. using compile time default '/usr/local/share/bochs'
00000000000i[      ] reading configuration from bochsrc.txt
00000000000i[      ] installing nogui module as the Bochs GUI
00000000000i[      ] using log file bochsout.txt
PiLo hda1
Loading.............
Kernel command line: -q
Pintos booting with 4,096 kB RAM...
383 pages available in kernel pool.
383 pages available in user pool.
Calibrating timer...  102,400 loops/s.
hda: 1,008 sectors (504 kB), model "BXHD00011", serial "Generic 1234"
hda1: 215 sectors (107 kB), Pintos OS kernel (20)
Kernel PANIC at ../../filesys/filesys.c:20 in filesys_init(): No file system device found, can't initialize file system.
Call stack: 0xc002ad3f 0xc002f278 0xc0020405.
The `backtrace' program can make call stacks useful.
Read "Backtraces" in the "Debugging Tools" chapter
of the Pintos documentation for more information.
Timer: 97 ticks
Thread: 0 idle ticks, 33 kernel ticks, 64 user ticks
Console: 679 characters output
Keyboard: 0 keys pressed
Exception: 0 page faults
Powering off...

Please don’t worry about the kernel PANIC complaining about a missing file system device. That is expected at this point.

Your PintOS has been booted successfully, congratulations :)

Please take a screenshot of your VSCode environment that shows the above boot message. You will need to provide this as part of your project 0 submission to prove you have successfully set up your PintOS environment. Please place the screenshot as booting_pintos.png in the directory results, next to the file answers.md.

You can shut down the Bochs emulator by Ctrl+a+x or Ctrl+c if the previous one does not work.

PintOS will exit immediately after booting (because of the -q on the command line), so you may not see much useful information in the output. Don’t be disappointed.

What’s the magic?

Now let’s conclude what you have done. First, You used docker to run a Ubuntu container that functions as a full-edged Linux OS inside your host OS. Then you used Bochs to simulate a 32-bit x86 computer inside your container. Finally, you booted a tiny toy OS – PintOS on the computer which Bochs simulates. Wow, virtualization is amazing, right?

Throughout this semester, you can modify your PintOS source code in your host machine with your favorite IDE but compile/run/debug/test your PintOS in the container. You can leave the container running when you are modifying PintOS, because your modification will be visible in the container immediately.

The next step for this assignment is described here.