Update documentation to v15.2

2024-11-30 13:35:27 +00:00 · 2018-01-08 22:33:55 +08:00 · 2018-01-08 22:33:55 +08:00 · 89ec7dad2b
commit 89ec7dad2b
parent 4fd61345af
10 changed files with 389 additions and 286 deletions
--- a/docs/README.MD
+++ b/docs/README.MD
@ -1,28 +1,36 @@
 # Magisk Documentations
-(Updated on 2017.9.28) ([Changelog](changelog.md))
+(Updated on 2018.1.8) ([Changelog](changelog.md))
 ## Table of Contents
 - [Introduction](#introduction)
 - [Tips and Tricks](tips.md)
    - [OTA Installation Tips](tips.md#ota-installation-tips)
 The following are for developers
 - [Procedure Diagram](https://cdn.rawgit.com/topjohnwu/Magisk/cc1809688299f1f8b5db494a234850852712c0c9/docs/procedures.html)
 - [Magisk Details](details.md)
    - [Boot Stages](details.md#boot-stages)
    - [Magic Mount Details](details.md#magic-mount-details)
    - [Simple Mount Details](details.md#simple-mount-details)
- [Available Applets](applets.md)
+- [Available Tools](tools.md)
-    - [magisk](applets.md#magisk)
+    - [magiskboot](tools.md#magiskboot)
-    - [su](applets.md#su)
+    - [magiskinit](tools.md#magiskinit)
-    - [resetprop](applets.md#resetprop)
+    - [magiskpolicy](tools.md#magiskpolicy)
-    - [magiskpolicy](applets.md#magiskpolicy)
+    - [magisk](tools.md#magisk)
-    - [magiskhide](applets.md#magiskhide)
+    - [su](tools.md#su)
- [Modules and Repos](module_repo.md)
+    - [resetprop](tools.md#resetprop)
-    - [Modules and Templates](module_repo.md#magisk-module-format)
+    - [magiskhide](tools.md#magiskhide)
-    - [Submit Modules to Repo](module_repo.md#submit-your-module-to-magisk-modules-repo)
+- [Modules](modules.md)
    - [Modules and Templates](modules.md#magisk-module-format)
    - [Submit Modules to Repo](https://github.com/topjohnwu/Magisk_Repo_Submissions)
 - [Tips and Tricks](tips.md)
    - [OTA Installation Tips](tips.md#ota-installation-tips)
    - [Remove Files](tips.md#remove-files)
    - [Remove Folders](tips.md#remove-folders)
 ## Introduction
-Magisk is a suite of open source tools for devices running Android version higher than 5.0 Lollipop (API 21). It establishes an environment which covers most Android aftermarket customization needs, such as root, boot scripts, SELinux patches, dm-verity/forceencrypt patches etc.. Furthermore, Magisk also provides a **Systemless Interface** to alter the system (or vendor) arbitrarily while the actual partitions stay completely intact, all of which accomplished by only patching the boot image, and adding some files into `/data`. With its systemless nature along with several other hacks, Magisk can hide modifications from device integrity verifications, one of the main target is to hide from [Google's SafetyNet API](https://developer.android.com/training/safetynet/index.html).
+Magisk is a suite of open source tools for devices running Android version higher than 5.0 Lollipop (API 21). It establishes an environment which covers most stuffs you need for Android customization, such as root, boot scripts, SELinux patches, AVB2.0 / dm-verity / forceencrypt patches etc..
 Furthermore, Magisk provides a **Systemless Interface** to alter the system (or vendor) arbitrarily while the actual partitions stay completely intact, all of which accomplished by only patching the boot image. With its systemless nature along with several other hacks, Magisk can hide modifications from nearly any existing system integrity verifications, one of the main target is to hide from [Google's SafetyNet API](https://developer.android.com/training/safetynet/index.html).
--- a/docs/applets.md
+++ b/docs/applets.md
@ -1,166 +0,0 @@
 ## Available Applets
 Magisk has a core binary which acts as a multi-call program with many applets. Here is an introduction to all available applets.
 ### magisk
 The magisk binary itself provides a lot of utility functions when called with the name `magisk`. They are used in both Magisk installation and module installation. The entry point for `init` to invoke magisk's boot procedures are also listed here.
 Command help message:
 ```
 Usage: magisk [applet [arguments]...]
   or: magisk [options]...
 Options:
   -c                        print current binary version
   -v                        print running daemon version
   -V                        print running daemon version code
   --list                    list all availible applets
   --install [SOURCE] DIR    symlink all applets to DIR. SOURCE is optional
   --createimg IMG SIZE      create ext4 image. SIZE is interpreted in MB
   --imgsize IMG             report ext4 image used/total size
   --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
   --[boot stage]            start boot stage service
   --unlock-blocks           set BLKROSET flag to OFF for all block devices
 Supported boot stages:
   post-fs, post-fs-data, service
 Supported applets:
    su, resetprop, magiskpolicy, supolicy, magiskhide
 ```
 ### su
 The MagiskSU entrypoint. Call `su` to gain a root shell.
 Command help message:
 ```
 Usage: su [options] [--] [-] [LOGIN] [--] [args...]
 Options:
  -c, --command COMMAND         pass COMMAND to the invoked shell
  -h, --help                    display this help message and exit
  -, -l, --login                pretend the shell to be a login shell
  -m, -p,
  --preserve-environment        do not change environment variables
  -s, --shell SHELL             use SHELL instead of the default /system/bin/sh
  -u                            display the multiuser mode and exit
  -v, --version                 display version number 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,
                                use if you need to publicly apply mounts
 ```
 Note: even though the `-Z, --context` option is not listed above, it actually still exists. However MagiskSU will silently ignore the option since it's not needed anymore. It is still left over because some apps still request root shell with specific contexts as an option.
 ### resetprop
 An advanced system prop manipulation utility; you can arbitrarily alter system props using this tool. Here's some background knowledge:
 > System props are stored in a hybrid trie/binary tree data structure in memory; it was originally designed to only support adding nodes, and no nodes should be removed. Props can be read by many processes (e.g. via the `getprop` command); however, only the `init` process have write access to the property data. `init` provides a `property_service` to accept property update requests, so all property changes are monitored and controlled by `init` Restrictions such as **read-only** props (props that starts with `ro.`), which can only be set once and cannot be changed afterwards, is therefore implemented in `init`.
 **resetprop** acts just like `init`: directly access the data structure, bypassing the whole `property_service` part. Doing so, we gain **arbitrary modification** power, including altering read-only props and deleting properties. Delete properties, which was stated *"forbidden"* in the data structure, is implemented through some tricks in the data structure.
 One subtle thing to be aware of is that if we change props by directly modifying the data structure, `on property:foo=bar` triggers registered in `*.rc` scripts will not be triggered properly. This may be a good thing or a bad thing, depending on what behavior you expect. I made the default behavior to match the original setprop command, which **WILL** trigger events, but of course I provide a flag (`-n`) to disable it if you need this special behavior.
 Command help message:
 ```
 Usage: resetprop [options] [args...]
 Options:
   -v      show verbose output
   -n      only modify property in memory
 resetprop  NAME VALUE        set property entry NAME with VALUE
 resetprop  --file FILE       load props from FILE
 resetprop  --delete NAME     remove prop entry NAME
 ```
 ### magiskpolicy
 (This tool is aliased to `supolicy` for compatibility)
 A tool to patch `sepolicy`. **magiskpolicy** also comes with built-in rules to unleash restrictions to make Magisk work properly. `sepolicy` is a compiled binary containing SELinux rules; we directly patch rules in the binary format since we don't have access to the SELinux policy source (`*.te`) files.
 The Magisk daemon itself, the root shell, and all processes spawned from the daemon and root shell are all running in the context `u:r:su:s0`. This context is not only patched to be permissive, but also patched to allow any transition from `u:r:su:s0` to any domain. This was done because Samsung devices do not support permissive out of the box.
 The built in patches are split to 3 parts: minimal, medium, and large. The full patch will result in a huge policy file, which might cause the `sepolicy` file unable to fit in `boot.img`.
 - The minimal patch is just enough to start Magisk daemon and allow the daemon to further patch the policy during boot time (which is called **live patch**). It is done at installation and directly into `boot.img`. 
 - The medium patch covers most common operations, and is live patched as soon as Magisk daemon is started (blocking boot process).
 - The large patch contains the full patch. Due to the concern of greatly increasing the boot time, it is designed to run in the background until it's joined in the non-blocking late_start bootstage.
 What this all means is that **only late_start service mode is guaranteed to run in a fully patched environment**. If any script is not time critical, it is **highly recommended to run those scripts in late_start service mode**.
 Command help message:
 ```
 Usage: magiskpolicy [--options...] [policystatements...]
 Options:
  --live                directly load patched policy to device
  --minimal             minimal patches, used for boot image patches
  --load <infile>       load policies from <infile>
                        (load from live policies if not specified)
  --save <outfile>      save policies to <outfile>
 One policy statement should be treated as one parameter;
 this means a full policy statement should be enclosed in quotes;
 multiple policy statements can be provided in a single command
 The statements has a format of "<action> [args...]"
 Use '*' in args to represent every possible match.
 Collections wrapped in curly brackets can also be used as args.
 Supported policy statements:
 Type 1:
 "<action> source-class target-class permission-class permission"
 Action: allow, deny, auditallow, auditdeny
 Type 2:
 "<action> source-class target-class permission-class ioctl range"
 Action: allowxperm, auditallowxperm, dontauditxperm
 Type 3:
 "<action> class"
 Action: create, permissive, enforcing
 Type 4:
 "attradd class attribute"
 Type 5:
 "typetrans source-class target-class permission-class default-class (optional: object-name)"
 Notes:
 - typetrans does not support the all match '*' syntax
 - permission-class cannot be collections
 - source-class and target-class can also be attributes
 Example: allow { source1 source2 } { target1 target2 } permission-class *
 Will be expanded to:
 allow source1 target1 permission-class { all-permissions }
 allow source1 target2 permission-class { all-permissions }
 allow source2 target1 permission-class { all-permissions }
 allow source2 target2 permission-class { all-permissions }
 ```
 ### magiskhide
 This is the CLI to control the state of MagiskHide.
 Command help message: 
 ```
 Usage: magiskhide [--options [arguments...] ]
 Options:
  --enable          Start magiskhide
  --disable         Stop magiskhide
  --add PROCESS     Add PROCESS to the hide list
  --rm PROCESS      Remove PROCESS from the hide list
  --ls              Print out the current hide list
 ```
--- a/docs/changelog.md
+++ b/docs/changelog.md
@ -4,3 +4,5 @@
 - 2017.9.28
    - Update applets info to Magisk v14.1
    - Add OTA tips
 - 2017.1.8
    - Update to Magisk v15.2
--- a/docs/details.md
+++ b/docs/details.md
@ -2,59 +2,58 @@
 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.
 - post-fs mode
-    - **This stage is BLOCKING. Boot process will NOT continue until everything is done, or 20 seconds has passed**
+    - **This stage is BLOCKING. Boot process will NOT continue until everything is done, or 10 seconds has passed**
-    - Happens after most partitions are mounted, except `/data`
+    - Happens after most partitions are mounted. `/data` might not be available since `vold` is not started yet
-    - Magisk will bind mount files under `/cache/magisk_mount/system` to corresponding paths
+    - Magisk will bind mount files under `/cache/magisk_mount/system` and `/cache/magisk_mount/vendor`
    - It is only **Simple Mount**, which means it will replace existing files, but cannot add/remove files.
    - 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 60 seconds has passed**
+    - **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)
-    - Mirrors will be mounted. These mirrors play a critical role in **Magic Mount**
+    - `/data/adb/magisk.img` will be merged, trimmed, and mounted to `MOUNTPOINT=/sbin/.core/img`
-    - `/data/magisk.img` will be merged, trimmed, and mounted to `/magisk`
+    - Magisk will run scripts under `$MOUNTPOINT/.core/post-fs-data.d`
-    - Magisk will run scripts under `/magisk/.core/post-fs-data.d`
+    - Magisk will run scripts: `$MOUNTPOINT/$MODID/post-fs-data.sh` (placed in each module directory)
    - Magisk will run scripts: `/magisk/$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 started
+    - Happens when class late_start is triggered
-    - Put time consuming but non time critical tasks here. Boot process will be stuck if it took too long to finish your tasks in previous modes
+    - The daemon will wait for the full `sepolicy` patch before running this stage, so SELinux is guaranteed to be fully patched
-    - SELinux is guaranteed to be fully patched in this stage; **it is recommended to run most scripts in this stage**, unless your scripts require some time critical operations
+    - Put time consuming scripts here. Boot process will get stuck if it took too long to finish your tasks in `post-fs-data`
-    - Magisk will run scripts under `/magisk/.core/service.d`
+    - **It is recommended to run all scripts in this stage**, unless your scripts requires doing stuffs before Zygote is started
-    - Magisk will run scripts: `/magisk/$MODID/service.sh` (placed in each module directory)
+    - 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
 ### Terminology
 - **Item**: A folder, file, or symbolic link
- **Leaf**: The very end of a directory structure tree, can be either a file or symbolic link
+- **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/build.prop` is a source item
+- **Source item**: An item under `$MODPATH/system`, for example, `$MODPATH/system/bin/app_process32` is a source item
- **Existing item**: An item under `/system`, for example, `/system/bin/app_process` is an existing item
+- **Existing item**: An item in the actual filesystem, for example, `/system/bin/app_process32` is an existing item
- **Target item**: A corresponding item of a source item. For example, the target item of `$MODPATH/system/build.prop` is `/system/build.prop`
+- **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 `/system`
+Note: A target item **does not** imply it is an existing item. A target item might not exist in the actual filesystem
 ### Policies
 - For a source leaf: if its target item is also an existing item, the existing item will be replaced with the source leaf
 - 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 files from `$MODPATH/system` into the real `/system`. A simpler way to understand is to think as it dirty copies the contents from `$MODPATH/system` into `/system`.
+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`.
 However, an addition rule will override the above policies:
- For a source folder containing the file `.replace`, the source folder will be treated as if it is a source leaf. That is, the items within the target folder will be completely discarded, and the target folder will be replaced with the source folder.
+- 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.
-Directories containing a file named `.replace` will NOT be merged into the system. It will directly replace 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.
+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.
 ### Notes
- 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` and **NOT** merge with the pre-optimized files.
+- 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.
 - 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.
 - Adding non-existing target items is a relatively expensive operation. Magisk would need to do **MANY** under-the-hood tasks to achieve it. Replacing a whole folder is recommended if viable, it reduces the complexity of the construction of the mounting tree and could speed up the booting time
 ## Simple Mount Details
-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`. At boot time, Magisk will **clone all the attributes from the target file**, which includes selinux context, permission mode, owner, group. It'll then bind mount the file to the target. This means you don't need to worry about the metadatas for files placed under `/cache/magisk_mount`: copy the file to the correct place, reboot then you're done!
+(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)
-This mode does not feature the same complex Magic Mount implementation, it will mount a source leaf to an existing target item under `/system`.
+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!
 For example, you want to replace `/system/media/bootanimation.zip`, copy your new boot animation zip to `/cache/magisk_mount/system/media/bootanimation.zip,` Magisk will mount your files in the next reboot.
--- a/docs/images/restore_boot.png
+++ b/docs/images/restore_boot.png
--- a/docs/images/restore_img.png
+++ b/docs/images/restore_img.png
--- a/docs/module_repo.md
+++ b/docs/module_repo.md
@ -1,76 +0,0 @@
 # Magisk Modules and Online Repo
 ## Magisk Module Format
 The Magisk module is a folder under `magisk`, which has a structure as described below:
 ```
 magisk
 ├── .
 ├── .
 ├── a_module                <--- The ID of the module, should match with module.prop
 │   ├── auto_mount          <--- If this file exists, auto mount is enabled
 │   ├── disable             <--- If this file exists, the module is disabled
 │   ├── module.prop         <--- This files stores the indentity and properties of the module
 │   ├── post-fs-data.sh     <--- This script will be executed in post-fs-data
 │   ├── remove              <--- If this file exists, the module will be removed next reboot
 │   ├── service.sh          <--- This script will be executed in late_start service
 │   ├── system.prop         <--- This file will be loaded as system props
 │   ├── system              <--- If auto mount is enabled, Magisk will "Magic Mount" this folder
 │   │   ├── app
 │   │   ├── .
 │   │   └── .
 │   ├── vendor              <--- Auto generated. A symlink to $MODID/system/vendor
 │   ├── .                   <--- Any other files/folders are allowed
 │   └── .		
 ├── another_module
 │   ├── .
 │   └── .
 ├── .
 ├── .
 ```
 ## Magisk Module Template
 The **Magisk Module Template** is hosted **[here](https://github.com/topjohnwu/magisk-module-template)**.
 It is a template to create a flashable zip to install Magisk Modules. It is created to be simple to use so that anyone can create their own modules easily. The template itself contains minimal scripting for installation; most of the functions are located externally in [util_functions.sh](https://github.com/topjohnwu/Magisk/blob/master/scripts/util_functions.sh), which will be installed along with Magisk, and can be upgraded through a Magisk upgrade without the need of a template update.
 The template should meet most modules' needs. Add files into `system`, which will be cloned into `/system` by Magisk after installing the module, and in addition to module files, `system.prop`, `post-fs-data.sh`, `service.sh` are also installable through this template.
 Here are some files you would want to know:
 - `config.sh`: A simple script used as a configuration file for the actual installation file to correctly install your module. It is the place you can select which features your module needs/disables.
 - `module.prop`: This file contains your module's indentity and properties, including name and versions etc.. This file will be used to identify your module on an actual device and in the [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo)
 - `common/*`: These files will be installed to the module with the correspond role
 - `META-INF/com/google/android/update-binary`: The actual installation script. Modify this file for advanced custom behavior
 ## Create a Magisk Module With The Template
 1. Clone / download [this repo](https://github.com/topjohnwu/magisk-module-template)
 1. Open `config.sh` and carefully read the fully documented file. Follow the instructions within the script
 1. You should at least have `config.sh` and `module.prop` modified
 1. Directly zip all files; the result zip file is a flashable zip that can be used in both Magisk Manager and custom recoveries
 1. Please check [**Notes**](#notes) for several precautions
 ## Submit Your Module to Magisk Modules Repo
 If you want to share your module with others, you can submit your modules to [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo). You would need some basic `git` knowledge here.
 1. Create a module as stated above, and test if it works properly
 1. Fork [this repo](https://github.com/topjohnwu/magisk-module-template) to your account
 1. Commit and push your changes to your forked repo
 1. Open an issue in [topjohnwu/Magisk_Repo_Central](https://github.com/topjohnwu/Magisk_Repo_Central/issues/new) with your repo link
 1. I will review your module, and once accepted, your repo should be cloned into [Magisk-Modules-Repo](https://github.com/Magisk-Modules-Repo)
 1. You should receive an email to become the collaborator so you can edit the repo in the future.
 #### Once your module is live on the Modules Repo, the description of your repo should be the ID of your module. Please do NOT change the description, repeat, do NOT change the description.
 ![repo_description.png](images/repo_description.png)
 ## Notes
 - The Module Template depends on external scripts, be aware of the minimal required Magisk version of the template.
 - **Windows users please check here!!** The line endings of all text files should be in the **Unix format**. Please use advanced text editors like Sublime, Atom, Notepad++ etc. to edit **ALL** text files, **NEVER** use Windows Notepad.
 - In `module.prop`, `version` can be an arbitrary string, so any fancy version name (e.g. ultra-beta-v1.1.1.1) is allowed. However, `versionCode` **MUST** be an integer. The value is used for version comparison.
 - Make sure your module ID **does not contain any spaces**.
 ## Notes For Repo Developers
 - Magisk Manager monitors all repo's `master` branch. Any changes to the branch `master` will be reflected to all users immediately. If you are working on an update for a module, please work on another branch, make sure it works, then finally merge the changes back to `master`.
 - Once you finished upgrading your repo, increase at least the `versionCode` in `module.prop`. Magisk Manager uses this value to compare with the local installed module to determine whether an update is availible.
 - The description of your repo should be the same as your module ID. If you changed your description, Magisk Manager will fail to identify your repo, and cannot relate installed module to the online repo together.
--- a/docs/modules.md
+++ b/docs/modules.md
@ -0,0 +1,49 @@
 # Magisk Modules
 ## Magisk Module Format
 A Magisk module is a folder placed in the root folder in `magisk.img`, which has a structure as described below:
 ```
 $MOUNTPOINT
 ├── .
 ├── .
 ├── $MODID                  <--- The ID of the module, should match with module.prop
 │   ├── auto_mount          <--- If this file exists, auto mount is enabled
 │   ├── disable             <--- If this file exists, the module is disabled
 │   ├── module.prop         <--- This files stores the identity and properties of the module
 │   ├── post-fs-data.sh     <--- This script will be executed in post-fs-data
 │   ├── remove              <--- If this file exists, the module will be removed next reboot
 │   ├── service.sh          <--- This script will be executed in late_start service
 │   ├── system.prop         <--- This file will be loaded as system props
 │   ├── system              <--- If auto mount is enabled, Magisk will "Magic Mount" this folder
 │   │   ├── .
 │   │   ├── .
 │   │   └── .
 │   ├── vendor              <--- Auto generated. A symlink to $MODID/system/vendor
 │   ├── .                   <--- Any other files/folders are allowed
 │   └── .		
 ├── another_module
 │   ├── .
 │   └── .
 ├── .
 ├── .
 ```
 You are not required to use my Magisk Module Template to create a module. As long as you place files with the structure above, it will be recognized as a module.
 ## Magisk Module Template
 The **Magisk Module Template** is hosted **[here](https://github.com/topjohnwu/magisk-module-template)**.
 It is a template to create a flashable zip to install Magisk Modules. It is designed to be simple to use so that anyone can create their own modules easily. The template itself contains minimal scripting for installation; most of the functions are located externally in [util_functions.sh](https://github.com/topjohnwu/Magisk/blob/master/scripts/util_functions.sh), which will be installed along with Magisk, and can be upgraded through a Magisk upgrade without the need of a template update.
 Here are some files you would want to know:
 - `config.sh`: A simple script used as a configuration file. It is the place to configure which features your module needs/disables. A detailed instructions on how to use the template is also written in this file.
 - `module.prop`: This file contains your module's indentity and properties, including name and versions etc.. This file will be used to identify your module on an actual device and in the [Magisk Modules Repo](https://github.com/Magisk-Modules-Repo)
 - `common/*`: Boot stage scripts and `system.prop`
 - `META-INF/com/google/android/update-binary`: The actual installation script. Modify this file for advanced custom behavior
 And here are some notes to be aware of:
 - The template depends on external Magisk scripts, please specify the correct `minMagisk` value in `module.prop` with the template version your module is based on, or the minimum Magisk version your module is tested on.
 - **Windows users please check here!!** The line endings of all text files should be in the **Unix format**. Please use advanced text editors like Sublime, Atom, Notepad++ etc. to edit **ALL** text files, **NEVER** use Windows Notepad.
 - In `module.prop`, `version` can be an arbitrary string, so any fancy version name (e.g. `ultra-beta-v1.1.1.1`) is allowed. However, `versionCode` **MUST** be an integer. The value is used for version comparison.
 - Make sure your module ID **does not contain any spaces**.
--- a/docs/tips.md
+++ b/docs/tips.md
@ -10,8 +10,8 @@ Magisk do modifications systemless-ly, which means applying official OTAs is muc
 #### Prerequisites
 1. Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement.  
    <img src="images/disable_auto_ota.png" width="250">
-1. When an OTA is available, please go to Magisk Manager → Uninstall → Restore Stock Boot. **Do not reboot immediately or you will have Magisk uninstalled.** This will restore your boot back to 100% untouched stock boot image in order to pass boot verification. **This step is required before doing any of the following steps written below!**  
+1. When an OTA is available, please go to Magisk Manager → Uninstall → Restore Images. **Do not reboot immediately or you will have Magisk uninstalled.** This will restore your boot (or dtbo if available) back to 100% untouched stock images in order to pass verifications. **This step is required before doing any of the following steps written below!**  
-    <img src="images/restore_boot.png" width="250">
+    <img src="images/restore_img.png" width="250">
 #### Devices with A/B Partitions
 (Includes Pixel family)
@ -36,7 +36,7 @@ The [FlashFire](https://play.google.com/store/apps/details?id=eu.chainfire.flash
 1. Press the big **Flash** button, after a few minutes it should reboot updated with Magisk installed.
 #### Other Devices - General Case
-Unfortunately, there are no real good ways to apply OTAs on all devices. Also, the tutorial provided below will not preserve Magisk - you will have to manually re-root your device after the upgrade, and this will require PC access. Here I share my personal experience with my daily driver - HTC U11.
+Unfortunately, there are no real good ways to apply OTAs on all devices. Also, the tutorial provided below will not preserve Magisk - you will have to manually re-root your device after the upgrade, and this will require PC access. Here I share my personal experience with HTC U11.
 1. To properly install OTAs, you should 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.  
 If you decide to start by installing Magisk without touching your recovery partition, you have a few choices, either way you will end up with a Magisk rooted device, but recovery remain stock untouched:
@ -47,7 +47,7 @@ If you decide to start by installing Magisk without touching your recovery parti
 1. Once it's done you will be left with an upgraded, 100% stock, un-rooted device. You will have to manually flash Magisk back. Consider using the methods stated in step 1. to flash Magisk without touching the recovery partition if you want to receive stock OTAs frequently.
 ## Remove Files
-How to efficiently 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.
+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.
 ## Remove Folders
 Same as mentioned above, actually making the folder to **disappear** is not worth the effort. **Replacing it with an empty folder should be good enough**! A handy trick for module developers using [Magisk Module Template](https://github.com/topjohnwu/magisk-module-template) is to add the folder you want to remove into the `REPLACE` list within `config.sh`. If your module doesn't provide a correspond folder, it will create an empty folder, and automatically add `.replace` into the empty folder so the dummy folder will properly replace the one in `/system`.
--- a/docs/tools.md
+++ b/docs/tools.md
@ -0,0 +1,287 @@
 ## Available 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:
 ```
 magiskboot                 /* binary */
 magiskinit                 /* binary */
 magiskpolicy -> magiskinit
 supolicy -> magiskinit     /* alias of magiskpolicy */
 magisk                     /* binary */
 magiskhide -> magisk
 resetprop -> magisk
 su -> magisk
 ```
 ### 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.
 `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).
 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.
 Command help message:
 ```
 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
  the current directory. Return value is the same as --parse
 --repack <origbootimg> [outbootimg]
  Repack kernel, ramdisk.cpio[.ext], second, dtb... from current directory
  to [outbootimg], or new-boot.img if not specified.
  It will compress ramdisk.cpio with the same method used in <origbootimg>,
  or attempt to find ramdisk.cpio.[ext], and repack directly with the
  compressed ramdisk file
 --hexpatch <file> <hexpattern1> <hexpattern2>
  Search <hexpattern1> in <file>, and replace with <hexpattern2>
 --cpio <incpio> [commands...]
  Do cpio commands to <incpio> (modifications are done directly)
  Each command is a single argument, use quotes if necessary
  Supported commands:
    rm [-r] ENTRY
      Remove ENTRY, specify [-r] to remove recursively
    mkdir MODE ENTRY
      Create directory ENTRY in permissions MODE
    ln TARGET ENTRY
      Create a symlink to TARGET with the name ENTRY
    mv SOURCE DEST
      Move SOURCE to DEST
    add MODE ENTRY INFILE
      Add INFILE as ENTRY in permissions MODE; replaces ENTRY if exists
    extract [ENTRY OUT]
      Extract ENTRY to OUT, or extract all entries to current directory
    test
      Test the current cpio's patch status. Return value: 
      0:stock   1:Magisk   2:other (phh, SuperSU, Xposed)
    patch KEEPVERITY KEEPFORCEENCRYPT
      Ramdisk patches. KEEP**** are boolean values
    backup ORIG [SHA1]
      Create ramdisk backups from ORIG
      SHA1 of stock boot image is optional
    restore
      Restore ramdisk from ramdisk backup stored within incpio
    magisk ORIG HIGHCOMP KEEPVERITY KEEPFORCEENCRYPT [SHA1]
      Do Magisk patches and backups all in one step
      Create ramdisk backups from ORIG
      HIGHCOMP, KEEP**** are boolean values
      SHA1 of stock boot image is optional
    sha1
      Print stock boot SHA1 if previously stored
 --dtb-<cmd> <dtb>
  Do dtb related cmds to <dtb> (modifications are done directly)
  Supported commands:
    dump
      Dump all contents from dtb for debugging
    test
      Check if fstab has verity/avb flags. Return value:
      0:no flags    1:flag exists
    patch
      Search for fstab and remove verity/avb
 --compress[=method] <infile> [outfile]
  Compress <infile> with [method] (default: gzip), optionally to [outfile]
  <infile>/[outfile] can be '-' to be STDIN/STDOUT
  Supported methods: gzip xz lzma bzip2 lz4 lz4_legacy 
 --decompress <infile> [outfile]
  Detect method and decompress <infile>, optionally to [outfile]
  <infile>/[outfile] can be '-' to be STDIN/STDOUT
  Supported methods: gzip xz lzma bzip2 lz4 lz4_legacy 
 --sha1 <file>
  Print the SHA1 checksum for <file>
 --cleanup
  Cleanup the current working directory
 ```
 ### 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.
 `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.
 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
 - 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...] [policystatements...]
 Options:
  --live            directly apply patched policy live
  --magisk          built-in rules for a Magisk selinux environment
  --load FILE       load policies from <infile>
  --save FILE       save policies to <outfile>
 If no input file is specified, it will load from current policies
 If neither --live nor --save is specified, nothing will happen
 One policy statement should be treated as one parameter;
 this means a full policy statement should be enclosed in quotes;
 multiple policy statements can be provided in a single command
 The statements has a format of "<action> [args...]"
 Use '*' in args to represent every possible match.
 Collections wrapped in curly brackets can also be used as args.
 Supported policy statements:
 Type 1:
 "<action> source-class target-class permission-class permission"
 Action: allow, deny, auditallow, auditdeny
 Type 2:
 "<action> source-class target-class permission-class ioctl range"
 Action: allowxperm, auditallowxperm, dontauditxperm
 Type 3:
 "<action> class"
 Action: create, permissive, enforcing
 Type 4:
 "attradd class attribute"
 Type 5:
 "typetrans source-class target-class permission-class default-class (optional: object-name)"
 Notes:
 - typetrans does not support the all match '*' syntax
 - permission-class cannot be collections
 - source-class and target-class can also be attributes
 Example: allow { source1 source2 } { target1 target2 } permission-class *
 Will be expanded to:
 allow source1 target1 permission-class { all-permissions }
 allow source1 target2 permission-class { all-permissions }
 allow source2 target1 permission-class { all-permissions }
 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.
 Command help message:
 ```
 Usage: magisk [applet [arguments]...]
   or: magisk [options]...
 Options:
   -c                        print current binary version
   -v                        print running daemon version
   -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
   --imgsize IMG             report ext4 image used/total size
   --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:
   daemon, post-fs, post-fs-data, service
 Supported applets:
    su, resetprop, magiskhide
 ```
 ### su
 An applet of `magisk`, the MagiskSU entry point, the good old `su` command.
 Command help message:
 ```
 Usage: su [options] [-] [user [argument...]]
 Options:
  -c, --command COMMAND         pass COMMAND to the invoked shell
  -h, --help                    display this help message and exit
  -, -l, --login                pretend the shell to be a login shell
  -m, -p,
  --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,
                                this is used almost exclusively by Superuser.apk
  -mm, -M,
  --mount-master                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.
 ### resetprop
 An applet of `magisk`, an advanced system property manipulation utility. Here's some background knowledge: 
 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...]
 Options:
   -h, --help        show this message
   (no arguments)    print all properties
   NAME              get property
   NAME VALUE        set property entry NAME with VALUE
   --file FILE       load props from FILE
   --delete NAME     delete property
 Flags:
   -v      print verbose output to stderr
   -n      set properties without init triggers
           only affects setprop
   -p      access actual persist storage
           only affects getprop and deleteprop
 ```
 ### 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...] ]
 Options:
  --enable          Start magiskhide
  --disable         Stop magiskhide
  --add PROCESS     Add PROCESS to the hide list
  --rm PROCESS      Remove PROCESS from the hide list
  --ls              Print out the current hide list
 ```