Warm Up Bonus

Contents

  1. Due Dates and Mark Distribution
  2. Introduction
  3. Getting Started
  4. Reading Component
  5. Working with the Kernel
  6. Your Task
  7. Submitting

1. Due Dates and Mark Distribution

Due Date: 8am (08:00), Mon March 20th (Week 4)

Marks: Worth 10 bonus marks (contributing to the 100 potential class marks available in the course)

This warmup is done as an individual.

No other bonuses apply for this warmup exercise.


2. Introduction

The aim of the warmup exercise is to have you familiarise yourself with the environment you will be using for the actual assignments. The exercise consists of two parts, an exercise for bonus marks and a non-assessable component. The non-assessable component consists of a set of directed questions to give you practice navigating and reading the code base. The answers to this code reading Q & A component of the exercise are available on the wiki (improvable by you the students). The bonus exercise consists of you making a very minor change to the existing OS and learning the submission process. The change is conceptually trivial, so you can view this exercise as us giving away marks as an incentive for you to get the assignment environment up and running early in the session in preparation for the assignments.

Note that this exercise is not indicative of the level of difficulty of the actual assignments. The assignments are much more challenging.

The OS/161 Environment

This assignment will introduce you to the components of the environment you will use during the semester:

The introduction to the OS/161 system explains how the components of the OS/161 system fit together, and contains important information about using the tools. You should take the time to read it now.

Subversion

Subversion is a source code management system used to track changes to a piece of software. We make use of Subversion in this course to allow you to manage the large code base (compared to most previous assignments you have done), and recover from potential problems. Subversion keeps a recoverable copy of specified versions of all your OS/161 files. It allows you to track the changes you have made, and more importantly, rollback to a known state if things get out of hand.

Subversion also enables you and your partner to work on the same code repository in a coordinated way. You can even work on versions of your code stored at home and at CSE.

Subversion is a large system of which you need to know only a small subset. We will give you directions for the parts you need to know. If you're curious, you can find detailed docs on Subversion at subversion.apache.org, in addtion to the resources indicated on the course web site.

Note: Those confident in the use of git can use it instead, but you're unsupported if in the unlikely event something goes wrong with version control. The forum has a good post on using git here.

We choose subversion over git as it has a smaller learning curve, and tends to be easier to recover from mistakes.


3. Getting Started

Setting up your account

For this exercise, you will be working by yourself (for later assignments, you will work with a partner).

First, you will need to set up various environment variables for you to access the tools needed for the course. Simply run

% 3231
in each new shell you use when working on the exercise. If you know what you're doing you can add /home/cs3231/bin and /home/cs3231/bin-${ARCH} to your PATH to avoid having to type
3231
every time you open a new terminal window.

Note: You must not have "." (or equivalent) prior to "/bin" in your PATH. The build will fail later if you do. Note: doing this is generally a really bad idea for security reasons anyway.

Obtaining and setting up the distribution with Subversion

Subversion is a "centralised" revision control system, which means that you will be checking code out of, and committing code back into, a single repository. In this section, you will be setting up the Subversion (often abbreviated "svn") repositories that you will work on. For this exercise, you will use a repository in your own home directory. For subsequent assignments, you and your partner will share a repository in your group's directory.

You should now have an asst0-src directory to work on.


4. Reading component

Now that you have an OS/161 source tree, read the code walkthrough.

This component of this warmup aims to guide you through the code base to help you begin comprehend its contents, identify what functionality is implemented where, and be able to make intelligent decisions on how to modify the code base to achieve the goals of the assignments.

Note that while the code reading component is not assessable, we view it as the ideal opportunity to get to know your way around the code, including practicing with whatever code browsing tool or editor you plan to use. You will benefit in the assignments by practicing navigating around and developing a rudimentary understanding of the code base. The code reading component is here to give you some of that practice.


5. Working with the Kernel

Building a Kernel

Now to the business end of this exercise. You will now build and install a kernel.

Running your Kernel

If you have made it this far, your have built and installed the entire OS. Now it is time to run it.

Using GDB

I cannot stress strongly enough to you the need to learn to use GDB. Read the directions and short tutorial on using GDB with OS/161.

Note: the version of GDB used for these assignments is os161-gdb.

Modifying your Kernel

We will now go through the steps required to modify and rebuild your kernel. We will add a new file to the sources. The file contains a function we will call from existing code. We need to add the file to the kernel configuration, re-config the kernel, and the rebuild again.

Note: If you simply modify a file in an already configed source tree, you can simply run bmake again to rebuild, followed by bmake install. You only need to reconfigure it if you add or remove a file from the config, and you only need to bmake depend if you add (or modify) a #include directive.

Some practice with Subversion

Now we will perform some operations with svn.

Subversion will revert main.c to the most recent committed version.


6. Your Task

Follow the above instructions to add the given file to the operating system. Once you have found (using GDB) and fixed the bugs, you have completed the exercise. Make sure you see the Hello World!!! output just prior to the menu prompt.

Note: The following sample output will vary slightly depending on the year it was originally generated.

sys161: System/161 release 2.0.8, compiled Feb 25 2017 06:18:37

OS/161 base system version 2.0.3
(with locks&CVs solution)
Copyright (c) 2000, 2001-2005, 2008-2011, 2013, 2014
   President and Fellows of Harvard College.  All rights reserved.

Put-your-group-name-here's system version 0 (ASST0 #1)

356k physical memory available
Device probe...
lamebus0 (system main bus)
emu0 at lamebus0
ltrace0 at lamebus0
ltimer0 at lamebus0
beep0 at ltimer0
rtclock0 at ltimer0
lrandom0 at lamebus0
random0 at lrandom0
lser0 at lamebus0
con0 at lser0

cpu0: MIPS/161 (System/161 2.x) features 0x0
Hello World!!!
OS/161 kernel [? for menu]: 
Check your potential submission works with the menu choice supplied on the command line as follows.
% sys161 kernel q

This is generally the way we test your submission, so make sure that you have tested using the above method, even if you have also tested interactively.


7. Submitting

You will be generating a patch file using svn's built-in "diff" command, by instructing svn to compare the original version of the repository (which we tagged with the name initial) against the latest commit.

% svn diff file:///home/$USER/cs3231/repo/asst0/initial file:///home/$USER/cs3231/repo/asst0/trunk >~/asst0.diff

You should now get a patch in ~/asst0.diff. It is worth examining this patch to see whether it contains what you expect, particularly later on.

Testing Your Submission

When you submit, your submission is tested and you will be informed if your submission is correct. (Note: This will not be the case for future assignments!) This means that you can check that you have completed this assignment correctly simply by submitting it again.

Note: In this exercise and future assignments, we run basic submission tests when you submit which can take a few minutes. If you see the following when you submit, something is wrong with your patch, and you should investigate.

 Submission test failed. Continue with submission (y/n)?  

See the submission guidelines for how to recreate your submission that failed the submission testing.

Warning! If you make any changes to your work, make sure you record the changes (svn commit) and create a new .diff file before resubmitting!

Submitting

Now submit the changeset as your solution to the exercise.
% cd ~
% give cs3231 asst0 asst0.diff

You're now done.

Even though the generated patch should represent all the changes you have made to the supplied code, occasionally students do something "ingenious". So always keep your Subversion repository so that we may recover your work should something go wrong.