3.1. Android Kernel

Android is built around a Linux kernel. By default, Android’s boot.img is build from a binary kernel Image located in:

${YOUR_PATH}/ti-aosp-16/device/ti/am62x-kernel/kernel/6.12

This guide describes how to rebuild and customize a Linux kernel for Android.

3.1.1. Downloading sources

Fetch the code using repo:

$ mkdir ${YOUR_PATH}/ti-kernel-aosp/ && cd $_
$ repo init -u https://git.ti.com/git/android/manifest.git -b android16-release -m releases/RLS_11_00_00_Kernel.xml
$ repo sync

Tip

To save some disk space, pass the --depth=1 option to repo init:

$ repo init -u https://git.ti.com/git/android/manifest.git -b android16-release -m releases/RLS_11_00_00_Kernel.xml --depth=1

3.1.2. Build Instructions

In this section, we will assume that we already have an Android source tree which has been fully build and is located in:

${YOUR_PATH}/ti-aosp-16/

3.1.2.1. Building everything from scratch

$ cd ${YOUR_PATH}/ti-kernel-aosp/
$ export DIST_DIR=${YOUR_PATH}/ti-aosp-16/device/ti/am62x-kernel/kernel/6.12
$ ./tools/bazel run --config=ti //private/devices/ti/am6x:ti_dist -- --destdir=$DIST_DIR

Re-running this command will rebuild incrementally.

Android uses Kleaf, a Bazel-based build system to build the kernel. AOSP documentation can be found here and Kleaf documentation here

Attention

Kernel builds hangs when using the btrfs file system. This is a known issue according to the kleaf documentation Make sure to pass the --workaround_btrfs_b292212788 flag to bazel when using btrfs.

3.1.2.2. Defconfig/menuconfig changes

The usual (make menuconfig) is done via bazel command :

$ cd ${YOUR_PATH}/ti-kernel-aosp/
$ tools/bazel run --config=ti //private/devices/ti/am6x:ti_config -- menuconfig

This will automatically update the private/devices/ti/am6x/ti.fragment.

Note

Users must have built the android kernel image prior to building the Android file system. Otherwise pre-built kernel images present in device/ti/am62x-kernel will be used to create boot.img

3.1.2.3. Rebuild Android images

We should re-generate the Android images to include the newly build kernel. Follow the Android Build Instructions to do so.

3.1.3. Flashing instructions

In order to flash a new kernel, several images should be flashed:

$ adb reboot fastboot
< Wait for fastbootd reboot >

$ cd <PATH/TO/IMAGES>
$ fastboot flash boot boot.img --disable-verity
$ fastboot flash vendor_boot vendor_boot.img --disable-verity
$ fastboot flash vendor_dlkm vendor_dlkm.img --disable-verity
$ fastboot reboot

The board should boot with the new kernel.

3.1.4. Enabling new drivers

Since the kernel is based on the Generic Kernel Image, new drivers should always be added as modules.

To enable new modules:

Run menuconfig as documented previously, Select =m for the driver.
Edit $YOUR_PATH/ti-kernel-aosp/private/ti/device/am6x/BUILD.bazel to add your new module. Look for the following sections:
TI_IN_TREE_MODULES = [
    # keep sorted
    "crypto/crc64_iso3309_generic.ko",
    "drivers/char/hw_random/optee-rng.ko",
    "drivers/clk/keystone/sci-clk.ko",
    ...
]

TI_VENDOR_DLKM_MODULES = [
    # keep sorted
    "am65-cpts.ko",
    "cc33xx.ko",
    "cdns-usb-common.ko",
    ...
]
Add your new kernel module to the appropriate array:

TI_IN_TREE_MODULES: For in-tree kernel modules. Use the full path from kernel root (e.g., "drivers/your_driver/your_module.ko")

TI_VENDOR_DLKM_MODULES: For vendor-specific dynamically loadable kernel modules. Use only the module filename (e.g., "your_module.ko")

Keep the list sorted alphabetically.

Rebuild the kernel as documented in Build Instructions.

Finally, rebuild the Android images.

3.1.5. Device tree overlays

3.1.5.1. Mapping `adtbo_idx` with filenames

Device tree overlays can be used to configure additional hardware peripherals. These overlays are stored in the dtbo.img. This image is generated when building the Android kernel as documented in Build Instructions.

As listed in Device Tree Overlay Support, we can configure an overlay to be applied from U-Boot by setting the adtbo_idx variable.

To view how the adtbo_idx maps with the dtbo file, we can inspect the BUILD.bazel from the kernel source code. Looking at the TI_DTBOS array, we can see:

TI_DTBOS = [
    "k3-am62x-sk-hdmi-audio.dtbo",
    "k3-am62x-sk-csi2-ov5640.dtbo",
    "k3-am62x-sk-csi2-tevi-ov5640.dtbo",
    "k3-am625-sk-microtips-mf101hie-panel.dtbo",
    "k3-am62x-sk-lpm-wkup-sources.dtbo",
    "k3-am62-lp-sk-microtips-mf101hie-panel.dtbo",
    "k3-am625-beagleplay-csi2-ov5640.dtbo",
    "k3-am625-beagleplay-csi2-tevi-ov5640.dtbo",
    "k3-am625-beagleplay-lincolntech-lcd185-panel.dtbo",
    "k3-am62p5-sk-mcan.dtbo",
    "k3-am62p5-sk-microtips-mf101hie-panel.dtbo",
    "k3-am625-sk-m2-cc3351.dtbo",
    "k3-am62p5-sk-m2-cc3351.dtbo",
    "k3-am625-sk-wl1837.dtbo",
    "k3-am62p5-sk-dsi-rpi-7inch-panel.dtbo",
    "k3-j722s-evm-csi2-quad-rpi-cam-imx219.dtbo",
    "k3-j722s-evm-csi2-quad-tevi-ov5640.dtbo",
    "k3-j722s-evm-dsi-rpi-7inch-panel.dtbo",
    "k3-j722s-evm-fpdlink-fusion.dtbo",
]

The TI_DTBOS array order dictates the index. For example:

filename	index
`k3-am62x-sk-hdmi-audio.dtbo`	0
`k3-am62x-sk-csi2-ov5640.dtbo`	1
`k3-am62x-sk-csi2-tevi-ov5640.dtbo`	2
`k3-am625-sk-microtips-mf101hie-panel.dtbo`	3
`k3-am62x-sk-lpm-wkup-sources.dtbo`	4

3.1.5.2. Adding more `.dtbo` files to the `dtbo.img`

In this section, we will see how to add more .dtbo files to the dtbo.img.

Edit $YOUR_PATH/ti-kernel-aosp/private/ti/device/am6x/BUILD.bazel. Look for the TI_DTBOS array and add your new dtbo file:
TI_DTBOS = [
    "k3-am62x-sk-hdmi-audio.dtbo",
    "k3-am62x-sk-csi2-ov5640.dtbo",
    ...
    "your-new-overlay.dtbo",  # Add your new dtbo here
]
Important

Make sure to add it at the end of the array. The order in TI_DTBOS will determine the adtbo_idx to be used.
Rebuild the kernel as documented in Build Instructions.