Introduction to KernelSU and Custom Module Development

KernelSU has revolutionized how we achieve and manage root access on Android devices by moving the core root functionality into the kernel space. Unlike traditional methods like Magisk, which operate primarily in user space, KernelSU leverages kernel-level privileges to offer a more robust and stealthy rooting solution. This shift opens up new possibilities for customization and system-level modifications through KernelSU modules, which are essentially kernel modules loaded directly by KernelSU.

This guide will walk you through the process of developing your own KernelSU modules, from understanding the core concepts to writing, compiling, and deploying a simple module. By the end, you’ll have the foundational knowledge to create powerful, kernel-level customizations for your Android device.

Why Develop KernelSU Modules?

Developing KernelSU modules allows you to:

• Execute code directly in the kernel’s context, offering unparalleled power and access to system internals.
• Implement low-level system hooks for monitoring or modifying kernel behavior.
• Bypass user-space detection mechanisms often employed by apps.
• Create highly optimized and efficient system tweaks.

Prerequisites for KernelSU Module Development

Before diving into coding, ensure you have the following setup:

1. Linux Development Environment: Ubuntu, Debian, or any similar Linux distribution is ideal for compiling kernel modules.
2. Android NDK: Essential for obtaining the cross-compilation toolchains that match your target Android device’s architecture. Download and install it from the Android developer website.
3. Kernel Source Code: You need the exact kernel source code for your device’s ROM. This is crucial for matching kernel headers and configurations during compilation. Many manufacturers provide their kernel sources.
4. KernelSU Module SDK/Headers: The KernelSU project provides specific headers and helper functions for module development. These are typically included with the KernelSU source or available as a separate SDK.
5. Basic C/C++ Knowledge: Kernel module development is done in C.
6. Familiarity with Linux Kernel Concepts: Understanding kernel modules, system calls, and basic kernel programming paradigms will be beneficial.

Let’s assume you have a Linux environment set up and the NDK installed. Typically, you’d set environment variables for your NDK toolchain:

export PATH=$PATH:/path/to/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/binexport ARCH=arm64export CROSS_COMPILE=aarch64-linux-android-

Adjust /path/to/android-ndk and ARCH/CROSS_COMPILE according to your NDK location and target device architecture (e.g., arm for 32-bit, arm64 for 64-bit).

Understanding KernelSU Module Structure

KernelSU modules are standard Linux kernel modules (.ko files) but are loaded and managed by the KernelSU framework. They interact with the kernel through standard Linux kernel APIs and can also leverage specific KernelSU APIs for more integrated functionality (e.g., interacting with the KernelSU Manager app).

A typical KernelSU module will involve:

• A module entry point (module_init) and exit point (module_exit).
• Using kernel APIs to register hooks (e.g., for system calls, network events, file operations).
• Interacting with the /sys filesystem for user-space communication.

Creating Your First KernelSU Module: A Simple ‘Hello World’

Let’s create a basic module that prints a message to the kernel log when loaded and unloaded.

Step 1: Create the Module Source File (kmod_hello.c)

#include <linux/module.h>#include <linux/kernel.h>#include <linux/init.h>static int __init kmod_hello_init(void){    printk(KERN_INFO "Hello from KernelSU module!n");    return 0;}static void __exit kmod_hello_exit(void){    printk(KERN_INFO "Goodbye from KernelSU module!n");}module_init(kmod_hello_init);module_exit(kmod_hello_exit);MODULE_LICENSE("GPL");MODULE_AUTHOR("Your Name");MODULE_DESCRIPTION("A simple KernelSU 'Hello World' module.");MODULE_VERSION("0.1");

Step 2: Create the Makefile

This Makefile assumes you have your kernel source code in a directory (e.g., ~/android/kernel_source). Replace this path with your actual kernel source location.

KDIR := /home/user/android/kernel_source  # Path to your kernel sourcePWD := $(shell pwd)obj-m := kmod_hello.oall:    $(MAKE) -C $(KDIR) M=$(PWD) modulesclean:    $(MAKE) -C $(KDIR) M=$(PWD) clean

Ensure the KDIR variable points to the root of your Android kernel source directory. The $(MAKE) -C $(KDIR) M=$(PWD) modules command tells the kernel’s build system to compile the module located in the current directory ($(PWD)) against the kernel source headers and configuration.

Step 3: Compile the Module

Navigate to the directory containing kmod_hello.c and Makefile in your Linux terminal and run:

make

If successful, this will generate kmod_hello.ko (and other temporary files) in the same directory. The .ko file is your compiled kernel module.

Packaging and Deploying Your KernelSU Module

KernelSU modules are distributed as standard Magisk-style ZIP archives. The ZIP must contain your .ko file(s) and a `module.prop` file, and optionally an `install.sh` script.

Step 1: Create module.prop

This file provides metadata for the KernelSU Manager app.

id=kmod_hello_worldname=KernelSU Hello World Moduleversion=v0.1versionCode=1author=Your NameDescription=A simple 'Hello World' module for KernelSU.

Step 2: Create the Module Directory Structure

Create a directory, for example, kmod_hello_world_module. Inside it, place module.prop and a system/lib/modules directory. Your .ko file goes into system/lib/modules.

kmod_hello_world_module/├── module.prop└── system/    └── lib/        └── modules/            └── kmod_hello.ko

Step 3: Create the ZIP Archive

Navigate to the parent directory of kmod_hello_world_module and create the ZIP:

zip -r kmod_hello_world_module.zip kmod_hello_world_module/

Installation and Testing

1. Transfer the ZIP: Copy kmod_hello_world_module.zip to your Android device (e.g., via adb push or MTP).
2. Install with KernelSU Manager: Open the KernelSU Manager app, navigate to the Modules section, tap “Install from storage,” and select your ZIP file.
3. Reboot: After installation, reboot your device.
4. Verify: After rebooting, connect your device to your computer and check the kernel log (dmesg) for your module’s messages:

adb shell dmesg | grep "Hello from KernelSU"

You should see Hello from KernelSU module! in the output. When you uninstall the module and reboot, you should see Goodbye from KernelSU module! in the logs.

Advanced Module Concepts

This