farfetchd

Farfetch’d

with a bowl because we insist on being kitchen-themed

farfetchd bowl

Submission

As with previous assignments, we wil be using GitHub to distribute skeleton code and collect submissions. Please refer to our Git Workflow guide for more details. Note that we will be using multiple tags for this assignment, for each deliverable part.

For students on ARM Mac computers (e.g. with M1 chip): if you want your submission to be built/tested for ARM, you must create and submit a file called .armpls in the top-level directory of your repo; feel free to use the following one-liner:

cd "$(git rev-parse --show-toplevel)" && touch .armpls && git add .armpls && git commit -m "ARM pls"

You should do this first so that this file is present in all parts.

Code Style

There is a script in the skeleton code named run_checkpatch.sh. It is a wrapper over linux/scripts/checkpatch.pl, which is a Perl script that comes with the linux kernel that checks if your code conforms to the kernel coding style.

Execute run_checkpatch.sh to see if your code conforms to the kernel style – it’ll let you know what changes you should make. You must make these changes before pushing a tag. Passing run_checkpatch.sh with no warnings and no errors is required for this assignment.

Skeleton code setup

Kernel system call stubs

In addition to the pristine Linux kernel source tree (now under linux/) we’ve provided a patch file which will create the syscall stubs for you. You will need to apply this patch to your repo.

The patch is under the following path:

patch/farfetch.patch

You can use git apply to apply this patch. First, check which files will be modified by the patch:

$ git apply --stat patch/farfetch.patch

You should also inspect what the patch is doing by reading the diffs inside. Finally, you can apply the patch with the following:

$ git apply patch/farfetch.patch

Now, when you run git status, you should see some files modified, as well as some .c and .h files added. After verifying that these changes worked as intended, commit them.

Building your patched kernel

Build your kernel. Make sure you’re building with a local version that is different from your fallback (-cs4118), so you don’t overwrite it; set your local version to your UNI (i.e. -<uni>-HW7).

Now, when you build your kernel, you should have the farfetch() syscall stub in your kernel.

Installing kernel headers

The syscall you will implement has a cmd parameter whose possible values (defined by an enum) are unique to the syscall, and which must be known by the caller. This means that the enum definition needs to be available in both kernel and user land. You’ll need to install the farfetch header (include/uapi/linux/farfetch.h) from the kernel source tree to userspace.

Once you’ve built your farfetch()-stubbed kernel, run the following command:

# make headers_install INSTALL_HDR_PATH=/usr

This command will install the headers found under include/uapi/ in your Linux source tree into /usr/include/. Now you should be able to #include <linux/farfetch.h> from userspace! Additionally, the syscall number should be available as __NR_farfetch from #include <asm-generic/unistd.h>. Try compiling the userspace utility (see below) to make sure this works.

farfetch: Fetching Pages from Afar

For this assignment, you will be implementing farfetch(), a system call that allows you to manipulate the memory of a specified process. The syscall number for farfetch() is 505, and it should be implemented as a dynamically loadable module.

Behavior

The function prototype for farfetch() is the following:

long farfetch(unsigned int cmd, void __user *addr, pid_t target_pid,
	      unsigned long target_addr, size_t len);

farfetch() will take in five arguments:

Return values and error handling

Part 1: Walking the Walk

You will be implementing farfetch() in this part, but with a few simplifying limitations; most significantly, you will only be dealing with the single physical page that is associated with target_addr, so there’s no need to worry about traversing to any subsequent pages. You will copy to/from this page up until either len bytes or the end of the page (whichever comes first).

There is one restriction on your implementation for this part: you may NOT use get_user_pages_remote()/pin_user_pages_remote(), nor anything which invokes them. You may reference their implementation for performing a page walk, but note that the relevant bits are buried in logic that deals with things you don’t need to worry about (traversing arbitrary address ranges, huge pages, special mappings, faulting in pages, etc.)—if your module contains such extraneous code, it will incur a steep deduction. Every line you write should be with purpose, so avoid haphazardly copy-pasting functions or large chunks of code.

Consequently, you will need to manually perform the 5-level page walk. Some additional simplifying limitations:

If performing a FAR_WRITE, you should mark the modified page as dirty using set_page_dirty_lock().

To determine if target_addr is a valid user-space address, it is sufficient to check against the end of the target process’s virtual address space, which is evaluated by the TASK_SIZE_OF() macro; anything >= TASK_SIZE_OF() cannot be a valid user address for the task.

Our recommendation is to start with the resources linked below before looking at kernel code, as those more directly get at what you need to implement the page walk.

Requirements

Submission

To submit this part, push the hw7p1handin tag with the following:

$ git tag -a -m "Completed hw7 part1." hw7p1handin
$ git push origin master
$ git push origin hw7p1handin

Part 2: Time for Takeoff

For this part, we are lifting the main restriction of Part 1 and encouraging that you use get_user_pages_remote(). You can let the internal “GUP” logic (belonging to the get_user_pages_* family of functions) handle the details of the walk.

The use of GUP logic provides the following functionalities which were not required in Part 1:

Remember to mark any modified pages dirty (as in Part 1).

Requirements

Submission

To submit this part, push the hw7p2handin tag with the following:

$ git tag -a -m "Completed hw7 part2." hw7p2handin
$ git push origin master
$ git push origin hw7p2handin

Testing

The farfetchd Hacker Utility

We’ve provided a userspace utility to test your implementation, under the following path:

user/test/farfetchd/

In particular, farfetchd takes a target PID, address, and maximum length, and will execute your syscall up to two times; once to FAR_READ from the target, and then if you choose to modify any memory, once to FAR_WRITE it.

You will need to install bvi before using farfetchd:

# apt install bvi

You will find the provided target programs useful for testing under the following path:

user/test/targets/

Though feel free to write your own for additional testing.

Linked below are some example shell sessions of testing with farfetchd, using the final Part 2 version. Note that the behavior will be different for Part 1 in some cases.

Deliverables


Useful Resources

Below is some online reading material that you may find helpful for this assignment:

For official Linux documentation on memory management:


chef farfetchd

Acknowledgments

The Farfetch’d assignment and reference implementation were designed and implemented by the following TAs of COMS W4118 Operating Systems I, Spring 2022, Columbia University:


Last updated: 2022-04-06