Android 系统定制

1. 概述

1.1 功能简介

本文按 SMDT RK3588 3588A V3.1 板的实际产线定制记录编写，配套 ch01-android-sdk-build.md（怎么编）与 ch02-android-build-system-incremental-build.md（怎么增量）。

双 SDK（A16 为 Android 16 的 AOSP framework 树，A14 为 Android 14 的 vendor/内核树）架构下，定制点分布在两棵树：

  • 板级定制（dts、外设驱动、kernel 配置/补丁、模块装载）：唯一源在 A16 板卡资产目录，deploy_board.sh 部署到 A14 内核树，随 vendor 阶段编译；
  • system 侧定制（framework 行为、locale/属性、预置应用、VINTF 矩阵）：直接改 A16 AOSP 树，随 ssi 阶段编译；
  • vendor 侧定制（rk3588_u 产品开关、fstab、装载清单）：改 A14 树。

GRF 双树必须遵守的规则：framework 侧（进 SYSTEM 分区）的所有改动必须落在 A16 树。A14 树里通过 PRODUCT_PACKAGES 装进 SYSTEM 分区的内容，合并（merge）阶段会被直接丢弃且没有任何报错；framework 兼容矩阵也只认 A16 侧的副本。

1.2 应用场景

  • 板级适配（dts、SMDT 私有驱动、USB/显示/NPU 外设）
  • 系统默认行为定制（永不息屏、锁屏、DOZE）
  • 开机 locale/时区/系统属性
  • 预置应用与 AI 三件套打包
  • VINTF 兼容矩阵放行新 HAL
  • 通用项（分区表、fstab、logo、开机动画）速查

1.3 工作原理

定制改动分布（唯一源 → 编译路径）：

板级 dts/驱动/kernel 补丁 ──► A16 board 资产目录 ──deploy_board.sh──► A14 kernel-6.1
                                                                    └► bash build_ssi16.sh all vendor
framework 行为/locale/预装/VINTF ──► A16 AOSP 树 ──────────────────► bash build_ssi16.sh all ssi
rk3588_u 产品开关/fstab/装载清单 ──► A14 device 树 ────────────────► bash build_ssi16.sh all vendor

权威改动清单：README_SMDT_MODIFICATIONS.md（A16 顶层，由 git index 快照比对写成，附带"已还原、无净变化"的清单，避免误判）。本文提炼的是方法论，逐文件明细以该 README 为准。

2. 硬件准备

组件型号/规格数量备注
编译主机x86_64 Linux（Ubuntu 22.04）1定制编译
目标板SMDT RK3588 3588A V3.1（rk3588_smdt_3588a_v31）1烧录验证

3. 软件准备

  • 双 SDK 树就位且至少一次全量编译通过（bash build_ssi16.sh all，见 ch01 §4.2）
  • 熟悉 ch02 §4.2 的增量出包路径表（本文所有编译命令都引自该表）
  • 改动前先读 README_SMDT_MODIFICATIONS.md，确认要改的文件是否已有 SMDT 定制（带 // smdt: / smdt 注释的就是）

4. 操作步骤

4.1 定制点总览（核心表）

定制类型修改位置（唯一源）部署/编译状态
板级 dtsA16 device/rockchip/rockchip_generic/board/rk3588_smdt_3588a_v31/rk3588_smdt_3588a_v31.dtsbash build_ssi16.sh all vendor（含 deploy）已验证
SMDT 外设驱动（8 个 .ko）同目录 drivers_smdt/同上已验证
kernel 模块开关A14 kernel-6.1/arch/arm64/configs/rockchip_gki.configall vendor已验证
4G modem/USB 串口/日志缓冲资产 patches/smdt_kernel_compat.patch（deploy 幂等重放）all vendor已验证
kernel 深层补丁直改 A14 kernel 树（清单见 4.3，需同步资产）all vendor已验证
模块自动装载清单A14 mkcombinedroot/res/*.loadall vendor（注意坑 6.3）已验证
framework 行为（息屏等）A16 frameworks/base/ 三件套（见 4.5）all ssi + 删 intermediates（ch02 §4.3）已验证端到端
locale/时区/系统属性A16 device/.../ssi_16_arm64/ssi_16_arm64.mkall ssi已验证
预置应用A16 device/.../ssi_16_arm64/device.mkall ssi已验证
VINTF 兼容矩阵A16 manifests/ + configs/vintf.mkall ssi（merge 阶段校验）已验证
分区表/DTBO/fstab/logo/动画A14 侧（见 4.9 速查）all vendor参考说明

4.2 板级定制：板卡资产与 dts

4.2.1 dts 功能块布局

板级设备树（dts，向内核描述硬件的配置文件）是一份独立完整的 dts，不在参考板上叠加 overlay，内容按功能块划分：

功能块内容解决的问题
chosen bootargsfw_devlink=permissive（display 依赖环）、pm_domains.always_on=1（genpd 下电崩溃）display 链打通 + 根治 external abort
为稳定启动禁用的块&av1d(+mmu)、&rkvdec_ccu/rkvdec0/1(+mmu)、&rkvenc_ccu/rkvenc0/1(+mmu)、mcu@62、i2c2 rk628permissive 模式下，资源缺失的外设探测会让整机无提示地卡死；板上没有 MCU 和 rk628 芯片，不禁用这两个节点则 I2C 报 -121 卡住
GPU 限频&gpu_opp_table 删全部 24 档 OPP 只留 opp-200000000@675mV，删 read-margin 属性SCMI 固件域一提频或下电就触发 SError；固定 200MHz 常开（配合内核冻结补丁）
显示路由&hdmi0/&route_hdmi0 disabled（rk628 桥死链）；&hdmi1 + default-output（主出）；&dsi1 链 okay（MIPI 屏）；dp/edp/dsi0 disabled；双 backlight屏接 HDMI1，Android 输出统一到 HDMI1
USBnca9555@20 + gpio-hog pin0/7 output-high（USB-A VBUS 常开）；husb311@4e 节点保留（仅注释，防 phandle 悬空）；&usbdrd_dwc3_0 peripheral + USB2-only（adb 口）；&usbdrd_dwc3_1 host 双 PHY super-speed（USB-A 口）VBUS 在扩展芯片不在 SoC GPIO；无 PD 芯片做不了 role-switch
RK1828 NPU&pcie2x1l2 okay + vcc3v3_pciem1 fixed regulator（GPIO4_B5）；&sata0 disabled（combphy0 让路）；&pcie3x4/&pcie30phy disabled（空槽）1828 实际接在 pcie2x1l2；SATA 先初始化会占住 combphy0，PCIe 就枚举不出来
WiFi&sdio 覆盖段已整体移除（2026-10 revert，走 evb 默认使能，commit 686bc0ed090）曾因 defer 循环冻机禁用；完整可用性以板上实测为准
/smdtio 板厂节点15 pin 表（红/蓝 LED、usb power、4G 电源、io1-4 等）+ gpio_names 三元组smdt_io.ko probe 后接管方向/电平，开机切红灯灭绿灯亮
其余外设es8389 音频（hp 检测走 ADC）、uart1/4/6/7/8、红外 pwm3 键表、&gt1x 触摸、风扇 pwm12、RS485 xrm117x、imx415 摄像头链（无 sensor 留链路）自旧 14 smdt 分支移植

4.2.2 修改流程

# 1. 改 A16 资产目录里的 dts
vim device/rockchip/rockchip_generic/board/rk3588_smdt_3588a_v31/rk3588_smdt_3588a_v31.dts

# 2. 快速验证（只编 dtb + 复核 MCU/rk628 disable 标记）
bash build_ssi16.sh dts

# 3. 出包（deploy 自动把资产推到 A14，随后 vendor→merge→update）
bash build_ssi16.sh all vendor

4.2.3 新增板卡适配（本产线的"新增产品"方式）

不新增 lunch 目标，而是新增板卡资产：

  1. 拷贝 board/rk3588_smdt_3588a_v31/ 为新目录，改 dts；
  2. 同步修改 deploy_board.sh 内的 KERNEL_DTS_NAME（当前硬编码为 rk3588_smdt_3588a_v31）；
  3. bash deploy_board.sh && KERNEL_DTS=<新名> bash build_ssi16.sh all（setup 阶段会写入 config.json 并校验）。

资产必须同步：任何直接改在 A14 内核树上的文件（包括 dts），都必须同步回 A16 资产目录。deploy_board.sh 每一轮部署都会用资产版覆盖内核树，资产目录里还是旧文件，改动就会消失。每轮构建后用 git diff HEAD --stat 复核关键文件。

4.3 kernel 配置与内核树补丁

类别文件内容施加方式
模块开关A14 arch/arm64/configs/rockchip_gki.configCONFIG_MOTORCOMM_PHY=m、USB_SERIAL 全家（CH341/CP210X/FTDI/PL2303/WWAN/OPTION）、USB_NET_CDC_NCM=m、CONFIG_PCIE_DW_DMATEST=y 等部分 compat patch 重放、部分直改
4G modemdrivers/usb/serial/{option,usb_wwan,ch341}.c、drivers/net/usb/{cdc_ncm,qmi_wwan}.cQuectel RM500U VID/PID、ZLP、GKI 符号白名单适配compat patch（deploy 幂等重放）
日志缓冲arch/arm64/boot/dts/rockchip/rk3588-android.dtsilog_buf_len=4Mcompat patch
PHY 驱动drivers/net/phy/motorcomm.c裕太 YT8531 vendor 版整体替换资产整体替换
音频sound/soc/rockchip/rockchip_multicodecs.chp 检测改 if (0)（本板走 ADC）deploy sed
直改内核树drivers/soc/rockchip/pm_domains.c2 处硬编码 panic() 降级 dev_err（permissive 下 genpd 抢跑会造成 0.6 秒一次的重启循环）deploy 不覆盖
直改内核树drivers/gpu/arm/valhall/platform/rk/mali_kbase_config_rk.cGPU 冻结 4 处（跳过 SCMI set_rate、不下电、双保险短路）deploy 不覆盖
诊断打印drivers/phy/rockchip/phy-rockchip-inno-usb2.c9 处 probe 插桩（无行为改动）deploy 不覆盖

重建 A14 树必须重打的清单：上表三个"直改内核树"文件 + 内核树 dts 的追加段（或先做资产回拷）。完整清单与原因见 README_SMDT_MODIFICATIONS.md 第五节。

4.4 内核模块自动装载（modules.load 三通道）

通道文件（A14）装载时机当前内容
vendor_dlkm（second_stage）mkcombinedroot/res/vendor_modules.loadvendor_dlkm 挂载后 insmod7×smdt（按依赖序）+ pcie-rkep.ko
vendor_boot（first_stage）mkcombinedroot/res/vendor_ramdisk_modules.load早期 ramdiskpcie-rkep.ko；PHY 顺序 inno-usb2 在 usbdp 前（反了 usbdp 永久 defer）
内核构建兜底kernel/prebuilts/6.1/arm64/modules.loadRockchip 内核流程同 first 通道

简单说，first_stage 指设备启动最早阶段从 vendor_boot 的内存盘（ramdisk）装载模块，second_stage 指系统起来后从 vendor_dlkm 分区装载模块。

4.5 framework 行为定制：永不息屏三件套

开机一段时间后自动息屏的问题，完整修复分布在 A16 的三个文件里（原因不止 DOZE 一处，也不要改 framework-res 之外的地方）：

文件（A16 frameworks/base/）改动
packages/SettingsProvider/res/values/defaults.xmldef_screen_off_timeout 60000 → 0x7fffffff；def_lockscreen_disabled false → true
core/res/res/values/config.xmldreams 五键全 false；config_dozeAlwaysOnEnabled false；config_maximumScreenDimDuration 0
services/core/java/.../power/PowerManagerService.java4 处短路（带 // smdt: 注释）：mSleepTimeoutSetting=-1、mAttentiveTimeoutSetting=-1（开机 12 秒后进入 DOZE 的另一个独立原因）、override 强制 -1、setDozeAfterScreenOff 强制 false

编译注意：PowerManagerService.java 属于 services.core，直接增量编译不会生效，必须先删对应 intermediates 再编（ch02 §4.3），出包走 bash build_ssi16.sh all ssi。验证用三层 md5 比对：源文件、编出的 SettingsProvider.apk、super.img 内的副本三者一致才算真正打进去（ch02 §4.7）。

4.6 locale 与系统属性

device/rockchip/rockchip_generic/ssi_16_arm64/ssi_16_arm64.mk（实测存在，位于 L27-29）：

PRODUCT_LOCALES := zh_CN $(filter-out zh_CN,$(PRODUCT_LOCALES))
PRODUCT_SYSTEM_PROPERTIES += persist.sys.locale=zh-CN
PRODUCT_SYSTEM_PROPERTIES += persist.sys.timezone=Asia/Shanghai

开机默认中文 + Asia/Shanghai 时区。其他 ro.product.* 属性同文件追加即可，编译走 all ssi。

4.7 预置应用

GRF 模式下预装到 SYSTEM 分区的应用必须在 A16 打包：

  1. A16 device/.../ssi_16_arm64/device.mk：BOARD_RK1820_SUPPORT=true + PRODUCT_PACKAGES += AI 三件套；
  2. APK 本体同步到 A16 vendor/rockchip/common/apps/RkAi{Service,Launcher,Asst}/（从 A14 取 rk182x 变体）；
  3. vendor/rockchip/common/apps/RkAiService/Android.mk 的 $(TARGET_BOARD_PLATFORM) 在 SSI 产品为空 → 硬编码 rk3588；
  4. A14 device/rockchip/rk3588/rk3588_u/rk3588_u.mk 同步 BOARD_RK1820_SUPPORT := true（开 rknn-smi 全家桶，须在 inherit common/device.mk 之前）。

编译 all ssi（vendor 侧开关变了则 all vendor）。验收：板上 rknn-smi info 显示 RK1828 Online。

4.8 VINTF 兼容矩阵定制

VINTF 是 Android 的接口兼容性清单机制：设备端 manifest 声明的每个 HAL 服务，都必须在 framework 兼容矩阵里有对应条目，否则合并阶段报 Incompatible VINTF。GRF 双树下这个矩阵在 A16 侧：

  • device/rockchip/rockchip_generic/manifests/frameworks_compatibility_matrix.xml：追加 rockchip.hardware.outputmanager 的 AIDL 条目（新 14 GRF 把它从 HIDL 迁到 AIDL，不放行则 merge 阶段 Incompatible VINTF）；
  • RK1828：configs/vintf.mk + ssi_16_arm64/vintf/*.xml 加 rknnsmi/rknnmodeltest 两条 optional AIDL 条目。

4.9 通用定制项速查（本产线未使用，路径已核实）

项实际路径编译路径
分区表 parameter.txtA14 device/rockchip/common/scripts/parameter_tools/parameter.in（PRODUCT_PARAMETER_TEMPLATE）all vendor
DTBO overlayA14 device/rockchip/rk3588/rk3588_u/dt-overlay.inall vendor；本产线板级差异直接用独立 dts，不用 overlay
fstabA14 device/rockchip/common/scripts/fstab_tools/fstab.inall vendor
uboot/kernel logoA14 kernel-6.1/logo.bmp、logo_kernel.bmp（BMP，≤8MB）all vendor
开机动画A14 device/rockchip/common/bootanimation.zip（默认）；A16 侧可 PRODUCT_COPY_FILES 覆盖到 system/media/bootanimation.zip覆盖走 all ssi
BoardConfig 特性开关A14 device/rockchip/rk3588/rk3588_u/BoardConfig.mk（BOARD_HDMI_IN_SUPPORT、BOARD_HAS_RK_4G_MODEM、BOARD_HS_ETHERNET 等；本产线实际用过的是双端 BOARD_RK1820_SUPPORT）all vendor
新增 lunch 目标（单 SDK 通用法）A14 device/rockchip/rk3588/ 拷产品目录 + 注册 AndroidProducts.mk需同步 rkbuild/config.json，本产线未使用

4.10 USB udev 规则（编译主机侧）

# /etc/udev/rules.d/99-rockchip.rules —— RK 设备免 root 烧录调试
ACTION=="add", ATTR{idVendor}=="2207", MODE="0666"

sudo udevadm control --reload-rules && sudo udevadm trigger

5. 代码详解

5.1 双树定制点分布（摘要）

  • A16（system 侧）：frameworks/base 3 文件（息屏三件套）、rockchip_generic 若干（vendorsetup 容错、FCM AIDL、locale、device.mk 预装、vintf）、板卡资产目录（dts + 8 驱动 + slog.h + motorcomm.c + compat patch）、顶层三脚本、RockitMetadataRetriever.h 符号链接。
  • A14（vendor 侧）：kernel-6.1 改 14 文件（gki.config/dtsi/Makefile/motorcomm/pm_domains/GPU/multicodecs/inno-usb2/4G 五件）+ 新增 dts 与 drivers/smdt/、mkcombinedroot 三个 .load + copy_moduls.sh、rk3588_u.mk/device.mk 开关、vendorsetup.sh 补拷 resource.img。

5.2 板卡资产目录结构

device/rockchip/rockchip_generic/board/rk3588_smdt_3588a_v31/
├── rk3588_smdt_3588a_v31.dts      # 板卡设备树（改动后必须与内核树版一致）
├── drivers_smdt/                  # 8 驱动 + Makefile（nca9555/param/info/io/serial/mouse/mcu/sys_serial_shim）
├── drivers_yt6801/                # 裕太 PCIe 网卡驱动（备查）
├── include_smdt/slog.h            # smdt 驱动头文件依赖（缺它编译必挂）
├── motorcomm.c                    # 裕太 PHY 驱动整体替换版
├── patches/smdt_kernel_compat.patch  # 7 文件小改（幂等重放）
└── wifi.load                      # 仅参考（构建自动重写，不部署）

5.3 deploy_board.sh 部署映射

资产部署目标
dtsA14 kernel-6.1/arch/arm64/boot/dts/rockchip/
drivers_smdt + MakefileA14 kernel-6.1/drivers/smdt/ + drivers/Makefile（obj-m）
slog.hA14 kernel-6.1/include/smdt/
motorcomm.cA14 PHY 驱动替换
compat patchA14 kernel 7 文件（幂等重放）
multicodecs 适配A14 rockchip_multicodecs.c sed
vendorsetup 容错 / FCMA16 侧（脚本一并施加）

6. 常见问题

6.1 直接改在 A14 树上的补丁，下一轮构建后消失了

原因： deploy_board.sh 每轮用 A16 资产版覆盖内核树文件，资产没同步 = 改动被冲掉。

解决： 直改树上的文件必须同步回 A16 资产目录；每轮构建后 git diff HEAD --stat 复核。已经发生的差异，以内核树上的版本为准回拷到资产目录。

6.2 modules.load 加了注释，ckati failed @ Makefile:583

原因： .load 清单内容会经 $(shell cat) 直接拼进 Make 的 target pattern，注释和空行会污染这个变量；ninja 缓存还会让错误潜伏下来，拖到下次某个文件变动时才报出来。

解决： 清单一律禁注释禁空行；排查时看 "was changed, regenerating" 前哪个文件变了。

6.3 改了驱动 .ko，烧进去还是旧版

原因： ninja 不跟踪 mkcombinedroot/vendor_ramdisk/lib/modules/*.ko 的 mtime，手工 strip-debug 进模块池后不会自动重拷到 out/.../vendor_dlkm/lib/modules/。

解决： rm $A14/out/target/product/rk3588_u/vendor_dlkm/lib/modules/smdt_*.ko + touch mkcombinedroot/res/vendor_modules.load + rkbuild_build vendor（或 bash build_ssi16.sh vendor）。验证用 modinfo 看 depends。

6.4 在 A14 加了 PRODUCT_PACKAGES，烧进系统后应用不存在

原因： GRF merge 丢弃 A14 的 SYSTEM 分区——A14 侧装到 system 的包全部静默消失。

解决： 预装到 SYSTEM 的一切移到 A16 ssi_16_arm64/device.mk。

6.5 merge 阶段 Incompatible VINTF

原因： device manifest 声明的 HAL 在 framework 矩阵无条目；或新 GRF 把 HAL 从 HIDL 迁到 AIDL 而 A16 矩阵只放行 HIDL。

解决： 矩阵在 A16 rockchip_generic/manifests/（或 vintf.mk 指定文件）加条目，注意 <hal format="aidl">。

6.6 dts 改了，烧录后行为没变

可能的原因： ① 资产与内核树两份 dts 不同步（deploy 部署了旧版）；② GRF 模式 mkimage 曾跳过 resource.img 拷贝，旧 dtb 被反复打包（已在 vendorsetup.sh 补拷修复）。

解决： 确认只改资产版；验证 dtb 用 dtc -I dtb -O dts 反编译看节点（strings | grep disabled 分不出新旧）；出包走 all vendor 而非手工 mkupdate。

6.7 framework 改动打镜像后无效

原因： 增量链路断层（m <module> 不重打 system.img、m systemimage 不触发 services.core 重编）。

解决： 见 ch02 §4.3/§5.3——删 intermediates + all ssi，三层 md5 验收。

6.8 dts 删节点后 dtb 编译报 phandle_references 错误

原因： 参考板 dtsi 里的端点树引用了被删/被禁的节点（如 husb311），板级同名节点只是属性覆盖，删不干净。

解决： 跨层节点用 /delete-node/ 组合删（&i2c6 { /delete-node/ husb311@4e; } + 删引用方的 port 端点树）；板上没芯片但拓扑被引用时保留节点 + 注释说明。改后 bash build_ssi16.sh dts 先验。

7. 相关文档

文档说明
README_SMDT_MODIFICATIONS.md（A16 顶层）净改动清单（逐文件，含已还原清单）
ch01-android-sdk-build.md双 SDK 联编主流程
ch02-android-build-system-incremental-build.md增量路径、断层点、clean
handoff_2026-09-21.md（A16 顶层）移交笔记（内核补丁演进、验证脚本）
hardware-reference/ch01-core-board-specifications.md核心板参数
m5-1820-a1_v10_20251120pm已更新.pdf板卡原理图（dts vs PCB 对账）