Update documentation

Still WIP

docs/README.MD

@@ -1,7 +1,6 @@
 # Magisk Documentations
-(Updated on 2018.1.8)
+(Updated on 2018.10.15)
 
-- [Introduction](#introduction)
 - [Tips and Tricks](tips.md)
     - [OTA Installation Tips](tips.md#ota-installation-tips)
 
@@ -9,17 +8,13 @@ The following are for developers
 
 - [Procedure Diagram](https://cdn.rawgit.com/topjohnwu/Magisk/7d1082b1cb91db90ed0a29d8b092723fc3d69c58/docs/procedures.html)
 - [Magisk Details](details.md)
-    - [Boot Stages](details.md#boot-stages)
+    - [File Structure](details.md#file-structure)
-    - [Magic Mount Details](details.md#magic-mount-details)
+    - [Magisk Booting Process](details.md#magisk-booting-process)
-    - [Simple Mount Details](details.md#simple-mount-details)
+    - [Resetprop](details.md#resetprop)
-- [Available Tools](tools.md)
+    - [Magic Mount](details.md#magic-mount)
-    - [magiskboot](tools.md#magiskboot)
+    - [Simple Mount](details.md#simple-mount)
-    - [magiskinit](tools.md#magiskinit)
+    - [Miscellaneous](details.md#Miscellaneous)
-    - [magiskpolicy](tools.md#magiskpolicy)
+- [Magisk Tools](tools.md)
-    - [magisk](tools.md#magisk)
-    - [su](tools.md#su)
-    - [resetprop](tools.md#resetprop)
-    - [magiskhide](tools.md#magiskhide)
 - [Modules](modules.md)
     - [Modules and Templates](modules.md#magisk-module-format)
     - [Submit Modules to Repo](https://github.com/topjohnwu/Magisk_Repo_Submissions)

docs/details.md

@@ -1,59 +1,144 @@
-## Boot Stages
+## File Structure
-If you are working on complicated projects, you shall need more control to the whole process. Magisk can run scripts in different boot stages, so you can fine tune exactly what you want to do. It's recommended to read this documentation along with the procedure graph.
+### Paths in "sbin tmpfs overlay"
+sbin tmpfs overlay is the key to hiding Magisk from detection. All Magisk binaries, applets, mirrors, mountpoints, loop devices, and other trivial stuffs are all located in the `tmpfs` mounted on `/sbin`. MagiskHide can just simply unmount `/sbin` and the bind mounts into `/system` and `/vendor` to hide all modifications easily. 
 
-- post-fs mode
+```
-    - **This stage is BLOCKING. Boot process will NOT continue until everything is done, or 10 seconds has passed**
+# The actual Magisk binary
-    - Happens after most partitions are mounted. `/data` might not be available since `vold` is not started yet
+/sbin/magisk.bin
-    - Magisk will bind mount files under `/cache/magisk_mount/system` and `/cache/magisk_mount/vendor`
+# Wrapper script to prevent stupid linker errors
-    - It is only **Simple Mount**, which means it will replace existing files, but cannot add/remove files.
+/sbin/magisk
-    - This part is mostly deprecated (reasons in details)
-- post-fs-data mode
-    - **This stage is BLOCKING. Boot process will NOT continue until everything is done, or 10 seconds has passed**
-    - Happens after `/data` is ready (including the case when `/data` is encrypted)
-    - Happens before Zygote and system servers are started (which means pretty much everything)
-    - `/data/adb/magisk.img` will be merged, trimmed, and mounted to `MOUNTPOINT=/sbin/.core/img`
-    - Magisk will run scripts under `$MOUNTPOINT/.core/post-fs-data.d`
-    - Magisk will run scripts: `$MOUNTPOINT/$MODID/post-fs-data.sh` (placed in each module directory)
-    - Magisk will finally **Magisk Mount** module files
-- late_start service mode
-    - **This stage is NON-BLOCKING, it will run in parallel with other processes**
-    - Happens when class late_start is triggered
-    - The daemon will wait for the full `sepolicy` patch before running this stage, so SELinux is guaranteed to be fully patched
-    - Put time consuming scripts here. Boot process will get stuck if it took too long to finish your tasks in `post-fs-data`
-    - **It is recommended to run all scripts in this stage**, unless your scripts requires doing stuffs before Zygote is started
-    - Magisk will run scripts under `$MOUNTPOINT/.core/service.d`
-    - Magisk will run scripts: `$MOUNTPOINT/$MODID/service.sh` (placed in each module directory)
 
-## Magic Mount Details
+# Other binaries like magiskinit, and all symlinks to
-### Terminology
+# applets are also directly stored in /sbin, so they
-- **Item**: A folder, file, or symbolic link
+# are all in PATH for apps and shell to access them
-- **Leaf**: An item that is on the very end of a directory structure tree. It can be either a file or symbolic link
-- **`$MODPATH`**: A variable to represent the path of a module folder
-- **Source item**: An item under `$MODPATH/system`, for example, `$MODPATH/system/bin/app_process32` is a source item
-- **Existing item**: An item in the actual filesystem, for example, `/system/bin/app_process32` is an existing item
-- **Target item**: The corresponding item of a source item. For example, the target item of `$MODPATH/system/bin/app_process32` is `/system/bin/app_process32`
 
-Note: A target item **does not** imply it is an existing item. A target item might not exist in the actual filesystem
+# Other crazy stuffs are stored in this directory
+MAGISKTMP=/sbin/.core
 
-### Policies
+# Magisk BusyBox path
-- For a source leaf: if its target item is also an existing item, the existing item will be replaced with the source leaf
+BBPATH=$MAGISKTMP/busybox
-- For a source leaf: if its target item is not an existing item, the source leaf will be added to the path of its target item
-- For any existing item that's not a target item, it will stay intact
 
-Above is the rule of thumb. Basically it means that Magic Mount merges the two folders, `$MODPATH/system` into `/system`. A simpler way to understand is to think as the items is dirty copied from `$MODPATH/system` into `/system`.
+# The mountpoint of magisk.img
+MOUNTPATH=$MAGISKTMP/img
 
-However, an addition rule will override the above policies:
+# Mount mirrors for MagicMount
+MIRRORDIR=$MAGISKTMP/mirror
+# System mirror
+SYSTEMMIR=$MIRRORDIR/system
+# Vendor mirror, could be a symlink to $SYSTEMMIR/vendor
+# if vendor is not a separate partition
+VENDORMIR=$MIRRORDIR/vendor
+# Mirror to magisk's persist binary directory
+BINMIRROR=$MIRRORDIR/bin
 
-- For a source folder containing the file `.replace`, the source folder will be treated as if it is a leaf. That is, the items within the target folder will be completely discarded, and the target folder will be replaced with the source folder.
+# Database storing settings and root permissons
+# Each user (in the case of multiuser) has a different path
+MAGISKDB_MANAGER=$MAGISKTMP/db-<USER>/magisk.db
 
-Directories containing a file named `.replace` will **NOT** be merged, instead it directly replaces the target directory. A simpler way to understand is to think as if it wipes the target folder, and then copies the whole folder to the target path.
+# Loop devices to mount ext4 images, the ending number will vary
+MAGISKLOOP=$MAGISKTMP/block/loop<XX>
+```
 
-### Notes
+### Paths in `/data`
-- If you want to replace files in `/vendor`, please place it under `$MODPATH/system/vendor`. Magisk will handle both cases, whether the vendor partition is separated or not under-the-hood, developers don't need to bother.
+Some binaries and files should be stored on non-volatile storages in `/data`. In order to prevent detection from crazy apps, everything has to be stored somewhere safe and undetectable in `/data`. The folder `/data/adb` was chosen because of the following advantages:
-- Sometimes, completely replacing a folder is inevitable. For example you want to replace `/system/priv-app/SystemUI` in your stock rom. In stock roms, system apps usually comes with pre-optimized files. If your replacement `SystemUI.apk` is deodexed (which is most likely the case), you would want to replace the whole `/system/priv-app/SystemUI` to make sure the folder only contains the modified `SystemUI.apk` without the pre-optimized files.
-- If you are using the [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template), you can create a list of folders you want to replace in the file `config.sh`. The installation scripts will handle the creation of `.replace` files into the listed folders for you.
 
-## Simple Mount Details
+- It is an existing folder on modern Android, so it cannot be used as an indication of the existence of Magisk.
-(Note: this part is mostly deprecated, since starting with devices using A/B partitions, there is no longer a dedicated partition for cache because OTAs are applied live at boot. Instead, `/cache` now points to `/data/cache`, which means `post-fs` mode does not have access to `/cache` anymore)
+- The permission of the folder is by default `700`, owner as `root`, so non-root processes are unable to enter, read, write the folder in any possible way.
+- The folder is labeled with secontext `u:object_r:adb_data_file:s0`, and very few processes have the permission to do any interaction with that secontext.
+- The folder is located in *Device encrypted storage*, so it is accessible as soon as data is properly mounted in FBE devices.
 
-Some files require to be mounted much earlier in the boot process, currently known are bootanimation and some libs (most users won't change them). You can simply place your modified files into the corresponding path under `/cache/magisk_mount`. For example, you want to replace `/system/media/bootanimation.zip`, copy your new boot animation zip to `/cache/magisk_mount/system/media/bootanimation.zip`, and Magisk will mount your files in the next reboot. Magisk will **clone all the attributes from the target file**, which includes selinux context, permission mode, owner, group. This means you don't need to worry about the metadata for files placed under `/cache/magisk_mount`: just copy the file to the correct place, reboot then you're done!
+There are some drawbacks though (only applies to FBE setups):
+
+- Since the folder is encrypted, it is inaccessible in custom recoveries without any form of decryption (very rare case but still exists).
+- FBE is very finicky. If you wiped `/data` in TWRP (which wipes all encryption) and manually create folders that are meant to be encrypted without special treatment, it will result in bootloop.
+
+The solution of both situations above is to use `/data/magisk` when `/data/adb` does not exist. Magisk will handle migration at boot and properly setup the files to the expected location.
+
+```
+SECURE_DIR=/data/adb
+
+# Magisk image, storing modules and scripts
+MAINIMG=$SECURE_DIR/magisk.img
+
+# The image to store updated modules when installing
+# in Magisk Manager since contents in $MAINIMG are not
+# safe to be modified live. This image will be merged to
+# $MAINIMG in the next reboot
+MERGEIMG=$SECURE_DIR/magisk_merge.img
+
+# Database storing settings and root permissions
+# This file will be bind mounted to $MAGISKDB_MANAGER
+MAGISKDB=$SECURE_DIR/magisk.db
+
+# All magisk related binaries, containing busybox,
+# scripts, and magisk binaries. Used in supporting
+# module installation, addon.d, Magisk Manager etc.
+# This folder will be bind mounted to $BINMIRROR
+DATABIN=$SECURE_DIR/magisk
+
+# The location to store simple_mount files
+SIMPLEMOUNT=$SECURE_DIR/magisk_simple
+```
+
+### Paths in `$MAINIMG`
+Each folder in `$MAINIMG` is a Magisk module, except the folder `.core` which stores files that are unrelated to any modules.
+
+```
+# The directory storing all non-module files
+COREDIR=$MOUNTPATH/.core
+
+# MagiskHide hidelist
+HIDELIST=$COREDIR/hidelist
+
+# Folder storing scripts that should be executed in post-fs-data mode
+POSTFSDATA_DIR=$COREDIR/post-fs-data.d
+
+# Folder storing scripts that should be executed in service mode
+SERVICE_DIR=$COREDIR/service.d
+```
+
+### 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.
+
+It then extracts `init.magisk.rc` and inject imports in `init.rc` for additional startup services, extracts `magisk` to `/sbin`, compile split sepolicy and patch `init` to always load `/sepolicy` instead of other sources (only on Treble devices), and patches `/sepolicy` with the additional rules. Finally, it will execute the original `init` to start the ordinary boot process.
+
+### Startup
+This triggers on `post-fs-data` when `/data` is properly decrypted (if required) and mounted. The command `/sbin/magisk --starup` is executed by `init`. The startup stage will remove all traces of Magisk in ramdisk, and do the extremely complicated initialization for sbin tmpfs overlay. After the setup is done, it will execute `/sbin/magisk --post-fs-data` to switch to the `magisk` binary located in `tmpfs` and start "post-fs-data" mode.
+
+### post-fs-data
+In this mode, the daemons, `magiskd` and `magisklogd`, will be launched. `$MAINIMG` is resized / merged and mounted to `$MOUNTPOINT`, post-fs-data scripts are executed, and module files are magic mounted.
+
+### late_start
+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.
+
+`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:
+
+- `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.
+- 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`)
+
+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.
+
+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.
+
+## Simple Mount
+**(Note: this implementation is and will not be fully tested, your mileage may vary)**
+
+Some files might have to be mounted earlier in the boot process like bootanimations. To replace it with Magisk, all you need to do is simply place the modified file into the corresponding path under `$SIMPLEMOUNT`. For example, your goal is to replace `/system/media/bootanimation.zip`; you only need to copy the new zip to `$SIMPLEMOUNT/system/media/bootanimation.zip` and you're done! Magisk will clone all the attributes from the target file to your replaced file before bind mounting, so you don't need to worry about it.
+
+## Miscellaneous
+Here are some tidbits in Magisk but unable to be categorized into any sections:
+
+- Socket name randomization: when you call `su`, `magiskhide`, and some commands in `magisk`, it connects to the magisk daemon `magiskd` running in the background. The connections are established through an abstract Unix socket. Any process can go through all active Unix sockets and see if the specifc name used by Magisk is in the list to determine whether `magiskd` is running. Starting from v15.4, the abstract name used in `magiskd` and `magisklogd` are randomized by `magiskinit` on each boot.
+- Sevice name randomization: each service started up by `init` will be recorded. Some apps will detect the name of magisk boot services to determine whether Magisk is installed. Starting from v17.2, the service name assigned in `init.magisk.rc` is randomized by `magiskinit`.

docs/tools.md

@@ -1,38 +1,37 @@
-## Available Tools
+## Magisk Tools
-Magisk comes with a lot of tools for installation, programs running as a daemon, and utilities for developers. This documentation covers 3 binaries, and many more tools are available as applets. The relation between tools are shown below:
+Magisk comes with a huge collections of tools for installation, daemons, and utilities for developers. This documentation covers the 3 binaries and all included applets. The binaries and applets are shown below:
 
 ```
 magiskboot                 /* binary */
 magiskinit                 /* binary */
 magiskpolicy -> magiskinit
-supolicy -> magiskinit     /* alias of magiskpolicy */
+supolicy -> magiskinit
 magisk                     /* binary */
 magiskhide -> magisk
 resetprop -> magisk
 su -> magisk
+imgtool -> magisk
 ```
 
+Note: The Magisk zip you download only contains `magiskboot` and `magiskinit`. The binary `magisk` is compressed and embedded into `magiskinit`. Push `magiskinit` to your device and run `./magiskinit -x magisk <path>` to extract `magisk` out of the binary.
+
 ### magiskboot
-A tool to unpack / repack boot images, parse and patch cpio and dtbs, hex patch binaries, compress / decompress with multiple algorithms. It is used to install Magisk into boot images.
+A tool to unpack / repack boot images, parse / patch / extract cpio, patch dtb, hex patch binaries, and compress / decompress files with multiple algorithms.
 
-`magiskboot` natively supports (which means it does not call external tools) all popular compression methods including `gzip` (used everywhere for compressing kernel and ramdisk), `lz4` (used to compress kernel in modern devices like Pixel), `lz4_legacy` (legacy LZ4 block format with special metadata used [only on LG](https://events.static.linuxfound.org/sites/events/files/lcjpcojp13_klee.pdf) to compress kernel), `lzma` (LZMA1 algorithm natively supported in Linux kernel, used in some custom kernel to compress ramdisk), `xz` (LZMA2 algorithm, very high compression rate, used in Magisk for high compression mode and storing binaries), and `bzip2` (used in desktop Linux boot images to create bzImage, haven't seen on Android yet).
+`magiskboot` natively supports (which means it does not rely on external tools) common compression formats including `gzip`, `lz4`, `lz4_legacy` ([only used on LG](https://events.static.linuxfound.org/sites/events/files/lcjpcojp13_klee.pdf)), `lzma`, `xz`, and `bzip2`.
 
-The concept of `magiskboot` is to keep the images as intact as possible. For unpacking, it extracts the large chunks of data (kernel, ramdisk, second, dtb, extra etc.) and decompress them if possible. When repacking a boot image, the original boot image has to be provided so it can use the original headers (including MTK specific headers) with only changing the necessary entries such as the data chunk sizes, and re-compress all data with the original compression method. The same concept also applies to CPIO patching: it does not extract all files, modify in file system, archive all files back to cpio as usually done to create Linux `initramfs`, instead we do modifications directly in the cpio level in memory without involving any data extraction.
+The concept of `magiskboot` is to make boot image modification much simpler. For unpacking, it parses the header and all sections in the image (kernel, ramdisk, second, dtb, extra), detect compression format used in each section, and decompress while extraction. Each extracted sections are raw data, ready for direct modification. For repacking, the original boot image is required so the original headers can be used, changing only the necessary entries such as section sizes and checksum, and finally compress each sections back with the original format.
 
-Command help message:
+The tool also supports a variaty of CPIO operations that can modify CPIO archives without any extracting and repacking involved.
 
 ```
-Usage: magiskboot <action> [args...]
+Usage: ./magiskboot <action> [args...]
 
 Supported actions:
- --parse <bootimg>
-  Parse <bootimg> only, do not unpack. Return values: 
-    0:OK   1:error   2:insufficient boot partition size
-    3:chromeos   4:ELF32   5:ELF64
-
   --unpack <bootimg>
-  Unpack <bootimg> to kernel, ramdisk.cpio, (second), (dtb), (extra) into
+    Unpack <bootimg> to kernel, ramdisk.cpio, and if available, second, dtb,
-  the current directory. Return value is the same as --parse
+    and extra into the current directory. Return values:
+    0:valid    1:error    2:chromeos    3:ELF32    4:ELF64
 
   --repack <origbootimg> [outbootimg]
     Repack kernel, ramdisk.cpio[.ext], second, dtb... from current directory
@@ -61,8 +60,9 @@ Supported actions:
       extract [ENTRY OUT]
         Extract ENTRY to OUT, or extract all entries to current directory
       test
-      Test the current cpio's patch status. Return value: 
+        Test the current cpio's patch status
-      0:stock   1:Magisk   2:other (phh, SuperSU, Xposed)
+        Return values:
+        0:stock    1:Magisk    2:unsupported (phh, SuperSU, Xposed)
       patch KEEPVERITY KEEPFORCEENCRYPT
         Ramdisk patches. KEEP**** are boolean values
       backup ORIG [SHA1]
@@ -70,10 +70,10 @@ Supported actions:
         SHA1 of stock boot image is optional
       restore
         Restore ramdisk from ramdisk backup stored within incpio
-    magisk ORIG HIGHCOMP KEEPVERITY KEEPFORCEENCRYPT [SHA1]
+      magisk ORIG KEEPVERITY KEEPFORCEENCRYPT [SHA1]
         Do Magisk patches and backups all in one step
         Create ramdisk backups from ORIG
-      HIGHCOMP, KEEP**** are boolean values
+        KEEP**** are boolean values
         SHA1 of stock boot image is optional
       sha1
         Print stock boot SHA1 if previously stored
@@ -84,7 +84,8 @@ Supported actions:
       dump
         Dump all contents from dtb for debugging
       test
-      Check if fstab has verity/avb flags. Return value:
+        Check if fstab has verity/avb flags
+        Return values:
         0:no flags    1:flag exists
       patch
         Search for fstab and remove verity/avb
@@ -107,35 +108,29 @@ Supported actions:
 ```
 
 ### magiskinit
-This tool is created to unify Magisk support for both legacy "normal" devices and new `skip_initramfs` devices. The compiled binary will replace `init` in the ramdisk, so things could be done even before `init` is started.
+This binary will replace `init` in the ramdisk of a Magisk patched boot image. It is required for supporting devices using system as root (most A/B devices, plus some odd-balls like Huawei EMUI 9), but the tool is extended to support all traditional devices so the same installation setup could be used on all devices. More details can be found in the **Pre-Init** section in [Magisk Booting Process](details.md#magisk-booting-process).
-
-`magiskinit` is responsible for constructing a proper rootfs on devices which the actual rootfs is placed in the system partition instead of ramdisk in `boot.img`, such as the Pixel familiy and most Treble enabled devices, or I like to call it `skip_initramfs` devices: it will parse kernel cmdline, mount sysfs, parse through uevent files to make the system (or vendor if available) block device node, then copy rootfs files from system. For normal "traditional" devices, it will simply swap `init` back to the original one and continue on to the next stage.
-
-With a proper rootfs, `magiskinit` goes on and does all pre-init operations to setup a Magisk environment. It patches rootfs on the fly, providing fundamental support such as patching `init`, `init.rc`, run preliminary `sepolicy` patches, and extracts `magisk` and `init.magisk.rc` (these two files are embedded into `magiskinit`). Once all is done, it will spawn another process (`magiskinit_daemon`) to asynchronously run a full `sepolicy` patch, then starts monitoring the main Magisk daemon to make sure it is always running (a.k.a invincible mode); at the same time, it will execute the original `init` to hand the boot process back.
 
 ### magiskpolicy
 (This tool is aliased to `supolicy` for compatibility with SuperSU's sepolicy tool)
 
-This tool is an applet of `magiskinit`: once `magiskinit` had finished its mission in the pre-init stage, it will preserve an entry point for `magiskpolicy`. This tool could be used for advanced developers messing with `sepolicy`, a compiled binary containing SELinux rules. Normally Linux server admins directly modifies the SELinux policy sources (`*.te`) and recompile the `sepolicy` binary, but here we directly patch the binary file since we don't have access to the sources.
+An applet of `magiskinit`. This tool could be used for advanced developers to modify SELinux policies. In common scenarios like Linux server admins, they would directly modify the SELinux policy sources (`*.te`) and recompile the `sepolicy` binary, but here on Android we directly patch the binary file (or runtime policies).
 
-All processes spawned from the Magisk daemon, including root shells and all its forks, are running in the context `u:r:su:s0`. Magisk splits the built in patches into 2 parts: preliminary and full
+All processes spawned from the Magisk daemon, including root shells and all its forks, are running in the context `u:r:magisk:s0`. The rule used on all Magisk installed systems can be viewed as stock `sepolicy` with these patches: `magiskpolicy --magisk 'allow magisk * * *'`.
-
-- The preliminary patch should allow all Magisk internal procedures to run properly (can be done manually by the `--magisk` option). It also contains quite a few additional patches so most scripts can run in the daemon before the full patch is done
-- The full patch adds the rule `allow su * * *` on top of the preliminary rules. This is done because stock Samsung ROMs do not support permissive; adding this rule makes the domain effectively permissive. Due to the concern of greatly increasing the boot time, the Magisk daemon will not wait for this patch to finish until the boot stage `late_start` triggers. What this means is that **only `late_start` service mode is guaranteed to run in a fully patched environment**. For non-Samsung devices it doesn't matter because `u:r:su:s0` is permissive anyways, but for full compatibility, it is **highly recommended to run boot scripts in `late_start` service mode**.
-
-Command help message:
 
 ```
 Usage: magiskpolicy [--options...] [policy statements...]
 
 Options:
-  --live            directly apply patched policy live
+   --live            directly apply sepolicy live
-  --magisk          built-in rules for a Magisk selinux environment
+   --magisk          inject built-in rules for a minimal
-  --load FILE       load policies from <infile>
+                     Magisk selinux environment
-  --save FILE       save policies to <outfile>
+   --load FILE       load policies from FILE
+   --compile-split   compile and load split cil policies
+                     from system and vendor just like init
+   --save FILE       save policies to FILE
 
-If no input file is specified, it will load from current policies
+If neither --load or --compile-split is specified, it will load
-If neither --live nor --save is specified, nothing will happen
+from current live policies (/sys/fs/selinux/policy)
 
 One policy statement should be treated as one parameter;
 this means a full policy statement should be enclosed in quotes;
@@ -181,9 +176,7 @@ allow source2 target2 permission-class { all-permissions }
 
 
 ### magisk
-The magisk binary contains all the magic of Magisk, providing all the features Magisk has to offer. When called with the name `magisk`, it works as an utility tool with many helper functions, and also the entry point for `init` to start Magisk services. These helper functions are extensively used by the [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template) and Magisk Manager.
+When the magisk binary is called with the name `magisk`, it works as an utility tool with many helper functions and the entry points for `init` to start Magisk services.
-
-Command help message:
 
 ```
 Usage: magisk [applet [arguments]...]
@@ -195,27 +188,21 @@ Options:
    -V                        print running daemon version code
    --list                    list all available applets
    --install [SOURCE] DIR    symlink all applets to DIR. SOURCE is optional
-   --createimg IMG SIZE      create ext4 image. SIZE is interpreted in MB
+   --daemon                  manually start magisk daemon
-   --imgsize IMG             report ext4 image used/total size
+   --[init trigger]          start service for init trigger
-   --resizeimg IMG SIZE      resize ext4 image. SIZE is interpreted in MB
-   --mountimg IMG PATH       mount IMG to PATH and prints the loop device
-   --umountimg PATH LOOP     unmount PATH and delete LOOP device
-   --[init service]          start init service
    --unlock-blocks           set BLKROSET flag to OFF for all block devices
    --restorecon              fix selinux context on Magisk files and folders
    --clone-attr SRC DEST     clone permission, owner, and selinux context
 
-Supported init services:
+Supported init triggers:
-   daemon, post-fs, post-fs-data, service
+   startup, post-fs-data, service
 
 Supported applets:
-    su, resetprop, magiskhide
+    magisk, su, resetprop, magiskhide, imgtool
 ```
 
 ### su
-An applet of `magisk`, the MagiskSU entry point, the good old `su` command.
+An applet of `magisk`, the MagiskSU entry point. Good old `su` command.
-
-Command help message:
 
 ```
 Usage: su [options] [-] [user [argument...]]
@@ -228,28 +215,15 @@ Options:
   --preserve-environment        preserve the entire environment
   -s, --shell SHELL             use SHELL instead of the default /system/bin/sh
   -v, --version                 display version number and exit
-  -V                            display version code and exit,
+  -V                            display version code and exit
-                                this is used almost exclusively by Superuser.apk
   -mm, -M,
-  --mount-master                run in the global mount namespace,
+  --mount-master                force run in the global mount namespace
-                                use if you need to publicly apply mounts
 ```
 
-Note: even though the `-Z, --context` option is not listed above, it actually still exists for compatibility with apps using SuperSU. However MagiskSU will silently ignore the option since it's no more relevant.
+Note: even though the `-Z, --context` option is not listed above, the option still exists for CLI compatibility with apps designed for SuperSU. However the option is silently ignored since it's no longer relevant.
 
 ### resetprop
-An applet of `magisk`, an advanced system property manipulation utility. Here's some background knowledge: 
+An applet of `magisk`. An advanced system property manipulation utility. Check the [Resetprop Details](details.md#resetprop) for more background information.
-
-System properties are stored in a hybrid trie/binary tree data structure in memory. These properties are allowed to be read by many processes (natively via `libcutils`, in shells via the `getprop` command); however, only the `init` process have direct write access to the memory of property data. `init` provides a `property_service` to accept property update requests and acts as a gatekeeper, doing things such as preventing **read-only** props to be overridden and storing **persist** props to non-volatile storages. In addition, property triggers registered in `*.rc` scripts are also handled here.
-
-`resetprop` is created by pulling out the portion of source code managing properties from AOSP and try to mimic what `init` is doing. With some hackery the result is that we have direct access to the data structure, bypassing the need to go through `property_service` to gain arbitrary control. Here is a small implementation detail: the data structure and the stack-like memory allocation method does not support removing props (they are **designed NOT** to be removed); prop deletion is accomplished by detaching the target node from the tree structure, making it effectively invisible. As we cannot reclaim the memory allocated to store the property, this wastes a few bytes of memory but it shouldn't be a big deal unless you are adding and deleting hundreds of thousands of props over and over again.
-
-Due to the fact that we bypassed `property_service`, there are a few things developer should to be aware of:
-
-- `on property:foo=bar` triggers registered in `*.rc` scripts will not be triggered when props are changed. This could be a good thing or a bad thing, depending on what behavior you expect. The default behavior of `resetprop` matches the original `setprop`, which **WILL** trigger events (implemented by deleting the prop and set the props via `property_service`), but there is a flag (`-n`) to disable it if you need this special behavior.
-- persist props are stored both in memory and in `/data/property`. By default, deleting props will **NOT** remove it from persistent storage, meaning the prop will be restored after the next reboot; reading props will **NOT** read from persistent storage, as this is the behavior of normal `getprop`. With the flag `-p` enabled, deleting props will remove the prop **BOTH** in memory and `/data/property`; props will be read from **BOTH** in memory and persistent storage.
-
-Command help message:
 
 ```
 Usage: resetprop [flags] [options...]
@@ -273,8 +247,6 @@ Flags:
 ### magiskhide
 An applet of `magisk`, the CLI to control MagiskHide. Use this tool to communicate with the daemon to change MagiskHide settings.
 
-Command help message: 
-
 ```
 Usage: magiskhide [--options [arguments...] ]
 
@@ -285,3 +257,18 @@ Options:
   --rm PROCESS      Remove PROCESS from the hide list
   --ls              Print out the current hide list
 ```
+
+### imgtool
+An applet of `magisk`, a collection of common commands used to create and manage `ext4` images.
+
+```
+Usage: imgtool <action> [args...]
+
+Actions:
+   create IMG SIZE      create ext4 image. SIZE is interpreted in MB
+   resize IMG SIZE      resize ext4 image. SIZE is interpreted in MB
+   mount  IMG PATH      mount IMG to PATH and prints the loop device
+   umount PATH LOOP     unmount PATH and delete LOOP device
+   merge  SRC TGT       merge SRC to TGT
+   trim   IMG           trim IMG to save space
+```