Submission Instructions

To submit your labs, you’ll use your email address and learn how to send emails using git!

Sending emails is the standard way for maintainers and users to contribute to the Linux kernel. Kernel developers develop new features or fix bugs, and they submit a patch by email to the Linux Kernel Mailing List (LKML). That patch is later reviewed and discussed by other kernel developers, often responsible for a specific Linux subsystem, until it is merged (or not!) to the mainline. More information regarding that process can be found on the kernel documentation.

For this course, you will not send emails directly to the Kernel Mailing List, but to the email address of the course: lkp-maintainers@os.rwth-aachen.de.

After receiving your patches by email, we are patching the Linux source code. We then compile and run the kernel in a VM. Some tests will be executed and depending on their output, your submission will be validated or not. Everything is automated and you’ll receive the output of the tests within a few minutes.

ImportantSubmission information

In the labs, we will specify whether each task has to be submitted or not.

You will see boxes like this one, classified into three categories:

  • Admission: the task must be submitted and the tests must succeed in order to register for the exam.
  • Grade: the task counts towards the 10% of the final grade for labs, but is not mandatory to register for the exam.
  • Others: tasks with no submission information box should not be submitted, as they will not trigger any automated test.


Set up the Linux Git repository

In Lab 2, we downloaded the tarball sources of Linux directly. We will now assume that the Linux kernel is a Git repository where every file of the tarball is tracked.

To do so, there are two distinct options that you can choose from:

  1. Download the Git repository of the Linux kernel

The Git repository of the kernel can be fetched directly from the Linux Kernel Archives. For this, we are using the stable version. The repository takes up to 6 GB of disk space.

git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/
cd linux
git checkout v6.6.137
git switch -c lkp
  1. Keep your kernel repository

Instead of downloading the whole history of the kernel, we can simply reuse the previous tarball and turn it into our own Git repository.

cd linux-6.6.137/
make mrproper # this will delete every generated config, including the .config
git init
git add .
git commit -m "initial commit"
curl https://teaching.os.rwth-aachen.de/LKP/Labs/data/config-lkp > .config # fetch the config back

Sending emails using Git

This section describes the steps to follow to send your labs using Git.

Configuring Git

First, start by configuring git to send emails using your RWTH email address. You can find instructions on git-send-email.

To set up RWTH’s SMTP server, use the following configuration file and change ab123456 to your TIM ID.

This configuration file can be found either under ~/.config/git/config or by typing git config --global --edit in your terminal.

[sendemail]
    smtpserver = mail.rwth-aachen.de
    smtpuser = ab123456@rwth-aachen.de
    smtpencryption = tls
    smtpserverport = 587
    suppressCc = all
    confirm = always

Then, you can set your RWTH email credentials for the repository with:

git config user.email "your.name@rwth-aachen.de"
git config user.name "Your Name"
git config sendemail.smtpPass 'your password'
Warning

Always use your @rwth-aachen.de email address! Emails from any other domain will be ignored.

Sending patches

Once git is set up, you can send your first patches by email with git send-email:

git send-email --no-cc --to lkp-maintainers@os.rwth-aachen.de your_patches.patch

You can manually generate your patches as shown in the lecture using diff. However, we strongly advise you to check out how git format-patch works and use it.

As an example, let’s go through the submission of lab 3 task 1. We will assume you are using git, and have the following commits on top of Linux 6.6.137:

2503386 (HEAD -> mybranch, origin/mybranch) allow users to change parameter values
bd397fc add hello_world_param code
9889dc3 add hello_world code

We can use git format-patch to generate the patch series for the last three commits:

$ git format-patch HEAD~3
0001-add-hello_world-code.patch
0002-add-hello_world_param-code.patch
0003-allow-users-to-change-parameter-values.patch

We can then submit these patches by email with git send-email:

git send-email --no-cc --to lkp-maintainers@os.rwth-aachen.de 0001-add-hello_world-code.patch 0002-add-hello_world_param-code.patch 0003-allow-users-to-change-parameter-values.patch

In order to trigger the proper tests on our side, you also need to modify the Subject of the first email of your patch series. You must prefix the subject with the following string: lab<lab nr>: task<task nr>: <email subject>. In our example, we would change the subject from

Subject: [PATCH 1/3] add hello_world code

to

Subject: [PATCH 1/3] lab3: task1: add hello_world code

This also means that you need to submit a patch series for each task that needs to be evaluated.

Warning

Before sending an email, double check the email you’re sending to. Please make sure you are sending the email only to your account and our specified address.

ImportantCheck who you are sending your patches to!

Never send a patch/commit that is not written by you. It might CC the original author of the patch and you will make Linux maintainers angry.

🤬 <– kernel developers receiving dozen of mails from rwth

Once you have submitted your first patches, you can automate the process using a single git command:

# send your last two commits
git send-email --no-cc --to lkp-maintainers@os.rwth-aachen.de HEAD~2

# send all commits between HEAD and v6.6.137
git send-email --no-cc --to lkp-maintainers@os.rwth-aachen.de v6.6.137..HEAD


Build your module in-tree

Often in the labs, you will be asked to develop new kernel modules. As seen in the lecture, those modules can be in-tree or out-of-tree.

Because we want to emulate the real process of patch submission to the linux kernel, and because developers submit patches to the Linux kernel tree directly, all the modules you will be submitting have to be in-tree. Our submission platform does not support out-of-tree kernel modules!

The rest of this section describes how to add in-tree modules to the kernel, so that the submission platform automatically builds the modules located inside the kernel sources from your patches.

Start by creating an lkp/ directory at the root of the kernel sources and put your C files inside. For instance, if you are developing the module associated with uname, your Linux source tree should contain this:

lkp/
    uname.c
    Makefile

You need to tell the kernel Makefile which directories to compile. For that, modify the Kbuild file at the root of the kernel sources to add the newly created directory:

obj-y           += lkp/

Inside the lkp/ directory, add your files and add a new Makefile with the following rules, matching the proper file names:

obj-m           += helloWorld.o
obj-m           += uname.o
...

Check that everything is working by compiling:

make lkp/   # check that the modules compile (don't forget the / at the end!)
make        # check that our lkp/ directory in included in the kernel makefile

Finally, don’t forget to add the modifications made to the Makefile in your patchset before sending the email. Otherwise, the automated submission platform won’t be able to compile your modules.

Note

The lkp/ folder is set as an example. You could use any other directory in the kernel tree, as long as the Makefile is able to compile your module.

Warning

The modules need to have the exact same name as specified in the lab assignment! If you are asked to write a uname module, we expect to find a uname.ko file after building everything. Otherwise, the automated tests will not be able to load and test your module.

Back to top