Weenix

January 29 - May 7

You can find the weenix documentation here - this pdf is your best friend.

Installation
You can get your copy of weenix by running: git clone /course/cs169/asgn/weenix (your folder)
This will create the folder if it doesn't exist, or place the project inside the folder if it does. Note that this is already set up as a git repo - we strongly encourage you to use git to manage your work. However, please make sure your code is not publicly visible online.

Getting Started
To run Weenix, use the following commands from the project root:
make
./weenix -n

(note that the -n is only required for the first run, more on this later)
Your weenix should run and then panic with the following error:
panic in main/kmain.c:132 bootstrap(): weenix returned to bootstrap()!!! BAD!!!
If this happens, you are all set to start working! Some suggestions for getting started:
Documentation and instructions for the projects can be found in the doc/latex folder of the Weenix repo. Run make inside of that directory to make a pdf.
Working on weenix can be overwhelming at first. We suggest starting with the functions proc_create(), kthread_create() and bootstrap(), which are some of the first functions called after booting.
To see a list of all of the functions you have to implement, you can run make nyi from the project root.
You might notice that there are some functions (like kmutex_*) that are declared in .h files, but not defined in any .c files. Since you are already implementing mutexes in uthreads, we will not make you do it again in procs, so we've implemented these functions (as well as a few functions declared in sched.h) for you. With that said, we've provided our implementations in assembly language to discourage you from trying to use the provided code as a hint for how to do uthreads. Once uthreads is turned in, we will provide you with the C implementations of these functions. Until then, if you're really interested in how these functions work, you can take a look at proc/kmutex.S and proc/sched_helper.S, but we recommend just waiting until uthreads is in.
Note that although we're providing some functions, you'll still have to implement everything listed by the output of make nyi.

Work from home
There are a few options if you want to work from home:
1. SSH -- Tom implemented Weenix just by SSHing from his Windows machine into the department machines, which works well if you use a terminal based text editor. You will need to forward X windows but only when spawning the emulator for Weenix (QEMU). Isaac has experience with this as well (SSHing from Linux).
2. Virtual machine -- this will be discussed further down below, in the section on "Vagrant". Steven has experience with this (SSHing from OS X).
3. Natively -- if you run Linux on your laptop, you may be able to install QEMU and other dependencies to build and run weenix. Isaac has experience with this.

Vagrant
If you want to work on weenix on your own machine, we recommend using Vagrant. Using Vagrant and the Vagrantfile provided in the directory you cloned, you can spawn a VM running linux with all dependencies necessary for running Weenix. You'll also need a virtualizer, such as VirtualBox or VMWare. To get this working:
1. Get the weenix source code onto your computer. If you are on windows we recommend you use WinSCP. Other methods, including creating a zipfile/tarball and emailing it to yourself have been known to cause issues with symlinks. If you have these problems look at the note below for Cygwin users. SCP works for Linux / macOS.
2. Install the relevant VirtualBox platform packages from here
3. Install Vagrant
4. Install an X server and an ssh client. Most people probably already have one installed (XQuartz on Mac, putty, MobaXTerm, or Xming on Windows), particularly if you've set up ssh with x11 forwarding. 5. In your weenix repository on your home computer, run vagrant up from the terminal on OS X or Linux, or the command prompt on Windows. Vagrant will traverse up until it finds the Vagrantfile at the root of the repository, create a VM with the correct specifications, and launch it in the background (headless). This will take some time.
After these steps, your virtual machine will be setup. You'll be able to ssh into the machine (with x11 forwarding), by running vagrant ssh -- -Y in a terminal on OSX. If you're on Windows, running this command may fail, but it will give you information that you can use to configure an ssh session in MobaXTerm or another ssh client, which you can use to ssh in to the VM. Once you're ssh'd in, cd to /vagrant. You should see your shared weenix directory. You can compile and run weenix from here.

Note: You'll have to change the CC line of Global.mk to equal gcc, and change this line back to the old path when working on department machines. Make sure to comment out the old path so you can get it back later!

When you're done working, remember to vagrant suspend or vagrant halt from the same place you ran vagrant up, otherwise it will continue running the VM in the background.

Cygwin
Cygwin may be used for editing the weenix source files. However we strongly recommend you DO NOT use it to transfer the weenix source to your windows computer. Doing so may cause issues with symbolic links. OSX users and WinSCPusers do not need to worry about this. If this happens we recommend copying it from the csdept again usingWinSCP. If this is impossible you must manually copy all the files listed here from the location on the left to the one on the right. Similar symlink issues may arise if using sftp on Linux.

Cscope
Cscope is an incredibly helpful tool for writing Weenix. Cscope provides Eclipse-like code navigation for C. It can do some extremely powerful things, like jump to the definition of a function or find all references to a particular symbol in your code. Plus, it's easy to learn! You can unlock much of the power of Cscope by learning only two commands.
To learn how to use Cscope, I would recommend reading this (short) guide. There are also (even shorter) guides on how to use Cscope in Vim, Emacs, and Sublime Text.

Tmux
If you use a terminal-based editor like Vim or Emacs (or ed or sam), you may find it useful to have various "panes" open in the same terminal window, where there might be a couple panes with Vim open, a pane with GDB running, etc. Tmux is a "terminal multiplexer" that allows you to do just this. It is a terminal based program, and thus can be run over SSH without X forwarding. Many TAs have a lot of experience with this.

Syntastic
Syntastic is a vim plugin that will automatically compile your code whenever you save it, and will show you your compile errors right in Vim. Needless to say, this is extraordinarily useful.
To download and set up Syntastic, first follow the instructions in the "Installation" section of this github page (the setup is mercifully short). Then, add the following line to your ~/.vimrc file:
let g:syntastic_c_checkers = ['make']
That line will tell Syntastic to compile your code with the Makefile in the current directory rather than by using gcc directly.

Scripts
You may have noticed that when running Weenix in gdb, the qemu window annoyingly stays open even after you quit gdb. You've probably noticed that running Weenix requires first cd'ing into the directory containing Weenix or typing the absolute path of the Weenix executable. The TAs a couple years ago wrote two very simple functions that rectified these problems.
If you copy and paste the text here into your .bashrc, you will be able to run the commands rw and wg. These are short for "run weenix" and "weenix gdb", respectively. The first script will run weenix (with the -n argument, if provided), while the second will run weenix with gdb (with the -n argument, if provided), and will close qemu after gdb exits. Both commands can be run from any directory.
Aside from placing these functions in your .bashrc, the only other step you need to take to get this to work is to replace \ with the directory where you normally run ./weenix.