CSE 306: Lab 1: System calls

Due 11:59 PM, Friday, February 26, 2016


This lab will introduce you to how system calls work, as well as xv6 internals. The main assignment will be to add a system call to xv6, which fills a buffer with an ascii art drawing of Wolfie.

Software Setup

The files you will need for this and subsequent lab assignments in this course are distributed using the Git version control system.

Git is a powerful, but tricky, version control system. We highly recommend taking time to understand git so that you will be comfortable using it during the labs. We recommend the following resources to learn more about git:

  1. Understanding git conceptually This is a MUST READ if you want to work on git smoothly. (You may skip the last part: Rebasing, for now)
  2. Quick 15-20 mins online exercise to get to know git.
  3. Git user's manual
  4. If you are already familiar with other version control systems, you may find this CS-oriented overview of Git useful.
  5. For reference, bookmark the Git Cheat Sheet, which includes a summary of useful git commands.

VM Setup

Each student (enrolled and on the waiting list) will be given a virtual machine on the OS teaching cluster with the basic required software installed. You will have root access to this machine, and be able to install additional tools (editors, debuggers, etc) as you see fit.

You are also welcome to install the needed software on your own laptop. The course staff is not available to help you debug your personal laptop configuration. The tools page has directions on how to set up and use gcc and other course software on your own machine.

Each student currently enrolled or on the waiting list will be assigned a VM and an initial password. Newly enrolled students will be assigned a VM within a few days of enrolling.

To get started with your VM, you must do some system setup. You must initially setup your VM via the vSphere client; after setup is complete you can use ssh to access your VM.

There are some helpful notes on using vSphere here. NOTE: DO NOT INSTALL A NEW OS (CentOS or otherwise)---only use these notes for tips on using vSphere.

  1. Use a remote desktop client to connect to connect to ts1.cs.stonybrook.edu:22. Use CS\userid to log in, using the same username and password you use for department email.
  2. Alternatively, you can use the instructions on this page to connect to vSphere: https://www.cs.stonybrook.edu/about-us/csintranet/faqs/Remote-Desktop-Web-Access.
  3. From the remote desktop, start the vSphere client. Select either, eg. esx10sc.cs.stonybrook.edu or esx11sc.cs.stonybrook.edu and again use your CS department credentials. Ignore the SSL warning. You will probably only be able to log into one of these servers, which contains your VM.

  4. Once you have logged in, click on "Inventory", then select your VM from the list. The naming convention is cse306-NETID (where NETID is your net id). Right click on it, and select "Open Console." Click the green "Play" button to start the VM. You can log in with the provided account and initial password. Immediately change your password! You can change your password using the passwd command on the console.

  5. Use the ifconfig command to identify the IP address of your VM. You will use this to connect directly to the VM in the future.

  6. After booting, the VM will be available via an ssh client on port 130 (use the -p option to specify a port, or add an entry to your .ssh/config file.). You will use the cse306 account and your newly changed password to log in over ssh.

  7. Warning: It is highly advisable that you take a checkpoint of your VM at this point, especially if you intend to modify packages on the VM. This allows you to rollback the VM to a working state without CS department administrator help (which is not available on the weekends or late at night) if something goes horribly wrong. The button to take a checkpoint in vSphere is next to the button you used to power on the VM.

    Additional notes on checkpointing your VM are posted here.

    Good citizenship. You have administrator access to this VM and can install anything you like. That said, to keep load down, DO NOT INSTALL A GRAPHICAL DESKTOP on the VM. You may tunnel the X protocol (ssh -X) to your local machine and display your editor in a window.

Getting started with git

Each student will be assigned a private git repository initially populated with the lab 1 skeleton code. You will use this repository to turn in your code (see below). To download the files into your development environment, you need to clone the course repository, by running the commands below. Substitute your CS netid for USER below.

kermit% mkdir ~/cse306
kermit% cd ~/cse306
kermit% chmod 0700 . # (sets appropriate permissions)
kermit% git clone ssh://USER@scm.cs.stonybrook.edu:130/scm/cse306git-s16/hw-USER xv6

Initialized empty Git repository in ......./cse306/xv6/.git/
got f6ec6e08634de9b9c4d73ab5af92da16cc610f44
walk f6ec6e08634de9b9c4d73ab5af92da16cc610f44
got a8d9dd484df67d928a51127ce4c6d9f6d01c5a6a
got c9dab101498914dbdce377b89a6eb0f6a421d018
Checking out files: 100% (44/44), done.
kermit% cd xv6

Notice that each student will have his or her own git repository hosted on scm; your CS user ID should substituted in the URL above (no CS\), and you will also use your CS department account to log into scm.

For students that do not have a private git repository yet, you may use the read-only git repository on the course webpage, using the alternate command below:

kermit% git clone http://www.cs.stonybrook.edu/~porter/courses/cse306/s16/xv6.git xv6

Git allows you to keep track of the changes you make to the code. For example, if you are finished with one of the exercises, and want to checkpoint your progress, you can commit your changes by running:

kermit% git commit -am 'my solution for lab1 exercise9'
Created commit 60d2135: my solution for lab1 exercise9
 1 files changed, 1 insertions(+), 0 deletions(-)

You can keep track of your changes by using the git diff command. Running git diff will display the changes to your code since your last commit, and git diff origin/master will display the changes relative to the initial code supplied for this lab. Here, origin/master is the name of the git branch with the initial code you downloaded from our server for this assignment.

We have set up the appropriate compilers and simulators for you on the CS lab machines.

Hand-In Procedure

Labs will be handed in using the make handin-lab1 command. This creates a tag in git and pushes the tag and changes to the source repository. You must commit all changes you want included in the handin.

When you are ready to hand in your lab, create a file slack.txt noting how many late hours you have used both for this assignment and in total. (This is to help us agree on the number that you have used.) This file should contain a single line formatted as follows (where n is the number of late hours):

late hours taken: n

Then run make handin-lab1. If you submit multiple times, we will take the latest submission and count late hours accordingly.

In this and all other labs, you may complete challenge problems for extra credit. If you do this, please create a file called challenge.txt, which includes a short (e.g., one or two paragraph) description of what you did to solve your chosen challenge problem and how to test it. If you implement more than one challenge problem, you must describe each one.

For answering questions in the labs, you will also have a file called answers.txt, in which you will write answers to the assigned questions.

Migrating to your private repository

If you initially cloned the read-only (http) repository, you must update your git configuration. First, do a git pull to pull any changes from the read-only source. Once you have a private repository for handing in the labs, you should issue this command to add the handin repository (substituting your user ID appropriately):

git remote add handin ssh://USER@scm.cs.stonybrook.edu:130/scm/cse306git-s16/hw-USER

You can double check the .git/config file to verify the update was successul. Initially, the config will look something like this:

	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = http://www.cs.stonybrook.edu/~porter/courses/cse306/s16/xv6.git
[branch "master"]
	remote = origin
	merge = refs/heads/master

There should now be a new remote entry like this:

	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = http://www.cs.stonybrook.edu/~porter/courses/cse306/s16/xv6.git
[branch "master"]
	remote = origin
	merge = refs/heads/master
[remote "handin"]
	fetch = +refs/heads/*:refs/remotes/handin/*
	url = ssh://USER@scm.cs.stonybrook.edu:130/scm/cse306git-s16/hw-USER

Set your umask

If you are working in a group, you also need to log in to scm and adjust your umask. The default settings on scm (0022) will cause files in your repository to be created without group write permission. You need to change your umask to (0002) so that files on scm are writable by your partner.

Add an entry to the .bashrc file in your home directory so that it looks like this:

# .bashrc

# Source global definitions
if [ -f /etc/bashrc ]; then
        . /etc/bashrc

# User specific aliases and functions
umask 0002

Part 1: Getting started with xv6

NB: This portion of the homework courtesy of MIT's 6.828.

Build xv6 on your VM:
$ cd xv6
$ make
gcc -O -nostdinc -I. -c bootmain.c
gcc -nostdinc -I. -c bootasm.S
ld -m    elf_i386 -N -e start -Ttext 0x7C00 -o bootblock.o bootasm.o bootmain.o
objdump -S bootblock.o > bootblock.asm
objcopy -S -O binary -j .text bootblock.o bootblock

Finding and breaking at an address

Find the address of _start, the entry point of the kernel:
$ nm kernel | grep _start
8010b50c D _binary_entryother_start
8010b4e0 D _binary_initcode_start
0010000c T _start
In this case, the address is 0010000c.

Run the kernel inside QEMU GDB, setting a breakpoint at _start (i.e., the address you just found).

$ make qemu-gdb
$ gdb
GNU gdb 6.8-debian
Copyright (C) 2008 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
+ target remote localhost:26000
The target architecture is assumed to be i8086
[f000:fff0]    0xffff0:	ljmp   $0xf000,$0xe05b
0x0000fff0 in ?? ()
+ symbol-file kernel
(gdb) br * 0x0010000c
Breakpoint 1 at 0x10000c
(gdb) c
The target architecture is assumed to be i386
=> 0x10000c:	mov    %cr4,%eax

Breakpoint 1, 0x0010000c in ?? ()
The details of what you see are likely to differ from the above output.

Exercise: What is on the stack?

You do not need to hand this in, but it is a helpful exercise to work through with your team.

Look at the registers and the stack contents:
(gdb) info reg
(gdb) x/24x $esp

Write a short (3-5 word) comment next to each non-zero value on the stack explaining what is. Which part of the stack printout is actually the stack? (Hint: not all of it.)

You might find it convenient to consult the files bootasm.S, bootmain.c, and bootblock.asm (which contains the output of the compiler/assembler). The reference page has pointers to x86 assembly documentation, if you are wondering about the semantics of a particular instruction. Here are some questions to help you along:

Part 2: Adding a system call

Your task is to add a system call to xv6. It will help to start by reading syscall.c (the kernel side of the system call table), user.h (the user-level header for the system calls), and usys.S (the user-level system call definitions). You may add additional files to xv6 to implement this call.

Exercise 1. (5 points.) Create a system call int sys_wolfie(void *buf, uint size), which copies an ASCII art image of Wolfie to a user-supplied buffer, provided that the buffer is large enough. You are welcome to use an ASCII art generator, or draw your own by hand.
If the buffer is too small, or not valid, return a negative value. If the call succeeds, return the number of bytes copied.

You may find it helpful to review how other system calls are implemented and compiled into the kernel, such as read.

Exercise 2. (3 points.)

You will also write a user-level application, called wolfietest.c that gets the Wolfie image from the kernel, and prints it to the console.

Challenge! (1 bonus point) The team with the coolest-looking Wolfie will get 1 bonus point, as subjectively judged by the course staff.

Challenge! (2 bonus points) The team that implements its system call and utility in the fewest lines of readable, clean code will get 2 bonus points. This count excludes blank lines and comments (comments are always welcome). Code that is confusing and difficult to read, as subjectively judged by the course staff, will be disqualified.

This completes the lab. Type make handin-lab1 in the xv6 directory. After successful submission, you should receive a confirmation email (although you may need to try twice to get the email). If submission fails, double check that you have committed all of your changes, followed the instructions to add the handin repository, and read any error messages carefully before emailing the TAs for help.

Last updated: 2016-02-20 11:37:43 -0500 [validate xhtml]