Introduction to KernelSU and Kernel-Level Root

KernelSU represents a significant evolution in Android rooting, offering kernel-level access and management capabilities. Unlike traditional user-space rooting solutions, KernelSU operates directly within the Linux kernel, providing a more robust, stable, and often harder-to-detect root environment. This deep integration allows for finer control over system processes and offers enhanced security by minimizing the attack surface presented by user-space exploits. For custom ROM developers and advanced users, integrating KernelSU directly into an AOSP or custom ROM build means providing a seamless, pre-rooted experience that leverages the full power of kernel-level superuser access from the get-go.

This guide will walk you through the process of embedding KernelSU into your AOSP or custom ROM source tree, covering everything from fetching the necessary components to modifying your kernel and build system, ensuring a fully functional, KernelSU-enabled ROM.

Prerequisites for KernelSU Integration

Before embarking on this integration journey, ensure you have the following:

• A functional AOSP/Custom ROM build environment: This includes a synced AOSP tree for your target device, with all necessary build tools and dependencies installed.
• Basic understanding of Android kernel compilation: Familiarity with kernel configurations (defconfig), makefiles, and device trees is crucial.
• Git knowledge: For cloning repositories and applying patches.
• Sufficient storage and computational resources: Building an AOSP ROM is resource-intensive.
• Target device knowledge: Understanding your device’s architecture and kernel source location.

Step-by-Step Integration Guide

1. Prepare Your AOSP/ROM Source Tree

First, navigate to your AOSP or custom ROM source directory. Identify your device’s kernel source path, typically found at kernel/<vendor>/<codename> or similar, specified in your device’s BoardConfig.mk or BoardConfig-common.mk via TARGET_KERNEL_SOURCE.

cd /path/to/your/aosp/source
ls kernel/<vendor>/<codename> # Verify your kernel source path

2. Clone KernelSU Source

KernelSU’s core components include the kernel module and the userspace application. For direct integration, we primarily focus on the kernel module. Clone the KernelSU repository into a convenient location. It’s often placed alongside other prebuilt modules or within the vendor kernel directory.

cd /path/to/your/aosp/source
git clone https://github.com/KernelSU/KernelSU.git external/kernelsu

3. Apply Kernel Patches

KernelSU requires specific patches to be applied to your kernel source to enable its functionality. These patches typically modify the kernel’s security context, LSM hooks, and other core components to allow KernelSU to inject its functionality. The KernelSU repository often provides a script or a set of patches for common kernel versions.

cd external/kernelsu
./scripts/apply_patch.sh /path/to/your/kernel/source

Note: The apply_patch.sh script dynamically determines the kernel version and applies appropriate patches. If this script fails, you may need to manually identify and apply the correct patches from the patches/ directory within the KernelSU repository, or adapt them to your specific kernel version.

4. Integrate KernelSU into Kernel Makefile and Kconfig

You need to tell your kernel’s build system about KernelSU. This involves modifying the kernel’s Makefile and Kconfig files.

Modify Kernel Makefile

Navigate to your kernel source directory (e.g., kernel/<vendor>/<codename>). Edit the main Makefile (or a relevant Kbuild file) to include KernelSU’s build process. You’ll typically add a line to include external/kernelsu‘s Kbuild file.

Example addition to your kernel’s Makefile (adjust path as necessary):

# Inside kernel/<vendor>/<codename>/Makefile

# ... existing lines ...

ifeq ($(CONFIG_KERNELSU),y)
objs-y += ../../../external/kernelsu/kernel
endif

# ... rest of Makefile ...

Modify Kernel Kconfig

You’ll also need to add a Kconfig entry to allow enabling/disabling KernelSU during kernel configuration. Edit kernel/<vendor>/<codename>/Kconfig (or a related Kconfig.common) to add a configuration option.

# Inside kernel/<vendor>/<codename>/Kconfig

menu "KernelSU Options"

config KERNELSU
bool "Enable KernelSU support"
default n
help
  Enables KernelSU, a kernel-based root solution.
  This will integrate KernelSU driver directly into the kernel.

endmenu

5. Configure Your Kernel

Now, enable the KERNELSU option in your kernel’s defconfig. Find your device’s defconfig file, usually located at arch/arm64/configs/<codename>_defconfig (for ARM64 devices).

echo "CONFIG_KERNELSU=y" >> arch/arm64/configs/<codename>_defconfig

It’s also advisable to run make <defconfig_name> menuconfig within your kernel source to visually confirm CONFIG_KERNELSU is enabled and to save the new configuration.

6. Integrate KernelSU into AOSP Build System (Optional, but recommended for app)

While the kernel module is the core, for a complete experience, you should also include the KernelSU manager application. Clone the manager app source into your AOSP tree.

cd /path/to/your/aosp/source
git clone https://github.com/KernelSU/KernelSU_app.git packages/apps/KernelSU

Then, modify your device’s device.mk file (e.g., device/<vendor>/<codename>/device.mk) to include the KernelSU manager application in your ROM build.

# Inside device/<vendor>/<codename>/device.mk

# ... existing lines ...

PRODUCT_PACKAGES += 
    KernelSU

# ... rest of device.mk ...

7. Build Your AOSP/Custom ROM

With all modifications in place, proceed to build your ROM as you normally would.

cd /path/to/your/aosp/source
source build/envsetup.sh
lunch <target_device_build_type> # e.g., aosp_raven-userdebug
make -j$(nproc)

This process will compile your kernel with KernelSU integrated and package the KernelSU manager app into your system image.

8. Flash and Verify

Once the build completes, flash the generated images (boot.img, system.img, vendor.img, etc.) to your device using fastboot or your preferred method.

fastboot flash boot <path_to_boot.img>
fastboot flash system <path_to_to_system.img>
# ... flash other partitions ...
fastboot reboot

After booting up, open the KernelSU Manager app. It should detect the kernel-level KernelSU installation and report that KernelSU is working correctly. You can then grant superuser permissions to other applications through the manager.

Conclusion

Integrating KernelSU directly into your AOSP or custom ROM build offers a streamlined and robust rooting solution for your users. By compiling KernelSU as part of the kernel, you bypass the need for separate flashing tools or post-installation modifications, delivering a fully-featured, kernel-level root environment from the very first boot. This method provides superior stability, enhanced security, and a cleaner overall user experience for advanced Android enthusiasts and custom ROM aficionados.