Code Reading

In this course, you may be getting your first taste of understanding and carefully modifying a large body of code that you did not write yourself. It is imperative that you take the time to read through the important parts of the code to get an understanding of the overall structure of the code, and what each part of the code does.

The code-reading component of this assignment aims to guide you through the code base to help you 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 this and later assignments.

You don't need to understand every line of code, but you should have a rough idea of what each file does.

The Top-Level Directory

The src directory contains the top-level directory of the OS/161. It contains a few files along with subdirectories containing distinct parts of OS/161. The files are:

• Makefile: Used to build the OS/161 base system, including all the provided utilities. It does not build the operating system kernel.
• configure: A configuration script, similar to the configuration scripts used in many open source programs (although it is not one of the impenetrable scripts generated by GNU autoconf). You shouldn't need to understand or tamper with it. It is run by our setup program.
• defs.mk: Definitions read in by the Makefile, and generated by the configure program.

In addition to these files, the src directory contains the following directories:

• kern/: Contains the sources to the OS/161 kernel itself. We will cover this code in more detail below.
• userland/: Contains the sources to the user-level utilities that come with OS/161. These are the programs that run on top of the OS/161 kernel. There's no need to look too closely at these for now, but you may find it interesting to see how they work.
• common/: Contains code that is shared between the kernel and user-level programs. This is where you will find the implementation of the C library functions that are available to both the kernel and user-level programs.
• 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. The man pages are HTML and can be read with any browser.
• mk/ — fragments of makefiles used to build the system.
• testscripts/: Contains scripts used to test the OS/161 system. You won't need to look at these for now.

We'll discuss these directories in more detail below.

The kern Subdirectory

This directory and its subdirectories are where most (if not all) of the action takes place. The only file in this directory is a Makefile. This Makefile only installs various header files. It does not actually build anything.

We will now examine the various subdirectories in detail.

The kern directory mostly contains subdirectories, it has one file.

• kern/Makefile — This is not the Makefile that builds the kernel, and is mostly uninteresting. It is used to install various header files. You can ignore it for now.

The directories in kern are as follows:

• 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.
  • 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 in later assignments.
  • 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/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.)

• 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 in for OS/161. We strongly encourage you to look around and see what we've provided for you.

• kern/compile/: Where you built your kernel. Remember...?

• kern/conf/: Where you configured your kernel. Hopefully you remember that too...

• kern/include/: Contains include files that the kernel needs. Every major piece of kernel functionality has an include file here describing its interface, and an implementation file in the appropriate subdirectory elsewhere in the kernel.

  • kern/include/kern: Contains include files that the kernel and user-level code needs.

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

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

• kern/synchprobs — This is the directory that contains/will contain the framework code that you will need to complete assignment 3. You can safely ignore it for now.

• kern/proc — This is where process support lives. You will write most of the code that goes here later in the course.

• 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. You'll implement this support later in the course.

• kern/vm — This directory is fairly vacant. Later in the class, we'll implement virtual memory and most of your code will go in here.

The remaining directories are less crucial to understand as we start the course. Here is a brief overview of what you can find in them:

• 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. The subdirectory semfs contains a special-purpose file system that provides semaphores to user-level programs. We may ask you more questions about this later on, after we discuss in class what semaphores are.
• 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 atvfs.h and vnode.h before looking at this directory.

The common Subdirectory

The common directory contains code that is shared between the kernel and user-level programs. This is where you will find the implementation of the C library functions that are available to both the kernel and user-level programs, such as the support for printf and C-string handling functions.

The userland Subdirectory

The userland directory contains the source code for the user-level utilities that are available on OS/161.

• userland/include — the include files that user-level programs need to build and run on OS/161. These files are not the same as the kernel include files.
• userland/lib/ — user-level library code. We have only two libraries: libc, the C standard library, and hostcompat, which is for recompiling OS/161 programs on the host UNIX system. There is also a crt0 directory, which contains the startup code for user programs (i.e., the low-level code that runs before main).
• userland/bin/ — source for 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.
• 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 a variety of test programs used to check kernel functionality. We won't necessarily use all of them, and very few if any of them will work until we've implemented support for user programs in the kernel.

(When logged in, completion status appears here.)

Previous Page Next Page