magisk-boot_patch.sh注解

magisk-boot_patch.sh注解

#!/system/bin/sh
#######################################################################################
# Magisk Boot Image Patcher
# 这段脚本是 Magisk Boot Image Patcher 的一部分，它的主要功能是修改 Android 设备的启动镜像（boot image），
# 以支持 Magisk root 权限管理工具的运行。Magisk 是一款流行的 Android root 权限解决方案，
# 它允许用户在不修改系统分区的情况下获得 root 访问权限，从而避免破坏厂商的保修或许可证协议
# 。以下是脚本的主要部分及其功能的详细解析：------------------
#
#初始化和参数读取
#脚本开始时会检查一些环境变量，如 KEEPVERITY, KEEPFORCEENCRYPT, PATCHVBMETAFLAG, RECOVERYMODE, SYSTEM_ROOT，这些变量控制了脚本的行为。例如，KEEPVERITY 控制是否保留完整性验证。
#
#处理输入的 Boot Image
#首先，脚本检查输入的启动镜像文件是否存在。
#如果输入的是一个设备节点（如 MTD 或 NAND 分区），脚本会使用 nanddump 工具将其转储为 boot.img 文件。
#接下来，脚本会使用 magiskboot 工具解包 boot.img 文件。
#检查和还原 Ramdisk 状态
#脚本会检查 ramdisk 的状态，判断其是否已经被 Magisk 或其他工具修改过。
#根据 ramdisk 的状态，它会进行相应的还原操作，例如恢复到原始状态或保存当前的 Magisk 状态。
#修改 Ramdisk
#脚本压缩一些关键的二进制文件（如 magisk64, magisk32, stub.apk），以节省 ramdisk 空间。
#它会在 ramdisk 中添加一些必要的文件，如 magiskinit，并创建适当的目录结构。
#更新配置文件，包含各种环境变量和随机种子，这些数据会在设备启动时被 magiskinit 使用。
#处理 DTB 和 Kernel
#脚本会检查和处理设备树二进制文件（DTB）和内核文件，例如移除特定的安全特性（如 Samsung RKP），以及对内核进行必要的 hexpatch 修改。
#重新打包和签名
#最后，脚本使用 magiskboot 工具重新打包修改后的 ramdisk 和其他组件，生成新的 boot.img 文件。
#如果检测到输入的是 Chrome OS 的 boot 分区，脚本会对其进行签名。
#脚本还包含了错误处理和日志打印功能，确保在出现问题时能够给出清晰的反馈。此外，它还提供了对不同设备和 Android 版本的兼容性处理，例如针对 Sony 设备的特别处理和对 Android 13 的支持。
#
#总之，这段脚本是 Magisk 安装过程中的核心部分，负责在不修改系统分区的前提下，使设备能够在启动时加载 Magisk 相关的模块和服务，从而实现 root 权限的管理。
#######################################################################################
#
# Usage: boot_patch.sh <bootimage>
#
# The following flags can be set in environment variables:
# KEEPVERITY, KEEPFORCEENCRYPT, PATCHVBMETAFLAG, RECOVERYMODE, SYSTEM_ROOT
#
# This script should be placed in a directory with the following files:
#
# File name          Type      Description
#
# boot_patch.sh      script    A script to patch boot image for Magisk.
#                  (this file) The script will use files in its same
#                              directory to complete the patching process.
# util_functions.sh  script    A script which hosts all functions required
#                              for this script to work properly.
# magiskinit         binary    The binary to replace /init.
# magisk(32/64)      binary    The magisk binaries.
# magiskboot         binary    A tool to manipulate boot images.
# stub.apk           binary    The stub Magisk app to embed into ramdisk.
# chromeos           folder    This folder includes the utility and keys to sign
#                  (optional)  chromeos boot images. Only used for Pixel C.
#
#######################################################################################

############
# Functions
############

# Pure bash dirname implementation
getdir() {
  case "$1" in
    */*)
      dir=${1%/*}
      if [ -z $dir ]; then
        echo "/"
      else
        echo $dir
      fi
    ;;
    *) echo "." ;;
  esac
}

#################
# Initialization
#################

if [ -z $SOURCEDMODE ]; then
  # Switch to the location of the script file
  cd "$(getdir "${BASH_SOURCE:-$0}")"
  # Load utility functions
  . ./util_functions.sh
  # Check if 64-bit
  api_level_arch_detect
fi

BOOTIMAGE="$1"
[ -e "$BOOTIMAGE" ] || abort "$BOOTIMAGE does not exist!"

# Dump image for MTD/NAND character device boot partitions
if [ -c "$BOOTIMAGE" ]; then
  nanddump -f boot.img "$BOOTIMAGE"
  BOOTNAND="$BOOTIMAGE"
  BOOTIMAGE=boot.img
fi

# Flags
[ -z $KEEPVERITY ] && KEEPVERITY=false
[ -z $KEEPFORCEENCRYPT ] && KEEPFORCEENCRYPT=false
[ -z $PATCHVBMETAFLAG ] && PATCHVBMETAFLAG=false
[ -z $RECOVERYMODE ] && RECOVERYMODE=false
[ -z $SYSTEM_ROOT ] && SYSTEM_ROOT=false
export KEEPVERITY
export KEEPFORCEENCRYPT
export PATCHVBMETAFLAG

chmod -R 755 .

#########
# Unpack
#########

CHROMEOS=false

ui_print "- Unpacking boot image"
./magiskboot unpack "$BOOTIMAGE"
# 这段脚本代码是在处理完 boot image 的 unpack 操作之后，根据返回的状态码（即 $?）来判断 unpack 操作的结果，并据此采取不同的行动。
# 在 shell 脚本中，$? 变量存储的是上一个命令的退出状态码，通常用于条件判断和错误处理。
case $? in
  0 ) ;;
  1 )
    abort "! Unsupported/Unknown image format"
    ;;
  2 )
    ui_print "- ChromeOS boot image detected"
    CHROMEOS=true
    ;;
  * )
    abort "! Unable to unpack boot image"
    ;;
esac

###################
# Ramdisk Restores
###################

# magiskboot 是 Magisk 项目的一部分，Magisk 是一个流行的 Android 设备上的 root 权限管理解决方案。
# magiskboot 是一个 shell 脚本或可执行程序，用于处理 Android 设备的 boot.img 文件和其他与设备启动相关的操作，如提取、修改、重新打包 boot 分区等。
# 使用 magiskboot 工具将 ramdisk.cpio 文件解压到 test 目录中，这样就可以访问和修改 ramdisk.cpio 中的文件，这对于调试、定制或修复 Android 设备的启动过程非常有帮助。
# Test patch status and do restore
ui_print "- Checking ramdisk status"
if [ -e ramdisk.cpio ]; then
  ./magiskboot cpio ramdisk.cpio test
  STATUS=$?
else
  # Stock A only legacy SAR, or some Android 13 GKIs
  STATUS=0
fi
case $((STATUS & 3)) in
  0 )  # Stock boot
    ui_print "- Stock boot image detected"
    SHA1=$(./magiskboot sha1 "$BOOTIMAGE" 2>/dev/null)
    cat $BOOTIMAGE > stock_boot.img
    cp -af ramdisk.cpio ramdisk.cpio.orig 2>/dev/null
    ;;
  1 )  # Magisk patched
    ui_print "- Magisk patched boot image detected"
    # Find SHA1 of stock boot image
    [ -z $SHA1 ] && SHA1=$(./magiskboot cpio ramdisk.cpio sha1 2>/dev/null)
    ./magiskboot cpio ramdisk.cpio restore
    cp -af ramdisk.cpio ramdisk.cpio.orig
    rm -f stock_boot.img
    ;;
  2 )  # Unsupported
    ui_print "! Boot image patched by unsupported programs"
    abort "! Please restore back to stock boot image"
    ;;
esac
# 判断以决定使用哪个初始化程序（init）。在 Unix/Linux 系统中，init 通常是系统启动的第一个进程，负责管理和控制其他进程的生命周期。
# Workaround custom legacy Sony /init -> /(s)bin/init_sony : /init.real setup
INIT=init
if [ $((STATUS & 4)) -ne 0 ]; then
  INIT=init.real
fi

##################
# Ramdisk Patches
##################

ui_print "- Patching ramdisk"

# Compress to save precious ramdisk space
SKIP32="#"
SKIP64="#"
# 如果 $BOOTMODE 是真（非零值或非空字符串），并且变量 $PREINITDEVICE 的值为空，则通过运行 ./magisk64 --preinit-device 命令来获取并设置 $PREINITDEVICE 的值。
# 接着，使用 magiskboot 命令和 xz 压缩算法来压缩 magisk64 文件，将其压缩为 magisk64.xz。
# unset SKIP64 清除 SKIP64 变量
if [ -f magisk64 ]; then
  $BOOTMODE && [ -z "$PREINITDEVICE" ] && PREINITDEVICE=$(./magisk64 --preinit-device)
  ./magiskboot compress=xz magisk64 magisk64.xz
  unset SKIP64
fi
if [ -f magisk32 ]; then
  $BOOTMODE && [ -z "$PREINITDEVICE" ] && PREINITDEVICE=$(./magisk32 --preinit-device)
  ./magiskboot compress=xz magisk32 magisk32.xz
  unset SKIP32
fi
./magiskboot compress=xz stub.apk stub.xz

echo "KEEPVERITY=$KEEPVERITY" > config
echo "KEEPFORCEENCRYPT=$KEEPFORCEENCRYPT" >> config
echo "PATCHVBMETAFLAG=$PATCHVBMETAFLAG" >> config
echo "RECOVERYMODE=$RECOVERYMODE" >> config
if [ -n "$PREINITDEVICE" ]; then
  ui_print "- Pre-init storage partition device ID: $PREINITDEVICE"
  echo "PREINITDEVICE=$PREINITDEVICE" >> config
fi
[ -n "$SHA1" ] && echo "SHA1=$SHA1" >> config
RANDOMSEED=$(tr -dc 'a-f0-9' < /dev/urandom | head -c 16)
echo "RANDOMSEED=0x$RANDOMSEED" >> config

# magiskboot 工具来修改 CPIO 格式的文件 ramdisk.cpio，目的是为了在 Android 设备上安装或更新 Magisk
# 在修改前，原始的 ramdisk.cpio 文件会被备份为 ramdisk.cpio.orig

./magiskboot cpio ramdisk.cpio \
"add 0750 $INIT magiskinit" \
"mkdir 0750 overlay.d" \
"mkdir 0750 overlay.d/sbin" \
"$SKIP32 add 0644 overlay.d/sbin/magisk32.xz magisk32.xz" \
"$SKIP64 add 0644 overlay.d/sbin/magisk64.xz magisk64.xz" \
"add 0644 overlay.d/sbin/stub.xz stub.xz" \
"patch" \
"backup ramdisk.cpio.orig" \
"mkdir 000 .backup" \
"add 000 .backup/.magisk config" \
|| abort "! Unable to patch ramdisk"

rm -f ramdisk.cpio.orig config magisk*.xz stub.xz

#################
# Binary Patches
# 主要目的是确保设备树二进制文件与 Magisk 兼容，如果发现文件被旧版本的 Magisk 或其他方式不正确地修改过，
# 脚本会阻止进一步的操作并提示用户。如果文件可以被安全地更新，脚本将尝试打上必要的补丁，特别是对 fstab 文件的更新，以确保 Magisk 能够正确识别和管理存储分区。
#################
# 主要负责检查和更新设备树二进制文件（Device Tree Blob，简称 DTB 或 DTS）
# 遍历三个文件名：dtb、kernel_dtb 和 extra。这三个名字通常指向不同的设备树二进制文件或与之相关的数据，可能包括主设备树、内核特定的设备树覆盖，以及额外的配置或覆盖文件。
# 使用 magiskboot 工具的 dtb 子命令和 test 功能对每个 DTB 文件进行测试。如果测试失败（即文件已经被旧版本的 Magisk 不支持的方式修改过），则通过 ui_print 函数向用户界面打印警告信息
# 每个存在的且尚未被不兼容方式修改的 DTB 文件，尝试使用 magiskboot 的 patch 功能进行更新


for dt in dtb kernel_dtb extra; do
  if [ -f $dt ]; then
    if ! ./magiskboot dtb $dt test; then
      ui_print "! Boot image $dt was patched by old (unsupported) Magisk"
      abort "! Please try again with *unpatched* boot image"
    fi
    if ./magiskboot dtb $dt patch; then
      ui_print "- Patch fstab in boot image $dt"
    fi
  fi
done

# 这段代码主要针对 Android 设备的内核文件 (kernel) 进行特定的修改，以便让设备能够更好地与 Magisk 或其他系统级修改兼容。

if [ -f kernel ]; then
  PATCHEDKERNEL=false
  # Remove Samsung RKP
  # 使用 magiskboot 的 hexpatch 功能来修改内核的二进制代码，以移除三星设备中的 Real Key Protection 特性。如果修改成功，则将 PATCHEDKERNEL 标志设置为 true。
  ./magiskboot hexpatch kernel \
  49010054011440B93FA00F71E9000054010840B93FA00F7189000054001840B91FA00F7188010054 \
  A1020054011440B93FA00F7140020054010840B93FA00F71E0010054001840B91FA00F7181010054 \
  && PATCHEDKERNEL=true

  # Remove Samsung defex
  # Before: [mov w2, #-221]   (-__NR_execve)
  # After:  [mov w2, #-32768]
  ./magiskboot hexpatch kernel 821B8012 E2FF8F12 && PATCHEDKERNEL=true

  # Force kernel to load rootfs for legacy SAR devices
  # skip_initramfs -> want_initramfs
  $SYSTEM_ROOT && ./magiskboot hexpatch kernel \
  736B69705F696E697472616D667300 \
  77616E745F696E697472616D667300 \
  && PATCHEDKERNEL=true

  # If the kernel doesn't need to be patched at all,
  # keep raw kernel to avoid bootloops on some weird devices
  $PATCHEDKERNEL || rm -f kernel
fi

#################
# Repack & Flash
#################

ui_print "- Repacking boot image"
./magiskboot repack "$BOOTIMAGE" || abort "! Unable to repack boot image"

# Sign chromeos boot
$CHROMEOS && sign_chromeos

# Restore the original boot partition path
[ -e "$BOOTNAND" ] && BOOTIMAGE="$BOOTNAND"

# Reset any error code
true