Link Search Menu Expand Document
CMSC 421

Due by 11:59 PM on Sunday, Oct 18

Project 2: Introduction

In this project, you will create a new version of the Linux kernel that adds various system calls that relate to inter process communication. While the kernel does already provide IPC-related calls, we wish to have a bit more control over the process. To that end, you will be implementing a relatively simple interface for sharing memory between multiple processes. We should note that this system will not do any memory mapping like the shared memory system you might have seen in class.

Before you begin, be sure to create your new GitHub repository for Project 2 by using the link posted on the course Piazza page. Then, follow the same steps you did in Project 0 to clone this new repository (obviously, substitute project2 for project0 from the earlier instructions). Also, you may remove the /usr/src/vanilla-project0 directory and create a new /usr/src/vanilla-project2 directory with the newly checked out code.

As a first step, change the version string of the new kernel to reflect that it is for Project 2. That is, make the version string read 5.5.0-cmsc421project2-USERNAME (substituting your UMBC username where appropriate). The code for your system can be placed in a directory called proj2 or mailbox_421 inside /usr/src/project2.

Incremental Development

One of the nice things about using GitHub for submitting assignments is that it lends itself nicely to an incremental development process. As they say, Rome wasn’t built in a day — nor is most software. Part of our goal in using GitHub for assignment submission is to give all of the students in the class experience with using a source control system for incremental development.

You are required in this project to plan out an incremental development process for yourself — one that works for you. There is no one-size-fits-all approach here. One suggested option is to break the assignment down into steps and implement things as you go. You are also encouraged to seek out the review of your TAs to determine whether an approach might be feasible.

You should not attempt to complete this entire project in one sitting. Also, we don’t want you all waiting until the last minute to even start on the assignment. Students doing either of these tend to lead to getting poor grades on the assignment. To this end, we are requiring you to make at least 3 non-trivial commits to your GitHub repository for the assignment. These three commits must be made on different dates and at least one must be done before Sunday, October 4th at 11:59 PM EST. You may make more than three commits during the timeline of the project — three is simply a minimum number required for full credit. In addition, you must have made a reasonable attempt at implementing the basic operations on the data structure described later in this document by October 4th. That is to say that we expect to see some version of code that is capable of initializing the IPC structure, writing data to it, and/or reading data from it by October 4th. This may be in the form of kernel-space code or in the form of a user-space prototype (as detailed below).

A non-trivial commit is defined for this assignment as one that meets all of these requirements:

  • Does not contain only documentation (i.e, just committing a README file does not count).
  • Does not contain only Makefile modifications or creation.
  • Modifies/creates at least 10 lines of code in a combination of existing or newly created .c or .h files. That is to say, creating a new file with 10 lines of code counts, but creating a new file with a 10 line comment does not.
  • Code modifications/creation must be relevant to the project. Creating a bunch of useless files/functions that are unrelated or otherwise superfluous to the assignment does not count. It is ok to reorganize your code after you have started and remove pieces of code, of course, but if you are obviously only adding code to the repository early on that you completely delete later (or that has nothing to do with the assignment), then that commit will not count toward the requirements herein.
  • Code implementing a prototype version of the assignment (for instance, a user-space version) does count, but any example code or anything else of that nature that you use in that prototype (for instance, a user-space version of the <linux/list.h> header file) does not count.
  • Failure to adhere to these requirements will result in a significant deduction in your score for the assignment. This deduction will be applied after the rest of your score is calculated, much like a deduction for turning in the assignment with a late penalty.

User-space prototype

As it is significantly easier to build and test code in user-space than it is in the kernel, you are encouraged to build a user-space prototype of at least part of your system before attempting to implement it in the kernel. Please note that we are not suggesting you implement the entire project in user-space, but rather just some of the basic functionality. One approach that many previous students have found that works for this is to implement a prototype version of the data structure that you will be using in user-space. This will allow you to ensure that you have the basic algorithms for implementing insertion, deletion, search, etc. working without having to spend a long time waiting on kernel builds. Some portions of the assignment are not feasible to be done in a user-space prototype, as the interfaces for doing so are significantly different in user-space and in kernel-space, so we do not necessarily recommend building a full prototype of the whole system in user-space. If you do choose to implement a user-space prototype of your code, please place it in a directory called proj2proto in the root of the Linux kernel source code and be sure to tell us about it in the README file (let us know what you did in the prototype, why you chose to do so, how things changed when you ported it over to the kernel, etc).

To that end, we have created a user-space compatible version of the kernel’s linked list. Please use this in your prototype only. Do not use in your kernel implementation as it can break stuff. The API is exactly the same between the two however, so it could make your code more portable. You can find the files at https://gist.github.com/Zinadore/0efe654e5744cb89d3fb5d6424cd3e51. Note that there are two files there, list.h and list_hacks.h. You need both of them in user-space.

You can also find some examples on how to use the list at https://gist.github.com/Zinadore/8bebd0e25cf079320c2d832ef34db182.

Another thing that you might want to use is the __KERNEL__ macro. When compiling the kernel that macro will be defined, but it won’t be defined in your user-space code. So you could do things like the following if you wanted:

#if defined(__KERNEL__)
// Code for the kernel only
#else
// Code for user-space only
#endif

// Common code for everyone !