How to install and run xv6 on Linux

1. Install QEMU. Please note that this step needs to be done only if QEMU is not already installed. The lab machines should already have QEMU installed. The preferred way is to use apt.

   
         sudo apt-get update
         sudo apt-get install qemu-system
   

   If the above does not work, you can also download and clone from git

   
      git clone https://gitlab.com/qemu-project/qemu.git
      cd qemu
      ./configure
      make
      

   Refer to the QEMU website for more details.

2. Download the xv6 code tarball we have put together for this course cs236-xv6-linux.tgz.

   Please note that we have made minor changes to the the original xv6 code tarball (which is the latest x86 version of the code from the xv6 github repo), to handle some gcc compiler related issues. The original xv6 code should also work fine on most Linux machines.

3. Untar the xv6 code tarball

   
   tar -zxvf cs236-xv6-linux.tgz
   

   or

   
   tar -zxvf xv6-public.tgz
   

4. Go to the uncompressed xv6 folder, and compile xv6 by typing for following inside the folder.

   
      cd xv6-public
      make clean
      make
   

5. Run xv6 inside QEMU as follows.

   
      make qemu
   

   or

   
      make qemu-nox
   

   The latter option will not pop up an extra window. To exit QEMU, type Ctrl+A X (First press Ctrl + A, where "A" is just key a, not the alt key, then release the keys, afterwards press X.)
6. You can now run simple commands like "ls" in the xv6 terminal. You will see something like this printed on screen.

   
   $ls
   .              1 1 512
   ..             1 1 512
   README         2 2 2286
   cat            2 3 15492
   echo           2 4 14376
   forktest       2 5 8812
   grep           2 6 18328
   init           2 7 14996
   kill           2 8 14460
   ln             2 9 14356
   ls             2 10 16924
   mkdir          2 11 14484
   rm             2 12 14464
   sh             2 13 28512
   stressfs       2 14 15392
   usertests      2 15 62884
   wc             2 16 15912
   zombie         2 17 14032
   console        3 18 0
   

7. You can also test your code by running all the user tests in xv6. Run the following command in the xv6 terminal.

   
      usertests
    

   If this command displays "All tests passed", then you are good to go.
8. For the regular lab sessions, start with the original xv6 code you have been given here, then copy the lab-specific code we have shared with each lab into the xv6 folder, and then run xv6.

How to install xv6 on MAC

1. Install Homebrew (if not already installed):

   
      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Install required packages (this step might take time)

   
      brew install qemu gcc
   

3. Tap the repository and install the packages (this step might take time)

   
      brew tap nativeos/i386-elf-toolchain
      brew install nativeos/i386-elf-toolchain/i386-elf-binutils
      brew install nativeos/i386-elf-toolchain/i386-elf-gcc
   

4. Download the xv6 port for MAC that we have put together for this course cs236-xv6-mac.tgz.
5. You should be able to follow the rest of the instructions given for Linux above.

A few things to note.

• If you receive a "Download resource" error while installing "i386-elf-gcc", then switch to some other network (preferably to personal hotspot).
• In case you receive errors related to xcode, then please install the app "xcode" from App Store.
• If you are still unable to install "i386-elf-gcc", then run the following command on terminal: "brew install i686-elf-binutils i686-elf-gcc". After this installation is complete, replace "i386" by "i686" in line 32 of the Makefile, and rerun "make clean && make && make qemu" on terminal.

For the regular lab questions, you need to change the Makefile for it to run suitably on macbook. Please change line number 32 to "TOOLPREFIX = i386-elf-".

In case, you want to work on linux systems, then you can use lab machines via ssh. Here are the instructions:

• First, enable ssh on your laptop. Here are the instructions to do this: https://www.autodesk.com/support/technical/article/caas/sfdcarticles/sfdcarticles/Enabling-remote-SSH-login-on-Mac-OS-X.html (it is a bit outdated, but should be similar on the newer versions too).
• Open terminal. Do "ssh labuser@slX-Y.cse.iitb.ac.in" with the suitable password to ssh into the software lab machine that you use during lab hours.
• If you want to use VS-Code to open a folder on the remote machine, then please follow this website: https://code.visualstudio.com/docs/remote/ssh

Writing and testing new code

In this course, you will write code inside the xv6 kernel to add and extend kernel features. It is recommended that you create separate copies of this xv6 folder for every assignment you solve (so that you do not disturb the original files).

Once you have added new kernel features, you will want to test your code. For this, you will need to write simple user programs or testcases that invoke OS functionality. Below are instructions on how you can write simple user programs in xv6. (How to write kernel code will be dealt with in detail during the course!)

First, write your user program in a C file in the xv6 folder, for example, in "simple.c". The code below just prints to screen, but you can write more complex code that invokes other xv6 system calls as well.

#include "types.h"      
#include "user.h"

int main(int argc, char *argv[]) 
{ 
    printf(1, "Hey, I am trying xv6\n"); 
    exit();
}

1. Add “_simple\” after line 183 of the Makefile.
2. Add “simple.c” after “umalloc.c” in line 253 of the Makefile.