Ambiguities in documentation #2775
Description
Please check before submitting an issue
- I have searched the issues and haven't found anything relevant
- I will upload bugreport file in KernelSU Manager - Settings - Report log
- I know how to reproduce the issue which may not be specific to my device
Describe the bug
The instructions in https://kernelsu.org/guide/installation.html are unclear, and in my opinion ought to be made more specific. In particular:
Unlike GKI mode, LKM mode modifies the ramdisk. Therefore, on devices with Android 13, it needs to patch the init_boot partition instead of the boot partition, while GKI mode always operates on the boot partition.
Does this refer to devices with exactly Android 13, or does it refer to devices with at least Android 13 and also later versions?
If the latter: Some Android distributions, like LineageOS, ask you not to flash init_boot.img. For example, see https://wiki.lineageos.org/devices/panther/install/#flashing-additional-partitions where the installation steps include flashing boot.img but not init_boot.img. In light of this, is the correct partition to use with KernelSU boot.img or init_boot.img?
If your device supports fastboot boot, 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.
What is the expected result of running fastboot boot? When I run it (while in the bootloader), it refreshes the screen of the bootloader with no visible changes, and then when selecting to boot the system, it boots into the normal operating system. Without any details in the documentation, I don't know if this is due to a bug, clicking the wrong button, or is the expected behavior.
You can use magiskboot to get the compression format of your original boot.img.
What is magiskboot and how can it be installed? I assume it's a command-line tool, but a search engine yields no obvious answer other than it might be something that someone could manually compile from an undocumented subdirectory https://github.com/topjohnwu/Magisk/tree/master/native/src/boot of the Magisk repository.
Upon scrolling many sections down, there's a heading called "Using magiskboot on Android devices" which explains what the tool is and how to use it, but that should be referenced in the section above.
For Pixel devices, follow the instructions below:
This section isn't followed by any "instructions below", so it's unclear how to determine the kernel compression format for a Pixel device.
You can download boot.img from GitHub Release. Please note that you should use the correct version of boot.img. If you don't know which file to download, carefully read the description of KMI and Security patch level in this document.
While the description of KMI is helpful, it only defines what the KMI is. It doesn't explain how to actually determine your KMI. It seems to me like the way to check this is to go to Settings > About phone > Android version > Kernel version. Mine lists 6.1.99-android14, so I presume android14-6.1.99_2024-10-boot.img.gz is the right version to use, but this is somewhat of a guess.
This is linked to as a way to run magiskboot on Linux, but it hasn't been updated in over a year and says "Android and Linux CI builds are not / no longer uploaded", so it's unclear what the user is intended to do. The note on the release page says "use libmagiskboot.so extracted from the official Magisk APKs instead", but doesn't explain how to "use" the file.
For some devices, the boot.img format isn't as common as lz4, gz, and uncompressed. A typical example is the Pixel, where the boot.img is compressed in the lz4_legacy format, while the, ramdisk may be in gz or also compressed in lz4_legacy. Currently, if you directly flash the boot.img provided by KernelSU, the device may not be able to boot. In this case, you can manually patch the boot.img to achieve this.
If using the directions in https://kernelsu.org/guide/installation.html#lkm-installation won't work for some devices, shouldn't there at least be a note in the main section explaining how to check whether or not your device is compatible with the recommended approach?
To Reproduce
No response
Expected behavior
No response
Screenshots
No response
Logs
No response
Device info
- Device: Google Pixel 7
- OS Version: Android 15
- KernelSU Version: 1.0.5
- Kernel Version: 6.1.99-android14
Additional context
If someone can help me understand the intended behavior with regard to some of the questions above, I would be happy to contribute improvements to the documentation, including both factual improvements as well as reorganization.