# 小米 2（aries / APQ8064）Alpine Linux armv7 移植文档

> 目标设备：Xiaomi Mi 2 / Mi 2S（代号 `aries`，Qualcomm APQ8064，Snapdragon S4 Pro）
> 基础项目：<https://github.com/jsjllymxbl/initramfs>
> 内核树：<https://github.com/jsjllymxbl/linux>，分支 `apq8064-7.2-xiaomi-aries`（Linux 7.2.0）
> 发行版：Alpine Linux **armv7**（musl + OpenRC）
> 本文只覆盖 Alpine 方案，不涉及 Debian/Ubuntu。

---

## 1. 为什么选 Alpine

| 优势 | 说明 |
|---|---|
| 作者实测 | initramfs 仓库的验证路径就是 Alpine armv7 |
| 体积小 | 基础系统约 100MB，XFCE 桌面约 1–1.5GB |
| 内存友好 | 2GB RAM 下运行 XFCE 压力远小于 GNOME |
| 无 systemd | OpenRC 不需要 `NAMESPACES`/`FHANDLE`/`AUTOFS_FS`/`PSI`/`CGROUP_BPF` 等内核选项 |
| 架构匹配 | armv7 是 Alpine 官方支持的架构，软件源完整 |

约束：Krait 300 是 **ARMv7-A 32 位**，只能使用 **armv7** 构建，不能用 aarch64。

---

## 2. 启动链与 initramfs 行为

```
bootloader -> lk2nd -> boot.img (zImage-dtb + initramfs)
                        -> /init (Rust, musl 静态)
                           -> 挂 /dev/mmcblk0p23 到 /newroot
                           -> 找 /newroot/rootfs 里的 init
                           -> pivot_root + exec
```

`/init` 的关键行为：

1. 挂 `devtmpfs` / `proc` / `sysfs`，打开 `/dev/kmsg`
2. 点亮背光（LM3530 默认熄灭，先写 127）
3. 等 `/dev/mmcblk0p23`（最多 15s），挂到 `/newroot`
4. 在 `/newroot/rootfs` 下按顺序找 init：
   `sbin/init` → `init` → `usr/sbin/init` → `bin/init` → `usr/bin/init`
5. 把 initramfs 的 `/lib/firmware` 拷进目标根，写入 `.aries-firmware-stamp`（FNV-1a 指纹）
6. 预挂 `dev` `dev/pts` `proc` `sys` `tmp` `run`
7. `pivot_root` 切根（失败回退 `MS_MOVE` + `chroot`），`exec /sbin/init`

Alpine 的 `/sbin/init` 是 busybox，正好命中第 4 步，随后由 OpenRC 接管。

### 失败处理

- 日志写到 `<userdata>/initramfs-boot.log`
- 屏幕提示，等待 15 秒后关机
- 没有救援 shell

因此务必先用 `fastboot boot boot.img` 试跑，不要直接刷 boot 分区。

---

## 3. 内核构建

### 3.1 依赖

```bash
sudo apt install build-essential git bc bison flex libssl-dev \
    libncurses-dev crossbuild-essential-armhf cpio lz4 python3
```

### 3.2 配置

```bash
git clone -b apq8064-7.2-xiaomi-aries https://github.com/jsjllymxbl/linux
cd linux

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- qcom_defconfig

# 显示链：编进内核，开机即可看到 console，便于排错
./scripts/config -e DRM -e DRM_MSM -e DRM_FBDEV_EMULATION \
  -e DRM_PANEL_XIAOMI_ARIES_720P -e LEDS_LM3530 \
  -e BACKLIGHT_CLASS_DEVICE -e FRAMEBUFFER_CONSOLE

# 触摸
./scripts/config -e RMI4_CORE -e RMI4_I2C -e TOUCHSCREEN_ATMEL_MXT

# USB 网络（救生通道）
./scripts/config -e USB_ETH -e USB_CONFIGFS -e USB_CONFIGFS_RNDIS

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- olddefconfig
```

> OpenRC 不需要 systemd 相关选项。`CONFIG_IPV6` 在 `qcom_defconfig` 中默认关闭，可选打开。

### 3.3 两个容易漏的符号

| 符号 | 源文件 | 说明 |
|---|---|---|
| `CONFIG_DRM_PANEL_XIAOMI_ARIES_720P` | `drivers/gpu/drm/panel/panel-xiaomi-aries-720p.c` | aries 专用 720p 面板，`qcom_defconfig` 默认不含 |
| `CONFIG_LEDS_LM3530` | `drivers/leds/leds-lm3530.c` | 背光驱动，**不在** `drivers/video/backlight/` |

### 3.4 模块

`qcom_defconfig` 下这些是模块：

```
CONFIG_DRM_MSM=m
CONFIG_WCN36XX=m
CONFIG_CFG80211=m
CONFIG_MAC80211=m
CONFIG_USB_ETH=m
```

`boot.img` 只含 zImage，initramfs 不加载模块，所以**必须把 `lib/modules/<版本>/` 放进 Alpine rootfs**。也可以把显示链编成 `=y`（推荐，便于排错），Wi-Fi 保持模块。

### 3.5 编译

```bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
     zImage dtbs modules -j$(nproc)

make ARCH=arm kernelrelease          # 记下版本号
make ARCH=arm INSTALL_MOD_PATH=/tmp/modules modules_install
```

> 版本串必须和模块目录一致。工作树有未提交改动时可能出现 `-dirty`，注意"编内核"和"装模块"用同一次构建的结果。

### 3.6 打包 boot.img

```bash
cat arch/arm/boot/zImage \
    arch/arm/boot/dts/qcom/qcom-apq8064-xiaomi-aries.dtb > /tmp/initramfs/zImage-dtb

cd /tmp/initramfs
make
make verify
```

地址布局：

- 默认 `BASE=0x88000000`，依赖打过补丁的 lk2nd（多恢复 128 MiB 内存）
- 用官方 lk2nd：改 `BASE=0x90000000` 后重新 `make`

---

## 4. Alpine rootfs 构建（在 PC 上）

已验证可用：`alpine-minirootfs-3.24.4-armv7.tar.gz`（armv7）。

### 4.1 解包与 chroot

```bash
curl -O https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/armv7/alpine-minirootfs-3.24.4-armv7.tar.gz
mkdir -p /tmp/rootfs
tar -xpf alpine-minirootfs-3.24.4-armv7.tar.gz -C /tmp/rootfs

sudo cp /usr/bin/qemu-arm-static /tmp/rootfs/usr/bin/
sudo mount --bind /dev  /tmp/rootfs/dev
sudo mount --bind /proc /tmp/rootfs/proc
sudo mount --bind /sys  /tmp/rootfs/sys
sudo cp /etc/resolv.conf /tmp/rootfs/etc/

sudo chroot /tmp/rootfs /bin/sh
```

### 4.2 基础系统

```sh
apk update
apk add alpine-base openssh wpa_supplicant iw dhcpcd

echo aries > /etc/hostname
passwd root

adduser -D -s /bin/ash aries
passwd aries
```

### 4.3 图形桌面

```sh
setup-xorg-base
setup-desktop xfce
```

等价手动安装：

```sh
apk add xorg-server xfce4 lightdm lightdm-gtk-greeter dbus
```

mesa 相关（用于 freedreno / 软件渲染）：

```sh
apk add mesa mesa-dri-gallium mesa-utils
ls /usr/lib/dri/ | grep -i msm     # 检查是否有 freedreno 驱动
```

### 4.4 服务

```sh
rc-update add sshd default
rc-update add dbus default
rc-update add lightdm default
```

### 4.5 内核模块

```sh
mkdir -p /lib/modules
cp -a /tmp/modules/lib/modules/7.2.0* /lib/modules/
depmod -b / 7.2.0
```

如果 `msm`、`wcn36xx` 是模块，让 OpenRC 开机加载：

```sh
cat >> /etc/modules <<'EOF'
msm
wcn36xx
EOF
```

> Alpine 默认用 busybox `mdev`，模块自动加载不总是可靠；显式写入 `/etc/modules` 最稳。内核模块的 ABI 与 libc 无关，用 glibc 交叉工具链编译的模块在 musl 系统里同样能加载。

### 4.6 网络配置

USB 网络（首选救生通道）：

```sh
cat >> /etc/network/interfaces <<'EOF'
auto usb0
iface usb0 inet static
    address 10.0.0.2
    netmask 255.255.255.0
EOF
```

Wi-Fi：

```sh
wpa_passphrase "SSID" "密码" >> /etc/wpa_supplicant/wpa_supplicant.conf

wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf
udhcpc -i wlan0
iw dev wlan0 link
```

Alpine 自带的是上游 wpa_supplicant（2.11，musl 构建），走标准 nl80211，和内核 `wcn36xx` 匹配。

### 4.7 fstab

```
/dev/mmcblk0p23  /          ext4   defaults,noatime  0 1
proc             /proc      proc   defaults          0 0
sysfs            /sys       sysfs  defaults          0 0
devpts           /dev/pts   devpts defaults          0 0
tmpfs            /tmp       tmpfs  defaults          0 0
```

### 4.8 固件规则

**不要**在 rootfs 里放 `lib/firmware`。initramfs 会在每次启动时把固件拷进 `/lib/firmware` 并按指纹管理；自带固件会破坏这个逻辑。

---

## 5. 部署到设备

Mi 2 没有 microSD，只能走 USB。推荐用 TWRP / OrangeFox，保留 Android 双系统。

```bash
# PC 上打包，保留 uid/gid
sudo tar -C /tmp/rootfs -cpf rootfs.tar --numeric-owner .

# TWRP 中 /data 就是 p23
adb push rootfs.tar /tmp/
adb shell "mkdir -p /data/rootfs && tar -xpf /tmp/rootfs.tar -C /data/rootfs"
```

Android 的 `/data` 与 Alpine 的 `/data/rootfs` 共存。XFCE 方案约占 1–1.5GB。

不要用 `cp`，必须用 `tar --numeric-owner`，否则 OpenRC/登录会因权限错乱失败。

---

## 6. 启动与验证

```bash
fastboot boot boot.img
```

首次启动 init 会把固件拷到 `/data/rootfs/lib/firmware`，然后切根执行 Alpine 的 `/sbin/init`。

失败时日志在 `/data/initramfs-boot.log`（用 TWRP 取出）。

### 验证清单

```sh
uname -r                      # 必须与 /lib/modules 下的目录名一致
ls /dev/dri/card0             # DRM/MSM 是否加载
ls /dev/fb0                   # fbdev 模拟是否可用
modprobe wcn36xx && dmesg | tail
nmcli device wifi list        # 若安装了 NetworkManager
ip addr show usb0             # USB 网络
zramctl                       # zram 是否生效
```

USB 网络连通后：

```bash
# PC 上
sudo ip addr add 10.0.0.1/24 dev usb0
ssh root@10.0.0.2
```

---

## 7. 可选优化

### 7.1 zram（2GB 内存必做）

```sh
apk add zram-init
# 默认按内存比例创建 zram0
rc-update add zram-init default
```

不要创建 swap 分区。

### 7.2 减少启动服务

Xfce 下可关闭不需要的服务，例如 `bluetooth`、`avahi`、`cups` 等，减少内存占用。

### 7.3 时间同步

设备有 PM8XXX RTC，可装 `chrony` 走网络对时；无网络时依赖 RTC。

### 7.4 显示与 3D

- 2D/合成：Xorg modesetting 或 fbdev 均可
- 3D：freedreno a3xx 未验证，若 Mesa 未带 msm 驱动会退回 llvmpipe（可用但慢）
- 不要期待硬件视频解码

---

## 8. 常见问题

| 问题 | 现象 | 处理 |
|---|---|---|
| 模块目录名与 `uname -r` 不一致 | 黑屏、无 Wi-Fi | 用 `make kernelrelease` 的版本号，重新 `depmod` |
| rootfs 不在 `p23/rootfs/` | 启动失败关机 | 必须是 `/data/rootfs` |
| 用 `cp` 部署 | 登录失败、权限错乱 | 用 `tar --numeric-owner` |
| 安装了 `linux-lts` / `linux-firmware` | 版本冲突、固件被覆盖 | 不装，内核和固件都用本项目的 |
| rootfs 自带 `lib/firmware` | 指纹逻辑失效 | 删除，交给 initramfs |
| userdata 加密 | init 挂载失败 | TWRP 中解密或格式化 |
| p23 不是 ext4 | 挂载失败 | `make ROOTFS_FSTYPE=f2fs` 或转换文件系统 |
| lk2nd 未打补丁 | 启动崩溃/内存异常 | 打补丁，或 `BASE=0x90000000` |
| 用原厂 fastboot 刷 boot | 冲掉 lk2nd，可能变砖 | 只在 lk2nd 的 fastboot 里刷 |
| 没有救援 shell | 启动失败只能看日志 | TWRP 取 `/data/initramfs-boot.log` |

---

## 9. 功能支持矩阵

| 功能 | 状态 | 说明 |
|---|---|---|
| 启动 / 切根 | ✅ 已验证 | Alpine 是作者实测路径 |
| 屏幕 / 背光 | ✅ 有专用驱动 | 建议实机确认 |
| 触摸 | ⚠️ RMI4/Atmel 驱动存在 | 未系统验证 |
| Wi-Fi | ⚠️ `wcn36xx` + 固件齐全 | 需实测 |
| USB 网络 | ⚠️ `g_ether` | 建议作为救生通道 |
| 3D 加速 | ⚠️ freedreno a3xx | 未验证，可能退回 llvmpipe |
| 音频 | ❌/⚠️ | WCD9310，主线支持不完整 |
| 蓝牙 | ⚠️ | WCN3660，未验证 |
| 相机 | ❌ | 传感器驱动缺失 |
| 传感器 | ⚠️ | DTS 有 lis3dh/l3gd20/ak8963/bmp180 节点 |
| 调制解调器 / 通话 / 移动数据 | ❌ | 无主线驱动 |
| 电量计 / 充电 | ⚠️ | BQ27520，未验证 |

---

## 10. 最短操作流程

```bash
# 1. 内核
git clone -b apq8064-7.2-xiaomi-aries https://github.com/jsjllymxbl/linux
cd linux
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- qcom_defconfig
./scripts/config -e DRM -e DRM_MSM -e DRM_FBDEV_EMULATION \
  -e DRM_PANEL_XIAOMI_ARIES_720P -e LEDS_LM3530 \
  -e BACKLIGHT_CLASS_DEVICE -e FRAMEBUFFER_CONSOLE \
  -e RMI4_CORE -e RMI4_I2C -e TOUCHSCREEN_ATMEL_MXT \
  -e USB_ETH -e USB_CONFIGFS -e USB_CONFIGFS_RNDIS
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- olddefconfig
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage dtbs modules -j$(nproc)
make ARCH=arm INSTALL_MOD_PATH=/tmp/modules modules_install

# 2. boot.img
cat arch/arm/boot/zImage \
    arch/arm/boot/dts/qcom/qcom-apq8064-xiaomi-aries.dtb > /tmp/initramfs/zImage-dtb
cd /tmp/initramfs && make && make verify

# 3. Alpine rootfs
curl -O https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/armv7/alpine-minirootfs-3.24.4-armv7.tar.gz
mkdir -p /tmp/rootfs && tar -xpf alpine-minirootfs-3.24.4-armv7.tar.gz -C /tmp/rootfs
cp /usr/bin/qemu-arm-static /tmp/rootfs/usr/bin/
# chroot 后：apk add alpine-base openssh wpa_supplicant iw dhcpcd
#          setup-xorg-base && setup-desktop xfce
#          拷模块 + depmod + 配置 fstab/网络/服务

# 4. 部署
tar -C /tmp/rootfs -cpf rootfs.tar --numeric-owner .
adb push rootfs.tar /tmp/
adb shell "mkdir -p /data/rootfs && tar -xpf /tmp/rootfs.tar -C /data/rootfs"

# 5. 试跑
fastboot boot boot.img
```

---

## 11. 参考

- initramfs 仓库：<https://github.com/jsjllymxbl/initramfs>
- 内核 fork：<https://github.com/jsjllymxbl/linux>（分支 `apq8064-7.2-xiaomi-aries`）
- Alpine armv7 下载：<https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/armv7/>
- Alpine 包搜索：<https://pkgs.alpinelinux.org/packages>
- Alpine 安装文档：<https://wiki.alpinelinux.org/wiki/Installation>
- lk2nd：<https://github.com/msm8916-mainline/lk2nd>
- 设备信息（已归档）：<https://wiki.nura.eco/wiki/Xiaomi_Mi_2_(xiaomi-aries)>