Obtain Driver Source and Build the Kernel Module Packages¶

About This Task¶

With an eLxr Server 12 development host, you can either obtain the source or create your own to build an out-of-tree kernel driver module.

This tutorial uses the hello-world kernel module available at https://gitlab.com/elxr/kernel/hello-world to demonstrate how to include your own modules with eLxr Server 12. You can use this repository as a reference for creating your own modules to ensure you have the required files and folder structures.

From the README.md file:

This module is an example for out of tree kernel driver on amd64 arch, and only involves simple “printk” functions which belong to the package, for example, linux-headers-6.1.0-22-common, and usually it can involve more functions related to the kernel architecture, which belongs to the package; e.g. linux-headers-6.1.0-22-amd64. This driver omits the complicated functions, but keeps enough build dependencies. You can customize this example by adding more complicated functions or changing the architecture as needed.

For more detailed information on working with the kernel, refer to the documentation at Debian Linux Kernel Handbook: Common kernel-related tasks.

Note

If you are using Secure Boot with your eLxr 12 host system, see Sign Kernel Modules to Verify Authenticity for specific information on signing kernel modules.

Before You Begin¶

You must have an eLxr Server 12 installation with the necessary development packages. For details, see Set Up the eLxr Server 12 Development Host.
If you want to use the tree application to view file folder structure as depicted in this procedure, you will need to install it, for example:
```
$ sudo apt-get install tree
```

Procedure¶

Create a directory for the kernel module project and navigate to it.
```
$ mkdir -p my-kernel-mod && cd my-kernel-mod
```

Clone the hello-world repository.

$ git clone https://gitlab.com/elxr/kernel/hello-world.git

Optionally make any changes to the source. Once you are complete, the parent folder should have the following files and structure.
```
$ tree -L 3

└── hello-world
    ├── debian
    │   ├── certs
    │   ├── extra
    │   ├── source
    │   ├── changelog
    │   ├── control
    │   ├── copyright
    │   ├── rules
    │   └── salsa-ci.yml
    ├── hello-world.c
    ├── Makefile
    └── README.md
```
The debian folder contains a number of template files necessary for building the kernel module packages. For additional information, see Generating and Modifying Package Template Files.
Specific to kernel module development:
- hello-world/debian/certs folder contains the machine owner keys (MOK) necessary for signing kernel modules to verify their authenticity.
- hello-world/debian/rules file contains the WITH_MOD_SIGN option that specifies whether to sign the kernel module. For details, see Sign Kernel Modules to Verify Authenticity.

Navigate to the hello-world folder and build the driver module. This build is expected to fail, because it is missing the required tar.gz file of the package repository.

$ cd hello-world
$ debuild -uc -us -ui

This package has a Debian revision number but there does not seem to be
an appropriate original tar file or .orig directory in the parent directory;
(expected one of hello-world_1.0-elxr3.orig.tar.gz, hello-world_1.0-elxr3.orig.tar.bz2,
hello-world_1.0-elxr3.orig.tar.lzma, hello-world_1.0-elxr3.orig.tar.xz or hello-world.orig)
continue anyway? (y/n)

Enter n and press ENTER to stop the build. Make note of the expected file name for the tar.gz file. In this example, the name is hello-world_1.0-elxr3.orig.tar.gz. This name depends on the eLxr version, and will differ between builds. From this point forward in this tutorial, the file names will reflect the version returned by the debuild command.
Navigate up one folder and create a tar.gz file of the repository using the file name from the previous step. This is necessary, as debuild requires a compressed file of the package source contents to build the kernel driver module packages. The build will fail without one.
```
$ cd ..
$ tar zcvf hello-world_1.0-elxr3.orig.tar.gz hello-world/
```
Navigate to the hello-world folder and build the driver module again. With the tar.gz file in place, it should complete successfully.
```
$ cd hello-world
$ debuild -uc -us -ui

--- Lots of build output ---
```

Navigate up to the parent folder and verify the build was successful. The hello-world folder will now include additional files created by the build process.

$ cd ..
$ tree -L 3

├── hello-world
│   ├── debian
│   │   ├── certs
│   │   ├── source
│   │   ├── changelog
│   │   ├── control
│   │   ├── copyright
│   │   ├── debhelper-build-stamp
│   │   ├── extra
│   │   ├── files
│   │   ├── hello-world
│   │   ├── hello-world-common
│   │   ├── hello-world-common.debhelper.log
│   │   ├── hello-world-common.substvars
│   │   ├── hello-world.debhelper.log
│   │   ├── hello-world.postinst.debhelper
│   │   ├── hello-world.postrm.debhelper
│   │   ├── hello-world.substvars
│   │   ├── rules
│   │   ├── salsa-ci.yml
│   │   └── source
│   ├── hello-world.c
│   ├── hello-world.ko
│   ├── hello-world.mod
│   ├── hello-world.mod.c
│   ├── hello-world.mod.o
│   ├── hello-world.o
│   ├── Makefile
│   └── README.md
├── hello-world_1.0-elxr3-1_amd64.build
├── hello-world_1.0-elxr3-1_amd64.buildinfo
├── hello-world_1.0-elxr3-1_amd64.changes
├── hello-world_1.0-elxr3-1_amd64.deb
├── hello-world_1.0-elxr3-1.debian.tar.xz
├── hello-world_1.0-elxr3-1.dsc
├── hello-world-common_1.0-elxr3-1_amd64.deb
└── hello-world_1.0-elxr3.orig.tar.gz

Notice a number of new directories and files in the hello-world/debian folder. These represent the package files created with the debuild command.

There should be two new deb packages in the parent folder:

$ ls |grep amd64.deb

hello-world_1.0-elxr3-1_amd64.deb
hello-world-common_1.0-elxr3-1_amd64.deb

The hello-world-common_1.0-elxr3-1_amd64.deb package includes the dependencies for the kernel module. You must install this package first.
The hello-world_1.0-elxr3-1_amd64.deb package includes the kernel module.

Note

The file names may differ depending on the eLxr kernel version and package version you are building.

Results¶

Now that you have completed the kernel driver module build, you can install the packages and verify its operation. For details, see Install and Verify the Kernel Module Packages.