magisk-boot_patch.sh注解

#!/system/bin/sh
#######################################################################################
# Magisk Boot Image Patcher
# 這段腳本是 Magisk Boot Image Patcher 的一部分，它的主要功能是修改 Android 設(shè)備的啟動(dòng)鏡像（boot image）姻成，
# 以支持 Magisk root 權(quán)限管理工具的運(yùn)行。Magisk 是一款流行的 Android root 權(quán)限解決方案痘绎，
# 它允許用戶在不修改系統(tǒng)分區(qū)的情況下獲得 root 訪問權(quán)限，從而避免破壞廠商的保修或許可證協(xié)議
# 萍鲸。以下是腳本的主要部分及其功能的詳細(xì)解析：------------------
#
#初始化和參數(shù)讀取
#腳本開始時(shí)會(huì)檢查一些環(huán)境變量匠襟，如 KEEPVERITY, KEEPFORCEENCRYPT, PATCHVBMETAFLAG, RECOVERYMODE, SYSTEM_ROOT，這些變量控制了腳本的行為疤坝。例如，KEEPVERITY 控制是否保留完整性驗(yàn)證馆铁。
#
#處理輸入的 Boot Image
#首先跑揉，腳本檢查輸入的啟動(dòng)鏡像文件是否存在。
#如果輸入的是一個(gè)設(shè)備節(jié)點(diǎn)（如 MTD 或 NAND 分區(qū)）埠巨，腳本會(huì)使用 nanddump 工具將其轉(zhuǎn)儲(chǔ)為 boot.img 文件历谍。
#接下來(lái)，腳本會(huì)使用 magiskboot 工具解包 boot.img 文件辣垒。
#檢查和還原 Ramdisk 狀態(tài)
#腳本會(huì)檢查 ramdisk 的狀態(tài)望侈，判斷其是否已經(jīng)被 Magisk 或其他工具修改過。
#根據(jù) ramdisk 的狀態(tài)勋桶，它會(huì)進(jìn)行相應(yīng)的還原操作脱衙，例如恢復(fù)到原始狀態(tài)或保存當(dāng)前的 Magisk 狀態(tài)侥猬。
#修改 Ramdisk
#腳本壓縮一些關(guān)鍵的二進(jìn)制文件（如 magisk64, magisk32, stub.apk），以節(jié)省 ramdisk 空間捐韩。
#它會(huì)在 ramdisk 中添加一些必要的文件退唠，如 magiskinit，并創(chuàng)建適當(dāng)?shù)哪夸浗Y(jié)構(gòu)荤胁。
#更新配置文件铜邮，包含各種環(huán)境變量和隨機(jī)種子，這些數(shù)據(jù)會(huì)在設(shè)備啟動(dòng)時(shí)被 magiskinit 使用寨蹋。
#處理 DTB 和 Kernel
#腳本會(huì)檢查和處理設(shè)備樹二進(jìn)制文件（DTB）和內(nèi)核文件，例如移除特定的安全特性（如 Samsung RKP）扔茅，以及對(duì)內(nèi)核進(jìn)行必要的 hexpatch 修改已旧。
#重新打包和簽名
#最后，腳本使用 magiskboot 工具重新打包修改后的 ramdisk 和其他組件召娜，生成新的 boot.img 文件运褪。
#如果檢測(cè)到輸入的是 Chrome OS 的 boot 分區(qū)，腳本會(huì)對(duì)其進(jìn)行簽名玖瘸。
#腳本還包含了錯(cuò)誤處理和日志打印功能秸讹，確保在出現(xiàn)問題時(shí)能夠給出清晰的反饋。此外雅倒，它還提供了對(duì)不同設(shè)備和 Android 版本的兼容性處理璃诀，例如針對(duì) Sony 設(shè)備的特別處理和對(duì) Android 13 的支持。
#
#總之蔑匣，這段腳本是 Magisk 安裝過程中的核心部分劣欢，負(fù)責(zé)在不修改系統(tǒng)分區(qū)的前提下，使設(shè)備能夠在啟動(dòng)時(shí)加載 Magisk 相關(guān)的模塊和服務(wù)裁良，從而實(shí)現(xiàn) root 權(quán)限的管理凿将。
#######################################################################################
#
# 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 操作之后，根據(jù)返回的狀態(tài)碼（即 $?）來(lái)判斷 unpack 操作的結(jié)果价脾，并據(jù)此采取不同的行動(dòng)牧抵。
# 在 shell 腳本中，$? 變量存儲(chǔ)的是上一個(gè)命令的退出狀態(tài)碼侨把，通常用于條件判斷和錯(cuò)誤處理犀变。
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 項(xiàng)目的一部分，Magisk 是一個(gè)流行的 Android 設(shè)備上的 root 權(quán)限管理解決方案座硕。
# magiskboot 是一個(gè) shell 腳本或可執(zhí)行程序弛作，用于處理 Android 設(shè)備的 boot.img 文件和其他與設(shè)備啟動(dòng)相關(guān)的操作，如提取华匾、修改映琳、重新打包 boot 分區(qū)等机隙。
# 使用 magiskboot 工具將 ramdisk.cpio 文件解壓到 test 目錄中，這樣就可以訪問和修改 ramdisk.cpio 中的文件萨西，這對(duì)于調(diào)試有鹿、定制或修復(fù) Android 設(shè)備的啟動(dòng)過程非常有幫助。
# 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
# 判斷以決定使用哪個(gè)初始化程序（init）谎脯。在 Unix/Linux 系統(tǒng)中葱跋，init 通常是系統(tǒng)啟動(dòng)的第一個(gè)進(jìn)程，負(fù)責(zé)管理和控制其他進(jìn)程的生命周期源梭。
# 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 的值為空，則通過運(yùn)行 ./magisk64 --preinit-device 命令來(lái)獲取并設(shè)置 $PREINITDEVICE 的值废麻。
# 接著荠卷，使用 magiskboot 命令和 xz 壓縮算法來(lái)壓縮 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 工具來(lái)修改 CPIO 格式的文件 ramdisk.cpio油宜，目的是為了在 Android 設(shè)備上安裝或更新 Magisk
# 在修改前，原始的 ramdisk.cpio 文件會(huì)被備份為 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
# 主要目的是確保設(shè)備樹二進(jìn)制文件與 Magisk 兼容怜姿，如果發(fā)現(xiàn)文件被舊版本的 Magisk 或其他方式不正確地修改過慎冤，
# 腳本會(huì)阻止進(jìn)一步的操作并提示用戶。如果文件可以被安全地更新沧卢，腳本將嘗試打上必要的補(bǔ)丁蚁堤，特別是對(duì) fstab 文件的更新，以確保 Magisk 能夠正確識(shí)別和管理存儲(chǔ)分區(qū)但狭。
#################
# 主要負(fù)責(zé)檢查和更新設(shè)備樹二進(jìn)制文件（Device Tree Blob违寿，簡(jiǎn)稱 DTB 或 DTS）
# 遍歷三個(gè)文件名：dtb、kernel_dtb 和 extra熟空。這三個(gè)名字通常指向不同的設(shè)備樹二進(jìn)制文件或與之相關(guān)的數(shù)據(jù)藤巢，可能包括主設(shè)備樹、內(nèi)核特定的設(shè)備樹覆蓋息罗，以及額外的配置或覆蓋文件掂咒。
# 使用 magiskboot 工具的 dtb 子命令和 test 功能對(duì)每個(gè) DTB 文件進(jìn)行測(cè)試。如果測(cè)試失斅鹾怼（即文件已經(jīng)被舊版本的 Magisk 不支持的方式修改過）绍刮，則通過 ui_print 函數(shù)向用戶界面打印警告信息
# 每個(gè)存在的且尚未被不兼容方式修改的 DTB 文件，嘗試使用 magiskboot 的 patch 功能進(jìn)行更新


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

# 這段代碼主要針對(duì) Android 設(shè)備的內(nèi)核文件 (kernel) 進(jìn)行特定的修改挨摸，以便讓設(shè)備能夠更好地與 Magisk 或其他系統(tǒng)級(jí)修改兼容孩革。

if [ -f kernel ]; then
  PATCHEDKERNEL=false
  # Remove Samsung RKP
  # 使用 magiskboot 的 hexpatch 功能來(lái)修改內(nèi)核的二進(jìn)制代碼，以移除三星設(shè)備中的 Real Key Protection 特性得运。如果修改成功膝蜈，則將 PATCHEDKERNEL 標(biāo)志設(shè)置為 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