Update documentations

docs/README.md

@@ -1,12 +1,7 @@
 # Magisk Documentations
-(Updated on 2019.5.1)
+(Updated on 2019.9.19)
 
 - [Installation](install.md)
-    - [Prerequisite](install.md#prerequisite)
-    - [Custom Recovery](install.md#custom-recovery)
-    - [Boot Image Patching](install.md#boot-image-patching)
-    - [Samsung (System-as-root)](install.md#samsung-system-as-root)
-    - [Huawei](install.md#huawei)
 - [Tutorials](tutorials.md)
     - [OTA Installation](tutorials.md#ota-installation)
     - [Best Practices for MagiskHide](tutorials.md#best-practices-for-magiskhide)
@@ -14,21 +9,6 @@
 The followings are for developers
 
 - [Magisk Details](details.md)
-    - [File Structure](details.md#file-structure)
-    - [Magisk Booting Process](details.md#magisk-booting-process)
-    - [Resetprop](details.md#resetprop)
-    - [Magic Mount](details.md#magic-mount)
-    - [Miscellaneous](details.md#miscellaneous)
 - [Magisk Tools](tools.md)
 - [Developer Guides](guides.md)
-    - [Magisk Modules](guides.md#magisk-modules)
-    - [Magisk Module Installer](guides.md#magisk-module-installer)
-    - [Submit Modules](guides.md#submit-modules)
-    - [Notes on Partitions](guides.md#notes-on-partitions)
-    - [Boot Scripts](guides.md#boot-scripts)
-    - [Remove Files](guides.md#remove-files)
-    - [Remove Folders](guides.md#remove-folders)
 - [Deployment](deploy.md)
-    - [Systemless](deploy.md#systemless)
-    - [System Only](deploy.md#system-only)
-    - [Exploits](deploy.md#exploits)

docs/deploy.md

@@ -16,24 +16,24 @@ Here are the bare minimum commands to install Magisk into a stock boot/recovery
 BOOTIMAGE=<path to boot>
 
 # First unpack the image
-./magiskboot --unpack $BOOTIMAGE
+./magiskboot unpack $BOOTIMAGE
 
 # In normal cases, after unpacking you should get at least kernel and ramdisk.cpio
 
 # Patch ramdisk
-./magiskboot --cpio ramdisk.cpio \
+./magiskboot cpio ramdisk.cpio \
 "mkdir 000 .backup" \          # create a folder to store our init backup
 "mv init .backup/init" \       # backup the original init
 "add 750 init magiskinit"      # replace init with magiskinit
 
 # Patch kernel to always use ramdisk as rootfs
 # You only need to do this on system-as-root devices
-./magiskboot --hexpatch kernel \
+./magiskboot hexpatch kernel \
 736B69705F696E697472616D6673 \
 77616E745F696E697472616D6673
 
 # Repack the boot image
-./magiskboot --repack $BOOTIMAGE
+./magiskboot repack $BOOTIMAGE
 
 # The patched image should be located in new-boot.img
 ```
@@ -45,6 +45,9 @@ WIP
 # Currently not available
 ```
 
+## Emulators (Official AVB Only)
+The script `scripts/emulator.sh` allows you to establish a minimal Magisk environment within the official Android Virtual Device included along with Android Studio / SDK. Please check the comments in the script for further information.
+
 ## Exploits
 **(Note: Magisk could only be used as root)**
 
@@ -53,52 +56,4 @@ Occasionally, there would be exploits in certain devices that could lead to full
 - Effective UID should be privileged (root, or `euid=0`)
 - Have the ability to reload `sepolicy` (which 99.9% of the time means SELinux permissive)
 
-Once you got a proper root shell, you should have `magiskinit` somewhere on the device. The basic idea is try to live patch `sepolicy` with `magiskpolicy`, and start `magiskd` with `magisk --daemon`. Here are some examples you could use as a reference.
+You can check out `scripts/emulator.sh` as a reference for bringing up Magisk with a root shell. Note that these changes are not persistent, and you will need to find ways to rerun the whole process every boot.
-
-If dm-verity is enforced (no system r/w allowed)
-
-```
-# Assume magiskinit is in current directory
-# All commands are required to run on each reboot
-
-# Live patch selinux
-ln -s ./magiskinit magiskpolicy
-./magiskpolicy --live --magisk "allow magisk * * *"
-
-# Mount tmpfs to /sbin
-mount -t tmpfs tmpfs /sbin
-chmod 755 /sbin
-chcon u:object_r:magisk_file:s0 /sbin
-
-# Add files to /sbin
-./magiskinit -x magisk /sbin/magisk
-cp -a magiskpolicy /sbin
-/sbin/magisk --install /sbin
-
-# Launch magisk daemon
-/sbin/magisk --daemon
-
-# (Optional) switch back to enforced
-setenforce 1
-```
-
-If dm-verity is not enforced (can modify system)
-
-```
-# Assume magiskinit is in current directory
-# The following commands should only need to run once
-
-# Mount system rw
-mount -o rw,remount /system
-
-# Add files to system
-./magiskinit -x magisk /system/xbin/magisk
-cp -a magiskinit /system/xbin
-ln -s /system/xbin/magiskinit /system/xbin/magiskpolicy
-/system/xbin/magisk --install /system/xbin
-
-# The following commands should run on each reboot
-/system/xbin/magiskpolicy --live --magisk "allow magisk * * *"
-/system/xbin/magisk --daemon
-
-```

docs/details.md

@@ -1,7 +1,7 @@
 # Magisk Details
 ## File Structure
 ### Paths in "sbin tmpfs overlay"
-sbin tmpfs overlay is the key to hiding Magisk from detection. All Magisk binaries, applets, mirrors, and other trivial stuffs are all located in the `tmpfs` mounted on `/sbin`. MagiskHide can just simply unmount `/sbin` and the bind mounts to hide all modifications easily.
+One of Magisk's breakthrough designs is sbin tmpfs overlay. It is required to support system-as-root devices, and also is the key to hiding Magisk from detection. All Magisk binaries, applets, mirrors, and other trivial stuffs are all located in the `tmpfs` mounted on `/sbin`. MagiskHide can just simply unmount `/sbin` and the bind mounts to hide all modifications easily.
 
 ```
 # Binaries like magisk, magiskinit, and all symlinks to
@@ -20,17 +20,21 @@ $MAGISKTMP/modules
 # The configuration used in last installation
 $MAGISKTMP/config
 
-MIRRORDIR=$MAGISKTMP/mirror
+# Partition mirrors.
+# There would be system, vendor, data, and possibly product
+# in this directory, each is the mirror to the name of the partition
+$MAGISKTMP/mirror
 
-# System mirror
+# Root directory patch files
-$MIRRORDIR/system
+# On system-as-root devices, / is not writable.
+# All patched files are stored here and bind mounted at boot.
+$MAGISKTMP/rootdir
 
-# Vendor mirror, could be a symlink to $SYSTEMMIR/vendor
+# The patched sepolicy file on system-as-root devices.
-# if vendor is not a separate partition
+# This is required as /sepolicy does not exist
-$MIRRORDIR/vendor
+# on those devices and / is not writable.
+/sbin/.se
 
-# Data mirror to workaround nosuid flag
-$MIRRORDIR/data
 ```
 
 ### Paths in `/data`
@@ -70,19 +74,15 @@ DATABIN=$SECURE_DIR/magisk
 
 ```
 
-### Final Words
-The file structure of Magisk is designed in a weird and overly complicated way. But all of these quirks are done to properly support hiding modifications from detection. These design choices are mostly what makes Magisk difficult to implement properly and maintain.
-
 ## Magisk Booting Process
 ### Pre-Init
-`magiskinit` will replace `init` as the first program to run. It is responsible for constructing rootfs on system-as-root devices: it parses kernel cmdline, sysfs, device tree fstabs, uevents etc., recreating **early-mount** and clones rootfs files from the system. On traditional devices, it will simply revert `init` to the original one and continue on to the following steps.
+`magiskinit` will replace `init` as the first program to run.
 
+- Early mount required partitions. On system-as-root devices, we will switch root to system
 - Inject magisk services into `init.rc`
 - Load sepolicy either from `/sepolicy`, precompiled sepolicy in vendor, or compile split sepolicy
-- Patch sepolicy rules and dump to `/sepolicy` and patch `init` to always load `/sepolicy`
+- Patch sepolicy rules and dump to `/sepolicy` or `/sbin/.se` and patch `init` or `libselinux.so` to load the patched policies
-- Fork a new daemon and wait for early-init trigger
 - Execute the original `init` to start the ordinary boot process
-- The early-init daemon will construct `/sbin` `tmpfs` overlay and remove all traces of Magisk in ramdisk
 
 ### post-fs-data
 This triggers on `post-fs-data` when `/data` is properly decrypted (if required) and mounted. The daemon `magiskd` will be launched, post-fs-data scripts are executed, and module files are magic mounted.
@@ -91,21 +91,21 @@ This triggers on `post-fs-data` when `/data` is properly decrypted (if required)
 Later in the booting process, the class `late_start` will be triggered, and Magisk "service" mode will be started. In this mode, service scripts are executed, and it will try to install Magisk Manager if it doesn't exist.
 
 ## Resetprop
-Usually, system properties are designed to only be updated by a single `init` process and read-only to non-root processes. With root you can change properties by sending requests via `property_service` using commands such as `setprop`, but you are still prohibited from changing read-only props (props that start with `ro.` like `ro.build.product`) and deleting properties.
+Usually, system properties are designed to only be updated by `init` and read-only to non-root processes. With root you can change properties by sending requests to `property_service` (hosted by `init`) using commands such as `setprop`, but changing read-only props (props that start with `ro.` like `ro.build.product`) and deleting properties are still prohibited.
 
-`resetprop` is implemented by distilling out the source code related to system properties from AOSP with modifications to map the property area, or `prop_area`, r/w and some clever hacks to modify the trie structure in ways it wasn't intended, like detaching nodes. In a nut shell, it directly do modifications to `prop_area`, bypassing the need to go through `property_service`. Since we are bypassing `property_service`, there are a few caveats:
+`resetprop` is implemented by distilling out the source code related to system properties from AOSP and patched to allow direct modification to property area, or `prop_area`, bypassing the need to go through `property_service`. Since we are bypassing `property_service`, there are a few caveats:
 
-- `on property:foo=bar` actions registered in `*.rc` scripts will not be triggered if property changes does not go through `property_service`. The default set property behavior of `resetprop` matches `setprop`, which **WILL** trigger events (implemented by first deleting the property then set it via `property_service`), but there is a flag `-n` to disable it if you need this special behavior.
+- `on property:foo=bar` actions registered in `*.rc` scripts will not be triggered if property changes does not go through `property_service`. The default set property behavior of `resetprop` matches `setprop`, which **WILL** trigger events (implemented by first deleting the property then set it via `property_service`). There is a flag `-n` to disable it if you need this special behavior.
 - persist properties (props that starts with `persist.`, like `persist.sys.usb.config`) are stored in both `prop_area` and `/data/property`. By default, deleting props will **NOT** remove it from persistent storage, meaning the property will be restored after the next reboot; reading props will **NOT** read from persistent storage, as this is the behavior of `getprop`. With the flag `-p`, deleting props will remove the prop in **BOTH** `prop_area` and `/data/property`, and reading props will be read from **BOTH** `prop_area` and persistent storage.
 
 ## Magic Mount
-I will skip the details in the actual implementation of how Magic Mount works as it will become a lecture, but you can always directly dive into the source code if interested. (`bootstages.c`)
+I will skip the details in the actual implementation and algorithm of Magic Mount, but you can always directly dive into the source code if interested. (`bootstages.cpp`)
 
-Even though the mounting logic and traversal algorithm is pretty complicated, the final result of Magic Mount is actually pretty simple. For each module, the folder `$MODPATH/system` will be recursively merged into the real `/system`; that is: existing files in the real system will be replaced by the one in modules' system, and new files in modules' system will be added to the real system.
+Even though the mounting logic is pretty complicated, the final result of Magic Mount is actually pretty simple. For each module, the folder `$MODPATH/system` will be recursively merged into the real `/system`; that is: existing files in the real system will be replaced by the one in modules' system, and new files in modules' system will be added to the real system.
 
 There is one additional trick you can use: if you place an empty file named `.replace` in any of the folders in a module's system, instead of merging the contents, that folder will directly replace the one in the real system. This will be very handy in some cases, for example swapping out a system app.
 
-If you want to replace files in `/vendor`, please place it under `$MODPATH/system/vendor`. Magisk will transparently handle both cases, whether vendor is a separate partition or not.
+If you want to replace files in `/vendor` or `/product`, please place them under `$MODPATH/system/vendor` or `$MODPATH/system/product`. Magisk will transparently handle both cases, whether vendor or product is a separate partition or not.
 
 ## Miscellaneous
 Here are some tidbits in Magisk but unable to be categorized into any sections:

docs/guides.md

@@ -1,5 +1,7 @@
 # Developer Guides
 
+Please read through [Magisk Details](details.md) before reading the following guides. If you are developing a module, pay extra attention to the [Magic Mount](details.md#magic-mount) section.
+
 ## Magisk Modules
 A Magisk module is a folder placed in `/data/adb/modules` with a structure below:
 
@@ -36,7 +38,11 @@ A Magisk module is a folder placed in `/data/adb/modules` with a structure below
 │   │   ├── .
 │   │   ├── .
 │   │   └── .
-│   ├── vendor              <--- Auto generated. A symlink to $MODID/system/vendor
+│   │
+│   │      *** Auto Generated by Magisk ***
+│   │
+│   ├── vendor              <--- A symlink to $MODID/system/vendor
+│   ├── product             <--- A symlink to $MODID/system/product
 │   │
 │   │      *** Others ***
 │   │
@@ -84,12 +90,6 @@ You can submit a module to **Magisk-Module-Repo** so users can download your mod
 - When your module is downloaded with Magisk Manager, `META-INF/com/google/android/update-binary` will be **forcefully** replaced with the latest [`module_installer.sh`](https://github.com/topjohnwu/Magisk/blob/master/scripts/module_installer.sh) to make sure all installation uses the latest scripts.
 - Since `update-binary` will be replaced, this means that all modules in the repo are expected to follow how the installation framework works: the installation framework will load your `install.sh` script and run the corresponding callbacks.
 - This also means that you should NOT add custom logic in `update-binary` as they will simply be ignored.
-- **Existing module devs please read!!** For devs migrating from the old template based modules to the new installer format, one thing you might overlook is the change in configuration flags: it no longer uses `AUTO_MOUNT`, but instead uses `SKIP_MOUNT`. In a nutshell, `AUTO_MOUNT=true` behaves exactly the same as `SKIP_MOUNT=false`, and 99% of the time you should NOT touch this flag.
-
-## Notes on Partitions
-On modern Android, `/system/vendor` is moved out from the system partition into its own separate `vendor` partition. For module developers, Magisk will handle these different configurations transparently so you do not need to worry anything about it. If you want to modify files in `vendor`, place the modified files under `/system/vendor` and you're good to go!
-
-Starting in Android Q and some devices on older Android versions, a separate partition `platform` is available. Support for `platform` will come soon in upcoming Magisk versions, please stay tuned!
 
 ## Boot Scripts
 In Magisk, you can run boot scripts in 2 different modes: **post-fs-data** and **late_start service** mode.
@@ -120,6 +120,17 @@ In Magisk, there are also 2 kinds of scripts: **general scripts** and **module s
 
 Magisk's internal busybox's path `$BBPATH` is always prepended in `PATH`. This means all commands you call in scripts are always using busybox unless the applet is not included. This makes sure that your script always run in a predictable environment and always have the full suite of commands regardless of which Android version it is running on.
 
+## Root Directory Overlay System
+Since `/` is read-only in system-as-root devices, Magisk provides an overlay system, allowing developers to patch files / add new rc scripts. Additional files shall be placed in the `overlay.d` folder in the ramdisk, and they will have the following restrictions:
+
+- All `*.rc` files in `overlay.d` will be read and concatenated *AFTER* `init.rc`
+- Replacing existing files are allowed.<br>
+e.g. you can replace `/res/random.png` by adding the file `overlay.d/res/random.png`
+- Non-existing files will be ignored (with exceptions detailed in the next point).<br>
+e.g. `overlay.d/new_file` will be ignored if `/new_file` does not exist
+- Additional files in `overlay.d/sbin` is allowed as they will be copied into Magisk's sbin overlay.<br>
+e.g. `overlay.d/sbin/libfoo.ko` will be copied to `/sbin/libfoo.ko`.
+
 ## Remove Files
 How to remove a file systemless-ly? To actually make the file *disappear* is complicated (possible, not worth the effort). Replacing it with a dummy file should be good enough! Create an empty file with the same name and place it in the same path within a module, it shall replace your target file with a dummy file.
 

docs/install.md

@@ -1,14 +1,37 @@
 # Installation
 If you already have Magisk installed, it is **strongly recommended to upgrade directly via Magisk Manager**. The following tutorial is for first time users.
 
+## Getting Started
 - If you are using a Huawei device running **EMUI 8 and higher**, please check [its own section](#huawei).
 - If you are using a Samsung device that is **launched with Android 9.0** (new devices in 2019), please check [its own section](#samsung-system-as-root).
-- Otherwise, follow [the normal tutorial](#boot-image-patching).
 
-## Prerequisite
+Otherwise, follow the instructions in [Knowing Your Device](#knowing-your-device), and choose the right steps
+
+- If your device is **NOT** A/B, but **IS** using system-as-root, then you will have to install Magisk to the recovery partition of your device. Follow the instructions in [Boot Image Patching](#boot-image-patching), but instead of using your boot image, use your recovery image. **Read through the [Magisk in Recovery](magisk-in-recovery) section!**
+- Otherwise, you can either follow the instructions in [Custom Recovery](#custom-recovery) (if your device have custom recovery available) or [Boot Image Patching](#boot-image-patching).
+
+Other notes:
+
 - If you plan to install custom kernels, flash the zip **AFTER** installing Magisk
 - Make sure to remove any 'boot image mods' such as other root solutions. The easiest way is to restore the boot image from factory images, or reflash a *non-prerooted* custom ROM
 
+### Knowing Your Device
+If your device is running anything older than Android 7.1, skip this section as your device will not be using A/B nor system-as-root.
+
+First, you need to know whether your device is using [A/B partitions](https://source.android.com/devices/tech/ota/ab). If you don't know, use a terminal (adb shell or any terminal emulator) to check with this command:
+```
+getprop ro.build.ab_update
+```
+If the result is `true`, then your device is using A/B partitions.
+
+If your device is A/B, then your device is also certainly using [system-as-root](https://source.android.com/devices/bootloader/system-as-root). To find out whether you are using system-as-root on a non-A/B device, use a terminal to check with this command:
+```
+getprop ro.build.system_root_image
+```
+If the result is `true`, then your device is using system-as-root.
+
+(P.S. If you are interested more regarding system-as-root, please check [this Twitter thread](https://twitter.com/topjohnwu/status/1174392824625676288))
+
 ## Custom Recovery
 If your device have custom recovery support, the easiest way is to install it through custom recoveries, such as TWRP.
 
@@ -18,49 +41,52 @@ If your device have custom recovery support, the easiest way is to install it th
 - Check whether Magisk Manager is installed. If for some reason it isn't installed automatically, manually install the APK
 
 ## Boot Image Patching
-This is the "cool" way to install Magisk on your device. Either your device does not have proper custom recoveries, your device is using the A/B partition scheme and you don't want to mix recovery and boot images together, or you have other concerns (e.g. [OTA Installation](tutorials.md#ota-installation)), you should use this method instead.
+You would want choose this method if either your device does not have custom recoveries, your device is A/B and you don't want to mix recovery and boot images, or your device is using system-as-root without A/B partitions.
 
-In order to use this method, you are required to obtain a copy of the stock boot image, which can be found by extracting OEM provided factory images or extracting from OTA update zips. If you are unable to obtain one yourself, someone on the Internet might share it somewhere. The following instructions will guide you through the process after you have the copy of boot image.
+In order to use this method, you are required to obtain a copy of the stock boot/recovery image, which can be found by extracting OEM provided factory images or extracting from OTA update zips. If you are unable to obtain one yourself, you might be able to find it somewhere on the internet. The following instructions will guide you through the process after you have the copy of boot/recovery image.
 
-- Copy the boot image to your device
+- Copy the boot/recovery image to your device
 - Download and install the latest Magisk Manager
-- Press **Install → Install → Select and Patch a File**, and select your stock boot image file
+- If you are patching a recovery image, **manually check "Recovery Mode" in Advanced Settings!**
-- Magisk Manager will install Magisk to your boot image, and store it in `[Internal Storage]/Download/magisk_patched.img`
+- Press **Install → Install → Select and Patch a File**, and select your stock boot/recovery image file
-- Copy the patched boot image from your device to your PC. If you can't find it via MTP, you can pull the file with ADB: <br>
+- Magisk Manager will patch the image, and store it in `[Internal Storage]/Download/magisk_patched.img`
+- Copy the patched image from your device to your PC. If you can't find it via MTP, you can pull the file with ADB: <br>
 `adb pull /sdcard/Download/magisk_patched.img`
-- Flash the patched boot image to your device and reboot. Here is the command if using fastboot on most devices: <br>
+- Flash the patched boot/recovery image to your device and reboot. For most devices, here is the fastboot command: <br>
-`fastboot flash boot /path/to/magisk_patched.img`
+`fastboot flash boot /path/to/magisk_patched.img` or <br>
+`fastboot flash recovery /path/to/magisk_patched.img` if you are patching a recovery image
 
 ## Magisk in Recovery
 Due to the fact that some devices no longer uses ramdisk in boot images, Magisk has no choice but to be installed in the recovery partition. For these devices, you will have to **boot to recovery every time** if you want Magisk. Since both Magisk and recovery lives in the same partition, what you actually end up getting when you choose to boot to recovery will be determined by **how long you press volume up**.
 
-Each OEM has its own key combo to boot into recovery. For example on Samsung it is **(Power + Bixby + Volume Up)**, and for Huawei it is **(Power + Volume Up)**. As soon as you press the combo and the device vibrates with a splash screen, the bootloader has already chosen which mode it is booting, either it be `boot`, `recovery`, or some OEM specific modes like `download`, `fastboot`, or `erecovery`. After the splash screen, release all buttons to boot into Magisk, since by default `recovery` mode will boot to the system with Magisk enabled. If you decide to boot to actual recovery, continue to press volume up until you see the recovery screen.
+Each OEM and device has its own key combo to boot into recovery. For example on Samsung S10 it is **(Power + Bixby + Volume Up)**, and for Huawei it is **(Power + Volume Up)**. As soon as you press the combo and the device vibrates with a splash screen, the bootloader has already chosen which mode it is booting, either it be `boot`, `recovery`, or some OEM specific modes like `download`, `fastboot`, or `erecovery`. After the splash screen, release all buttons to boot into Magisk, since by default `recovery` mode will boot to the system with Magisk enabled. If you decide to boot to actual recovery, continue to press volume up until you see the recovery screen.
 
-**In summary, after installing Magisk:**
+**After installing Magisk in recovery:**
 - **(Powering up normally) → (System with NO Magisk)**
 - **(OEM Recovery Key Combo) → (Splash screen) → (Release all buttons) → (System with Magisk)**
 - **(OEM Recovery Key Combo) → (Splash screen) → (Keep pressing volume up) → (Actual recovery)**
 
+Important Note: **You CANNOT use custom recoveries to install/upgrade Magisk!**
+
 ## Samsung (System-as-root)
-**If your device is NOT launched with Android 9.0 or higher (released after 2019), follow [the normal tutorial](#boot-image-patching)**
+**If your device is NOT launched with Android 9.0 or higher (released after 2019), you are reading the wrong section.**
 
 ### Before Installing Magisk
+- Your device is non-A/B and uses system-as-root, so Magisk will be installed to the **recovery** partition of your device. **Please read the [Magisk in Recovery](#magisk-in-recovery) section!**
 - Installing Magisk **WILL** trip KNOX
 - Installing Magisk for the first time **REQUIRES** a full data wipe, backup before continue
 - You have to have your bootloader unlocked before following the instructions
-- Magisk will be installed to the **recovery** partition of your device. **Please read the [Magisk in Recovery](#magisk-in-recovery) section before following the instructions below!**
-- After installing Magisk, you can directly upgrade Magisk within Magisk Manager without an issue. **Flashing in custom recovery is not supported for now.**
 
 ### Unlocking Bootloader
-Normally I won't provide instructions for this, but since things had changed drastically from previous Samsung devices, and there are some details that many might not know, I figure this would be helpful.
+Normally I wouldn't provide instructions for this, but since things had changed drastically from previous Samsung devices, and there are some caveats, I figure this would be helpful.
 - Allow bootloader unlocking in Developer options → OEM unlocking
-- Power off your device. Press *Bixby + Volume Down* and plug in your device to a PC to boot into download mode
+- Reboot your device to download mode. Either use `adb reboot download`, or use the key combo for your device.
 - Long press volume up to unlock the bootloader. **This will wipe your data and automatically reboot.**
 
-Just when you think the bootloader is unlocked, surprise surprise, it is *actually* not! Samsung introduced `VaultKeeper` in the system, meaning the bootloader will reject any unofficial partitions before `VaultKeeper` explicitly allows it.
+Just when you think the bootloader is unlocked, it is *actually* not! Samsung introduced `VaultKeeper`, meaning the bootloader will reject any unofficial partitions before `VaultKeeper` explicitly allows it.
 
 - Go through the initial setup. Skip through all the steps since data will be wiped again later when we are installing Magisk. **Connect the device to internet in the setup!**
-- Enable developer options, and **confirm that the OEM unlocking option exists and grayed out!** The `VaultKeeper` service will unleash the bootloader after it confirms that the user has the OEM unlocking option enabled. This step is to simply make sure the service gets the correct info, and also double check that our device is in a correct state
+- Enable developer options, and **confirm that the OEM unlocking option exists and grayed out!** The `VaultKeeper` service will unleash the bootloader after it confirms that the user has the OEM unlocking option enabled.
 - Your bootloader now accepts unofficial images in download mode.
 
 ### Instructions
@@ -70,14 +96,14 @@ Just when you think the bootloader is unlocked, surprise surprise, it is *actual
 4. In Magisk Manager: **Install → Install → Select and Patch a File** and select the AP tar file.
 5. Magisk Manager will patch the whole firmware file and store the output to
 `[Internal Storage]/Download/magisk_patched.tar`
-6. Copy the tar file to your PC (using `adb`: some people report corruption using MTP), and boot your device to download mode.
+6. Copy the patched file to your PC with `adb pull /sdcard/Download/magisk_patched.tar`. Do not use MTP as it is reported to corrupt files.
-7. Flash `magisk_patched.tar` as AP in ODIN, together with the BL, CP and HOME_CSC files. Never flash only an AP file, as Odin can shrink your `/data` file-system if you do.<br> **Important: Uncheck "Auto Reboot" in Options!**
+7. Reboot to download mode, and flash `magisk_patched.tar` as AP in Odin, together with the BL, CP and HOME_CSC files. Never flash only an AP file, as Odin can shrink your `/data` file-system if you do.<br> **Important: Uncheck "Auto Reboot" in Options!**
 8. Magisk is now successfully flashed to your device! But there are still several steps before you can properly use the device.
 9. We now want to boot into the stock recovery to factory reset our device. <br>
 **Full data wipe is mandatory! Do not skip this step.** <br>
-Press *Power + Volume Down* to exit download mode. As soon as the screen turns off, immediately press *Power + Bixby + Volume Up* to boot to recovery partition. Just as mentioned in the previous section, since we want to boot into stock recovery, **continue pressing the volume up button until you see the stock recovery screen**.
+Press *Power + Volume Down* to exit download mode. As soon as the screen turns off, immediately press the combo key to boot to recovery (e.g. on the S10 it is *Power + Bixby + Volume Up*). Since we want to boot into stock recovery, **continue pressing the volume up button until you see the stock recovery screen**.
-10. In the stock recovery menu, use volume buttons to navigate through menus, and the power button to select the option. Select *Wipe data/factory reset* to wipe the data of the device.
+10. Use volume buttons to navigate through the stock recovery menu, and the power button to select an option. Choose *Wipe data/factory reset* to wipe the data of the device.
-11. This time, we can finally boot to the system with Magisk. Select *Reboot system now*, and immediately press *Power + Bixby + Volume Up*. After seeing the bootloader warning screen, release all buttons so it can boot to the system.
+11. This time, we can finally boot to the system with Magisk. Select *Reboot system now*, and immediately press the combo key to recovery. After seeing the bootloader warning screen, release all buttons so it can boot to the system.
 12. The device will automatically reboot for the first time it boots. This is completely normal and done by design.
 13. After the device is booted up, do the usual initial setup. **The following steps will need internet connection.**
 14. You shall see Magisk Manager in your app drawer; if not, manually install the APK you downloaded in step 3 and continue to the next step. The app would be a stub and it shall automatically upgrade to the full Magisk Manager when you open it.
@@ -89,8 +115,8 @@ Press *Power + Volume Down* to exit download mode. As soon as the screen turns o
     - `vbmeta`: replace with empty vbmeta image to disable partition verification
     - `boot`: remove the signature of the image to prevent soft bricks
     - `recovery`: this is where Magisk is actually installed
-- **Never, ever** try to restore either of the 3 images mentioned back to stock! You can easily brick your device by doing so, and the only way out is to do full ODIN restore following with factory reset. Just don't do it.
+- **Never, ever** try to restore either of the 3 images mentioned back to stock! You can easily brick your device by doing so, and the only way out is to do full Odin restore following with factory reset. Just don't do it.
-- If you want to upgrade your device, **never** flash the stock **AP** tar file with reasons mentioned above. **Always** pre-patch the firmware before flashing in ODIN.
+- If you want to upgrade your device, **never** flash the stock **AP** tar file with reasons mentioned above. **Always** pre-patch the firmware before flashing in Odin.
 -  If you don't need to patch the full firmware, you can manually create a tar file with **at least** `vbmeta.img`, `boot.img`, and `recovery.img` to let Magisk Manager patch your images in the proper way.
 
 ## Huawei

docs/tools.md

@@ -33,11 +33,12 @@ Supported actions:
     Return values:
     0:valid    1:error    2:chromeos
 
-  repack <origbootimg> [outbootimg]
+  repack [-n] <origbootimg> [outbootimg]
     Repack boot image components from current directory
     to [outbootimg], or new-boot.img if not specified.
-    It will compress ramdisk.cpio and kernel with the same method in
+    If '-n' is provided, it will not attempt to recompress ramdisk.cpio,
-    <origbootimg> if the file provided is not already compressed.
+    otherwise it will compress ramdisk.cpio and kernel with the same method
+    in <origbootimg> if the file provided is not already compressed.
 
   hexpatch <file> <hexpattern1> <hexpattern2>
     Search <hexpattern1> in <file>, and replace with <hexpattern2>
@@ -81,7 +82,7 @@ Supported actions:
       test
         Check if fstab has verity/avb flags
         Return values:
-        0:no flags    1:flag exists
+        0:flag exists    1:no flags
       patch
         Search for fstab and remove verity/avb
 
@@ -192,6 +193,7 @@ Options:
    -V                        print running daemon version code
    --list                    list all available applets
    --daemon                  manually start magisk daemon
+   --remove-modules          remove all modules and reboot
    --[init trigger]          start service for init trigger
 
 Advanced Options (Internal APIs):
@@ -199,13 +201,14 @@ Advanced Options (Internal APIs):
    --restorecon              restore selinux context on Magisk files
    --clone-attr SRC DEST     clone permission, owner, and selinux context
    --clone SRC DEST          clone SRC to DEST
-   --sqlite SQL              exec SQL to Magisk database
+   --sqlite SQL              exec SQL commands to Magisk database
+   --use-broadcast           use broadcast for su logging and notify
 
 Supported init triggers:
    post-fs-data, service, boot-complete
 
 Supported applets:
-    magisk, su, resetprop, magiskhide
+    su, resetprop, magiskhide
 ```
 
 ### su
@@ -255,13 +258,16 @@ Flags:
 An applet of `magisk`, the CLI to control MagiskHide. Use this tool to communicate with the daemon to change MagiskHide settings.
 
 ```
-Usage: magiskhide [--option [arguments...] ]
+Usage: magiskhide [action [arguments...] ]
 
-Options:
+Actions:
-  --status          Return the status of magiskhide
+   status          Return the status of magiskhide
-  --enable          Start magiskhide
+   enable          Start magiskhide
-  --disable         Stop magiskhide
+   disable         Stop magiskhide
-  --add PKG [PROC]  Add a new target to the hide list
+   add PKG [PROC]  Add a new target to the hide list
-  --rm PKG [PROC]   Remove from the hide list
+   rm PKG [PROC]   Remove target(s) from the hide list
-  --ls              List the current hide list
+   ls              Print the current hide list
+   exec CMDs...    Execute commands in isolated mount
+                   namespace and do all hide unmounts
+   test            Run process monitor test
 ```

docs/tutorials.md

@@ -44,7 +44,7 @@ The [FlashFire](https://play.google.com/store/apps/details?id=eu.chainfire.flash
 
 - Press the big **Flash** button, after a few minutes it should reboot and updated with Magisk installed.
 
-### Legacy "Non A/B" Devices - General Case
+### "Non A/B" Devices - General Case
 Unfortunately, there are no real good ways to apply OTAs on these devices. The following tutorial will not preserve Magisk - you will have to manually re-root your device after the upgrade, and this will require PC access. This is a general "best practice".
 
 - To properly install OTAs, you must have your stock recovery installed on your device. If you have custom recovery installed, you can restore it from your previous backup, or dumps found online, or factory images provided by OEMs.