KernelPatch Module (KPM)
About 1026 wordsAbout 3 min
2025-12-23
FolkPatch is based on secondary development of APatch. APatch depends on KernelPatch, inherits all its features and extends them. Therefore, FolkPatch also supports using KernelPatch Modules (KPM). Below are instructions for using KPM.
What is KPM?
KPM is a module running in kernel space, allowing code to run directly in kernel space, similar to Loadable Kernel Modules (LKM), but loaded through KernelPatch's SuperCall mechanism.
KPM is in ELF format, built using the aarch64-none-elf- toolchain, and loaded into the kernel via sc_kpm_load() SuperCall. Each KPM declares metadata such as KPM_NAME and KPM_VERSION, and implements lifecycle callbacks such as KPM_INIT, KPM_CTL0, KPM_CTL1, and KPM_EXIT.
KPM can use KernelPatch's inline hook (hook, hook_wrap) and syscall hook (hook_syscalln, fp_hook_syscalln) capabilities, as well as access kernel symbols through kallsyms_lookup_name().
Through KPM, you can implement some functions that APM cannot achieve, such as:
- Partition image protection (format interception)
- Kernel-level hiding
- Syscall monitoring and modification
- Kernel function hooking
How to Install KPM?
There are three ways to install KPM: Embed, Load, and Install.
About "Install"
Currently, FolkPatch has not implemented the "Install" operation for KPM, because its upstream APatch has not implemented it yet. Therefore, at this stage, FolkPatch's KPM can only be installed via "Embed" and "Load". KernelPatch and APatch developers are working hard to implement related functions, please wait patiently.
Embed
Embed refers to embedding KPM directly into the kernel. KPM installed in this mode will be merged into boot.img together with kernel and loaded during the pre-kernel-init stage.
KPM embedding can be done when patching boot.img using FolkPatch Manager for the first time or after FolkPatch installation is complete. You can also use kptools to manually embed.
Embed at First Patching
Follow the automatic patching process in the Installation Guide. Do not immediately proceed to the next step after setting SuperKey.
Click the "Embed Module" button, then select the KPM file you want to embed (suffix is
.kpm).Confirm that the KPM to be embedded is the one you want to use.
Complete the remaining "Automatic Patching" process.
Embed After Installing FolkPatch
After FolkPatch is installed, the way to embed KPM is roughly the same as installing APM. You can click the button in the lower right corner of the "Kernel Module" interface, select "Embed", and the subsequent steps can be carried out with reference to Embed at First Patching.
注意
Embedded KPM will not be updated until boot.img is re-patched. If you need to update an embedded KPM, you need to re-run the patching process.
Load
Load refers to handing KPM over to the kernel for loading immediately. KPM loaded in this way will take effect immediately, but will disappear after the next restart (non-persistent).
The way to load KPM is roughly the same as installing APM, the only difference is that KPM does not need to be restarted after loading.
Install
Note
Currently, KernelPatch and APatch have not yet implemented KPM installation. The following description is only a description of the expected behavior for installing KPM.
Install refers to installing KPM as a module file similar to APM into /data/adb/kpmodules or a similar directory. KPM installed in this way can be loaded at specific events.
Auto Load
FolkPatch provides KPM auto-loading functionality, allowing specified KPMs to be automatically loaded into the kernel at system startup.
The KPM storage directory is /data/adb/fp/kpms/, and auto-loaded KPMs are placed in the /data/adb/fp/kpms/autoload/ directory. The configuration file is /data/adb/fp/kpms/kpm_autoload_config.json.
/data/adb/fp/kpms# KPM storage directory
autoload# Auto-load directory
example.kpm# KPM module file
kpm_autoload_config.json# Auto-load configuration file
FolkPatch provides two configuration methods:
- Visual Configuration: Add KPM files through the interface, edit parameters and loading phases
- JSON Configuration: Edit the JSON configuration file directly
The rest of the behavior is consistent with Load.
Loading Phases
Each KPM can be configured to load in one of two phases:
| Phase | Description |
|---|---|
service (default) | Loaded during the service phase, after SELinux policies are applied and module mounting is complete |
post-fs-data | Loaded during early boot, before SELinux policy injection and module mounting |
Most use cases work fine with the default service phase. Only select post-fs-data when you need to intervene in kernel behavior during early boot.
Parameter Passing
Each KPM can be configured with a parameter string that is passed at startup. Parameters are passed directly to the KPM's initialization function through the kernel SuperCall.
In visual mode, click the edit button on a KPM entry to set parameters. In JSON mode, fill in the args field.
Safe Mode
When the device enters safe mode, the auto-loading feature is automatically disabled and all configured KPMs will not be loaded. This prevents boot issues caused by abnormal KPMs.
Configuration File Format
{
"enabled": true,
"kpmEntries": [
{
"path": "/data/adb/fp/kpms/autoload/example.kpm",
"event": "service",
"args": ""
}
]
}enabledRequiredboolean
Whether auto-loading is enabled
pathRequiredstring
KPM file path (must be within /data/adb/fp/kpms/autoload/ directory)
eventOptionalstring
service
Loading phase: service or post-fs-data
argsOptionalstring
Parameter string passed to the KPM, defaults to empty
注意
A maximum of 64 KPM auto-load entries can be configured. KPM files must be located in the /data/adb/fp/kpms/autoload/ directory, otherwise loading will be rejected.
Copyright
Copyright Ownership:APatch Document
This article is reprint from:https://apatch.dev/zh_CN/kpm-usage-guide.html(Open in new window)
License under:Attribution-ShareAlike 4.0 International
