.. _modify-kernel:

==========================
Modify Ubuntu Linux Kernel
==========================

Overview
========

When developing your hardware, you might want to integrate or port your hardware driver to the Linux kernel.

To modify the kernel used in Ubuntu, instead of flashing the entire eMMC partition,
you need to build a set of Debian kernel packages (``*.deb`` files), and then install
those packages on the target board.


Ubuntu Kernel Source Code
=========================

.. code-block::

    https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-mtk/+git/jammy

This git repository stores the kernel source code used in Ubuntu on Genio images,
and also the device tree for the following boards:

* MediaTek Genio 350 EVK
* MediaTek Genio 510 EVK
* MediaTek Genio 700 EVK
* MediaTek Genio 1200 EVK

Please note that this is a "HWE"(hardware enablement) kernel, which is a fork of the generic Ubuntu kernel.
It contains patches specific to the MediaTek Genio platform; and is not tested on any other platform.

.. note::

    The branch ``master-next`` can be rebased (history re-written) regularly. 
    We recommend using tags such as ``Ubuntu-mtk-5.15.0-1018.20`` when downloading kernel source.


How to Build
============

This section provides instructions on building a Ubuntu kernel Debian package that you can
deploy to a MediaTek Genio EVK that runs Ubuntu Linux (Classic).

Please note that installing the resulting kernel Debian package on Ubuntu Core and IoT Yocto does not work,
due to the differences in kernel image location and partition layout design.

Build Requirement
=================

Prepare a host machine with Ubuntu 22.04 (Jammy).
You can download the ISO here:
https://releases.ubuntu.com/22.04/

Build Environment Setup
=======================

On your build host, install the following packages:

.. prompt::

    $ echo "deb-src http://archive.ubuntu.com/ubuntu jammy main" | sudo tee -a /etc/apt/sources.list.d/jammy.list
    $ sudo apt-get update
    $ sudo apt-get build-dep linux
    $ sudo apt-get install git fakeroot libncurses-dev gcc-aarch64-linux-gnu


.. note::

    ``gcc-aarch64-linux-gnu`` is not required if your build host is an ARM64 system.

Get the kernel source
=====================

Clone the repo and checkout the tag that you'd like to try out:

.. prompt::

    $ git clone https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-mtk/+git/jammy
    $ cd jammy
    $ git checkout <tag>

Please replace ``<tag>`` with one of the tags available, e.g. ``git checkout Ubuntu-mtk-5.15.0-1018.20``.
To get the list of tags:

.. prompt::

    $ git tag --sort=-v:refname
    Ubuntu-mtk-5.15.0-1018.20
    Ubuntu-mtk-5.15.0-1017.19
    Ubuntu-mtk-5.15.0-1016.18
    ...

Note that you can use ``uname`` to check the kernel tag version on a running board:

.. prompt::

    $ uname -r
    5.15.0-1018-mtk

In the example above, the version is ``5.15.0-1018-mtk``, so the corresponding tag would be ``Ubuntu-mtk-5.15.0-1018.20``.
The number ``.20`` is a build number and increases monotonically.
You could also view the list of available tags via a browser at https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-mtk/+git/jammy/refs/.

Set Cross Compilation Environment Variables
===========================================

This step is required only if your build host is a non-ARM64 platform:

.. prompt::

    $ export ARCH=arm64
    $ export $(dpkg-architecture -aarm64)
    $ export CROSS_COMPILE=aarch64-linux-gnu-

Modify the kernel configuration
===============================

You can skip this step if no configuration changes are wanted.

.. prompt::

    $ fakeroot debian/rules clean
    $ fakeroot debian/rules editconfigs

Build the kernel
================

.. prompt::

    $ fakeroot debian/rules clean
    $ fakeroot debian/rules binary

The building system will produce five Debian packages in the upper-level directory.
For example,

.. code-block::

    $ cd ..
    $ ls -1 *.deb
    linux-buildinfo-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb
    linux-headers-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb
    linux-image-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb
    linux-modules-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb
    linux-mtk-headers-5.15.0-1003_5.15.0-1003.4_all.deb

Install the Kernel
==================

Copy the Debian packages to the target system.
Login into the target system, and install them:

.. prompt::

    $ cd <where_the_debian_packages_are_stored>
    $ sudo dpkg -i *.deb
    $ sudo reboot

After reboot, you can use ``uname`` to check the kernel tag version:

.. prompt::

    $ uname -a
    Linux mtk-genio 5.15.0-1018-mtk #20-Ubuntu SMP PREEMPT Mon Jun 12 07:43:59 UTC 2023 aarch64 aarch64 aarch64 GNU/Linux

The version above is ``5.15.0-1018-mtk``, so the corresponding tag is ``Ubuntu-mtk-5.15.0-1018.20``.
You can view the list of available tags in https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-mtk/+git/jammy/refs/.

References
==========

[1] https://wiki.ubuntu.com/Kernel/BuildYourOwnKernel