Beyond Magisk: Developing Your First Custom KernelSU Module for Advanced Android Control

Introduction to KernelSU and Advanced Android Control

For years, Magisk has been the undisputed king of Android rooting, offering a powerful userspace solution for systemless modifications. However, a new player has emerged: KernelSU. KernelSU operates at a fundamentally deeper level, integrating directly into the Linux kernel itself. This paradigm shift opens up unprecedented possibilities for system control and customization, allowing developers to create kernel-level modules that bypass many of the limitations faced by userspace solutions. This tutorial will guide you through the process of developing your very first custom KernelSU module, demystifying kernel driver integration and empowering you with advanced Android control.

Prerequisites for KernelSU Module Development

Before diving into kernel-level hacking, ensure you have the necessary knowledge and tools:

Essential Knowledge

C programming language: Kernel modules are written in C. A solid understanding of C syntax, pointers, and memory management is crucial.
Linux kernel basics: Familiarity with concepts like kernel modules, procfs, sysfs, device drivers, and kernel programming paradigms.
Android build system (basic understanding): While we won’t build a full Android ROM, understanding toolchains and cross-compilation is important.
Git and command-line proficiency: For managing source code and executing build commands.

Required Tools

Linux development environment: Ubuntu or Debian is highly recommended for kernel development.
Android NDK and toolchain: Necessary for cross-compiling your module for ARM64 architecture.
Kernel source code: The exact kernel source code for your target Android device, matching the KernelSU installation. This is critical for compatibility.
A KernelSU-rooted Android device: Essential for testing your module.

Understanding KernelSU Module Architecture

KernelSU modules are not like traditional Magisk modules. Instead, they are standard Linux kernel modules (`.ko` files) that run directly within the kernel. KernelSU’s `ksud` daemon is responsible for discovering, loading, and managing these kernel objects. This kernel-space execution grants immense power, allowing direct manipulation of kernel functions, system calls, and hardware interfaces, but it also demands extreme caution, as errors can easily lead to system instability or even bricking your device.

A KernelSU module package typically consists of a `module.prop` file for metadata and the compiled `.ko` file(s) placed in a specific directory structure within a ZIP archive, much like Magisk modules. However, the `install.sh` script is less critical for simple module loading, as `ksud` handles the loading of `.ko` files found in `/data/adb/modules//system/lib/modules/`.

Setting Up Your Development Environment

Obtaining Kernel Source Code

The first step is to get the kernel source code for your specific device. This is often available from your device manufacturer or community repositories (e.g., GitHub, GitLab). Additionally, you’ll need the KernelSU source code, as it provides necessary headers and build modifications.

# Replace with your device's actual kernel repository and branchgit clone [YOUR_DEVICE_KERNEL_REPO] kernel_srccd kernel_srcgit checkout [YOUR_KERNEL_BRANCH]# Clone KernelSU source into the kernel directorygit clone https://github.com/KernelSU/KernelSU.git -b [KernelSU_BRANCH_OR_TAG]

Toolchain Configuration

You need an ARM64 (AArch64) cross-compilation toolchain to build kernel modules for Android devices. The Android NDK provides suitable toolchains. Adjust the `PATH` and define architecture-specific variables:

# Adjust the path to your NDK's prebuilt toolchains accordinglyexport PATH="/path/to/your/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH"export ARCH=arm64export SUBARCH=arm64export CROSS_COMPILE=aarch64-linux-android-

Crafting Your First KernelSU Module: A Simple `/proc` Entry

We’ll start with a straightforward kernel module that creates a readable entry in the `/proc` filesystem. This demonstrates basic kernel module loading and interaction.

`my_kernelsu_module.c`

Create a file named `my_kernelsu_module.c` with the following content:

#include <linux/module.h>#include <linux/kernel.h>#include <linux/init.h>#include <linux/proc_fs.h>#include <linux/seq_file.h>#include <linux/jiffies.h> // For jiffiesMODULE_LICENSE("GPL");MODULE_AUTHOR("Your Name");MODULE_DESCRIPTION("A simple KernelSU module for /proc entry");static int my_proc_show(struct seq_file *m, void *v) {    seq_printf(m, "Hello from KernelSU Module! The current jiffies are %lun", jiffies);    return 0;}static int my_proc_open(struct inode *inode, struct file *file) {    return single_open(file, my_proc_show, NULL);}static const struct proc_ops my_proc_fops = {    .proc_open    = my_proc_open,    .proc_read    = seq_read,    .proc_lseek   = seq_lseek,    .proc_release = single_release,};static int __init my_module_init(void) {    if (proc_create("kernelsu_hello", 0444, NULL, &my_proc_fops) == NULL) {        printk(KERN_ERR "KernelSU Hello: Failed to create /proc/kernelsu_hellon");        return -ENOMEM;    }    printk(KERN_INFO "KernelSU Hello: Module loaded, /proc/kernelsu_hello createdn");    return 0;}static void __exit my_module_exit(void) {    remove_proc_entry("kernelsu_hello", NULL);    printk(KERN_INFO "KernelSU Hello: Module unloaded, /proc/kernelsu_hello removedn");}module_init(my_module_init);module_exit(my_module_exit);

`Makefile` for the Module

Next, create a `Makefile` in the same directory as `my_kernelsu_module.c`. This Makefile tells the kernel build system how to compile our module.

obj-m := my_kernelsu_module.oKERN_DIR := $(PWD)/..all:    make -C $(KERN_DIR) M=$(PWD) modulesclean:    make -C $(KERN_DIR) M=$(PWD) clean

Building Your Kernel Module

With your source files ready, navigate to your module’s directory and run `make`. Ensure `KERN_DIR` in your Makefile correctly points to the root of your cloned kernel source.

cd /path/to/my_kernelsu_module/make

If the compilation is successful, you should find `my_kernelsu_module.ko` (kernel object) in your current directory. This is the binary file that KernelSU will load.

Packaging for KernelSU Installation

KernelSU modules are installed via a standard ZIP package. The structure is critical for KernelSU to correctly identify and load your module:

my_first_ksu_module/├── module.prop├── install.sh (optional, but good practice for future expansions)└── system/    └── lib/        └── modules/            └── my_kernelsu_module.ko

`module.prop`

Create `module.prop` at the root of your module directory:

id=my_first_ksu_modulename=My First KernelSU Moduleversion=v1author=Your NameDescription=A simple /proc entry module for KernelSU.

`install.sh` (Optional)

For a basic module like this, `install.sh` isn’t strictly necessary as KernelSU automatically loads `.ko` files found in `system/lib/modules/`. However, for future modules involving custom scripts, permissions, or symlinks, this file would contain the logic. For now, you can omit it or leave it empty.

Creating the ZIP file

Navigate to the parent directory containing your `my_first_ksu_module` folder and create the ZIP archive:

zip -r my_first_ksu_module.zip my_first_ksu_module/

Installation and Verification

Install via KernelSU Manager

Transfer `my_first_ksu_module.zip` to your KernelSU-rooted Android device.
Open the KernelSU Manager app.
Navigate to the

Android Mobile Specs & Compare Directory

Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!
Compare Devices Specs →