CSE 451 Assignment 0

Due: Friday, April 10, 2015 11:59pm

The project is to be done in groups of 2-3. Everyone in the group should be able to answer the questions in this assignment. If you have not formed a group yet, please get started on the assignment anyway, and then compare answers and resolve any questions you may still have.

The purpose of this assignment is to introduce you to the code you will be using throughout the rest of the course. We will address significant portions of this assignment in the material in lectures and sections. Even if your answers come directly from that material, include them in what you hand in.

By the time you complete this assignment you should be able to:

• Build OS/161 and run Sys/161
• Discover important design aspects of OS/161 by examining its code base
• Configure and build OS/161 kernels
• Manage OS/161 using git, including creating a repository and tracking your changes
• Use GDB to manipulate OS/161
• Tackle Assignment 1

You must turn in the answers to the code-reading questions via Catalyst.

The instructions below explain how to obtain the os161 source base. You'll need the build environment as well. See Setting Up a Toolchain.

• You'll fetch the code base from a git repository, then create a new git repository to warehouse your team's work.

  To pull the baseline code for OS/161:

  % git clone /projects/instr/15sp/cse451/os161
  

  That command works only on machines where the file path is mounted, such as the attu's and CSE lab Linux workstations. (If you plan to work on some other machine, first fetch the files on a CSE machine and then copy them to that other machine.) It creates a directory named os161 containing the source code for the operating system and various utilities.

• The operating system is written for a cache-coherent MIPS computer named System/161. For this, you will need to use a cross-compiler: a compiler for generating MIPS instructions, along with various other related tools such as a cross-gdb. You will need to put the following directory in your UNIX path:

  /projects/instr/15sp/cse451/tools/bin
  

  In this directory you will find all the necessary tools, such as cse451-gcc and cse451-gdb.

  See Setting Up a Toolchain if you want to build OS/161 for your own VM.

• Typical practice when developing a new OS is to run it on a machine simulator. The simulator, sys161, is in the same directory as the cross-compile binaries, along with a few other versions like trace161 and stats161 that may be useful later.

• Next, tag your repository to indicate that you are beginning assignment 0. In your git repository, issue the following command:

  % git tag asst0-start
  

• To build and execute your the kernel, consult the Building OS/161 document.

Once you have a group, you should set up your own group repository on GitLab. If you or your groupmates have not used GitLab before, you will first need to log in so that your account is set up.

Only one of you needs to create the GitLab repository. This person should create an empty project on GitLab with an informative project name. To push the tag and the code you just pulled to this project, issue the following commands from the directory containing your os161 source code:

git remote rename origin distrib   # Rename the git repo you initially cloned from
git remote add origin git@gitlab.cs.washington.edu:yourCSID/yourProjectName.git    # The new repo you want to push to
git push -u origin master    # Push the initial commit to the GitLab repo

Then add the rest of your group members and the course instructional staff to the project. Make sure to give your fellow group members developer status and allow developers to push to the repository.

The other member(s) of each group should complete the following instructions:

Navigate to the directory containing your os161 source code and execute the following instructions:

git remote rename origin distrib   # Rename the git repo you initially cloned from
git remote add origin git@gitlab.cs.washington.edu:firstGroupMembersCSID/yourProjectName.git    # The new repo you want to use for your group
git fetch origin     # Fetch the data from the repo
git branch --set-upstream-to=origin/master    # Set group repo as the default.

Note: Setting up a group repository is not necessary for starting on the code reading questions. Start looking through the code as soon as possible.

OS/161 is a simplified skeleton of a modern operating system. It comes with a configurable build system, code for some useful user-level utilities that can be run from within OS/161, and of course code for the operating system itself. To complete the assignments of this course, you will need to get your hands deep in the guts of the OS/161 codebase, and the sooner you become familiar with it, the better. To that end, you should look through the files and begin to internalize how the code is structured, what goes where, and how things work. This applies both to the build system and the codebase itself.

To guide you in this process, please write up and hand in answers to the questions below.

The questions are designed to encourage code exploration (we tried to avoid questions you could answer simply using grep). The goal is to help you understand key parts of the system. That said, you are not yet expected to understand everything you see (that's what the rest of the course is for!). But you should get the "gist," and your answers should reflect that. Please give function names and full pathnames in the source tree where appropriate. You don't need to explain what every last line of a function does, but your answers should be conceptually complete. Note that some questions may require longer answers than others.

Let's begin with some discussion questions:

• Discuss Me! Question 1 Chapter 2 of the text discusses the mechanisms used to transfer control between user processes and the operating system. For each of trap and interrupt, tell us where we can find the first line of OS/161 code that is executed when it occurs. Then tell us where control gets transferred to from that point.
• Discuss Me! Question 2 A system call, such as write, ultimately leads to a trap. Find where in OS/161 this trap is invoked.
• Discuss Me! Question 3 Why do you suppose there are libc functions in the source tree (common/libc)?

Below is a brief overview of the organization of the source tree, and a description of what goes where.

• configure -- top-level configuration script; configures the OS/161 distribution, including all the provided utilities, but does not configure the operating system kernel.

  Question 4: From what directory should you run configure again? What should you do immediately after running configure?

• Makefile -- top-level makefile; builds the OS/161 distribution, including all the provided utilities, but does not build the operating system kernel.

• common/ -- code used both by the kernel and user-level programs, mostly standard C library functions.

• kern/ -- the kernel source code.

  • kern/Makefile -- Once again, there is a Makefile. This Makefile installs header files but does not build anything.

  • kern/arch/ -- This is where architecture-specific code goes. By architecture-specific, we mean the code that differs depending on the hardware platform on which you're running. There are two directories here: mips which contains code specific to the MIPS processor and sys161 which contains code specific to the System/161 simulator.

    • kern/arch/mips/conf/conf.arch -- This tells the kernel config script where to find the machine-specific, low-level functions it needs (throughout kern/arch/mips/*).

    • kern/arch/mips/include/ -- This folder and its subdirectories include files for the machine-specific constants and functions.

      Discuss Me! Question 5: What are some of the details which would make a function "machine dependent"? Why might it be important to maintain this separation, instead of just putting all of the code in one function?

    • kern/arch/mips/* -- The other directories contain source files for the machine-dependent code that the kernel needs to run. A lot of this code is in assembler and will seem very low level, but understanding how it all fits together will help you immensely on Assignment 2.

      Question 6: How large is a trapframe? Why?

    • kern/arch/sys161/conf/conf.arch -- Similar to mips/conf/conf.arch.

    • kern/arch/sys161/include -- These files are include files for the System161-specific hardware, constants, and functions. machine-specific constants and functions.

  • kern/compile -- This is where you build kernels. See below.

    Question 7: Under what circumstances should you re-run the kern/conf/config script?

    Question 8: Under what circumstances should you run bmake depend in kern/compile/ASST<n>?

    Question 9: Under what circumstances should you run bmake or bmake install in kern/compile/ASST<n>?

  • kern/dev -- This is where all the low level device management code is stored. Unless you are really interested, you can safely ignore most of this directory.

  • kern/fs -- This is where the actual file system implementations go. The subdirectory sfs contains a simple default file system. You would have augmented this file system as part of Assignment 4.

  • kern/include -- These are the include files that the kernel needs. The kern subdirectory contains include files that are visible not only to the operating system itself, but also to user-level programs. (Think about why it's named "kern" and where the files end up when installed.)

    Question 10: Describe the steps you would need to take to add a new system call to the kernel.

  • kern/lib -- These are library routines used throughout the kernel, e.g., arrays, kernel printf, etc. Note: You can use these data structures as you implement your assignments. We strongly encourage you to look around and see what we've provided for you.

  • kern/main -- This is where the kernel is initialized and where the kernel main function is implemented.

    Question 11: When you booted your kernel, you found that there were several commands that you could issue to experiment with it. Explain exactly where and what you would have to do to add a command that printed out, "Hello world!"

  • kern/proc -- This is where process support lives. You will write most of the code that goes here during Assignment 2.

  • kern/syscall -- This is where you will add code to create and manage user level processes. As it stands now, OS/161 runs only kernel threads; there is no support for user level code. In Assignment 2, you'll implement this support.

  • kern/thread -- Threads are the fundamental abstraction on which the kernel is built (do not forget to look back at header files!)

  • kern/vfs -- The vfs is the "virtual file system." It is an abstraction for a file system and its existence in the kernel allows you to implement multiple file systems, while sharing as much code as possible. The VFS layer is the file-system independent layer. You will want to go look at vfs.h and vnode.h before looking at this directory.

  • kern/vm -- This directory is fairly vacant. In Assignment 3, you'll implement virtual memory and most of your code will go in here.

• /man/ -- the OS/161 manual ("man pages") appear here. The man pages document (or specify) every program, every function in the C library, and every system call. You will use the system call man pages for reference in the course of assignment 2. The man pages are HTML and can be read with any browser.

• /mk/ -- fragments of makesfiles used to build the system.

• /userland/ -- user-level libraries and program code

  • /userland/bin/ -- all the utilities that are typically found in /bin, e.g., cat, cp, ls, etc. The things in bin are considered "fundamental" utilities that the system needs to run.

    Question 12: Why do we need to include these in your OS/161 distribution? Why can't you just use the standard utilities that are present on the machine on which you're working?

  • /userland/include/ -- these are the include files that you would typically find in /usr/include (in our case, a subset of them). These are user level include files; not kernel include files.

  • /userland/lib/ -- library code lives here. We have only two libraries: libc, the C standard library, and hostcompat, which is for recompiling OS/161 programs for the host UNIX system. There is also a crt0 directory, which contains the startup code for user programs.

    Question 13: When a user program exits, where is the return value of the program left?

  • /userland/sbin/ -- this is the source code for the utilities typically found in /sbin on a typical UNIX installation. In our case, there are some utilities that let you halt the machine, power it off and reboot it, among other things.

  • /userland/testbin/ -- these are pieces of test code.

Discuss Me! Question 14: Refer to the document Using GDB and run gdb on your kernel. Experiment a bit and follow the execution from the start.S file through the main menu kmain and then to the code that executes some of the commands. Explain the control flow from start.S through the menu and on to other parts of the kernel.

Congratulations! You're done with assignment 0!