FolkPatch

English

简体中文

English

简体中文

Appearance

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

  1. Follow the automatic patching process in the Installation Guide. Do not immediately proceed to the next step after setting SuperKey.

  2. Click the "Embed Module" button, then select the KPM file you want to embed (suffix is .kpm).

  3. Confirm that the KPM to be embedded is the one you want to use.

  4. 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:

  1. Visual Configuration: Add KPM files through the interface, edit parameters and loading phases
  2. 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:

PhaseDescription
service (default)Loaded during the service phase, after SELinux policies are applied and module mounting is complete
post-fs-dataLoaded 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 Ownership:APatch Document

This article is reprint from:https://apatch.dev/zh_CN/kpm-usage-guide.html

License under:Attribution-ShareAlike 4.0 International