diff --git a/website/docs/guide/faq.md b/website/docs/guide/faq.md index 4281b97b..cc3c66f2 100644 --- a/website/docs/guide/faq.md +++ b/website/docs/guide/faq.md @@ -34,4 +34,8 @@ It is possible. But you should download the kernel source and intergrate KernelS ## Can KernelSU support old kernel? -It is possible, but you need to backport it manully and PRs welcome! \ No newline at end of file +It is possible, but you need to backport it manully and PRs welcome! + +## How to integrate KernelSU for old kernel? + +Please refer [guide](how-to-integrate-for-non-gki) \ No newline at end of file diff --git a/website/docs/guide/how-to-integrate-for-non-gki.md b/website/docs/guide/how-to-integrate-for-non-gki.md new file mode 100644 index 00000000..3045d5fe --- /dev/null +++ b/website/docs/guide/how-to-integrate-for-non-gki.md @@ -0,0 +1,138 @@ +# How to integrate KernelSU for non GKI kernel? + +KernelSU can be integrate to non GKI kernel, and it is backported to 4.14 now, it is also possible to run on kernel below 4.14. + +Since the fragmentization of non GKI kernels, we don't have a uniform way to build it, so we can not provide non GKI boot images. But you can build the kernel yourself with KernelSU integrated. + +First, you should be able to build a bootable kernel from kernel source code, if the kernel is not open sourced, then it is difficult to run KernelSU for your device. + +If you can build a bootable kernel, there are two ways to integrate KernelSU to the kernel source code: + +1. Automatically with `kprobe` +2. Manully + +## Integrate with kprobe + +KernelSU use kprobe to do kernel hooks, if the *kprobe* runs well in your kernel, it is recommended to use this way. + +First, add KernelSU to your kernel source tree: + +```sh +curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash - +``` + +Then, you should check if *kprobe* is enabled in your kernel config, if it is not, please add these configs to it: + +```txt +CONFIG_KPROBES=y +CONFIG_HAVE_KPROBES=y +CONFIG_KPROBE_EVENTS=y +``` + +And build your kernel again, KernelSU should works well. + +But if you encounter a boot loop when integrated KernelSU, it is maybe *kprobe is broken in your kernel*, you should fix the kprobe bug or use the second way. + +## Manully modify the kernel source + +If kprobe can not work in your kernel (maybe a upstream bug or kernel below 4.8), then you can try this way: + +First, add KernelSU to your kernel source tree: + +```sh +curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash - +``` + +Then, add KernelSU calls to the kernel source, here is a patch to refer: + +```diff +diff --git a/fs/exec.c b/fs/exec.c +index ac59664eaecf..bdd585e1d2cc 100644 +--- a/fs/exec.c ++++ b/fs/exec.c +@@ -1890,11 +1890,14 @@ static int __do_execve_file(int fd, struct filename *filename, + return retval; + } + ++extern int ksu_handle_execveat(int *fd, struct filename **filename_ptr, void *argv, ++ void *envp, int *flags); + static int do_execveat_common(int fd, struct filename *filename, + struct user_arg_ptr argv, + struct user_arg_ptr envp, + int flags) + { ++ ksu_handle_execveat(&fd, &filename, &argv, &envp, &flags); + return __do_execve_file(fd, filename, argv, envp, flags, NULL); + } + +diff --git a/fs/open.c b/fs/open.c +index 05036d819197..965b84d486b8 100644 +--- a/fs/open.c ++++ b/fs/open.c +@@ -348,6 +348,8 @@ SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) + return ksys_fallocate(fd, mode, offset, len); + } + ++extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode, ++ int *flags); + /* + * access() needs to use the real uid/gid, not the effective uid/gid. + * We do this by temporarily clearing all FS-related capabilities and +@@ -355,6 +357,7 @@ SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) + */ + long do_faccessat(int dfd, const char __user *filename, int mode) + { ++ ksu_handle_faccessat(&dfd, &filename, &mode, NULL); + const struct cred *old_cred; + struct cred *override_cred; + struct path path; +diff --git a/fs/read_write.c b/fs/read_write.c +index 650fc7e0f3a6..55be193913b6 100644 +--- a/fs/read_write.c ++++ b/fs/read_write.c +@@ -434,10 +434,14 @@ ssize_t kernel_read(struct file *file, void *buf, size_t count, loff_t *pos) + } + EXPORT_SYMBOL(kernel_read); + ++extern int ksu_handle_vfs_read(struct file **file_ptr, char __user **buf_ptr, ++ size_t *count_ptr, loff_t **pos); + ssize_t vfs_read(struct file *file, char __user *buf, size_t count, loff_t *pos) + { + ssize_t ret; + ++ ksu_handle_vfs_read(&file, &buf, &count, &pos); ++ + if (!(file->f_mode & FMODE_READ)) + return -EBADF; + if (!(file->f_mode & FMODE_CAN_READ)) +diff --git a/fs/stat.c b/fs/stat.c +index 376543199b5a..82adcef03ecc 100644 +--- a/fs/stat.c ++++ b/fs/stat.c +@@ -148,6 +148,8 @@ int vfs_statx_fd(unsigned int fd, struct kstat *stat, + } + EXPORT_SYMBOL(vfs_statx_fd); + ++extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags); ++ + /** + * vfs_statx - Get basic and extra attributes by filename + * @dfd: A file descriptor representing the base dir for a relative filename +@@ -170,6 +172,7 @@ int vfs_statx(int dfd, const char __user *filename, int flags, + int error = -EINVAL; + unsigned int lookup_flags = LOOKUP_FOLLOW | LOOKUP_AUTOMOUNT; + ++ ksu_handle_stat(&dfd, &filename, &flags); + if ((flags & ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT | + AT_EMPTY_PATH | KSTAT_QUERY_FLAGS)) != 0) + return -EINVAL; +``` + +You should found the four functions in kernel source: + +1. do_faccessat, usually in `fs/open.c` +2. do_execveat_common, usually in `fs/exec.` +3. vfs_read, usually in `fs/read_write.c` +4. vfs_statx, usually in `fs/stat.c` + +Finally, edit `KernelSU/kernel/ksu.c` and comment out `enable_sucompat()` then build your kernel again, KernelSU should works well. diff --git a/website/docs/zh_CN/guide/faq.md b/website/docs/zh_CN/guide/faq.md index e1d271f3..971cc55b 100644 --- a/website/docs/zh_CN/guide/faq.md +++ b/website/docs/zh_CN/guide/faq.md @@ -34,4 +34,8 @@ KernelSU 的模块系统与 Magisk 的 magic mount 有冲突，如果 KernelSU ## KernelSU 可以支持旧内核吗？ -可以，但你需要手动移植它，欢迎 PR ！ \ No newline at end of file +可以，但你需要手动移植它，欢迎 PR ！ + +## 如何为旧内核基础 KernelSU？ + +参考[教程](how-to-integrate-for-non-gki) diff --git a/website/docs/zh_CN/guide/how-to-integrate-for-non-gki.md b/website/docs/zh_CN/guide/how-to-integrate-for-non-gki.md new file mode 100644 index 00000000..65843ace --- /dev/null +++ b/website/docs/zh_CN/guide/how-to-integrate-for-non-gki.md @@ -0,0 +1,138 @@ +# 如何为非 GKI 内核集成 KernelSU + +KernelSU 可以被集成到非 GKI 内核中，现在它最低支持到内核 4.14 版本；理论上也可以支持更低的版本。 + +由于非 GKI 内核的碎片化极其严重，因此通常没有统一的方法来编译它，所以我们也无法为非 GKI 设备提供 boot 镜像。但你完全可以自己集成 KernelSU 然后编译内核使用。 + +首先，你必须有能力从你设备的内核源码编译出一个可以开机并且能正常使用的内核，如果内核不开源，这通常难以做到。 + +如果你已经做好了上述准备，那有两个方法来集成 KernelSU 到你的内核之中。 + +1. 借助 `kprobe` 自动集成 +2. 手动 + +## 使用 kprobe 集成 + +KernelSU 使用 kprobe 机制来做内核的相关 hook，如果 *kprobe* 可以在你编译的内核中正常运行，那么推荐用这个方法来集成。 + +首先，把 KernelSU 添加到你的内核源码树，在内核的根目录执行以下命令： + +```sh +curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash - +``` + +然后，你需要检查你的内核是否开启了 *kprobe* 相关的配置，如果没有开启，需要添加以下配置： + +```txt +CONFIG_KPROBES=y +CONFIG_HAVE_KPROBES=y +CONFIG_KPROBE_EVENTS=y +``` + +最后，重新编译你的内核即可。 + +如果你在集成 KernelSU 之后手机无法启动，那么很可能你的内核中 **kprobe 工作不正常**，你需要修复这个 bug 或者用第二种方法。 + +## Manully modify the kernel source + +如果 kprobe 工作不正常（通常是上游的 bug 或者内核版本过低），那你可以尝试这种方法： + +首先，把 KernelSU 添加到你的内核源码树，在内核的根目录执行以下命令： + +```sh +curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash - +``` + +然后，手动修改内核源码，你可以参考下面这个 patch: + +```diff +diff --git a/fs/exec.c b/fs/exec.c +index ac59664eaecf..bdd585e1d2cc 100644 +--- a/fs/exec.c ++++ b/fs/exec.c +@@ -1890,11 +1890,14 @@ static int __do_execve_file(int fd, struct filename *filename, + return retval; + } + ++extern int ksu_handle_execveat(int *fd, struct filename **filename_ptr, void *argv, ++ void *envp, int *flags); + static int do_execveat_common(int fd, struct filename *filename, + struct user_arg_ptr argv, + struct user_arg_ptr envp, + int flags) + { ++ ksu_handle_execveat(&fd, &filename, &argv, &envp, &flags); + return __do_execve_file(fd, filename, argv, envp, flags, NULL); + } + +diff --git a/fs/open.c b/fs/open.c +index 05036d819197..965b84d486b8 100644 +--- a/fs/open.c ++++ b/fs/open.c +@@ -348,6 +348,8 @@ SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) + return ksys_fallocate(fd, mode, offset, len); + } + ++extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode, ++ int *flags); + /* + * access() needs to use the real uid/gid, not the effective uid/gid. + * We do this by temporarily clearing all FS-related capabilities and +@@ -355,6 +357,7 @@ SYSCALL_DEFINE4(fallocate, int, fd, int, mode, loff_t, offset, loff_t, len) + */ + long do_faccessat(int dfd, const char __user *filename, int mode) + { ++ ksu_handle_faccessat(&dfd, &filename, &mode, NULL); + const struct cred *old_cred; + struct cred *override_cred; + struct path path; +diff --git a/fs/read_write.c b/fs/read_write.c +index 650fc7e0f3a6..55be193913b6 100644 +--- a/fs/read_write.c ++++ b/fs/read_write.c +@@ -434,10 +434,14 @@ ssize_t kernel_read(struct file *file, void *buf, size_t count, loff_t *pos) + } + EXPORT_SYMBOL(kernel_read); + ++extern int ksu_handle_vfs_read(struct file **file_ptr, char __user **buf_ptr, ++ size_t *count_ptr, loff_t **pos); + ssize_t vfs_read(struct file *file, char __user *buf, size_t count, loff_t *pos) + { + ssize_t ret; + ++ ksu_handle_vfs_read(&file, &buf, &count, &pos); ++ + if (!(file->f_mode & FMODE_READ)) + return -EBADF; + if (!(file->f_mode & FMODE_CAN_READ)) +diff --git a/fs/stat.c b/fs/stat.c +index 376543199b5a..82adcef03ecc 100644 +--- a/fs/stat.c ++++ b/fs/stat.c +@@ -148,6 +148,8 @@ int vfs_statx_fd(unsigned int fd, struct kstat *stat, + } + EXPORT_SYMBOL(vfs_statx_fd); + ++extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags); ++ + /** + * vfs_statx - Get basic and extra attributes by filename + * @dfd: A file descriptor representing the base dir for a relative filename +@@ -170,6 +172,7 @@ int vfs_statx(int dfd, const char __user *filename, int flags, + int error = -EINVAL; + unsigned int lookup_flags = LOOKUP_FOLLOW | LOOKUP_AUTOMOUNT; + ++ ksu_handle_stat(&dfd, &filename, &flags); + if ((flags & ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT | + AT_EMPTY_PATH | KSTAT_QUERY_FLAGS)) != 0) + return -EINVAL; +``` + +主要是要改四个地方： + +1. do_faccessat, usually in `fs/open.c` +2. do_execveat_common, usually in `fs/exec.` +3. vfs_read, usually in `fs/read_write.c` +4. vfs_statx, usually in `fs/stat.c` + +改完之后，打开 `KernelSU/kernel/ksu.c`，注释 `enable_sucompat()`调用，然后重新编译内核即可。