FLUSP - FLOSS at USP

Linux kernel patch submission guidelines (FSD 2026)

2026-04-08T00:00:00-03:00

1. Clone the right kernel tree and branch

For each Linux subsystem/subproject you want to contribute to, you must use a dedicated git repository (called kernel tree, in this context). The information about where this tree is located so you can do a git clone is at the MAINTAINERS file present at the root of any kernel tree. Here is a Web version of it: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS.

Search for the subsystem/subproject you are working on and, if it has a dedicated git tree, it will be indicated in the T: <remote-url> attribute. The <remote-url> points to the tree, so you can do the below to clone the respective kernel tree:

git clone <remote-url>

In the case of the Industrial I/O (IIO) and AMD DRM subsystems, which we have curated issues, the git clone commands are:

# IIO
git clone git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio --branch togreg

# AMD DRM
git clone https://gitlab.freedesktop.org/agd5f/linux.git --branch amd-staging-drm-next

Note: The --branch option that sets the development branch used as a base. This is because, apart from the right kernel tree, we need to ensure we are at the latest development branch before making patches to avoid working on something that has already been solved or that doesn’t make sense anymore.

Unfortunately, I don’t know a clear-cut way of knowing the right development branch of a project. Still, it should be documented somewhere in the subsystem/subproject.

Also, don’t forget to keep the development branch updated with

git pull

Note: If you are working on a branch like testing for IIO, it is also recommended to do a rebase (git pull --rebase) because the maintainers frequently make changes to the tree. This ensures your local branch stays up-to-date and avoids unnecessary merge commits.

2. Create a dedicated local branch to isolate your work

As mentioned, you will be using a specific branch as base for each subsystem/subproject and objective. So, after checking out to the correct base branch (testing for IIO and amd-staging-drm-next), create a new branch to isolate your work. The name doesn’t matter to anyone but you, but having a meaningful name to keep things organized is a good idea:

git switch <base-branch>
git checkout -b <name-of-your-patch-branch>

3. Ensure that your change is being compiled

When tinkering with the Linux codebase, you need to be sure that the code you are modifying (at least) doesn’t break compilation. For this, you need to have a .config file configured to compile the portion of the code you’ve changed in the correct context. Ok, this is really ambiguous and circular, so here is one way you can be sure that the file you are modifying is being considered for compilation.

I can’t confirm that this is the most efficient and reliable way, but this helps on getting an idea of the configurations you need to enable in order to produce the correct compilation. We are going to show an example on how to proceed when you don’t know much about the file you are editing.

Say you are modifying the file drivers/iio/dummy/iio_simple_dummy.c and you don’t know how to include it in the compilation. You should look in the same directory of the file for a Kconfig. This file has many configuration definitions in the form of

config <config_name>

    ...

    help

    <description_of_the_config>

You would look for a config name and description that relates to where you are working, like IIO_SIMPLE_DUMMY. Then, you would open the .config file for editing with make nconfig or kw build --menu. Hit the F8 Key (SymSearch) and type in the config name you’ve noted. This should open a menu with entries starting with Symbol:. You would look for the config name you’ve typed at the top. You should see a Depends on: attribute with the dependencies needed to be enabled before IIO_SIMPLE_DUMMY. There is also a Location: with a series of indentations that show the menus sequence to activate the config you’ve entered; you should see a number by the side of the closest menu entry you can reach.

For example, you might see something like this:

Symbol: IIO_SIMPLE_DUMMY [=n]                                                       
Type  : tristate                                                                    
Defined at drivers/iio/dummy/Kconfig:12                                             
  Prompt: An example driver with no hardware requirements                           
  Depends on: IIO [=y] && IIO_SW_DEVICE [=n]                                        
  Location:                                                                         
    -> Device Drivers                                                               
      -> Industrial I/O support (IIO [=y])                                          
(1)     -> IIO dummy driver                                                         
          -> An example driver with no hardware requirements (IIO_SIMPLE_DUMMY [=n])

In this case you would need to hit ESC, hit F8, and search for IIO_SW_DEVICE (which is not enabled). You could see an output like

Symbol: IIO_SW_DEVICE [=n]                                        
Type  : tristate                                                  
Defined at drivers/iio/Kconfig:53                                 
  Prompt: Enable software IIO device support                      
  Depends on: IIO [=y]                                            
  Location:                                                       
    -> Device Drivers                                             
      -> Industrial I/O support (IIO [=y])                        
(1)     -> Enable software IIO device support (IIO_SW_DEVICE [=n])
Selects: IIO_CONFIGFS [=n]                                        

Hitting 1 should jump you to the menu that enables IIO_SW_DEVICE. Then you would repeat it to enable the IIO_SIMPLE_DUMMY config. Finally, you would save and quit the editing of the .config.

Note that this is a “blind” direction on how to enable a specific config in the Kbuild/Kconfig system, which doesn’t guarantee that the compilation will be “correct” for your patchset context (maybe the config name you’ve noted doesn’t even enable the target file).

Nevertheless, to test if file is being compiled, use the old technique add-a-clear-compilation-error to the file. If the compilation fails, then you can be sure that your file is being compiled (at least, part of it).

4. Backup your .config files

When developing for Linux, having to stop everything to produce a new .config file is tedious and time consuming. So whenever you have a working .config file that is of your interest backup it by copying it to a “safe” location or by using kw kernel-config-manager.

The same goes for the virtual machine images you use to test custom built kernel. You can make backups of these images with simple cp commands.

5. Make atomic commits and work on your commit message

General good commit practices are almost obligatory in the kernel, to the point that a perfect change, from the technical perspective, can be rejected if the commit does multiple things at once, so focus on atomic changes.

Descriptive commit messages that follow the subsystem/subproject pattern are also important. For example, doing

git log drivers/iio/adc/ad4030.c

will output all the commits that modified the file, and can give us with a good base for writing our commit subject. Pay attention to the prefix of the message. For this example, the command will (probably, if you are on the IIO testing branch) output as the latest commit (first entry in the list)

iio: adc: ad4030: Add support for ADAQ4216 and ADAQ4224

What is of interesting to us is the iio: adc: ad4030: part, which we can use as reference for our commit message title. However, the maintainer/community have the final word, so if they ask you to change the format of the title follow the request (even though, you can mention you’ve used a past commit as an example, pointing to it).

Important: The commit message body is obligatory, even if your change is so small and simple that it will be redundant with the title.

For more guidance on writing good commit messages, see [1].

6. Add your Signed-off-by and Co-developed-by

There is another hard-rule that is homogenous for every subsystem/subproject which is the addition of a Signed-off-by: Your Name <your@email.com> line with the author’s name and email. To configure git to automatically add this for you, run

git config --global user.name <Your Name>
git config --global user.email <your@email.com>

then just do commit as follow

git commit --signoff
# or
git commit -s

All integrants of the group must add their own signature. By rule, only the committer should add a Signed-off-by and the remaining developers should add Co-developed-by followed by a Signed-off-by. Apart from the committer that has the signature added automatically (with the --signoff flag) the others should add their signatures manually or when doing the commit by modifying the command to

git commit --signoff --trailer='Co-developed-by: Integrant 2 <email@2.com>' --trailer='Signed-off-by: Integrant 2 <email@2.com>' ...

As an example, imagine that Paulo Meirelles and David Tadokoro are developing the patchset. Considering that Paulo is the committer (the one that runs git commit --signoff), the signatures at the end of the commit message should be

Signed-off-by: Paulo Meirelles <paulormm@ime.usp.br>
Co-developed-by: David Tadokoro <davidbtadokoro@ime.usp.br>
Signed-off-by: David Tadokoro <davidbtadokoro@ime.usp.br>

7. Check that your patchset doesn’t introduce coding style problems

To make your patchset more robust, it is advisable to check for possible coding style problems that your patchset may be introducing. To do this, run

git format-patch -1 --stdout | ./scripts/checkpatch.pl --

This will make checkpatch.pl check for problems on the current commit (the one pointed by the HEAD; the commit you are at the moment) and will output the ones it finds.

Important: The problems found by the tool are not always correct, so be critic about them and apply them only if they are reasonable.

8. Official Linux kernel guidelines in submitting patches

There is also an official guide on submitting patches done by the Linux kernel community[2]. It is very extensive (even more than the one I did above), but you can check it if you are in doubt about anything more specific.

9. Configure `git send-email`

Before sending patches, you need to do some configuration. We assume you are using you @usp.br email, which is gmail under the hood. The configuration is described in this tutorial: Sending patches with git and a USP email

10. Send your contribution to our CI before sending it “to the world”

After your patch(set) is ready, before sending your contributions to the respective mailing list(s) and maintainer(s), send your contribution only to the address kernel@lists.ime.usp.br. Below is the safe command to send the last <n> commits.

kw send-patch --send -<n> --simulate --private --to=kernel@lists.ime.usp.br

The above command is safe because the --simulate option makes kw do everything except sending the message(s). Before removing this option to actually send the message(s), make sure that the recipients (the RCPT TO: fields) are correct. You can optionally append a --cc=<your@email.com> at the end the command to copy yourself and be more comfortable about the email being delivered.

All the patches sent to the mailing list will be available on our lore instance: https://lore.kernel.ime.usp.br/kernel.ime/

It may take some time for the patch to appear in the mailing list archive.

Sending the patchset to this address will trigger our local CI where the patch will be applied to the corresponding kernel tree, compiled, and booted into a VM where a basic boot cycle test will be executed. The main job stages are build and test. The former is responsible for applying and compiling the kernel image. The latter loads it and runs the boot cycle.

We have 4 CI repositories. When submitting a patch, you can track its progress on the respective repository, by finding the CI pipeline that was triggered the moment you’ve sent the patch.

DSL-LINUX is the main CI repository. It detects the tree that matches your patch and triggers the build and test jobs to one of the repository below. You can track the entire CI flow for every tree from here.
IIO-CI is the repository for the IIO tree. CI jobs for IIO patches will be here;
AMD-DISPLAY-CI is the repository for the AMD DISPLAY tree. CI jobs for AMD DISPLAY jobs will be here;
LINUX-NEXT-CI is the repository for the LINUX-NEXT tree. This tree contains bleeding edge from all development trees and is used as a fallback if your patch doesn’t match the IIO or AMD trees.

Important: Despite being functional, our UI/UX for CI feedback is still lacking a centralized and organized interface. You may ask one of the teacher assistants if you struggle to track the CI status of your patch. Keep in mind that the UI aspect of our CI is WIP and may face significant improvements during the next days (and this documentation will be updated accordingly)

The CI pipeline may present some bugs, such as wrong job failures. If your patch gets buggy pipelines, we’ll address the bug and manually run your patch through the CI until it is properly evaluated by our CI system.

11. Send your patchset “to the world” after approval from our CI

After your patchset has been approved in the previous step, you can send it to the correct maintainers and mailing list by running the previous command without the additional --private and --to options:

kw send-patch --send -<n> --simulate

Remember to drop the --simulate flag after you feel confident that the messages to be sent are correct and destined to the correct recipients.

History

V1: First version release (thanks to Guilherme Ivo).

References

[1] cbeams. “How to Write a Git Commit Message”. (2014) URL: https://cbea.ms/git-commit/. ⤴

[2] Linux Kernel Community. “Submitting Patches - The Linux Kernel”. (2026) URL: https://www.kernel.org/doc/html/v6.14/process/submitting-patches.html. ⤴

Linux kernel patch suggestions (FSD 2026)

2026-04-07T00:00:00-03:00

To finalise the first phase of the Free Software Development 2026 course, each group will send one or more contributions to the Linux project. There are no restrictions on which subsystems the groups can send patches to, and this post includes a few directions to help you devise your contributions. The mentors of FSD 2026 have curated these suggestions, but always rely on the Linux community and maintainers, as well as on your own critical sense when developing for the kernel.

Important: Before proceeding to the patch suggestions, make sure you are comfortable with the submission part of the process by consulting the patch submission guidelines post.

This is an WIP version that may be altered in the future.

Suggestions summary

Suggestion 1.1) Replace mutex_lock(&lock) and mutex_unlock(&lock) calls with guard(mutex)(&lock)
Suggestion 2.1) Replace manual bitfield manipulations with FIELD_GET(), FIELD_PREP(), and FIELD_MODIFY()
Suggestion 2.2) Update IIO drivers to be Include-What-You-Use (IWYU) compliant
Suggestion 2.3) Improvements in the IIO area of staging
Suggestion 3.1) Convert logging to drm_* functions with drm_device parameter
Suggestion 3.2) Read and expand the subsystem documentation
Suggestion 4.1) Duplications with 100% similarity
Suggestion 4.2) Duplications with 90% similarity

1. Any subsystem/subproject

Suggestion 1.1) Replace `mutex_lock(&lock)` and `mutex_unlock(&lock)` calls with `guard(mutex)(&lock)`

Synchronisation is fundamental in the Linux kernel, as you need to be mindful of concurrency issues such as data inconsistency, race conditions, and deadlocks. A common synchronisation primitive is a mutex, which is implemented in Linux. An example of initialising a mutex, acquiring it, and unlocking it would be

struct mutex lock;   // declaring a mutex
mutex_init(&lock);   // dynamically initialising the mutex
mutex_lock(&lock);   // acquiring the mutex
...                  // critical section
mutex_unlock(&lock); // unlocking the mutex

However, there are two problems with this approach that compromise cleanup after calling mutex_lock():

The developer needs to remember to call mutex_unlock()
Depending on the conditional paths of the critical section, many mutex_unlock() calls need to be placed

To circumvent these problems, developers may use the goto error pattern, where the mutex_unlock() is centralised at the end of the critical section. For instance, this template of a function is pretty common:

int function_with_mutex_and_goto_error_pattern(void)
{
    int ret = 0;
    
    mutex_lock(&lock);  // lock is a struct mutex that has been initialised
    switch (var) {
    case FOO:
        do_foo(); // suppose this function never fails
        break;
    case BAR:
        ret = do_first_bar();  // suppose this function can fail
        if (ret)  // i.e., if do_first_bar() failed
            goto out;
            
        ret = do_second_bar();  // suppose this function can fail
        if (ret)  // i.e., if do_second_bar() failed
            goto out;
            
        do_third_bar(); // suppose this function never fails
        break;
    default:
        ret = -EINVAL;
    }
    
out:
    mutex_unlock(&lock);
    return ret;
}

The kernel provides what it calls Scope-based Cleanup Helpers (defined in include/linux/cleanup.h), which, in a very broad sense, allow transparent cleanup when resources go out of scope. For mutexes, the guard(mutex)(&lock) macro basically solves the two mentioned problems associated with cleaning up acquired mutexes. In the above example, if we were to use guard(mutex)(&lock), the code could be rewritten without any functional change as

int function_with_guard_mutex(void)
{
    int ret = 0;

    guard(mutex)(&lock);  // lock is a struct mutex that has been initialised
    switch (var) {
    case FOO:
        do_foo(); // suppose this function never fails
        return 0;
    case BAR:
        ret = do_first_bar();  // suppose this function can fail
        if (ret)  // i.e., if do_first_bar() failed
            return ret;
            
        ret = do_second_bar();  // suppose this function can fail
        if (ret)  // i.e., if do_second_bar() failed
            return ret;
        
        do_third_bar(); // suppose this function never fails
        return 0;
    default:
        return -EINVAL;
    }
}

Note that in this example, as guard(mutex)(&lock) is called “at the root scope” of the function, the mutex is unlocked if and only if it goes out of the function scope (in the example, in any of the return statements). There is a similar macro, scoped_guard(mutex, &lock), that creates an explicit block scope where the mutex is unlocked when it goes out of this block. For example, if we have a sequence in which we only want a small part of it to represent our critical section, we can use scoped_guard(mutex, &lock):

int function_with_scoped_guard_mutex(void)
{
    ...  // do some stuff with no mutex active
    scoped_guard(mutex, &lock) { // lock is a struct mutex that has been initialised
    ...  // inside these curly braces, the mutex is active
    }  // from here on, the mutex is unlocked
    ...  // do some other stuff with no mutex active
}

Important observations

Obs.1: guard(mutex)(&lock) and scoped_guard(mutex, &lock) are only a specific type of guard cleanups, and guard cleanups are only part of these Scope-based Cleanup Helpers. You can check the documentation https://docs.kernel.org/core-api/cleanup.html to understand this better, if you are interested.
Obs.2: The goto error pattern isn’t solely used for mutex_unlock(&lock), as other unwind operations can happen in the same goto (deallocate memory, unregister char device, and so on). In these cases, you can’t simply throw away the gotos and enforce the guard mutex cleanups.
Obs.3: We exemplified the use of mutex_lock(&lock) and mutex_unlock(&lock) with the goto error pattern, but even in cases where multiple explicit mutex_unlock(&lock) calls are made to avoid gotos, refactoring with guard mutex cleanups can make the code more robust. { .warning}

Patch examples

2. Industrial I/O (IIO)

The suggestions below were pointed by Marcelo Schmitt and refined by us.

Suggestion 2.1) Replace manual bitfield manipulations with `FIELD_GET()`, `FIELD_PREP()`, and `FIELD_MODIFY()`

Although we normally think of numbers in the decimal system, we can represent them in different bases. Take the number 26, for example. In binary, it is:

\[\begin{aligned} (11010)_2 &= (2^4*1 + 2^3*1 + 2^2*0 + 2^1*1 + 2^0*0)_{10} \\ &= (16*1 + 8*1 + 4*0 + 2*1 + 1*0)_{10} \\ &= (16 + 8 + 0 + 2 + 0)_{10} \\ &= (26)_{10} \end{aligned}\]

We can also represent 26 in the hexadecimal system:

\[\begin{aligned} (1\textrm{A})_{16} &= (16^1*1 + 16^0*10)_{10} \\ &= (16*1 + 1*10)_{10} \\ &= (16 + 10)_{10} \\ &= (26)_{10} \end{aligned}\]

In kernel development, it is common to treat numbers as bitfields, where each bit or bit sequence encodes a different attribute. As an analogy, imagine a 4-bit bitfield dish that encodes an order at a restaurant serving 4 dishes, with each dish having two sizes (small and large) and two spice levels (regular and spicy). We can define how the bits in dish represent every possible dish as such (“bigger bits” to the left):

Bits 0-1 -> Dish ID: $(00)_2$ is dish 0, $(01)_2$ is dish 1, $(10)_2$ is dish 2, and $(11)_2$ is dish 3.
Bit 2 -> Dish size: $(0)_2$ is the small size and $(1)_2$ is the large size.
Bit 3 -> Dish spiciness: $(0)_2$ is regular and $(1)_2$ is spicy.

In this analogy, the bitfield dish that represents the spicy small dish 1 is $(1001)_2$ (or $(9)_{10}$, in decimal). Now, imagine I want to query the bitfield dish for the dish size, i.e., isolate bit 2 from this 4-bit bitfield. The way to compute this value is to perform a mask (target specific bits) and a shift (move the bits left/right) operation. More specifically, these are the operations in pseudocode:

size = dish AND (0100)_2  // MASK: "selects" only bit 2
size = size >> 2          // SHIFT: "moves" bit 2 to bit 0

Alternatively, if you were handed a bit spiceness and you had to modify dish to have this spiceness. In this case, there would be a shift, a mask, then an OR operation:

val = spiceness << 3    // SHIFT: "moves" spiceness to bit 3
val = val AND (1000)_2  // MASK: "selects" only bit 3
dish = val OR dish      // MODIFY: "updates" dish with spiceness

This simple analogy illustrates the core common bitfield manipulations in the kernel, and the pseudocodes aren’t too far from the real implementations. These manipulations are so frequent that the kernel provides macros that simplify them, while making them more secure. These macros are the FIELD_GET(mask, bitfield) (e.g., get dish size), FIELD_PREP(mask, field_val) (e.g., prepare dish spiceness), and FIELD_MODIFY(mask, bitfield, field_val) (e.g., prepare dish spiceness and modify dish). These macros are defined in include/linux/bitfield.h.

In the context of IIO, you can check for manual bitfield (also referred to as registers) manipulations and see if they can be replaced by one of the above macros.

Patch examples

…

Suggestion 2.2) Update IIO drivers to be Include-What-You-Use (IWYU) compliant

IWYU is a Clang-based tool developed by Google to optimize #include directives in C/C++ code (https://include-what-you-use.org/). Check the patch examples for guidelines on how to pursue this suggestion.

Patch examples

Suggestion 2.3) Improvements in the IIO area of staging

Linux has its own “quarantine zone” for drivers, where code that is either entering or leaving the kernel lives, due to it not being quite refined or being problematic, respectively. This area is located in the drivers/staging directory, and the IIO-related drivers of staging are in drivers/staging/iio.

Usually, staging drivers are really rough, in terms of following the kernel conventions, coding style, and other requirements, so some patch opportunities can be considered newcomer friendly. (Un)fortunately, the IIO staging drivers are already well developed, making these easier tasks more rare.

Nevertheless, see this message from Marcelo Schmitt on the mailing list regarding possible tasks for IIO staging drivers: https://lore.kernel.org/linux-iio/Z8U0lsntJpTuBzyT@debian-BULLSEYE-live-builder-AMD64/

Patch examples

…

3. DRM AMDGPU DRIVERS

The suggestions below were taken from https://dri.freedesktop.org/docs/drm/gpu/todo.html and from https://dri.freedesktop.org/docs/drm/gpu/amdgpu/display/display-contributing.html. If you want to dig for other TODOs feel free to investigate these lists.

Suggestion 3.1) Convert logging to drm_* functions with drm_device parameter

For drivers which could have multiple instances, it is necessary to differentiate between which is which in the logs. Since DRM_INFO/WARN/ERROR don’t do this, drivers used dev_info/warn/err to make this differentiation. We now have drm_* variants of the DRM print functions, so we can start to convert those drivers back to using DRM-formatted specific log messages. This should only work in files inside drivers/gpu/drm/amd/display/amdgpu_dm/.

Before you start this conversion please contact the relevant maintainers to make sure your work will be merged - not everyone agrees that the DRM dmesg macros are better. The documentation mentions contacting Sean Paul and the maintainer of the driver you plan to convert.

Patch examples

…

Suggestion 3.2) Read and expand the subsystem documentation

Graphics is already a complicated field, but when it comes to 3D-accelerated graphics in the kernel, things can be get really complex really fast. So reading through the GPU Driver Developer’s Guide (https://docs.kernel.org/gpu/index.html), the DRM AMDGPU drivers doc (https://docs.kernel.org/gpu/amdgpu/index.html), and the display part of DRM AMDGPU drivers doc (https://docs.kernel.org/gpu/amdgpu/display/index.html), can be a great way to grasp some knowledge, whilst contributing to it.

An important observation is that we don’t encourage you to simply correct typos, but to dive deep into the documentation, reading the code, and updating/expanding parts that seem incorrect/unclear.

Patch examples

…

4. Code duplications

Suggestion 4.1) Duplications with 100% similarity

1) 3 sets of correlated duplications. Feel free to try to solve one or all of them. The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

jpeg_v5_0_1.c::jpeg_v5_0_1_process_interrupt AND jpeg_v5_0_2.c::jpeg_v5_0_2_process_interrupt , TOTAL NUMBER LINES IN FUNCTIONS: 59

jpeg_v5_0_0.c::jpeg_v5_0_0_process_interrupt AND jpeg_v5_3_0.c::jpeg_v5_3_0_process_interrupt , TOTAL NUMBER LINES IN FUNCTIONS: 18

jpeg_v2_0.c::jpeg_v2_0_process_interrupt AND jpeg_v3_0.c::jpeg_v3_0_process_interrupt , TOTAL NUMBER LINES IN FUNCTIONS: 18

2) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gfx_v11_0.c::gfx_v11_0_eop_irq AND gfx_v12_0.c::gfx_v12_0_eop_irq , TOTAL NUMBER LINES IN FUNCTIONS: 52

3) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gfx_v11_0.c::gfx_v11_0_ring_preempt_ib AND gfx_v12_0.c::gfx_v12_0_ring_preempt_ib , TOTAL NUMBER LINES IN FUNCTIONS: 49

4) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gmc_v10_0.c::gmc_v10_0_get_vm_pte AND gmc_v11_0.c::gmc_v11_0_get_vm_pte , TOTAL NUMBER LINES IN FUNCTIONS: 46

5) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gfx_v11_0.c::gfx_v11_0_set_userq_eop_interrupts AND gfx_v12_0.c::gfx_v12_0_set_userq_eop_interrupts , TOTAL NUMBER LINES IN FUNCTIONS: 42

6) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gfx_v11_0.c::gfx11_kiq_map_queues AND gfx_v12_0.c::gfx_v12_0_kiq_map_queues , TOTAL NUMBER LINES IN FUNCTIONS: 42

7) 2 sets of correlated duplications. Feel free to try to solve one or all of them. The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

Functions find: cik_sdma.c::cik_sdma_process_trap_irq AND sdma_v2_4.c::sdma_v2_4_process_trap_irq , TOTAL NUMBER LINES IN FUNCTIONS: 40

Functions find: cik_sdma.c::cik_sdma_process_trap_irq AND sdma_v3_0.c::sdma_v3_0_process_trap_irq , TOTAL NUMBER LINES IN FUNCTIONS: 40

8) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gmc_v10_0.c::gmc_v10_0_vm_fault_interrupt_state AND gmc_v12_0.c::gmc_v12_0_vm_fault_interrupt_state , TOTAL NUMBER LINES IN FUNCTIONS: 36

9) The specified files are in the directory drivers/gpu/drm/amd/amdgpu/:

gfx_v11_0.c::gfx_v11_0_handle_priv_fault AND gfx_v12_0.c::gfx_v12_0_handle_priv_fault , TOTAL NUMBER LINES IN FUNCTIONS: 36

10) drivers/iio/: the cluster only identifies these 6 files. However, it is possible to find other functions that exhibit minor variations in their signature, for example, receiving only a pointer to a channel (chan) or using an explicit index (channel) within the channels array.

Cluster #3 (Files: 6, Pairs: 15, Lines: 270)
---------------------
Function find: accel/hid-sensor-accel-3d.c::accel_3d_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9
Function find: pressure/hid-sensor-press.c::press_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9
Function find: magnetometer/hid-sensor-magn-3d.c::magn_3d_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9
Function find: light/hid-sensor-prox.c::prox_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9
Function find: light/hid-sensor-als.c::als_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9
Function find: gyro/hid-sensor-gyro-3d.c::gyro_3d_adjust_channel_bit_mask, TOTAL NUMBER LINES IN FUNCTION: 9

11) drivers/iio/: bidirectional mappings of the same table.

Cluster #5 (Files: 2, Pairs: 1, Lines: 74)
---------------------
Function find: light/tsl2591.c::tsl2591_persist_cycle_to_lit, TOTAL NUMBER LINES IN FUNCTION: 37
Function find: light/tsl2591.c::tsl2591_persist_lit_to_cycle, TOTAL NUMBER LINES IN FUNCTION: 37

Suggestion 4.2) Duplications with 90% similarity

1) drivers/iio/: There is a common configuration sanitization step for both functions (retained from 2025)

imu/inv_icm42600/inv_icm42600_core.c::inv_icm42600_set_accel_conf AND imu/inv_icm42600/inv_icm42600_core.c::inv_icm42600_set_gyro_conf , TOTAL NUMBER LINES IN FUNCTIONS: 60

2) drivers/iio/: Possibly a refactoring opportunity (retained from 2025)

light/veml6030.c::veml6030_hw_init AND light/veml6030.c::veml6035_hw_init , TOTAL NUMBER LINES IN FUNCTIONS: 49

Difference in the configuration of register 0x00: https://www.vishay.com/docs/84366/veml6030.pdf and https://www.vishay.com/docs/84889/veml6035.pdf

Deduplications from last year (2025)

https://github.com/arkanjo-tool/arkanjo/blob/main/docs/PATCHES_MAC0470_5856_2025.md

History

V0.1: First work-in-progress version for the FSD 2026 workshop of 07/04/2026.
V0.2: Add link to patch submission guidelines (thanks to Guilherme Ivo).

Sending patches with git and a USP email

2026-03-24T00:00:00-03:00

This tutorial explains how to send patches via git send-email using a USP email account, which involves some extra steps. We will be using kworkflow (kw) to simplify setup and automatically resolve maintainers when dealing with kernel contributions. An important prerequisite of this tutorial is reading the “Sending patches by email with git” post.

Introduction

When contributing to projects that do not use workflows like GitHub’s Pull-Requests or GitLab’s Merge-Requests (some call those Web-based workflows), but rather workflows where you need to send contributions via email, using a tool like git send-email is very convenient, as it greatly simplifies the process of converting and sending your commits. For example, you do not need to worry about your email messages (that contain your code) being misformatted or even leaving your local repository to accomplish the task.

Nevertheless, no matter the tool you use, you need to deal with authentication issues that may vary widely depending on your email account and provider. In this case, we are focusing on USP email accounts, which are Gmail accounts with some particularities when used to send patches.

What is the problem with USP emails?

Usually, when using Gmail accounts, you need to set up an App Password to signal Google that you are allowing an external service that uses this password to (in our case) send email messages with git send-email. To set up an App Password, you must first enable 2-Step Verification, which is not possible for USP emails.

To cover cases where setting up an App Password is not an option, Google still provides Less Secure Apps to allow authentication with the usual Gmail account password, even though this method is said to be unsupported since January 2025. You can check your USP Google account settings for the Less Secure Apps configuration, enable it, and try to use it, but I can tell you that this won’t work (at least, I would be very surprised if it did). The motive behind it is a long and obscure one, but the TL;DR is that the USP systems suffered security attacks in the first semester of 2025, which resulted in the admins locking down some vulnerable features like Less Secure Apps (you can imagine why).

The alternative: OAuth 2.0

OAuth 2.0 is a widely used protocol for authentication. It “delegates” authentication of the third-party app (again, in our case, git send-email) to an authorisation server (Google itself) without ever needing to store or share sensitive passwords.

This post is not about OAuth, so feel free to consult the linked page for further information.

Through OAuth, we can finally overcome the problems with USP emails, though it requires some (hopefully) not-so-complicated setup. More specifically, we will present two options to handle the OAuth protocol part, which git send-email doesn’t do:

Option A) Using the git credential command with a helper.
Option B) Using an email proxy capable of authenticating through OAuth.

Each option is suited for a different scenario. We suggest trying Option A first, then, only if things go wrong, moving to Option B.

Summary of this tutorial

Option A: git credential helper
- Installing the git credential helper and generating the access token
- Configuring git send-email and credential manually
- Testing the setup with kw send-patch
Option B: Email Proxy
- Running the email proxy
- Configuring git send-email with kw send-patch
- Testing the setup with kw send-patch
Miscellaneous Notes

For students of the Free Software Development course, pay attention to these warning boxes, as they will contain specific instructions for this audience.

Option A: `git credential` helper

Beyond helping you with commits, branches, remotes, sending emails, etc., git also has a command for storing/retrieving credentials and prompting the user for usernames and passwords called git credential. This is a versatile command that is extensible using arbitrary helpers that need “only” to provide the fill (fill username and password), approve (store credentials), and reject (remove credentials) actions.

An example of a built-in helper in git is credential-cache, which can temporarily store credentials for a given context.

Installing the `git credential` helper and generating the access token

As mentioned, you can create your own helper that implements the necessary actions for a USP (Gmail) email. Nevertheless, for simplicity, we will use an existing project called git-credential-email, which provides a helper for Gmail accounts. To install git-credential-gmail (the Gmail helper), refer to the installation section for system-specific instructions. Note that you only need to install the git-credential-gmail helper, not the helpers for other email providers.

After installing git-credential-gmail, you need to obtain an OAuth client ID and secret. These two client tokens need to be generated on your own, although you can reuse other “open” tokens. By default, git-credential-email helpers use the Thunderbird token pair, but you can set specific ones by running this command and selecting the 6th option it gives:

git credential-gmail --set-client

Note that this will also prompt for a Redirect URI, which you should fill with:

Enter the Redirect URI: http://localhost

For students of the Free Software Development course, consult the pad for the tokens, set them, and don’t forget to add your USP email address there as instructed by the mentors.

After setting the OAuth client, we need to generate the access token (the OAuth “password”) by authenticating:

git credential-gmail --authenticate --external-auth

Follow the instructions that appear, which boil down to pasting the provided URL in a browser, authenticating your USP email, and then pasting the resulting URL back in the terminal. If everything went right, you should be able to see the access token with:

git credential-gmail

git-credential-email stores the access token (and the refresh token) in your system’s keyring with the help of the keyring Python module.

Configuring `git send-email` and `credential` manually

For this tutorial, we will not develop or submit a real contribution, so create an empty repository just for us to test the setup:

git init /tmp/git-credential-test

Then, move to this repo:

cd /tmp/git-credential-test

Inside the created repo, let’s edit the local configurations that git send-email and credential will use:

git config --local --edit

This will open an editor, with the local git config file (.git/config), where you need to append it with (adapt the necessary fields):

...
[credential "smtp://smtp.gmail.com:465"]
helper = 
helper = gmail
[sendemail]
smtpEncryption = ssl
smtpServer = smtp.gmail.com
smtpUser = <ADAPT-TO-YOUR-USP-EMAIL-ADDRESS>
smtpServerPort = 465
smtpAuth = OAUTHBEARER
from = <ADAPT-TO-YOUR-NAME-AND-SURNAME>

The configurations above tell git send-email to use OAuth to authenticate to Google’s SMTP servers, and to use the credential helper gmail (i.e., the git-credential-gmail helper we installed) for credentials. These commands will modify your local Git configurations inside .git/config. In case of any trouble, check this file to see if the information is correct.

Testing the setup with `kw send-patch`

After configuring your git send-email and credential helper for Gmail, we are ready to test our setup! For this, we will be using kw send-patch.

We won’t cover installing kw, so refer to the kworkflow site or the GitHub repo if you need help.

Inside the empty repo, we initialised and configured git send-email and the credential helper. Create any commit you wish and choose the email address(es) that will receive this test message.

For students of the Free Software Development course, create a commit titled <YOUR-FIRST-NAME> <YOUR-SURNAME> that adds a file named <YOUR-FIRST-NAME>.<YOUR-SURNAME>.txt that contains the string I am <YOUR-FIRST-NAME> <YOUR-SURNAME>. For the message recipients, use your own email address and dsl26oauthproxy@gmail.com.

After preparing our test commit, first let us check if kw send-patch would send the correct message to the correct people before actually sending the message (this is a good idea every time we are dealing with kw send-patch or git send-email) adapting the necessary fields:

kw send-patch --send -1 --private --simulate --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

This command will open an editor with the contents of the message to be sent, including the code. With the --simulate flag, kw send-patch will do everything it would do if it were to send the message, except actually sending it. In this sense, you can check the output of the command to see if the To: and Cc: fields are correct, along with the message subject, contents, etc. After being sure that the correct message and recipients are generated, drop the --simulate flag and rerun the command:

kw send-patch --send -1 --private --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

After exiting the editor, it should indicate that the message was successfully sent, and you can check the recipient(s) of your test email to see if the message(s) have arrived.

For students of the Free Software Development course, you don’t need to notify the mentors to check if the messages arrived in the previously provided email address, as just checking your own email inboxes will be sufficient.

Option B: Email Proxy

Our email proxy will be based on the email-oauth2-proxy project, a Python script configurable via an INI-like file. To avoid distro-specific nuances, we will use docker and docker-compose to streamline the process, so make sure they are installed and configured on your system!

Running the email proxy

Once you have docker and docker-compose installed and configured, clone this repository:

git clone https://github.com/davidbtadokoro/emailproxy-container.git

In this repo, you will find 3 files:

Dockerfile: the recipe for our cotainer image.
docker-compose.yaml: the orchestration script to simplify running our container.
emailproxy.config: the configuration file for the email proxy.

For this tutorial, you will only need to modify emailproxy.config; however, you can check and tinker with the other 2 files if you are curious, as they are really simple.

Opening emailproxy.config, you will notice some <FILL-HERE-...> fields:

...

[Account setup]

[<FILL-HERE-USP-EMAIL-ADDRESS>]
permission_url = https://accounts.google.com/o/oauth2/auth
token_url = https://oauth2.googleapis.com/token
oauth2_scope = https://mail.google.com/
redirect_uri = http://localhost
client_id = <FILL-HERE-CLIENT-ID>
client_secret = <FILL-HERE-CLIENT-SECRET>

...

You need to replace these fields with the USP email address you will use and the OAuth client ID and secret. These two client tokens need to be generated on your own, although you can reuse other “open” tokens.

For students of the Free Software Development course, consult the pad for the tokens and don’t forget to add your USP email address there as instructed by the mentors.

After filling the necessary fields, build and start the container with docker-compose:

docker compose up --build

If you investigated the Dockerfile, you may have noticed that this container does nothing (it only sleeps to infinity), so, on another terminal, enter the container:

docker exec -it emailproxy-container-server-1 /bin/bash

The container name should match the one above. If you run into any trouble, first check that you are using the correct name with docker ps. Inside the container, start the email proxy:

emailproxy --no-gui --external-auth --config-file /app/emailproxy.config

If everything worked correctly, you should see this at the end:

...
Initialised Email OAuth 2.0 Proxy - listening for authentication requests. Connect your email client to begin

Of course, don’t kill this process or the container, as the email proxy needs to be running for the next steps.

Configuring `git send-email` with `kw send-patch`

For this tutorial, we will not develop or submit a real contribution, so we will use the previously cloned repo for the email proxy in our git send-email configuration and testing. To accomplish this, we will leverage the convenience of kw send-patch.

We won’t cover installing kw, so refer to the kworkflow site or the GitHub repo if you need help.

On another terminal (again, keep the container and process running in the other terminals), go to the email proxy repo and run the following commands adapting the necessary fields:

kw send-patch --setup --name '<ADAPT-TO-YOUR-NAME-AND-SURNAME>'
kw send-patch --setup --email '<ADAPT-TO-YOUR-USP-EMAIL-ADDRESS>'
kw send-patch --setup --smtpuser '<ADAPT-TO-YOUR-USP-EMAIL-ADDRESS>'
kw send-patch --setup --smtpserver '127.0.0.1'
kw send-patch --setup --smtpserverport '2587'

These commands will modify your local Git configurations inside .git/config. In case of any trouble, check this file to see if the information is correct.

Testing the setup with `kw send-patch`

After starting the email proxy and configuring your git send-email with kw send-patch, we are ready to test our setup! Inside the email proxy repo, create any commit you wish and choose an email address(es) that will receive this test message.

kw send-patch --send -1 --private --simulate --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

kw send-patch --send -1 --private --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

After exiting the editor, you will be prompted to enter a password. For example:

...
Password for 'smtp://davidbtadokoro%40ime.usp.br@127.0.0.1:2587':

This password is not the same as the one you use for your account; actually, you can type in any password you wish, as this will be a local password for the email proxy. Just note that you need to use this same local password in future uses of the email proxy. After providing your password, go back to the terminal running the container (the one you ran docker exec), and note that you have an output similar to:

Please visit the following URL to authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br

Copy+paste or press [↵ Return] to visit the following URL and authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br then paste here the full post-authentication URL from the browser's address bar (it should start with http://localhost):

I suggest not using the [↵ Return] option and instead copying and pasting the URL into your browser. Doing so will open a Google authentication page that first asks whether you trust the client app associated with the tokens you provided, then prompts you to log in if necessary. After doing those, you will land on an Unable to connect or Problem loading page, which is expected! The only use of this page is its URL, starting with http://localhost/... that you need to copy and then paste back in the terminal running the container and press enter:

Copy+paste or press [↵ Return] to visit the following URL and authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br then paste here the full post-authentication URL from the browser's address bar (it should start with http://localhost): http://localhost/?iss=https://accounts.google.com&code=4/0Aci98E-fygcbbASm0JYllktwUvUo6gKexj4khWtKBMlLWWutANBX3tUtKHJAwaWq3uEcgg&scope=https://mail.google.com/

After that, you should see a log like:

SMTP (0.0.0.0:2587; davidbtadokoro@ime.usp.br) [ Successfully authenticated SMTP connection - releasing session ]

With that, you can go back to the terminal where you ran kw send-patch, and it should indicate success. Check the recipient(s) of your test email to see if the message(s) have arrived.

Miscellaneous Notes

The email proxy approach used in this tutorial focused on portability and on the specific task of sending patches with kw/git. You can optimise the approach to run natively on your own system and for other purposes. For example, I use the email proxy project mentioned as a systemd service that initialises with my system and that I use for my email client.
We didn’t delve deep into the protocol part of sending emails, but this is related to SMTP. That is why you see that the server setup in emailproxy.config has only an SMTP section with very specific values.
As OAuth is a protocol, you could implement your own system to do this proxying. The question is that git send-email (and sometimes other email-related apps too) doesn’t implement the client-side of the protocol, so we need to fill this in some way or another.
We used local Git configurations, which will be enforced in a per-repo logic. For global configurations, simply remove the --local flags in the configuration commands.

History

V1: Release with just the email proxy option.
V2: Include the credential helper option and do small adjustments to the rest of the post. Thanks Guilherme Ivo for the helper idea and for the review of this post.

Building and booting a custom Linux kernel for ARM using kw

2025-03-09T00:00:00-03:00

This tutorial describes how to build - in other words, compile - the Linux kernel for the ARM architecture and boot test it in a Virtual Machine (VM) using kw to streamline and automate some processes we will be doing. Basic kernel build configuration is covered too.

This tutorial was originally thought to be part of a set of tutorials tailored to aid newcomers in developing the Linux kernel Industrial I/O subsystem (IIO). It is the second in the series and a continuation of the “Setting up a test environment for Linux Kernel Dev using QEMU and libvirt” tutorial. This post is an adaptation of “Building and booting a custom Linux kernel for ARM” to use kw wherever is convenient.

Command Summary

Skip this section if you have not completed this tutorial yet. This is a reference for those who have gone through this tutorial and want to remember specific commands.

### INSTALL `kw`
git clone https://github.com/kworkflow/kworkflow.git "$KW_DIR"
cd "$KW_DIR"
git switch unstable # changes to the branch `unstable`
./setup.sh --full-installation # install `kw` w/ all dependencies for building Linux kernel

### SHALLOWLY CLONING THE IIO TREE W/ ACTIVE DEVELOPMENT BRANCH
git clone git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git "${IIO_TREE}" --branch testing --single-branch --depth 10

### CONFIGURING `kw`
cd "$IIO_TREE" # go to the IIO tree directory
kw init # initialize local configurations for the IIO tree
kw remote --add arm64 root@<VM-IP-address> --set-default # adds a remote named `arm64` to local context and set it to default
kw config build.arch 'arm64' # defines the target architecture to ARM64
kw config build.cross_compile 'aarch64-linux-gnu-' # defines the cross-compiler
kw config build.kernel_img_name 'Image.gz' # defines the kernel image format
kw config --show build # check `kw build` configurations

### CREATING A LEAN `.config` file
cd "$IIO_TREE" # go to the IIO tree directory
make ARCH=arm64 defconfig # create predefined defconfig
make ARCH=arm64 olddefconfig # update defconfig with new default values
kw ssh --get '~/vm_mod_list' # copy VM modules list to IIO tree
make ARCH=arm64 LSMOD=vm_mod_list localmodconfig
kw kernel-config-manager --save arm64-optimized # saves `.config` w/ name `arm64-optimized`
kw kernel-config-manager --list # lists all managed `.config`s
kw kernel-config-manager --get arm64-optimized # gets managed `.config` w/ name `arm64-optimized`

### BUILDING A LINUX KERNEL FROM SOURCE CODE
cd "$IIO_TREE" # go to the IIO tree directory
kw build --menu # safely modify `.config` w/ a TUI
kw build # compile Linux kernel from source considering local configurations

### INSTALLING LINUX KERNEL MODULES
cd "$IIO_TREE" # go to the IIO tree directory
kw deploy --modules # only install modules into the VM

Introduction

After setting up a test environment with VMs using QEMU and libvirt, we begin compiling (also called building) a custom Linux kernel from source and booting it. This involves taking the source code developed by the Linux community, compiling it into a monolithic executable that can be loaded into memory and run on hardware (virtualized or not), and using it to start a system. Additionally, we will compile and install kernel modules, smaller units that can be dynamically loaded and unloaded while the system is running. Cross-compilation will also be a factor, as we assume that the machine used to compile the source code to these artifacts has an AMD64 architecture, while the target architecture is ARM64.

kworkflow, or just kw, is a Free/Libre and Open Source Software (FLOSS) Developer Automation Workflow System (DAWS), which has the mission of reducing the environment and setup overhead of developing for Linux. Similar to how libvirt facilitated our management of VMs - albeit after some overhead setting its permissions to work - the kw project helps kernel developers in their day-to-day tasks, like streamlining and automating building and deploying custom Linux kernels from source. In this tutorial, kw will help us fetch an optimized .config for our VM, build the custom kernel image and modules, and install the modules inside the VM. It will also ease our life in terms of installing necessary dependencies to compile a Linux kernel.

Configuring, building, and booting a custom Linux kernel

In this section we will go through the steps on how to configure, compile, and boot customized Linux images in ARM64 VMs using kw.

Summary of this tutorial:

Installing kw
Cloning a Linux kernel tree
Configure kw in a local context for IIO development
Configuring the Linux kernel compilation
Building a custom Linux kernel
Installing modules and booting the custom-built Linux kernel

Before proceding remember to have the activate.sh script we’ve created available to be modified and active for all the commands run in the host system. Also assure that you have your testing environment set up from the last tutorial.

1) Installing `kw`

The easiest way to install kw is to clone it using git and run the setup.sh script. First, let’s add an env var for the path of kw repository in the activate.sh script.

--- a/activate.sh
+++ b/activate.sh
@@ -4,6 +4,7 @@
 export LK_DEV_DIR='/home/lk_dev' # path to testing environment directory
 export VM_DIR="${LK_DEV_DIR}/vm" # path to VM directory
 export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
+export KW_DIR="${LK_DEV_DIR}/kw" # path to `kw` repository

 # utility functions

Rerun the activate.sh after that and clone the kw repository

git clone https://github.com/kworkflow/kworkflow.git "$KW_DIR"

Then, go to the repository’s root and change it to the unstable branch. The default master is OK for this tutorial, but the latest kw development is pretty stable, although the name of the branch suggests otherwise.

cd "$KW_DIR"
git switch unstable # changes to the branch `unstable`

Finally, do the full installation of kw to include dependencies for building the kernel. If you are using a Arch, Debian, or Fedora-based distro, it should detect it and prompt you to enter the superuser credentials to start installing all the packages necessary.

./setup.sh --full-installation # install `kw` w/ all dependencies for building Linux kernel

From now on, you can update kw with itself! Running kw self-update updates kw with the latest development on the master branch, while kw self-update --unstable does the same for the unstable branch.

You may need to exit and rerun the activate.sh script for kw to show on your PATH. To ensure your kw installation was successful, run the following to see information about the release.

kw --version # print information about the `kw` release installed

2) Cloning a Linux kernel tree

There are several repositories that contain the source code for the Linux kernel. These repositories are known as Linux kernel trees, in short, kernel trees or just trees, because, as every software project, its source code is arranged in a tree-like file hierarchy. Some trees are widely known such as Linus Torvalds’ tree (known as mainline) that represent the most updated official version of Linux and the Linux stable tree that represents the stable releases (the 6.10, 6.11, 6.12, etc.). In general, a Linux tree is a repository where some development for the kernel happens and each tree follows its own development ruled by its own community. Many of those repos are at kernel.org.

Some examples of Linux kernel trees are:

For this workshop, we’ll be using the Industrial I/O (IIO) subsystem tree so download (clone) it with git. First, modify your activate.sh script

--- a/activate.sh
+++ b/activate.sh
@@ -4,6 +4,7 @@
 export LK_DEV_DIR='/home/lk_dev' # path to testing environment directory
 export VM_DIR="${LK_DEV_DIR}/vm" # path to VM directory
 export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
 export KW_DIR="${LK_DEV_DIR}/kw" # path to `kw` repository
+export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree

 # utility functions

then rerun the activate.sh script and clone the tree.

git clone git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git "${IIO_TREE}" --branch testing --single-branch --depth 10

In terms of source code, Linux kernel trees are already huge (a couple of GB in disk space), but the git history is even bigger at this point (around 5GB). To (hopefully) not use too much disk space and avoid longer download times, we use the --branch option, which tells git we want the testing branch of the remote pointed by the URL, and the --depth=10 option, which limits the git history to the latest 10 commits in the branch to be fetched. We’ve chosen the testing branch instead of the default master because the former is where the actual development happens. Hence, as in this series, we aim to (possibly) develop and propose changes to IIO, the testing branch is the one we are interested in.

If you have plenty of disk space (and probably some spare time), I suggest you clone the tree without the --branch and --depth flags because commit logs are often a good source of information when trying to understand kernel code. By the time this post was written, the IIO tree (with its entire git history) was sizing roughly 5GB.

3) Configure `kw` in a local context for IIO development

kw can create specific isolated configurations for each Linux kernel tree in the user’s filesystem. It can actually create multiple environments for a single tree, but this is too advanced for this tutorial. For now, let’s move into the IIO tree and initialize local configurations for that tree.

cd "$IIO_TREE" # go to the IIO tree directory
kw init # initialize local configurations for the IIO tree

For all kw commands run inside this tree, local configurations will override global ones whilst keeping them encapsulated in this context. This is similar to how git config and git config --global work.

Before moving forward, let’s start the VM running ARM64, which we set up in the last tutorial. Note that if either libvirtd, the default network, or the VM are already started, some commands will raise errors, indicating that these are already active.

@host
sudo systemctl start libvirtd # starts the libvirt daemon
sudo virsh net-start default # starts `virsh` default network
sudo virsh start --console arm64 # start a registered instance attaching console
sudo virsh net-dhcp-leases default # list `default` network to get VM IP

Inside the IIO tree, add the VM remote configurations for kw to manage it seamlessly.

@host
cd "$IIO_TREE"
### ADAPT THE COMMAND BELOW ###
kw remote --add arm64 root@<VM-IP-address> --set-default # adds a remote named `arm64` to local context and set it to default

To test if the remote addition was correctly done, run the following to initiate an SSH connection inside the IIO tree.

@host
cd "$IIO_TREE"
kw ssh # initiate an SSH connection to the default remote

You can check the remotes available in the current local context with kw remote --list.

4) Configuring the Linux kernel compilation

The Kernel Build System (kbuild) is based on make and other GNU tools and allows a highly modular and customizable build process for the Linux kernel. By default, kbuild uses the configuration options stored in the .config file under the root directory of the Linux kernel tree, which shouldn’t be present in a freshly cloned tree. Those options hold values for configuration symbols associated with kernel resources such as drivers, tools, and features in general. Nearly all directories inside a kernel tree have a Kconfig file, which defines the symbols for the resources at the same level. Top Kconfig files include (source) Kconfig files from subdirectories thus creating a tree of configuration symbols. When needed, kbuild generates configuration options from Kconfig symbols and stores their values in a .config file. kbuild Makefiles then use these configuration values to compile code conditionally and to decide which objects to include in the monolithic kernel image and which objects to become modules [1] [2].

There are predefined .configs for building kernels for different architectures and purposes. These are called defconfig (default configuration) files. defconfig files store only specific non-default values for configuration symbols. For instance, one can find defconfig files for ARM architecture machines under arch/arm/configs. We will create a .config file from the arm64 defconfig.

@host
cd "$IIO_TREE"
make ARCH=arm64 defconfig # create predefined defconfig
make ARCH=arm64 olddefconfig # update defconfig with new default values

Fetch the saved list of modules you’ve generated in the first tutorial of the series and generate an optimized .config based on it. Refer to section 4 of the first tutorial, in case you don’t have this file.

@host
cd "$IIO_TREE"
kw ssh --get '~/vm_mod_list' # copy VM modules list to IIO tree
make ARCH=arm64 LSMOD=vm_mod_list localmodconfig

kw kernel-config-manager helps us manage multiple configs without having to manually move and rename files. Below are some commands to help you more robustly manage these .configs. Note that .configs are considered in a “global” context, so files managed by kw are accessible no matter the kernel tree you are.

@host
kw kernel-config-manager --save arm64-optimized # saves `.config` w/ name `arm64-optimized`
kw kernel-config-manager --list # lists all managed `.config`s
kw kernel-config-manager --get arm64-optimized # gets managed `.config` w/ name `arm64-optimized`

It is possible to open the .config file and directly edit it, but this isn’t recommended. A safer and more palatable way is to use one of the Terminal User Interfaces (TUI) provided by the Linux project

@host
cd "$IIO_TREE"
kw build --menu # open a TUI to safely edit the `.config`

Use the arrow keys to navigate and ENTER to change/toggle a configuration. You can take some time to familiarize with these menus and see the available configurations.

For this tutorial, we want to make a tiny customization: change the kernel image name. In the menu, select General setup, then in Local version - append to kernel release, put whatever you want to be appended after the kernel version, and disable Automatically append version information to the version string. Be aware that the string you input will be part of the name of your first custom kernel, so treat it well :)

To exit, hit F9, which will prompt you to save the changes. The figure below illustrates the steps.

Figure 1. Changing the kernel name with nconfig

You can check how many modules will be compiled along with other informations using kw.

@host
cd "$IIO_TREE"
kw build --info

5) Building a custom Linux kernel

Different processor architectures have distinct instruction sets and register names. Due to that, the binaries produced by a compiler for architecture A will not work on a machine of architecture B. So, we need to use a compiler that produces binaries compatible with the instruction set of the machine we want to run our kernel. Essentially, this concept is called Cross-Compilation.

In our case, we assume we have a development system of the AMD64 (x86_64) architecture, and the target machine is a VM of the ARM64 architecture.

Most distros should have a GCC package with a compiler for AMD64 host machines that produces binaries for ARM64 targets. On Debian and Fedora, the package name is gcc-aarch64-linux-gnu, while in Arch the package name is aarch64-linux-gnu-gcc.

# Arch-based distros
sudo pacman -Syy && sudo pacman -S aarch64-linux-gnu-gcc
# Debian-based distros
sudo apt update && sudo apt install gcc-aarch64-linux-gnu
# Fedora-based distros
sudo dnf update && sudo dnf install gcc-aarch64-linux-gnu

See the Complementary Commands section for advice if you are having problems in finding an equivalent package to your distro.

We just need to configure kw a little bit more to be good to go. As said, the IIO tree has local configurations, and we need to set some related to kw build, the feature that deals with everything related to compiling kernels. kw config --show build shows the status of configurations available.

@host
cd "$IIO_TREE"
kw config build.arch 'arm64' # defines the target architecture to ARM64
kw config build.cross_compile 'aarch64-linux-gnu-' # defines the cross-compiler
kw config build.kernel_img_name 'Image.gz' # defines the kernel image format
kw config --show build # check `kw build` configurations

Finally, let’s build our custom Linux kernel from source code. Mind that, although we made a really lean .config, compiling the kernel still is a heavy task, and even more so when cross-compiling.

@host
cd "$IIO_TREE"
kw build # compile Linux kernel from source considering local configurations

If everything goes right, you should see an arch/arm64/boot/Image, modules.order and alike files under the Linux source root directory.

6) Installing modules and booting the custom-built Linux kernel

@host
kw deploy --modules # only install modules into the VM

There may be some errors thrown about strip or make not being able to do some things, but they may not indicate a real error.

Finally, update your activate.sh script to boot the VM (both through pure QEMU and with libvirt) with the custom-built kernel. Don’t forget to adapt the modification to have the correct initrd and the correct vda partition depending on your VM particularities!

--- a/activate.sh
+++ b/activate.sh
@@ -23,7 +23,7 @@ function launch_vm_qemu() {
         -smp 2 \
         -netdev user,id=net0 -device virtio-net-device,netdev=net0 \
         -initrd "${BOOT_DIR}/<initrd>" \
-        -kernel "${BOOT_DIR}/<kernel>" \
+        -kernel "${IIO_TREE}/arch/arm64/boot/Image" \
         -append "loglevel=8 root=/dev/<vdaX> rootwait" \
         -device virtio-blk-pci,drive=hd \
         -drive if=none,file="${VM_DIR}/arm64_img.qcow2",format=qcow2,id=hd \
@@ -41,7 +41,7 @@ function create_vm_virsh() {
         --import \
         --features acpi=off \
         --disk path="${VM_DIR}/arm64_img.qcow2" \
-        --boot kernel=${BOOT_DIR}/<kernel>,initrd=${BOOT_DIR}/<initrd>,kernel_args="loglevel=8 root=/dev/<vdaX> rootwait" \
+        --boot kernel=${IIO_TREE}/arch/arm64/boot/Image,initrd=${BOOT_DIR}/<initrd>,kernel_args="loglevel=8 root=/dev/<vdaX> rootwait" \
         --network bridge:virbr0 \
         --graphics none
 }

Rerun the activate.sh script. Shutdown the VM and undefine it from libvirt managed VMs. Then, created it again

@host
sudo virsh shutdown arm64
sudo virsh undefine arm64
create_vm_virsh

Log into the VM and run

@VM
uname --kernel-release

to check that you are now running the custom kernel we just built. The output of this command should be something in the format of

<major-release-nr>.<minor-release-nr>.<patch-release-nr>-rc<one-through-eight>-<the-name-you-wrote>+

like, for example,

6.14.0-rc1-free-software+

Congratulations, you’ve just compiled and boot-tested a Linux kernel! From now on, whenever you make a change on the Linux kernel tree, you can “just” compile it, install the modules, and then shutdown, with sudo virsh shutdown arm64, and start the VM, with sudo virsh start arm64 (rebooting it doesn’t works). It will run the new custom kernel we will be capable to run validations inside this testing environment!

6.1) Installing the kernel image

Often, kernel developers also need to explicitly install the Linux kernel image to their target test machines. Notice that here, we are not copying or moving the Linux kernel image to nowhere inside the VM like we did when installing modules. Neither we are dealing with a physical machine.

Essentially, installing a new kernel image would be to just replace the vmlinuz/Image/zImage/bzImage/uImage file, which contains the Linux boot executable program. However, some platforms (such as AMD64 and ARM64) have fancy boot procedures with boot loaders that won’t find kernel images without very specific configuration pointing to them (e.g., GRUB), which might mount temporary file systems (initrd), load drivers prior to mounting the rootfs, and so on. To help setup those additional boot files and configuration, the Linux kernel has a install rule. So, kernel developers may also run make install or make install INSTALL_PATH=<path_to_bootfs> when deploying kernels to those platforms.

For this setup, we shall not bother with that. We don’t need to run the installation rule because we instructed QEMU (with -kernel) and libvirt (with --boot kernel=...) to pick up the kernel image in the tree that resulted from the compilation, and we are reusing the initrd file from the original guest OS that came with disk image.

This shows the plurality of the umbrella Linux project; Linux is composed of many subprojects (called subsystems), each one with their own development contexts, accomplishing similar tasks in the most varied ways, sometimes even duplicating (or wasting) efforts.

Complementary Commands

One may also download cross compiler toolchains from different vendors. For instance, ARM provides an equivalent cross compiler that you may download if having trouble finding a proper distro package.

wget -O "${LK_DEV_DIR}/gcc-aarch64-linux-gnu.tar.xz" https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
tar -xf -C "$LK_DEV_DIR" "${LK_DEV_DIR}/gcc-aarch64-linux-gnu.tar.xz"

Sometimes identifying the cross compiler for your combination of host and target machines may require some understanding of what is called the compiler triplet. Conceptually, the compiler triplet should contain three fields: the name of the CPU family/model, the vendor, and the operating system name [3]. However, sometimes the vendor is omitted so one may find a triplet like x86_64-freebsd (FreeBSD kernel for 64-bit x86 CPUs) [3]. It is also common to see the operating system information split into two separate fields, one for indicating the kernel and the other for describing the runtime environment or C library which is being used. The the debian package for x86-64 gcc is an example of this triplet format mutation: gcc-x86-64-linux-gnu (compiler for 64-bit x86 targets that will run a Linux kernel and have GNU glibc in their runtime). But things can get even more unintuitive when system call conventions or Application Binary Interfaces (ABI) are specified in the OS field as in arm-linux-gnueabi (compiler for 32-bit ARM targets that will run Linux using the EABI system call convention) or as in arm-none-eabi (compiler for 32-bit ARM that will run no OS (bare-metal) using the EABI system call convention).

Anyways, you may point to the generic cross compiler name when using compilers not under your PATH. For example:

export CROSS_COMPILE="${LK_DEV_DIR}/gcc-aarch64-linux-gnu/bin/aarch64-none-linux-gnu-"

Conclusion

This tutorial described how to configure and build a custom Linux kernel and boot-test it into a VM. To accomplish that, we covered basic concepts of Linux kernel build configuration to guide readers into generating feasible .config files, and some cross-compilation concepts. By this point, you should be able to configure, build, and boot-test a custom Linux kernel from source code in a safe, while not-so-much efficient (we will work on that), testing environment.

We also introduced kw, a feature-rich system with the mission of helping kernel developers do their day-to-day tasks more efficiently, error-free, and intuitively.

History

V1: Release

References

[1] Javier Martinez Canillas. “Kbuild: the Linux Kernel Build System”. (2012) URL: https://www.linuxjournal.com/content/kbuild-linux-kernel-build-system. ⤴

[2] Michael Elizabeth Chastain and Kai Germaschewski and Sam Ravnborg. “Linux Kernel Makefiles”. (2023) URL: https://www.kernel.org/doc/html/latest/kbuild/makefiles.html. ⤴

[3] . “Target Triplet”. (2019) URL: https://wiki.osdev.org/Target_Triplet. ⤴

Introduction to Linux kernel Character Device Drivers

2024-02-15T00:00:00-03:00

This tutorial explains a few aspects of Linux character devices with a basic character device driver example. It is best enjoyed as a continuation of “Introduction to Linux kernel build configuration and modules” tutorial.

Command Summary

Skip this section if you have not completed this tutorial yet. This is a reference for those who have gone through this tutorial and want to remember specific commands.

cat /proc/devices
stat <file>
mknod <file_name> <type> <major_num> <minor_num>
dmesg -w

Introduction

In Linux, character devices facilitate sequential data exchange between user space and the system, handling dynamic data streams. They provide a flexible interface for interacting with hardware or software components.

Character device drivers define how these devices operate, managing data flow and access. They serve as an abstraction layer, enabling controlled and efficient communication between applications and the underlying system.

Introduction to Linux kernel character device drivers

This tutorial presents and explains a few key concepts related to Linux character devices, then presents an example Linux kernel character device driver that is built on top of the presented ideas.

Summary of the parts of this tutorial:

Character devices
Major and Minor Numbers
File operations
Bringing device IDs and file operations together
A character device driver example
Testing the simple_char driver

1) Character devices

A character device is an abstraction provided by Linux operating systems to support devices that can be read from or written to with relatively small data transfers which are usually byte size or few bytes size. They are often abstracted as files in the file system and accessed through conventional file access system calls. Devices supported as character devices are serial ports, keyboards, mice, etc. Example of character device files are /dev/ttyS0, dev/input/mouse0, /dev/kmsg, /dev/zero.

2) Major and Minor Numbers

The files associated with character devices (like /dev/ttyS0 and dev/input/mouse0) are special types of files which allow users to interface with devices from the user space. Under the hood of character device files are the device drivers that handle the system calls for them.

The association between device files and devices is made with a device ID that consists of two parts: a major and a minor number [1]. The minor number is only used within the device driver to distinguish between multiple devices of same type (such as the first and the second display) or to switch between operation modes of a device. The major number can be requested to be a specific number or allocated dynamically. The device ID formed from the major/minor number combination is what the kernel uses to choose which driver to run to support a particular device. Inside the Linux kernel, the device ID is stored as a 32-bit unsigned integer defined by the dev_t type. The 12 most significant bits of a dev_t variable store the major device number while the 20 remaining bits store the minor number.

In old versions of the Linux kernel, once a major number was registered for a driver, no other driver could use the same major number and all minor numbers associated with that major number were owned by the driver. Back then, one could state that a major number was unique for a driver. That might not hold always true nowadays since, in modern kernels, drivers allocate a range (not all) of minor numbers within the set of possible minor numbers. With that, it is now possible for more than one driver to have the same major number as long as their range of minor numbers do not intersect.

Within the Linux kernel, one can use the functions declared in include/linux/fs.h to allocate device major and minor numbers for a device. For example, to dynamically allocate a device major number along with a range of minor numbers one can call alloc_chrdev_region().

#include <linux/fs.h>

int alloc_chrdev_region(dev_t *dev, unsigned baseminor, unsigned count, const char *name);

The macros MAJOR(), MINOR(), and MKDEV() from include/linux/kdev_t.h can be used to extract the major/minor number from a dev_t variable and to make a device ID from a pair of major and minor numbers, respectively.

At any moment, a list of character and block devices in the system can be retrieved from the /proc/devices file.

$ cat /proc/devices
Character devices:
mem
/dev/vc/0
tty
ttyS
/dev/tty
/dev/console
/dev/ptmx
lp
...

The numbers on the left are the major device numbers and the strings on the right correspond to the registered names of the device drivers that handle the respective device. Notice in the example above that the devices represented by the files /dev/tty, /dev/console, and /dev/ptmx share the same major number. That is possible thanks to each driver only registering a subset of the available minor numbers.

One can use stat to get major and minor numbers for the device backing a file. For example:

$ stat /boot/vmlinuz-6.5.0-5-amd64
  File: /boot/vmlinuz-6.5.0-5-amd64
  Size: 9127904         Blocks: 17832      IO Block: 4096   regular file
Device: 8,1     Inode: 4981079     Links: 1
Access: (0644/-rw-r--r--)  Uid: (    0/    root)   Gid: (    0/    root)
Access: 2024-01-04 10:51:19.000000000 -0300
Modify: 2023-11-29 04:45:07.000000000 -0300
Change: 2024-01-04 10:53:32.315343926 -0300
 Birth: 2024-01-04 10:53:29.707343958 -0300

The output of stat shows that the Linux image (vmlinuz-6.5.0-5-amd64) is stored as a regular file and the device responsible for it has major number 8 and minor number 1 (/dev/sda1).

To get major and minor numbers of character devices we must look at the Device type field.

$ stat /dev/ttyS0
  File: /dev/ttyS0
  Size: 0               Blocks: 0          IO Block: 4096   character special file
Device: 0,5     Inode: 94          Links: 1     Device type: 4,64
Access: (0660/crw-rw----)  Uid: (    0/    root)   Gid: (   20/ dialout)
Access: 2024-03-29 09:14:38.329879779 -0300
Modify: 2024-03-29 09:14:57.329879779 -0300
Change: 2024-03-29 09:14:38.329879779 -0300
 Birth: 2024-03-29 09:14:32.192000051 -0300

So, that tty character device has major number 4 and minor number 64.

We can manually create files to interface with character devices using mknod [2]. A file that serves as interface for a device is often called a device node, device file, or device special file [3].

3) File operations

Since character devices may interface with user space through files, character device drivers may implement functions to handle file access system calls. The set of those syscalls implemented by a device driver is set into a struct file_operations object. There are several different file operations a character driver can implement. In this tutorial we will focus on the most basic system calls for a character device: open, close, read, write. All of those have manual pages of same name. Whithin the Linux kernel, these operations are respectively handled by open, release, read, and write functions stored in struct file_operations objects.

struct file_operations {
	struct module *owner;
	loff_t (*llseek) (struct file *, loff_t, int);
	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
	ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
<snipped>
	int (*open) (struct inode *, struct file *);
	int (*flush) (struct file *, fl_owner_t id);
	int (*release) (struct inode *, struct file *);
<snipped>
}

See the definition of struct file_operations in include/linux/fs.h for a complete list of entry points a driver can implement.

File read/write operations

Kernel code should not directly de-reference pointers to memory in user space (i.e., we should not access the __user buffer with conventional C memory access operations). Kernel and user space memory addresses may be (and often are) in separate address regions, offset by PAGE_OFFSET physical memory addresses. Because of that, the address of a user space pointer might not lead to the memory address of user space data when de-referencing it from kernel space. Furthermore, most modern systems provide virtualised memory address for user space memory and memory paging, meaning that a user space memory address may not be valid at a given moment either because its page has not been allocated yet or it has been swapped out. If you got interested about Linux memory management, watch Matt Porter’s Introduction to Memory Management in Linux after finishing this tutorial.

To implement the read and write entry points we will use memory access functions from include/linux/uaccess.h.

#include <linux/uaccess.h>

unsigned long copy_from_user(void *to, const void __user *from, unsigned long n)
unsigned long copy_to_user(void __user *to, const void *from, unsigned long n)

The semantics of the copy_from_user() function are the same as memcpy(). It copies n bytes of data from the source (from) memory area to the destination one (to). One important difference though is that the return of copy_from_user() is the number of bytes not successfully copied. The copy_to_user() is analogous to copy_from_user() but with opposite direction.

4) Bringing device IDs and file operations together

For a character device, we have major/minor numbers (combined into dev_t) to identify the driver to handle system calls for files/nodes linking to it. We also have struct file_operations to store the set of operations supported for the character device. To tie together device IDs and file operations, the kernel uses the struct cdev structure (character device) defined in include/linux/cdev.h.

struct cdev {
	struct kobject kobj;
	struct module *owner;
	const struct file_operations *ops;
	struct list_head list;
	dev_t dev;
	unsigned int count;
} __randomize_layout;

struct kobject kobj is the embedded kobject struct of the cdev structure used for reference counting.

struct module *owner holds the owner of the resource within the kernel. Later, we will use the character device module as resource owner.

const struct file_operations *ops is the file operations structure discussed earlier.

struct list_head list is a double linked list for traversing character devices.

dev_t dev is the device ID.

unsigned int count holds the amount of minor numbers owned by the character device.

The rudimentary functions for registering a cdev are:

#include <linux/cdev.h>

struct cdev *cdev_alloc(void)
void cdev_init(struct cdev *cdev, const struct file_operations *fops)
int cdev_add(struct cdev *p, dev_t dev, unsigned count)
void cdev_del(struct cdev *p)

struct cdev *cdev_alloc(void) allocates and initializes a cdev struct object.

void cdev_init(struct cdev *cdev, const struct file_operations *fops) is equivalent to cdev_alloc() except it expects the caller to pass a pointer to an already allocated cdev object and it also sets the file operations field for it. If using cdev_init(), the caller is responsible for freeing the cdev object after the character device is removed from the system.

int cdev_add(struct cdev *p, dev_t dev, unsigned count) registers/adds the character device to the system by creating an entry for it in the struct kobj_map *cdev_map array kept in fs/char_dev.c.

void cdev_del(struct cdev *p) removes the character device from the system by removing its entry from the cdev_map array. It also decrement the reference count of the character device which will free the cdev struct if it was allocated with cdev_alloc().

5) A character device driver example

Let’s create an example character device driver to see how it all works. Create ${IIO_TREE}/drivers/char/simple_char.c in the Linux kernel sources and add the code for it. Notice most of the ideas within it have been covered in previous sections.

#include <linux/init.h>
#include <linux/module.h>

#include <linux/kdev_t.h> /* for MAJOR */
#include <linux/cdev.h> /* for cdev */
#include <linux/fs.h> /* for chrdev functions */
#include <linux/slab.h> /* for malloc */
#include <linux/string.h> /* for strlen() */
#include <linux/uaccess.h> /* copy_to_user() */

struct cdev *s_cdev;
static dev_t dev_id;

#define S_BUFF_SIZE 4096
static char *s_buf;

#define MINOR_NUMS 1

static int simple_char_open(struct inode *inode, struct file *file)
{
	pr_info("%s: %s\n", KBUILD_MODNAME, __func__);
	return 0;
}

static ssize_t simple_char_read(struct file *file, char __user *buffer,
				size_t count, loff_t *ppos)
{
	int n_bytes;

	pr_info("%s: %s about to read %ld bytes from buffer position %lld\n",
		KBUILD_MODNAME, __func__, count, *ppos);
	n_bytes = count - copy_to_user(buffer, s_buf + *ppos, count);
	*ppos += n_bytes;
	return n_bytes;
}

static ssize_t simple_char_write(struct file *file, const char __user *buffer,
				size_t count, loff_t *ppos)
{
	int n_bytes;
	pr_info("%s: %s about to write %ld bytes to buffer position %lld\n",
		KBUILD_MODNAME, __func__, count, *ppos);
	n_bytes = count - copy_from_user(s_buf + *ppos, buffer, count);
	return n_bytes;
}

static int simple_char_release(struct inode *inode, struct file *file)
{
	pr_info("%s: %s\n", KBUILD_MODNAME, __func__);
	return 0;
}

static const struct file_operations simple_char_fops = {
	.owner = THIS_MODULE,
	.open = simple_char_open,
	.release = simple_char_release,
	.read = simple_char_read,
	.write = simple_char_write,
};

static int __init simple_char_init(void)
{
	int ret;

	pr_info("Initialize %s module.\n", KBUILD_MODNAME);

	/* Allocate an internal buffer for reads and writes. */
	s_buf = kmalloc(S_BUFF_SIZE, GFP_KERNEL);
	if (!s_buf)
		return -ENOMEM;

	strcpy(s_buf, "This is data from simple_char buffer.");

	/* Dynamically allocate character device device numbers. */
	/* The name passed here will appear in /proc/devices. */
	ret = alloc_chrdev_region(&dev_id, 0, MINOR_NUMS, "simple_char");
	if (ret < 0)
		return ret;

	/* Allocate and initialize the character device cdev structure */
	s_cdev = cdev_alloc();
	s_cdev->ops = &simple_char_fops;
	s_cdev->owner = simple_char_fops.owner;

	/* Adds a mapping for the device ID into the system. */
	return cdev_add(s_cdev, dev_id, MINOR_NUMS);
}

static void __exit simple_char_exit(void)
{
	/*
	 * Undoes the device ID mapping and frees cdev struct, removing the
	 * character device from the system.
	 */
	cdev_del(s_cdev);
	/* Unregisters (disassociate) the device numbers allocated. */
	unregister_chrdev_region(dev_id, MINOR_NUMS);

	kfree(s_buf);
	pr_info("%s exiting.\n", KBUILD_MODNAME);
}

module_init(simple_char_init);
module_exit(simple_char_exit);

MODULE_AUTHOR("A Linux kernel student <name.surname@usp.br>");
MODULE_DESCRIPTION("A simple character device driver example.");
MODULE_LICENSE("GPL");

Don’t forget to add a configuration symbol for the simple_char driver within ${IIO_TREE}/drivers/char/Kconfig.

config SIMPLE_CHAR
       tristate "Simple character driver example"
       default m
       help
         This option enables a simple character driver that implements basic
         file access operations.

Also add a build rule for it in ${IIO_TREE}/drivers/char/Makefile.

obj-$(CONFIG_SIMPLE_CHAR)      += simple_char.o

Configure and build the Linux kernel with the simple_char driver as explained in previous build and configuration tutorials.

If you get prompted by many config options after running make -C "$IIO_TREE" Image.gz modules, consider interrupting the kernel build and running make -C "$TREE_IIO" olddefconfig.

6) Testing the `simple_char` driver

Install the simple_char driver in a Linux OS. If you have followed the previous tutorials, you can install it to the arm64 virtual machine. Load the driver module and inspect /proc/devices to get what major number the character device got. Then use that major number to create a file to interface with your character device.

@VM
root@localhost:~# modprobe simple_char
root@localhost:~# cat /proc/devices | grep simp
511 simple_char
root@localhost:~# mknod simple_char_node c 511 0
root@localhost:~# stat simple_char_node
  File: simple_char_node
  Size: 0               Blocks: 0          IO Block: 4096   character special file
Device: 254,2   Inode: 2142        Links: 1     Device type: 511,0
Access: (0644/crw-r--r--)  Uid: (    0/    root)   Gid: (    0/    root)
Access: 2024-03-16 18:26:55.133581798 +0000
Modify: 2024-03-16 18:26:55.133581798 +0000
Change: 2024-03-16 18:26:55.133581798 +0000
 Birth: 2024-03-16 18:26:55.133581798 +0000

Create ${LK_DEV_DIR}/read_prog.c to test reading from our character device.

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>

#define BUF_SIZE 256

/* Example inspired from open(2) */
int main(int argc, const char **argv)
{
	char buf[BUF_SIZE];
	int fd;

	if (argc < 2)
		return -22;

	fd = open(argv[1], O_RDONLY);
	read(fd, buf, BUF_SIZE);
	printf("Read buffer: %s\n", buf);
	close(fd);
}

Although it is advisable to handle possible errors that may happen when accessing files, ${LK_DEV_DIR}/read_prog.c was left with no error handling to keep the example small and simple. Compile the read test program for your Linux test machine. If you have followed the previous tutorials, you can use the GCC from the cross compiler toolchain you have for building the kernel to compile the test program. Send the binary to the virtual machine and run it there.

@host
aarch64-linux-gnu-gcc read_prog.c -o read_prog
scp read_prog root@<VM-IP-ADDRESS>:~/
@VM
root@localhost:~# ./read_prog simple_char_node

Here is the ${LK_DEV_DIR}/write_prog.c test program for writing to the character device.

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <errno.h>

#define BUF_SIZE 256

int main(int argc, const char **argv)
{
	char buf[BUF_SIZE];
	int errsv;
	int ret;
	int fd;

	if (argc < 2)
		return -EINVAL;

	sprintf(buf, "A new message for simple_char.");
	fd = open(argv[1], O_RDWR);
	ret = write(fd, buf, BUF_SIZE);
	if (ret < 0) {
		errsv = errno;
		printf("Error: %d", errsv);
	}
	printf("wrote %d bytes to buffer\n", ret);
	return close(fd);
}

Build and run the same way done for the read test program.

@host
aarch64-linux-gnu-gcc write_prog.c -o write_prog
scp write_prog root@<VM-IP-ADDRESS>:~/
@VM
root@localhost:~# ./write_prog simple_char_node

Proposed Exercises

Printing device numbers: Modify the simple_char driver to make it print major and minor device numbers on device open.
Device private data: Modify the simple_char driver to register more than one minor device number and make it keep separate buffers for each of them. Check the device minor number on device open and allocate a buffer for it if it doesn’t have one. Also, make the read/write operations run over the buffer for the particular major/minor device number pair. Access f_inode field of struct file to get a pointer to the device inode then access i_rdev field of struct inode to get the device ID (dev_t) from which you can extract the device minor number. On module unload, free all allocated buffers. With that, we can think of each pair of major/minor numbers as a different character device and each of them will have their own data. Finally, create device nodes with different minor numbers to test you implementation.

Conclusion

This post presented a few key concepts related to Linux kernel character devices and provided a character device driver example that shows how the covered concepts apply in practice.

History

V1: Release
V2: Review for the Free Software Development course offered in 2025-1 at IME-USP

References

[1] . “makedev(3)”. URL: https://man.archlinux.org/man/makedev.3.en. ⤴

[2] David MacKenzie. “MKNOD(1)”. URL: https://man.archlinux.org/man/mknod.1. ⤴

[3] David MacKenzie. “device_node”. URL: https://wiki.debian.org/device_node. ⤴

Introduction to Linux kernel build configuration and modules

2023-10-14T00:00:00-03:00

This tutorial shows how to make a simple Linux kernel module and how to create build configurations for new kernel features.

This tutorial was originally thought to be part of a set of tutorials tailored to aid newcomers to develop for the Linux kernel Industrial I/O subsystem. This is a continuation for the “Building and booting a custom Linux kernel for ARM” and “Building and booting a custom Linux kernel for ARM using kw” tutorial.

Command Summary

If you did not read this tutorial yet, skip this section. This section was added as a summary for those that already went through this tutorial and just want to remember a specific command.

### MAKE COMMANDS TO CONFIGURE, COMPILE, AND INSTALL MODULES
make -C "$IIO_TREE" menuconfig # manage `.config` w/ a TUI
make -C "$IIO_TREE" -j$(nproc) Image.gz modules # compile kernel image and modules
make -C "$IIO_TREE" modules_install # install modules
make -C "$IIO_TREE" modules_prepare # refresh modules for compilation
make -C "$IIO_TREE" M=<path-of-dir-to-build> # compile only a subset of the tree

### MANIPULATING MODULES
modinfo <module_name> # see information about module of given name
insmod <module_file.ko> # loads module at given location
rmmod <module_name> # unloads module of given name
modprobe <module_name> # loads module of given name and its dependencies 
modprobe -r <module_name> # unloads module of given name
depmod --quick # updates the module dependency list only if a module is added or removed

### SEE KERNEL LOGS
dmesg | tail # see last logs

Introduction

Kernel modules are code segments that can be dynamically inserted into or removed from the kernel as needed. They enhance the kernel’s capabilities without requiring a system reboot. A prime example is a device driver module, which enables the kernel to communicate with connected hardware. Without modules, systems typically rely on monolithic kernels, where new features must be directly incorporated into the kernel image. This results in larger kernel sizes and demands recompilation and a system restart whenever additional functionality is introduced.

Starting to tinker with the Linux codebase through modules is interesting as we can have an isolated context to understand other concepts about Linux development, and this is precisely what we will do in this tutorial.

Introduction to Linux kernel build configuration and modules

This part shows how to build and test a simple kernel module and explores the Linux kernel build configuration further by explaining how to use menuconfig to enable kernel features and how to create your own build configuration for a simple example module.

Summary of the parts of this tutorial:

Creating a simple example module
Creating Linux kernel configuration symbols
Configuring the Linux kernel build with menuconfig
Installing Linux kernel modules
Dependencies between kernel features

1) Creating a simple example module

Don’t forget to have the activate.sh script built in the last tutorials running.

From the root of the Linux kernel source code, create the file ${IIO_TREE}/drivers/misc/simple_mod.c and add the code for the simple mod in there.

#include <linux/module.h>
#include <linux/init.h>

static int __init simple_mod_init(void)
{
	pr_info("Hello world\n");
	return 0;
}

static void __exit simple_mod_exit(void)
{
	pr_info("Goodbye world\n");
}

module_init(simple_mod_init);
module_exit(simple_mod_exit);

MODULE_LICENSE("GPL");

2) Creating Linux kernel configuration symbols

Now, let’s create a Kconfig configuration symbol for our simple module and add the associated Kbuild configuration option to build it. When adding new Kconfig symbols we usually write them in the Kconfig file that stands in the same directory of the thing we want to build. The simple_mod.c module is under ${IIO_TREE}/drivers/misc/ so we will add a configuration symbol for that in ${IIO_TREE}/drivers/misc/Kconfig.

When adding entries to kbuild Kconfig and Makefiles we also follow the convention of keeping the entries in alphabetical order. The convention is not enforced by the build system so out of order entries will not prevent us from building the kernel. Nevertheless, keeping entries in order definitely helps developers find build configurations when looking for them. Also, the Linux kernel community will ask code submitters to keep things organized when upstreaming new configuration symbols. Let’s keep the good practices.

config SIMPLE_MOD
	tristate "Simple example Linux kernel module"
	default	n
	help
	  This option enables a simple module that says hello upon load and
	  bye on unloading.

The config keyword defines a new configuration symbol. Further, Kbuild will generate a configuration option for that symbol which in turn will be stored as a configuration entry in the .config file. Configuration options will also show in kernel configuration tools such as menuconfig, nconfig, or during the compilation process. In particular, the SIMPLE_MOD configuration symbol has the following attributes:

tristate: the type for the configuration option. It declares that this symbol stands for something that may be compiled as a module (m), built-in compiled (y) (i.e., included in the kernel image), or not compiled at all (n). The type definition also accepts an optional input prompt to set the option name that kernel configuration tools display.
default: the value that should be selected by kernel config tools if no explicit value has been assigned to the associated configuration option (such as when applying a defconfig).
help: defines a help text to be displayed as auxiliary info.

Other common attributes for configuration symbols are:

bool: type for features that can only be either enabled or disabled.
depends on: list of dependency symbols. If its dependencies are not satisfied, this symbol may become non-visible during configuration or compilation time. As an experiment, try to disable SPI support at Device Drivers. Many ADCs will no longer be listed at Device Drivers -> Industrial I/O support -> Analog to digital converters.
select: when the symbol containing the select list is enabled, the symbols from its select list will also be enabled. Note the symbols in this list will not be disabled if the symbol containing the select list is later disabled.

Now we add the simple_mod module to the list of build objects in ${IIO_TREE}/drivers/misc/Makefile.

obj-$(CONFIG_SIMPLE_MOD)		+= simple_mod.o

That’s all we need for enabling the configuration of our simple_mod with kbuild.

3) Configuring the Linux kernel build with menuconfig

Run menuconfig and enable our example module.

make -C "$IIO_TREE" menuconfig

Type forward slash (/) to search by symbol name. In the search screen, type simple_mod then enter. The description of the simple_mod will appear. Type 1 to go to the configuration option. With selection over the simple_mod option, type m to enable it as a module. Save the configuration and exit menuconfig.

Figure 1. Enabling simple_mod with menuconfig

Before building the image and modules, let’s clean any artifacts from previous compilations. This isn’t strictly necessary, but it helps us ensure we are on the same page as much as possible.

```
cd "$IIO_TREE"
kw build --clean
```
```
make -C "$IIO_TREE" -j$(nproc) clean
```

Build image and modules again.

```
cd "$IIO_TREE"
kw build
```

make -C "$IIO_TREE" -j$(nproc) Image.gz modules

Install new kernel modules. No need to copy or install the kernel image since virt will pick the generated image file at ${IIO_TREE}/arch/arm/boot/Image.

mkdir "${VM_DIR}/arm64_rootfs"
### ADAPT THE COMMAND BELOW ###
sudo guestmount --rw --add "${VM_DIR}/arm64_img.qcow2" --mount /dev/<rootfs> "${VM_DIR}/arm64_rootfs" # mount the VM `rootfs` to the given mount point in read and write mode (this could take a while)
sudo --preserve-env make -C "${IIO_TREE}" INSTALL_MOD_PATH="${VM_DIR}/arm64_rootfs" modules_install # install modules to inside the VM
sudo guestunmount "${VM_DIR}/arm64_rootfs" # unmount the VM `rootfs`

### ADAPT THE COMMAND BELOW ###
sudo guestmount --rw --add "${VM_DIR}/arm64_img.qcow2" --mount /dev/<rootfs> "${VM_MOUNT_POINT}" # mount the VM `rootfs` to the given mount point in read and write mode (this could take a while)
sudo --preserve-env make -C "${IIO_TREE}" modules_install # install modules to inside the VM
sudo guestunmount "$VM_MOUNT_POINT" # unmount the VM `rootfs`

Connect to the VM with ssh.

```
sudo virsh start arm64
kw ssh
```

sudo virsh start arm64
sudo virsh start arm64
sudo virsh net-dhcp-leases default
ssh root@<VM-IP-address>

Verify the kernel version.

@VM
uname --all
cat /proc/version

4) Installing Linux kernel modules

Run modinfo which shows main info related to a kernel module. When known, modinfo will show the module file name, module author, module description, license, ailas, dependencies, signature, and signer.

@VM
modinfo simple_mod

List currently loaded kernel modules.

@VM
lsmod

You should have an output in similar to the below.

root@localhost:~# lsmod
Module                  Size  Used by
crct10dif_ce           12288  1
cfg80211              409600  0
rfkill                 28672  2 cfg80211
drm                   577536  0
dm_mod                131072  0
ip_tables              28672  0
x_tables               40960  1 ip_tables

Notice our simple_mod is not loaded. Let’s take care of it. There are two ways of loading a Linux kernel module: insmod and modprobe.

insmod takes a path to a module file (.ko) and loads that into the running kernel. The kernel object file doesn’t really need to have been installed as we did with modules_install. rmmod unloads the module. Load our example module with insmod.

@VM
insmod /lib/modules/$(uname -r)/kernel/drivers/misc/simple_mod.ko # loads module at given location

Then run dmesg to see kernel log messages. You should have something like this

root@localhost:~# dmesg | tail
<snipped>
[ 3962.547283] Hello world

Remove the module with rmmod.

@VM
rmmod simple_mod # unloads module of name `simple_mod`

Then run dmesg again to see kernel log messages. You should have something like this

root@localhost:~# dmesg | tail
<snipped>
[ 3973.986089] Goodbye world

We can do the same with modprobe.

@VM
modprobe simple_mod # loads module of name `simple_mod` 
dmesg | tail
modprobe -r simple_mod # unloads module of name `simple_mod` 
dmesg | tail

Instead of a module file, modprobe takes the module name as argument. For that to work, the module has to be installed within the kernel and module tracking files (such as modules.dep) must contain references to the requested module. The advantage of having that is that modprobe will look for module dependencies and (if any) properly load them before loading the requested module [1]. insmod does not check for any module dependencies.

5) Dependencies between kernel features

Let’s increment our example module to export a function that can be called by other modules.

#include <linux/module.h>
#include <linux/init.h>

void simple_mod_func(void);

void simple_mod_func(void)
{
	pr_info("Called %s, %s function\n", KBUILD_MODNAME, __func__);
}
EXPORT_SYMBOL_NS_GPL(simple_mod_func, "IIO_WORKSHOP_SIMPLE_MOD");

static int __init simple_mod_init(void)
{
	pr_info("Hello from %s module\n", KBUILD_MODNAME);
	return 0;
}

static void __exit simple_mod_exit(void)
{
	pr_info("Goodbye from %s\n", KBUILD_MODNAME);
}

module_init(simple_mod_init);
module_exit(simple_mod_exit);

MODULE_LICENSE("GPL");

Rebuild the example module and copy it to the virtual machine.

cd "$IIO_TREE"
kw build
kw ssh --send drivers/misc/simple_mod.ko

make -C "$IIO_TREE" M="${IIO_TREE}/drivers/misc/"
scp "${IIO_TREE}/drivers/misc/simple_mod.ko" root@<VM-IP-address>:~/

The M= option specify a directory for external module build. With that, we can only rebuild the modules of a child directory such as ${IIO_TREE}/drivers/misc. Inside the virtual machine, test the new simple_mod version. No need to reboot.

Inside the VM, do

@VM
cp simple_mod.ko /lib/modules/`uname -r`/kernel/drivers/misc/
depmod --quick
modprobe simple_mod
modprobe -r simple_mod
dmesg | tail

Now, let’s add another module to call the exported simple_mod function. Create a file ${IIO_TREE}/drivers/misc/simple_mod_part.c with the following contents.

#include <linux/module.h>
#include <linux/init.h>

extern void simple_mod_func(void);

static int __init simple_mod_part_init(void)
{
	pr_info("Hello from %s module\n", KBUILD_MODNAME);
	simple_mod_func();
	return 0;
}

static void __exit simple_mod_part_exit(void)
{
	pr_info("Goodbye from %s\n", KBUILD_MODNAME);
}

module_init(simple_mod_part_init);
module_exit(simple_mod_part_exit);

MODULE_LICENSE("GPL");
MODULE_IMPORT_NS("IIO_WORKSHOP_SIMPLE_MOD");

Also add entries to ${IIO_TREE}/drivers/misc/Kconfig and ${IIO_TREE}/drivers/misc/Makefile as we did for simple_mod.

config SIMPLE_MOD_PART
	tristate "Simple Test Partner Module"
	depends on SIMPLE_MOD
	help
	   Enable this configuration option to enable the simple test partern
	   module.

obj-$(CONFIG_SIMPLE_MOD_PART) += simple_mod_part.o

Run menuconfig again to enable simple_mod_part to build as a module.

make -C "$IIO_TREE" menuconfig

You will notice though, if you try to build the modules with make M=drivers/misc/ that it will build simple_mod but won’t build simple_mod_part. To get simple_mod_part built and setup as we have simple_mod, run the modules_prepare rule. Alternatively, we can rebuild the kernel and install the modules again. Let’s go for the first option which is faster.

cd "$IIO_TREE"
kw build
kw ssh --send drivers/misc/simple_mod_part.ko

make -C "$IIO_TREE" modules_prepare
make -C "$IIO_TREE" M=drivers/misc/
scp "${IIO_TREE}/drivers/misc/simple_mod_part.ko" root@<VM-IP-address>:~/

Load simple_mod_part and check out the output in kernel logs.

@VM
cp simple_mod_part.ko /lib/modules/`uname -r`/kernel/drivers/misc/
depmod --quick
modinfo simple_mod_part
modprobe simple_mod_part
modprobe -r simple_mod_part
dmesg | tail

You should have an output like

root@localhost:~# dmesg | tail
[  119.775025] Hello from simple_mod module
[  119.777102] Hello from simple_mod_part module
[  119.777290] Called simple_mod, simple_mod_func function
[  128.551064] Goodbye from simple_mod_part
[  128.563960] Goodbye from simple_mod

Note you don’t have to explicitly ask to load simple_mod if using modprobe. To summarize, when adding new modules we need to prepare them for inclusion or rebuild the whole kernel to get the modules correctly setup. After the modules have been setup, we can modify modules, build only those that were updated, copy them to the VM, update module dependancies with depmod, then test.

Proposed Exercices

The .config file that comes with the arm64 VM is bloated with features built together with the kernel image (y config value) which is why even after make localmodconfig the .config file did not reduce significantly and the build took a lot of time. Run make allmodconfig to turn builtin configuration values into module values when possible. After that, boot the VM, regenerate the list of needed modules as described in Part 1, run make localmodconfig with new list of modules. Did it reduce .config size further? How much? Does the whole kernel build take less time with the new .config? Does the resulting kernel still boot?
Sometimes developers lose track of what .config was used to generate a running kernel after messing arround for enough time. The in kernel configuration config (IKCONFIG) exports (imports?) the .config file used to build the kernel into the kernel image and make it later availabe as /proc/config.gz file. Enable IKCONFIG, rebuild the kernel and read your .config from /proc/config.gz within the VM.
Customize the log messages for simple_mod and simple_mod_part. Add #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt at the top of the module source files. KBUILD_MODNAME will expand to the module source file name resulting in every message logged through pr_info() (and friends) being prepended by the module name. See include/linux/printk.h for documentation. Tip, add the above define before header inclusions to avoid build warnings.

Conclusion

This tutorial described how to add a module to the Linux codebase, create a configuration for it, enable it to be compiled as a module, and install it. We also covered how to dynamically load and unload modules, and how to use modules functionalities in other modules.

History

V1: Release
V2: Review for the Free Software Development course offered in 2025-1 at IME-USP

Building and booting a custom Linux kernel for ARM

2023-08-17T00:00:00-03:00

This tutorial describes how to build - in other words, compile - the Linux kernel for the ARM architecture and boot test it in a Virtual Machine (VM). Basic kernel build configuration is covered too.

This tutorial was originally thought to be part of a set of tutorials tailored to aid newcomers to develop for the Linux kernel Industrial I/O subsystem (IIO). It is the second in the series and a continuation of the “Setting up a test environment for Linux Kernel Dev using QEMU and libvirt” tutorial.

Command Summary

Skip this section if you have not completed this tutorial yet. This is a reference for those who have gone through this tutorial and want to remember specific commands.

### SHALLOWLY CLONING THE IIO TREE W/ ACTIVE DEVELOPMENT BRANCH
git clone git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git "${IIO_TREE}" --branch testing --single-branch --depth 10

### CREATING A LEAN `.config` file
make -C "$IIO_TREE" defconfig # create predefined defconfig
make -C "$IIO_TREE" olddefconfig # update defconfig with new default values
make -C "$IIO_TREE" localmodconfig # reduce compilation to minimal set of modules

### SAFELY MODIFYING THE `.config` W/ A TUI
make -C "$IIO_TREE" nconfig

### BUILDING A LINUX KERNEL FROM SOURCE CODE
make -C "$IIO_TREE" -j$(nproc) Image.gz modules

### MOUNTING VM `rootfs` AND INSTALLING MODULES
sudo guestmount --rw --add "${VM_DIR}/arm64_img.qcow2" --mount /dev/<rootfs> "${VM_MOUNT_POINT}" # mount the VM `rootfs` to the given mount point in read and write mode (this could take a while)
sudo --preserve-env make -C "${IIO_TREE}" modules_install # install modules to inside the VM
sudo guestunmount "$VM_MOUNT_POINT" # unmount the VM `rootfs`

Introduction

Configuring, building, and booting a custom Linux kernel

In this section we will go through the steps on how to configure, compile, and boot customized Linux images in ARM64 VMs.

Summary of this tutorial:

Cloning a Linux kernel tree
Configuring the Linux kernel compilation
Building a custom Linux kernel
Installing modules and booting the custom-built Linux kernel

1) Cloning a Linux kernel tree

Some examples of Linux kernel trees are:

For this workshop, we’ll be using the Industrial I/O (IIO) subsystem tree so download (clone) it with git. First, modify your activate.sh script

--- a/activate.sh
+++ b/activate.sh
@@ -4,6 +4,7 @@
 export LK_DEV_DIR='/home/lk_dev' # path to testing environment directory
 export VM_DIR="${LK_DEV_DIR}/vm" # path to VM directory
 export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
+export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree

 # utility functions

then rerun the activate.sh script and clone the tree.

git clone git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git "${IIO_TREE}" --branch testing --single-branch --depth 10

2) Configuring the Linux kernel compilation

The Kernel Build System (kbuild) is based on make and other GNU tools and allows a highly modular and customizable build process for the Linux kernel. By default, kbuild uses the configuration options stored in the .config file under the root directory of the Linux kernel tree, which isn’t present in a freshly cloned tree. Those options hold values for configuration symbols associated with kernel resources such as drivers, tools, and features in general. Nearly all directories inside a kernel tree have a Kconfig file, which defines the symbols for the resources at the same level. Top Kconfig files include (source) Kconfig files from subdirectories thus creating a tree of configuration symbols. When needed, kbuild generates configuration options from Kconfig symbols and stores their values in a .config file. kbuild Makefiles then use these configuration values to compile code conditionally and to decide which objects to include in the monolithic kernel image and which objects to become modules [1] [2].

--- a/activate.sh
+++ b/activate.sh
@@ -5,6 +5,8 @@ export LK_DEV_DIR='/home/lk_dev' # path to testing environment directory
 export VM_DIR="${LK_DEV_DIR}/vm" # path to VM directory
 export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
 export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree
+## Linux kernel tree build variables
+export ARCH=arm64 # variable defining target architecture

 # utility functions

Then create the .config defconfig file for the ARM architecture.

make -C "$IIO_TREE" defconfig # create predefined defconfig
make -C "$IIO_TREE" olddefconfig # update defconfig with new default values
ls -alFh "${IIO_TREE}/.config" # list file infos of generated `.config`

The -C option, like with git, tells make to run the commands as if it was in the path passed as value. This series of tutorials does this (and other things) to avoid requiring commands to be run in implied directories. Ideally, you should always be aware of where you are executing a command and if it makes sense. Nevertheless, to avoid unexpected troubles, we present make commands with “mistake mitigation” flags.

@host
sudo systemctl start libvirtd # starts the libvirt daemon
sudo virsh net-start default # starts `virsh` default network
sudo virsh start --console arm64 # start a registered instance attaching console

After the VM is running, fetch the saved list of modules you’ve generated in the first tutorial of the series. Refer to section 4 of the first tutorial, in case you don’t have this file.

@host
sudo virsh net-dhcp-leases default # list `default` network to get VM IP
scp root@<VM-IP-address>:~/vm_mod_list "${IIO_TREE}" # copy VM modules list to IIO tree

Now, use this file to make a minimal set of modules selected for compilation, thus reducing the time to build the kernel and the amount of VM disk space required to install the modules. First, modify and rerun the activate.sh script

--- a/activate.sh
+++ b/activate.sh
@@ -7,6 +7,7 @@ export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
 export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree
 ## Linux kernel tree build variables
 export ARCH=arm64 # variable defining target architecture
+export LSMOD="${IIO_TREE}/vm_mod_list" # path to list of minimal set of modules

 # utility functions

then, optimize the .config file with the minimal set of modules to be built

make -C "$IIO_TREE" localmodconfig

New options might be prompted due to the differences in the files. You can just spam the ENTER key for the default values.

make -C "$IIO_TREE" nconfig

Use the arrow keys to navigate and ENTER to change/toggle a configuration. You can take some time to familiarize with these menus and see the available configurations.

To exit, hit F9, which will prompt you to save the changes. The figure below illustrates the steps.

Figure 1. Changing the kernel name with nconfig

3) Building a custom Linux kernel

In our case, we assume we have a development system of the AMD64 (x86_64) architecture, and the target machine is a VM of the ARM64 architecture.

# Arch-based distros
sudo pacman -Syy && sudo pacman -S aarch64-linux-gnu-gcc
# Debian-based distros
sudo apt update && sudo apt install gcc-aarch64-linux-gnu
# Fedora-based distros
sudo dnf update && sudo dnf install gcc-aarch64-linux-gnu

See the Complementary Commands section for advice if you are having difficulties in finding an equivalent package to your distro.

Modify the activate.sh script (don’t forget to rerun it) to include a env variable that defines our cross-compiler

--- a/activate.sh
+++ b/activate.sh
@@ -5,10 +5,12 @@ export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree
 ## Linux kernel tree build variables
 export ARCH=arm64 # variable defining target architecture
 export LSMOD="${IIO_TREE}/vm_mod_list" # path to list of minimal set of modules
+export CROSS_COMPILE=aarch64-linux-gnu- # cross-compiler

# utility functions

The kernel has many build targets, though we will only use the Image.gz and modules targets. Use make help to view a list of available targets. Finally, let’s build our custom Linux kernel from source code. Mind that, although we made a really lean .config, compiling the kernel still is a heavy task, and even more so when cross-compiling.

make -C "$IIO_TREE" -j$(nproc) Image.gz modules

It is likely that the above command will fail due to the software required for the build being missing. Yet, kbuild does a good job of telling what is missing from the Linux build. So, one may often identify what to install after analyzing the errors in the build output. On Debian-based OSes, developers often need to install flex, bison, and ncurses.

There is also a minimal requirements to compile the kernel page with a list of software required to build Linux and how to check your system has the minimal required versions of them.

The make command will instruct kbuild Makefiles to start the build process. The main goal of the kbuild Makefiles is to produce the kernel image (vmlinuz) and modules [2]. Akin to Kconfig files, kbuild Makefiles are also present in most kernel directories, often working with the values assigned for the symbols defined by the former.

The whole build is done recursively — a top Makefile descends into its sub- directories and executes each subdirectory’s Makefile to generate the binary objects for the files in that directory. Then, these objects are used to generate the modules and the Linux kernel image. [1]

If everything goes right, you should see an arch/arm64/boot/Image, modules.order and alike files under the Linux source root directory.

4) Installing modules and booting the custom-built Linux kernel

Before booting the custom-built kernel, we need to install the modules into the VM, i.e., we need to move the module objects compiled to the right place inside the VM’s filesystem. To do this, we mount the VM rootfs (it should be the same sdaX partition from the first tutorial), which essentially attaches the virtual disk representing the rootfs into a mount point that can be accessed by our host filesystem.

First, alter the activate.sh script to include an env variable for the mount point and the path to install the modules used by the make command we will run.

--- a/activate.sh
+++ b/activate.sh
@@ -5,10 +5,12 @@ export LK_DEV_DIR='/home/lk_dev' # path to testing environment directory
 export VM_DIR="${LK_DEV_DIR}/vm" # path to VM directory
 export BOOT_DIR="${VM_DIR}/arm64_boot" # path to boot artifacts
 export IIO_TREE="${LK_DEV_DIR}/iio" # path to IIO subsystem Linux kernel tree
+export VM_MOUNT_POINT="${VM_DIR}/arm64_rootfs" # path to mount point for VM rootfs
 ## Linux kernel tree build variables
 export ARCH=arm64 # variable defining target architecture
 export LSMOD="${IIO_TREE}/vm_mod_list" # path to list of minimal set of modules
 export CROSS_COMPILE=aarch64-linux-gnu- # cross-compiler
+export INSTALL_MOD_PATH="$VM_MOUNT_POINT" # path to install modules inside VM

 # utility functions

Rerun the activate.sh script, then create a mount point, mount the VM, and install the modules. The commands below are being run with superuser privileges due to actions related to mounting, manipulating mounted directories, and unmounting not being available for normal users. ASSURE THAT THE VM IS SHUT DOWN BEFORE PROCEEDING.

mkdir "$VM_MOUNT_POINT" # creates mount point
### ADAPT THE COMMAND BELOW ###
sudo guestmount --rw --add "${VM_DIR}/arm64_img.qcow2" --mount /dev/<rootfs> "${VM_MOUNT_POINT}" # mount the VM `rootfs` to the given mount point in read and write mode (this could take a while)
sudo --preserve-env make -C "${IIO_TREE}" modules_install # install modules to inside the VM
sudo guestunmount "$VM_MOUNT_POINT" # unmount the VM `rootfs`

ASSURE THAT THE VM ROOTFS IS UNMOUNTED BEFORE PROCEDING.

--- a/activate.sh
+++ b/activate.sh
@@ -23,7 +23,7 @@ function launch_vm_qemu() {
         -smp 2 \
         -netdev user,id=net0 -device virtio-net-device,netdev=net0 \
         -initrd "${BOOT_DIR}/<initrd>" \
-        -kernel "${BOOT_DIR}/<kernel>" \
+        -kernel "${IIO_TREE}/arch/arm64/boot/Image" \
         -append "loglevel=8 root=/dev/<vdaX> rootwait" \
         -device virtio-blk-pci,drive=hd \
         -drive if=none,file="${VM_DIR}/arm64_img.qcow2",format=qcow2,id=hd \
@@ -41,7 +41,7 @@ function create_vm_virsh() {
         --import \
         --features acpi=off \
         --disk path="${VM_DIR}/arm64_img.qcow2" \
-        --boot kernel=${BOOT_DIR}/<kernel>,initrd=${BOOT_DIR}/<initrd>,kernel_args="loglevel=8 root=/dev/<vdaX> rootwait" \
+        --boot kernel=${IIO_TREE}/arch/arm64/boot/Image,initrd=${BOOT_DIR}/<initrd>,kernel_args="loglevel=8 root=/dev/<vdaX> rootwait" \
         --network bridge:virbr0 \
         --graphics none
 }

Rerun the activate.sh script. We need to undefine our libvirt managed VM, then created it again

@host
sudo virsh undefine arm64
create_vm_virsh

Log into the VM and run

@VM
uname --kernel-release

to check that you are now running the custom kernel we just built. The output of this command should be something in the format of

<major-release-nr>.<minor-release-nr>.<patch-release-nr>-rc<one-through-eight>-<the-name-you-wrote>+

like, for example,

6.14.0-rc1-free-software+

Congratulations, you’ve just compiled and boot-tested a Linux kernel! From now on, whenever you make a change on the Linux kernel tree, you can “just” compile it, install the modules, and then start the VM to boot the new custom kernel and be able to run validations inside the testing environment!

4.1) Installing the kernel image

For this setup, we shall not bother with that. We don’t need to run the installation rule because we instructed QEMU (with -kernel) and libvirt (with --boot kernel=...) to pick up the kernel image that resulted from the compilation, and we are reusing the initrd file from the original guest OS that came with the disk image.

Complementary Commands

wget -O "${LK_DEV_DIR}/gcc-aarch64-linux-gnu.tar.xz" https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
tar -xf -C "$LK_DEV_DIR" "${LK_DEV_DIR}/gcc-aarch64-linux-gnu.tar.xz"

Anyways, you may point to the generic cross compiler name when using compilers not under your PATH. For example:

export CROSS_COMPILE="${LK_DEV_DIR}/gcc-aarch64-linux-gnu/bin/aarch64-none-linux-gnu-"

Conclusion

History

V1: Release
V2: Review for the Free Software Development course offered in 2025-1 at IME-USP
V3: Incorporate Marcelo Schmitt feedbacks from Merge Request 135

References

[1] Javier Martinez Canillas. “Kbuild: the Linux Kernel Build System”. (2012) URL: https://www.linuxjournal.com/content/kbuild-linux-kernel-build-system. ⤴

[2] Michael Elizabeth Chastain and Kai Germaschewski and Sam Ravnborg. “Linux Kernel Makefiles”. (2023) URL: https://www.kernel.org/doc/html/latest/kbuild/makefiles.html. ⤴

[3] . “Target Triplet”. (2019) URL: https://wiki.osdev.org/Target_Triplet. ⤴

FLUSP - FLOSS at USP

Linux kernel patch submission guidelines (FSD 2026)

1. Clone the right kernel tree and branch

2. Create a dedicated local branch to isolate your work

3. Ensure that your change is being compiled

4. Backup your .config files

5. Make atomic commits and work on your commit message

6. Add your Signed-off-by and Co-developed-by

7. Check that your patchset doesn’t introduce coding style problems

8. Official Linux kernel guidelines in submitting patches

9. Configure git send-email

10. Send your contribution to our CI before sending it “to the world”

11. Send your patchset “to the world” after approval from our CI

History

References

Linux kernel patch suggestions (FSD 2026)

Suggestions summary

1. Any subsystem/subproject

Suggestion 1.1) Replace mutex_lock(&lock) and mutex_unlock(&lock) calls with guard(mutex)(&lock)

Important observations

Patch examples

2. Industrial I/O (IIO)

Suggestion 2.1) Replace manual bitfield manipulations with FIELD_GET(), FIELD_PREP(), and FIELD_MODIFY()

Patch examples

Suggestion 2.2) Update IIO drivers to be Include-What-You-Use (IWYU) compliant

Patch examples

Suggestion 2.3) Improvements in the IIO area of staging

Patch examples

3. DRM AMDGPU DRIVERS

Suggestion 3.1) Convert logging to drm_* functions with drm_device parameter

Patch examples

Suggestion 3.2) Read and expand the subsystem documentation

Patch examples

4. Code duplications

Suggestion 4.1) Duplications with 100% similarity

Suggestion 4.2) Duplications with 90% similarity

Deduplications from last year (2025)

History

Sending patches with git and a USP email

Introduction

What is the problem with USP emails?

The alternative: OAuth 2.0

Summary of this tutorial

Option A: git credential helper

Installing the git credential helper and generating the access token

Configuring git send-email and credential manually

Testing the setup with kw send-patch

Option B: Email Proxy

Running the email proxy

Configuring git send-email with kw send-patch

Testing the setup with kw send-patch

Miscellaneous Notes

History

Building and booting a custom Linux kernel for ARM using kw

Command Summary

Introduction

Configuring, building, and booting a custom Linux kernel

1) Installing kw

2) Cloning a Linux kernel tree

3) Configure kw in a local context for IIO development

4) Configuring the Linux kernel compilation

5) Building a custom Linux kernel

6) Installing modules and booting the custom-built Linux kernel

6.1) Installing the kernel image

Complementary Commands

Conclusion

History

References

Introduction to Linux kernel Character Device Drivers

Command Summary

Introduction

Introduction to Linux kernel character device drivers

1) Character devices

2) Major and Minor Numbers

3) File operations

File read/write operations

4) Bringing device IDs and file operations together

5) A character device driver example

6) Testing the simple_char driver

Proposed Exercises

9. Configure `git send-email`

Suggestion 1.1) Replace `mutex_lock(&lock)` and `mutex_unlock(&lock)` calls with `guard(mutex)(&lock)`

Suggestion 2.1) Replace manual bitfield manipulations with `FIELD_GET()`, `FIELD_PREP()`, and `FIELD_MODIFY()`

Option A: `git credential` helper

Installing the `git credential` helper and generating the access token

Configuring `git send-email` and `credential` manually

Testing the setup with `kw send-patch`

Configuring `git send-email` with `kw send-patch`

Testing the setup with `kw send-patch`

1) Installing `kw`

3) Configure `kw` in a local context for IIO development

6) Testing the `simple_char` driver