From f73885fc9560f9378745c9e9883605ea9d265d9c Mon Sep 17 00:00:00 2001 From: weishu Date: Sat, 23 Mar 2024 16:05:21 +0800 Subject: [PATCH] website: Add docs for LKM mode --- website/docs/guide/installation.md | 97 +++++++++++++++++++++++- website/docs/zh_CN/guide/installation.md | 93 ++++++++++++++++++++++- 2 files changed, 186 insertions(+), 4 deletions(-) diff --git a/website/docs/guide/installation.md b/website/docs/guide/installation.md index a6b719e589c3..8e6904a9b22c 100644 --- a/website/docs/guide/installation.md +++ b/website/docs/guide/installation.md @@ -57,7 +57,98 @@ If you find that your kernel version is `android12-5.10.101`, but your Android s ## Introduction -There are several installation methods for KernelSU, each suitable for a different scenario, so please choose as needed. +Since version `0.9.0`, KernelSU supports two running modes on GKI devices: + +1. `GKI`: Replace the original kernel of the device with the **Generic Kernel Image** (GKI) provided by KernelSU. +2. `LKM`: Load the **Loadable Kernel Module** (LKM) into the device kernel without replacing the original kernel. + +These two modes are suitable for different scenarios, and you can choose according to your needs. + +### GKI Mode {#gki-mode} + +In GKI mode, the original kernel of the device will be replaced with the generic kernel image provided by KernelSU. The advantages of GKI mode are: + +1. Strong universality, suitable for most devices; for example, Samsung has enabled KNOX devices, and LKM mode cannot operate. There are also some niche modified devices that can only use GKI mode; +2. Can be used without relying on official firmware; no need to wait for official firmware updates, as long as the KMI is consistent, it can be used; + +### LKM Mode {#lkm-mode} + +In LKM mode, the original kernel of the device will not be replaced, but the loadable kernel module will be loaded into the device kernel. The advantages of LKM mode are: + +1. Will not replace the original kernel of the device; if you have special requirements for the original kernel of the device, or you want to use KernelSU while using a third-party kernel, you can use LKM mode; +2. It is more convenient to upgrade and OTA; when upgrading KernelSU, you can directly install it in the manager without manually flashing; after the system OTA, you can directly install it to the second slot without manually flashing; +3. Suitable for some special scenarios; for example, LKM can also be loaded with temporary ROOT permissions. Since it does not need to replace the boot partition, it will not trigger avb and will not cause the device to be bricked; +4. LKM can be temporarily uninstalled; if you want to temporarily cancel root, you can uninstall LKM, this process does not require flashing partitions, or even rebooting the device; if you want to root again, just reboot the device; + +:::tip Coexistence of two modes +After opening the manager, you can see the current mode of the device on the homepage; note that the priority of GKI mode is higher than that of LKM. For example, if you use GKI kernel to replace the original kernel, and use LKM to patch the GKI kernel, then LKM will be ignored, and the device will always run in GKI mode. +::: + +### Which one to choose? {#which-one} + +If your device is a mobile phone, we recommend that you prioritize LKM mode; if your device is an emulator, WSA, or Waydroid, we recommend that you prioritize GKI mode. + +## LKM Installation + +### Get the official firmware + +To use LKM mode, you need to get the official firmware and then patch it on the basis of the official firmware; if you use a third-party kernel, you can use the `boot.img` of the third-party kernel as the official firmware. + +There are many ways to get the official firmware. If your device supports `fastboot boot`, then we recommend **the most recommended and simplest** method is to use `fastboot boot` to temporarily boot the GKI kernel provided by KernelSU, then install the manager, and finally install it directly in the manager; this method does not require you to manually download the official firmware, nor do you need to manually extract the boot. + +If your device does not support `fastboot boot`, then you may need to manually download the official firmware package and then extract the boot from it. + +Unlike GKI mode, LKM mode will modify the `ramdisk`, so on devices with Android 13, it needs to patch the `init_boot` partition instead of the `boot` partition; while GKI mode always operates the `boot` partition. + +### Use the manager + +Open the manager, click the installation icon in the upper right corner, and several options will appear: + +1. Select and patch a file; if your phone does not have root permissions, you can choose this option, and then select your official firmware, and the manager will automatically patch it; you only need to flash this patched file to permanently obtain root permissions; +2. Install directly; if your phone is already rooted, you can choose this option, the manager will automatically get your device information, and then automatically patch the official firmware, and then flash it; you can consider using `fastboot boot` KernelSU's GKI kernel to get temporary root and install the manager, and then use this option; this is also the main way to upgrade KernelSU; +3. Install to another partition; if your device supports A/B partition, you can choose this option, the manager will automatically patch the official firmware, and then install it to another partition; this method is suitable for devices after OTA, you can directly install it to another partition after OTA, and then restart the device; + +### Use the command line + +If you don’t want to use the manager, you can also use the command line to install LKM; the `ksud` tool provided by KernelSU can help you quickly patch the official firmware and then flash it. + +This tool supports macOS, Linux, and Windows. You can download the corresponding version from [GitHub Release](https://github.com/tiann/KernelSU/releases). + +Usage: `ksud boot-patch` You can check the command line help for specific usage. + +```sh +oriole:/ # ksud boot-patch -h +Patch boot or init_boot images to apply KernelSU + +Usage: ksud boot-patch [OPTIONS] + +Options: + -b, --boot boot image path, if not specified, will try to find the boot image automatically + -k, --kernel kernel image path to replace + -m, --module LKM module path to replace, if not specified, will use the builtin one + -i, --init init to be replaced + -u, --ota will use another slot when boot image is not specified + -f, --flash Flash it to boot partition after patch + -o, --out output path, if not specified, will use current directory + --magiskboot magiskboot path, if not specified, will use builtin one + --kmi KMI version, if specified, will use the specified KMI + -h, --help Print help +``` + +A few options that need to be explained: + +1. The `--magiskboot` option can specify the path of magiskboot. If it is not specified, ksud will look for it in the environment variables; if you don’t know how to get magiskboot, you can check [here](#patch-boot-image); +2. The `--kmi` option can specify the `KMI` version. If the kernel name of your device does not follow the KMI specification, you can specify it through this option; + +The most common usage is: + +```sh +ksud boot-patch -b --kmi android13-5.10 +``` + +## GKI mode Installation + +There are several installation methods for GKI mode, each suitable for a different scenario, so please choose as needed. 1. Install with fastboot using the boot.img provided by KernelSU 2. Install with a kernel flash app, such as KernelFlasher @@ -76,7 +167,7 @@ You can download boot.img from [GitHub Release](https://github.com/tiann/KernelS Normally, there are three boot files in different formats under the same KMI and security patch level. They are all the same except for the kernel compression format. Please check the kernel compression format of your original boot.img. You should use the correct format, such as `lz4`, `gz`; if you use an incorrect compression format, you may encounter bootloop after flashing boot. -::: info +:::info Compression format of boot.img 1. You can use magiskboot to get the compression format of your original boot; of course you can also ask other, more experienced kids with the same model as your device. Also, the compression format of the kernel usually does not change, so if you boot successfully with a certain compression format, you can try that format later. 2. Xiaomi devices usually use `gz` or **uncompressed**. 3. For Pixel devices, follow below instructions. @@ -120,7 +211,7 @@ This way requires the kernel flash App to have root permissions. You can use the PS. This method is more convenient when upgrading KernelSU and can be done without a computer (backup first!). . -## Patch boot.img manually +## Patch boot.img manually{#patch-boot-image} For some devices, the boot.img format is not so common, such as not `lz4`, `gz` and uncompressed; the most typical is Pixel, its boot.img format is `lz4_legacy` compressed, ramdisk may be `gz` may also be `lz4_legacy` compression; at this time, if you directly flash the boot.img provided by KernelSU, the phone may not be able to boot; at this time, you can manually patch the boot.img to achieve. diff --git a/website/docs/zh_CN/guide/installation.md b/website/docs/zh_CN/guide/installation.md index 1e2fd120901a..4cf81e571595 100644 --- a/website/docs/zh_CN/guide/installation.md +++ b/website/docs/zh_CN/guide/installation.md @@ -57,7 +57,98 @@ w .x .y -zzz -k -something ## 安装介绍 {#installationintroduction} -KernelSU 的安装方法有如下几种，各自适用于不同的场景，请按需选择： +自 `0.9.0` 版本以后，在 GKI 设备中，KernelSU 支持两种运行模式： + +1. `GKI`：使用**通用内核镜像**（GKI）替换掉设备原有的内核。 +2. `LKM`：使用**可加载内核模块**（LKM）的方式加载到设备内核中，不会替换掉设备原有的内核。 + +这两种方式适用于不同的场景，你可以根据自己的需求选择。 + +### GKI 模式 {#gki-mode} + +GKI 模式会替换掉设备原有的内核，使用 KernelSU 提供的通用内核镜像。GKI 模式的优点是： + +1. 通用型强，适用于大多数设备；比如三星开启了 KNOX 的设备，LKM 模式无法运作。还有一些冷门的魔改设备，也只能使用 GKI 模式； +2. 不依赖官方固件即可使用；不需要等待官方固件更新，只要 KMI 一致，就可以使用； + +### LKM 模式 {#lkm-mode} + +LKM 模式不会替换掉设备原有的内核，而是使用可加载内核模块的方式加载到设备内核中。LKM 模式的优点是： + +1. 不会替换掉设备原有的内核；如果你对设备原有的内核有特殊需求，或者你希望在使用第三方内核的同时使用 KernelSU，可以使用 LKM 模式； +2. 升级和 OTA 较为方便；升级 KernelSU 时，可以直接在管理器里面安装，无需再手动刷写；系统 OTA 后，可以直接安装到第二个槽位，也无需再手动刷写； +3. 适用于一些特殊场景；比如使用临时 ROOT 权限也可以加载 LKM，由于不需要替换 boot 分区，因此不会触发 avb，不会使设备以外变砖； +4. LKM 可以被临时卸载；如果你临时想取消 root，可以卸载 LKM，这个过程不需要刷写分区，甚至也不用重启设备；如果你想再次 root，只需要重启设备即可； + +:::tip 两种模式共存 +打开管理器后，你可以在首页看到设备当前运行的模式；注意 GKI 模式的优先级高于 LKM，如你你既使用 GKI 内核替换掉了原有的内核，又使用 LKM 的方式修补了 GKI 内核，那么 LKM 会被忽略，设备将永远以 GKI 的模式运行。 +::: + +### 选哪个？ {#which-one} + +如果你的设备是手机，我们建议您优先考虑 LKM 模式；如果你的设备是模拟器、WSA 或者 Waydroid 等，我们建议您优先考虑 GKI 模式。 + +## LKM 安装 + +### 获取官方固件 + +使用 LKM 的模式，需要获取官方固件，然后在官方固件的基础上修补；如果你使用的是第三方内核，可以把第三方内核的 boot.img 作为官方固件。 + +获取官方固件的方法有很多，如果你的设备支持 `fastboot boot`，那么我们最推荐以及最简单的方法是使用 `fastboot boot` 临时启动 KernelSU 提供的 GKI 内核，然后安装管理器，最后在管理器中直接安装；这种方法不需要你手动下载官方固件，也不需要你手动提取 boot。 + +如果你的设备不支持 `fastboot boot`，那么你可能需要手动去下载官方固件包，然后从中提取 boot。 + +与 GKI 模式不同，LKM 模式会修改 `ramdisk`，因此在出厂 Android 13 的设备上，它需要修补的是 `init_boot` 分区而非 `boot` 分区；而 GKI 模式则永远是操作 `boot` 分区。 + +### 使用管理器 + +打开管理器，点击右上角的安装图标，会出现若干个选项： + +1. 选择并修补一个文件；如果你手机目前没有 root 权限，你可以选择这个选项，然后选择你的官方固件，管理器会自动修补它；你只需要刷入这个修补后的文件，即可永久获取 root 权限； +2. 直接安装；如果你手机已经 root，你可以选择这个选项，管理器会自动获取你的设备信息，然后自动修补官方固件，然后刷入；你可以考虑使用 `fastboot boot` KernelSU 的 GKI 内核来获取临时 root 安装管理器，然后再使用这个选项；这种方式也是 KernelSU 升级最主要的方式； +3. 安装到另一个分区；如果你的设备支持 A/B 分区，你可以选择这个选项，管理器会自动修补官方固件，然后安装到另一个分区；这种方式适用于 OTA 后的设备，你可以在 OTA 后直接安装到另一个分区，然后重启设备即可； + +### 使用命令行 + +如果你不想使用管理器，你也可以使用命令行来安装 LKM；KernelSU 提供的 `ksud` 工具可以帮助你快速修补官方固件，然后刷入。 + +这个工具支持 macOS、Linux 和 Windows，你可以在 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下载对应的版本。 + +使用方法：`ksud boot-patch` 具体的使用方法你可以查看命令行帮助。 + +```sh +oriole:/ # ksud boot-patch -h +Patch boot or init_boot images to apply KernelSU + +Usage: ksud boot-patch [OPTIONS] + +Options: + -b, --boot boot image path, if not specified, will try to find the boot image automatically + -k, --kernel kernel image path to replace + -m, --module LKM module path to replace, if not specified, will use the builtin one + -i, --init init to be replaced + -u, --ota will use another slot when boot image is not specified + -f, --flash Flash it to boot partition after patch + -o, --out output path, if not specified, will use current directory + --magiskboot magiskboot path, if not specified, will use builtin one + --kmi KMI version, if specified, will use the specified KMI + -h, --help Print help +``` + +需要说明的几个选项： + +1. `--magiskboot` 选项可以指定 magiskboot 的路径，如果不指定，ksud 会在环境变量中查找；如果你不知道如何获取 magiskboot，可以查阅[这里](#patch-boot-image)； +2. `--kmi` 选项可以指定 `KMI` 版本，如果你的设备内核名字没有遵循 KMI 规范，你可以通过这个选项来指定； + +最常见的使用方法为： + +```sh +ksud boot-patch -b --kmi android13-5.10 +``` + +## GKI 安装 + +GKI 的安装方法有如下几种，各自适用于不同的场景，请按需选择： 1. 使用 KernelSU 提供的**通用内核镜像**使用 fastboot 安装 2. 使用内核刷写 App（如 KernelFlasher）安装