| Home | Syllabus | Assignments | Resources | Piazza |
Due: Tuesday, February 3, 5:00pm
The purpose of this assignment is to introduce you to the code you will be using throughout the rest of the course. You have already completed significant portions of this assignment in class and in your web work -- setting up your virtual machine, cloning the code repository, learning how to configure and build kernels -- these are all different aspects of becoming familiar with the system you'll be using. You also spent time in class reading code and answering questions. Those questions are a subset of the ones in this assignment. Even if you found the answers during class time, include them here in your answers to hand in.
By the time you complete this assignment and the related in-class work, you should be able to:
You must hand in answers to the code-reading questions. The answers should be placed in a file named asst0-answers.txt that resides in the directory ~cs161/os161/submit/asst0, or more generally in the submit/asst0 subdirectory of your cloned repository. (You will need to create this directory.)
% git tag asst0-start % git push origin master --tags
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 found below in this section. Put them in a text file asst0-answers.txt in the submit/asst0 subdirectory of your OS/161 repository.
The questions are designed to encourage code exploration. (We've tried to avoid questions that can be answered 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 be as detailed as possible, giving 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 for the in-class part of this assignment.
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 and build system. It does not configure the operating system kernel, which is a slightly different kind of configuration.
Question 4: Name two things that configure configures. What might invalidate that configuration and make you need/want to rerun it?
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 will augment this file system as part of Assignment 4, so we'll ask you more questions about it then. 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/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: What is the point of all the preprocessor hackery in array.h? What does it accomplish (vs. just having the plain "struct array") and when might you use it?
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 CS161. 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/synchprobs -- This is the directory that contains/will contain the framework code that you will need to complete assignment 1. You can safely ignore it for now.
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 makefiles 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, what is done with the program's return value?
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/ -- this is the source code for the test programs found in /testbin in the installed OS/161 tree. You will want to examine this directory closely and be aware of what's available here, as many of these test programs will be useful during the course of the semester.
Discuss Me! Question 14: Imagine that you wanted to add a new system call. List all the places that you would need to modify/add code. Then review your answers to questions 7-9 and note which of those actions you need to take in order to test the new system call.
Discuss Me! Question 15: 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.
You should review the document How to Submit CS161 Assignments for detailed submission directions.
As noted above, you should put the answers to the code reading questions in a new file in your source tree, submit/asst0/asst0-answers.txt. Make your git repository aware of the new file using git add:
% cd ~/cs161/os161/submit/asst0 % git add asst0-answers.txt
Next, commit your changes to your local repository using git commit:
% git commit
Git will provide you the opportunity to add a comment to the commit. Add an appropriate comment to the commit (like "adding assignment 0 code reading answers") and save the temporary file.
Note that while you have committed the change to your local repository, you have not yet published them anywhere (and thus you have not yet submitted your completed assignment!). To do so, you need to push your repository back to code.seas:
% cd ~/cs161/os161 % git push origin master
Finally, you should tag your repository to tell us that you have finished the assignment.
% git tag asst0-submit % git push origin master --tags
Congratulations! You're done with assignment 0!