Lab 1: A Brand New Operating System!

Our goals for this lab are to:

Part 1: Creating the OS

In this course you will build your own OS and be responsible for maintaining it throughout the semester. Luckily, you aren’t starting from scratch. Visit this page to create a fork of the base CS 326 Operating System, FogOS. You’ll use it as a starting point for your work in the class.

Since everything you do in CS 326 will build off the code you create today, it’s worth getting it right. So don’t rush things.

Getting set up

Once you’ve created your OS repo, you’ll need to clone it to start working.

First, we need to access the department’s Jump Host, stargate:

ssh username@stargate.cs.usfca.edu

Once you’ve logged in (the default password is your student ID… you should probably change it if you haven’t already), head over to our virtualization host, gojira:

ssh gojira

When you see a giant ASCII art Gojira appear on the screen, you will know you’re in the right place.

You might be used to cloning your git repositories directly in your home directory, but gojira has a separate disk with much more storage space in /raid. To access your storage directory, simply run cd /raid/$(whoami). The $(whoami) in the command will resolve to whatever your username is, so when I do this I get:

$ cd /raid/$(whoami)
$ pwd
/raid/mmalensek

NOTE: if this step fails and your directory isn’t there, angrily yell at the course staff!

Now you can git clone git@github.com:usf-cs326-.......(your path here)....

If that doesn’t work, then you probably need to add your public key to your Github account. First, check to see if you have any public keys (this has to be done on a CS machine):

$ ls ~/.ssh/id_*.pub

If you don’t have an id_*.pub file, run ssh-keygen to create an SSH key pair. You can accept the default settings, then follow the next steps.

If you have an id_*.pub file, head to Github, click your profile, then Settings, SSH and GPG Keys, New SSH Key. Give the key a name (maybe ‘CS 326’, ‘USF CS’, etc) and paste the contents of the id_*.pub file in the ‘key’ text box. To get the contents of the file, you can use cat ~/.ssh/id_*.pub and paste the whole line in.

Starting Up

To make sure everything is okay, cd into your OS project directory you just cloned and run make. This process will build the OS, and once that finishes running make qemu will run it. The OS should boot!

You might be wondering what make qemu means. This runs your OS in the QEMU emulator, so now you’ve got an OS running on emulated hardware on another OS. Wild! But why? Well, our OS is designed for RISC-V CPUs and the machine we’re using has an x86-64 CPU, so we’re basically having QEMU translate from one architecture to another.

Anyhow, run ls to see what the root of the file system on your OS looks like. There are some other programs (commands) already available, go ahead and try them!

Once you’re done, you can press CTRL A then X to quit (NOTE: that’s not CTRL A CTRL X, it’s just CTRL A, release the keys, and then press X). This will return you to the familiar Linux environment you know and love, and will be standard practice throughout the semester – edit the OS on Linux, then build and run it in QEMU.

Part 2: Getting to Know You

So, great job. You created an OS. All in a day’s work, right? Now we need to get better acquainted. To do this, you’re going to add an about command to your OS so when the course staff runs it they can learn all about you.

Here’s a demo (instructions follow):

$ /about
Welcome to <OS NAME HERE>!
-------------------------------------
Author: Matthew Malensek
USF Username: mmalensek
Preferred Name: Matthew
Pronouns: he/him/his
About me:
        I am originally from Glenwood Springs, Colorado, a town with more
        bears than people (that's not actually true, don't Google it). In
        my free time, I like to drink coffee and listen to music.

        In class, I enjoy making bad jokes. FYI: they don't get any better
        as the semester goes on.

        I hope to do everything in my power to make this a great semester
        for you! Please reach out if you need anything at any time.

Here is the REQUIRED information:

The rest of the information is OPTIONAL:

For the “about me” section, please let me know if there’s anything I can do to accommodate your learning in this class.

Adding a New Utility

We will add about as a new command line utility.

Operating systems are generally split in two pieces: kernel space, and user space. A command line utility doesn’t really interact directly with the hardware or need to manage other programs or resources, so we need to modify user space for this.

First, create user/about.c and add an empty main() { ... } to it. Next, we need to tell make how to build the new utility, so open up Makefile and locate the UPROGS variable. Add $U/_about\ to the beginning of the list. The part of the Makefile you want looks something like this:

UPROGS=\
        $U/_cat\
        $U/_echo\
        $U/_forktest\
        $U/_grep\
        $U/_init\
        $U/_kill\
        $U/_ln\
        $U/_ls\
        $U/_mkdir\
        $U/_rm\
        $U/_sh\
        $U/_stressfs\
        $U/_usertests\
        $U/_grind\
        $U/_wc\
        $U/_zombie\

There’s a bit to unpack here:

To make your life and the life of the course staff easier, keep your UPROGS variable in alphabetical order.

Go ahead and run make – it’ll build your new (empty) program. If that works, then you can move on to the actual program implementation.

Implementing ‘About’

Hopefully you already have a good idea of what user/about.c should contain. However, you might notice that some things work slightly different in this environment. If you add the usual #include <stdio.h> to use standard I/O library functions, things break. To figure out what you should include instead, take a peek at the source code of some of the other utility programs. echo might be a good place to start.

Once you’re finished, to make sure everything works, double check the following:

$ make clean
$ make qemu

... boot info displays ...

$ /about
Welcome to FranciscOS!
-------------------------------------
Author: Don Francisco
USF Username: don
About me: I like fog and sea lions.

Part 3: Remembering How to C

In 326, C sells C shells down by the C shore. Can’t you C it?

C is the lingua franca of OS development. This lab includes a series of exercises to help get the C flowing again.

Preparation

First, log into gojira and grab a copy of broken.c. The program is named after the brokenness of your professor’s spirit. If you’d like, you can download it directly with wget:

cd /raid/$(whoami)/
cd os-githubusername/user     # e.g., cd os-malensek/user
wget 'https://www.cs.usfca.edu/~mmalensek/cs326/assignments/code/broken.c'

This downloads broken.c to the ‘user’ directory of your OS repo.

Then you need to update the Makefile to build this new program, just like we did for the about utility. It should be called broken so we can run /broken and see the results. Note that the program will most likely crash in the state it has been given to you; that’s part of the “fun.”

Fixing What’s Broken

The exercises in broken.c all have something wrong with them. Your job is to:

  1. Determine what the problem is
  2. Fix the problem
  3. Explain what was wrong (why the bug occurred) and how you fixed it. Edit the comments at the top of each function to give your explanation.

You can work on this lab with other students in class (please limit groups to 3 students max). Discussing the problems with others and experimenting is a good way to figure out what’s wrong. However, the final submission you make should represent your own work and ideas/thoughts – not a copy of someone else’s.

Grading and Submission

To receive 70% credit:

To receive 90% credit:

To receive full credit for this lab:

Once you are finished, check your changes into your OS repo. Then have a member of the course staff take a look at your lab to check it off. You may need to retry some of the problems if you missed something – so give yourself some extra time to finish this!