Branches

Typically, a master branch does not exist in the repositories provided on this web site. Because of this, when initially cloning a repository you may get an inscrutable error message because git enjoys baffling its users. You may instead clone the repository, enter the directory it was cloned into, and use git branch -av to view the available branches.

We have multiple repositories. Generally speaking, you should use the same branch for each repository being tested. For example, if you check out the dev branch for the kernel repository, this is meant to correspond to the dev repository in the userspace library. You may be able to use separate branches for each component, but if a system call or API changes there may be errors in building or running the code.

The OSDI branches correspond to the code that existed at the time we performed the evaluation. They will not be updated or modified. The dev branch is the current branch under development. I will push dev changes to the repositories on this page occasionally. In all cases, the code is based on a release candidate for the FreeBSD 11.0 kernel. I will port to the updated kernel soon for the non-OSDI branches. I cannot promise that there won't be a forced push on those branches.

Building the kernel

The kernel is forked off of FreeBSD 11 RC4. For best results, build the kernel on a FreeBSD 11 base system.

Assuming the kernel is checked out in ~/kernel (on branch snap/11-BETA4), to build the kernel type this:

make -C ~/kernel buildkernel KERNCONF=SNAP -jx

Replace x with the number of cores you have.

This is using the SNAP configuration. There are SNAP_EVAL and SNAP_PROFILE evaluations as well. When testing, SNAP has more asserts and other debugging facilities built in, so it's what I use until I am ready to do doing evaluation or profiling.

You'll notice that this is slow. Once you've compiled once you can do the following to not recompile everything from scratch every time.

make -C ~/kernel buildkernel -DKERNFAST KERNCONF=SNAP -jx

I don't build the kernel as root (though you may). The build process will attempt to create some directories under /usr/obj/usr/home/username, so as long as your user has privileges to do this (e.g., sudo mkdir -p /usr/obj/usr/home/$(whoami) && sudo chown $(whamoi) /usr/obj/usr/home/$(whoami)) you do not have to build the kernel as root.

To install the kernel do:

sudo make -C ~/kernel installkernel KERNCONF=SNAP

This will install the kernel and set it to be used on the next boot. Before you do this you may want to do a recursive copy of /boot/kernel to /boot/GENERIC and then make the generic kernel available in the boot menu in case things go sideways. This shouldn't be necessary with kernels I've made available on this site, but it can be nice to have some insurance, especially if you modify the kernel.

Once you boot into the new kernel you can confirm it with uname -a

User-level code

Code that uses the lwC system calls has to have access to the system call API and library. These are made available in the userspace library. Within that repository the /libs/ directory houses the code that is commonly shared between userspace applications. Specifically, this includes a header file describing the system calls and some assembly that invokes them. Any evaluation software must link against these libraries.

Differences between the paper and the code

The implementation we evaluated does differ from the API presented in the paper in either superficial aspects or in ways that do not affect its performance. Specifically, the evaluation code did not include per-thread lwC state. Instead, lwCs were essentially assumed to be treated as thread local or used more carefully if shared. Since all of the code we evaluated was single-threaded and would not be affected by this change, we did not modify the implementation to include this difference. Additionally, the implementation has some syntactic differences from what was written. Finally, we did not implement or evaluate the signal handling semantics proposed in the paper.

Except for the signal handling mechanism, these differences have been eliminated in the dev branch. We will implement the signal handling at some future date.

Collaboration, pull-requests, feature requests, and bug reports

I'm happy to discuss collaboration or answer questions on building on top of lwCs. You can reach me via e-mail.

If you modify the kernel or other libraries and would like the changes to be included "upstream," you may send me an email either containing a link to the git server so I may access your changes or send a patchset so that I may test it. If you do so, please explain the purpose of your changes as best you can. Code testing the changes is appreciated. If the changes are in line with our broader vision we will incorporate them into the code-base.

If you feel like lwCs would benefit from a feature and would like to request it be added, this is something you may request. I'm more likely to be able to accommodate such a request as part of a larger collaboration, but will keep feature requests on mind as I'm working through the roadmap.