device/amlogic/ross/ 设备配置

分析 ross (S905X5M) 设备的完整构建配置,理解一个 Android 嵌入式设备是如何定义的 参考代码库:device/amlogic/ross/,Android 14 + Amlogic S905X5M ATV


1. 总览

device/amlogic/ross/ 是 Android 构建系统中设备配置目录。它定义了:

  • 选择什么 SoC(S905X5M)和平台(s7d)
  • 选择什么 kernel(common14-5.15,GKI 方式)
  • 选择什么 bootloader(U-Boot,支持 AVB2 + VAB)
  • 分区布局 和文件系统类型
  • 硬件特性(显示、音频、编解码、WiFi/BT、摄像头等)
  • 打包哪些模块(继承 vendor/giec/ 的定制)

文件布局

device/amlogic/ross/
├── BoardConfig.mk                  # ★ 板级配置(硬件、分区、AVB)
├── device.mk                       # ★ 设备配置(媒体、音频、GPU、显示)
├── ross.mk                         # ★ 产品配置主入口
├── AndroidProducts.mk              # 注册所有产品变体(lunch 选项)
├── AndroidBoard.mk                 # 板级构建(kernel、factory)
├── Android.mk / Android.bp
│
├── ross_atv.mk                     # ATV 变体
├── ross_dongle.mk                  # 加密狗/电视棒变体
├── ross_soundbar.mk                # 条形音箱变体
├── ross_hybrid.mk                  # Hybrid 变体
├── ross_hybrid_atf.mk              # Hybrid ATF 变体
├── ross_cbs.mk                     # CBS 广播变体
├── ross_mxl258c.mk                 # MXL258C 调谐器变体
│
├── part_table_5_15.txt             # ★ 分区表(AB 系统,动态分区)
├── part_table_U_8G_emmc.txt        # 8G eMMC 备选分区表
├── fstab.ab_oem.amlogic            # ★ 文件系统挂载表
│
├── vendor_prop.mk                  # 供应商属性
├── product_property.mk             # 产品属性(oem key)
├── kernel_config_build.mk          # Kernel 构建配置
├── wifibt.build.config.trunk.mk    # WiFi/BT 模块选择
├── AVSync.mk                       # 音视频同步配置
│
├── init.amlogic.board.rc           # 板级 init 脚本
├── init.amlogic.board.ext.rc       # 板级扩展 init 脚本
├── ueventd.parallel.rc             # ueventd 并行恢复上下文
├── board-info.txt                  # bootloader 版本约束
│
├── files/                          # ★ 硬件配置文件(编解码、音频、显示)
│   ├── media_codecs*.xml           #   媒体编解码配置
│   ├── mixer_paths.xml             #   音频通路配置
│   ├── mesondisplay.cfg            #   显示配置
│   ├── mali_platform.config        #   GPU/Mali 配置
│   ├── audio_effects.conf          #   音效配置
│   └── speaker_*.dat/xml           #   音箱调优数据
├── permissions/                    # 权限配置文件
├── overlay/                        # 资源覆盖
├── oem/                            # OEM 分区预置内容
├── prebuilt/                       # 预编译二进制
├── recovery/                       # Recovery 相关配置
├── logo_img_files/                 # 开机 logo
├── upgrade/                        # 升级相关
└── tools/                          # 签名工具

2. Android 构建系统的设备配置层级

理解 Android 构建系统的层次结构 是嵌入式开发的基础。一个产品配置(ross.mk)通过 $(call inherit-product, ...) 逐层继承,最终形成完整的构建配置。

ross.mk  (产品级 —— 顶层入口,定义 PRODUCT_NAME/DEVICE/BRAND/MODEL)
    │
    ├── product_mbox.mk  (Amlogic 通用产品配置,包含 TV HAL 等)
    │       └── core_amlogic.mk  (Amlogic 核心配置)
    │
    ├── s7d.mk  (芯片平台级 —— s7d/S905X5 平台通用配置)
    │
    ├── device.mk  (板级 —— 本设备特有配置)
    │       └── device/amlogic/common/products/mbox/s7d/device.mk
    │               (s7d 平台默认板级配置,包含 keylayout、init.rc、媒体配置)
    │
    ├── vendor_prop.mk  (供应商属性)
    ├── product_property.mk  (产品属性)
    │
    ├── vendor/amlogic/ross/device-vendor.mk  (如果存在,OEM 额外配置)
    │
    └── device/giec/device-giec.mk  (通过 device.mk 中的 inherit)

实践意义:当需要在某款设备上添加功能时,搞清楚改哪个层级的文件:

  • 改整个 SoC 平台 → s7d.mk
  • 改本设备特有 → device.mkross.mk
  • 改厂商定制 → vendor/giec/device-giec.mk

3. BoardConfig.mk —— 板级硬件定义

BoardConfig.mk 定义的是板级硬件参数:CPU 架构、分区大小、文件系统类型、AVB 配置等。

3.1 SoC 与 CPU 架构

PRODUCT_DIR := ross
TARGET_BOARD_PLATFORM := s7d          # Amlogic s7d 平台
TARGET_BOOTLOADER_BOARD_NAME := ross

# 64 位主架构 + 32 位兼容
TARGET_ARCH := arm64
TARGET_ARCH_VARIANT := armv8-2a
TARGET_CPU_VARIANT := cortex-a55
TARGET_CPU_ABI := arm64-v8a

# 32 位次架构(兼容旧应用)
TARGET_2ND_ARCH := arm
TARGET_2ND_ARCH_VARIANT := armv8-2a
TARGET_2ND_CPU_VARIANT := cortex-a55

TARGET_SUPPORTS_32_BIT_APPS := true
TARGET_SUPPORTS_64_BIT_APPS := true

Cortex-A55 是 ARM v8.2-A 的中核,常用于电视盒子和嵌入式设备。支持 64 位主架构同时兼容 32 位应用。

3.2 显示与 GPU

# 显示输出
HWC_PRIMARY_FRAMEBUFFER_WIDTH := 1920
HWC_PRIMARY_FRAMEBUFFER_HEIGHT := 1080
HWC_PRIMARY_CONNECTOR_TYPE := hdmi
HWC_DISPLAY_NUM := 1         # 单显示输出

HWC_ENABLE_REAL_MODE := true    # 支持真实 HDMI 分辨率
HWC_ENABLE_SEAMLESS_MODE_SWITCH := true  # 无缝切换分辨率
HWC_ENABLE_PRIMARY_HOTPLUG := true  # 支持 HDMI 热插拔
HWC_HDMI_FRAC_MODE := 2       # HDMI 分数刷新率

# Mali GPU 配置
include hardware/amlogic/gralloc/gralloc.device.mk
include hardware/amlogic/hwcomposer/hwcomposer.device.mk

3.3 摄像头

BOARD_HAVE_FRONT_CAM := false
BOARD_HAVE_BACK_CAM := false
BOARD_USE_USB_CAMERA := true   # 仅支持 USB 摄像头

3.4 分区与文件系统

分区配置 是嵌入式 Android 中最关键的硬件参数之一。分区大小决定系统能装多少东西,文件系统类型影响性能和可靠性。

# 文件系统类型(EROFS 是 Android 14 主推的只读文件系统)
BOARD_SYSTEMIMAGE_FILE_SYSTEM_TYPE := erofs
BOARD_VENDORIMAGE_FILE_SYSTEM_TYPE := erofs
BOARD_PRODUCTIMAGE_FILE_SYSTEM_TYPE := erofs
BOARD_USERDATAIMAGE_FILE_SYSTEM_TYPE := f2fs    # 数据分区用 F2FS
BOARD_EROFS_COMPRESSOR := eamfc                 # EROFS 压缩算法

# 分区大小(预置在动态分区之前)
BOARD_BOOTIMAGE_PARTITION_SIZE := 67108864      # 64M  boot
BOARD_VENDOR_BOOTIMAGE_PARTITION_SIZE := 67108864   # 64M  vendor_boot
BOARD_DTBOIMG_PARTITION_SIZE := 2097152          # 2M   dtbo
BOARD_DTBIMAGE_PARTITION_SIZE := 258048          # 252K dtb

# 动态分区(super 分区)
BOARD_SUPER_PARTITION_SIZE := 3355443200         # 3.2G super
BOARD_AMLOGIC_DYNAMIC_PARTITIONS_SIZE := 3344957440
BOARD_AMLOGIC_DYNAMIC_PARTITIONS_PARTITION_LIST := \
    system vendor product odm system_ext \
    vendor_dlkm system_dlkm odm_dlkm

3.5 AVB(Android Verified Boot)

# 每个分区独立签名
BOARD_AVB_SYSTEM_ADD_HASHTREE_FOOTER_ARGS += --hash_algorithm sha256
BOARD_AVB_VENDOR_ADD_HASHTREE_FOOTER_ARGS += --hash_algorithm sha256
BOARD_AVB_PRODUCT_ADD_HASHTREE_FOOTER_ARGS += --hash_algorithm sha256

# vbmeta_system 链式验证
BOARD_USES_VBMETA_SYSTEM := true
BOARD_AVB_VBMETA_SYSTEM := system system_ext system_dlkm
BOARD_AVB_VBMETA_SYSTEM_KEY_PATH := external/avb/test/data/testkey_rsa2048.pem
BOARD_AVB_VBMETA_SYSTEM_ALGORITHM := SHA256_RSA2048

3.6 Boot 相关

BOARD_BOOT_HEADER_VERSION := 4          # GKI 要求的 boot header v4
BOARD_KERNEL_CMDLINE += bootconfig      # 使用 bootconfig
BOARD_BOOTCONFIG += androidboot.dynamic_partitions=true
BOARD_RAMDISK_USE_LZ4 := true           # LZ4 压缩 ramdisk(更快解压)
BOARD_INCLUDE_DTB_IN_BOOTIMG := true    # DTB 内嵌在 boot.img 中

4. 分区布局详解

分区布局 定义了 eMMC/NAND Flash 上每个分区的起始位置、大小和属性。AB 系统(A/B slot)架构下,关键分区都有 _a 和 _b 两份,确保升级失败可回滚。

4.1 分区表文件

part_table_5_15.txt —— 适用于 5.15 kernel 的标准分区表:

// 格式:分区名, 起始地址, 大小, 间隔, 属性
// 属性 0x0001 = 普通分区
// 属性 0x0002 = 普通分区(特殊)
// 属性 0x0011 = 工厂分区(持久化)
// 属性 0x1001 = 元数据分区
// 属性 0x1004 = 用户数据分区

reserved,      36M,   64M,  8M,  0         # 保留区(给 bootloader 用)
env,           -,     8M,   16M, 0         # U-Boot 环境变量
frp,           -,     2M,   8M,  0x0001    # Factory Reset Protection
factory,       -,     8M,   1M,  0x0011    # 工厂数据(持久化,跨升级保留)
vendor_boot_a, -,     64M,  1M,  0x0001    # vendor_boot(GKI 必须)
vendor_boot_b, -,     64M,  1M,  0x0001
bootloader_a,  -,     8M,   1M,  0x0001    # U-Boot
bootloader_b,  -,     8M,   1M,  0x0001
tee,           -,     32M,  1M,  0x0001    # TrustZone 安全环境
logo,          -,     8M,   1M,  0x0001    # 开机 logo
misc,          -,     2M,   1M,  0x0001    # misc(bootloader 通信)
dtbo_a,        -,     2M,   1M,  0x0001    # Device Tree Blob Overlay
dtbo_b,        -,     2M,   1M,  0x0001
cri_data,      -,     8M,   1M,  0x0002    # 关键数据
param,         -,     16M,  1M,  0x0002    # 参数分区
odm_ext_a,     -,     16M,  1M,  0x0001    # ODM 扩展
odm_ext_b,     -,     16M,  1M,  0x0001
oem_a,         -,     32M,  1M,  0x0001    # OEM 分区(DRM 证书等)
oem_b,         -,     32M,  1M,  0x0001
boot_a,        -,     64M,  1M,  0x0001    # boot.img(GKI kernel + ramdisk)
boot_b,        -,     64M,  1M,  0x0001
init_boot_a,   -,     8M,   1M,  0x0001    # init_boot(GKI 通用 ramdisk)
init_boot_b,   -,     8M,   1M,  0x0001
metadata,      -,     64M,  1M,  0x1001    # 加密元数据
vbmeta_a,      -,     2M,   1M,  0x0001    # 启动验证描述符
vbmeta_b,      -,     2M,   1M,  0x0001
vbmeta_system_a,-,    2M,   1M,  0x0001    # system 分区验证
vbmeta_system_b,-,    2M,   1M,  0x0001
super,         -,     3200M,1M,  0x0001    # ★ 动态分区(包含 system/vendor 等)
rsv,           -,     64M,  1M,  0x0001    # 保留区
userdata,      -,     -,   1M,  0x1004    # ★ 用户数据(剩余全部空间)

4.2 分区大小汇总

分区 大小 用途
super 3200 MB (3.2 GB) 动态分区容器:system + vendor + product + odm + system_ext + vendor_dlkm + system_dlkm + odm_dlkm
userdata 剩余全部 应用数据、用户文件(F2FS)
vendor_boot 64 MB × 2 GKI vendor ramdisk
boot 64 MB × 2 GKI kernel
tee 32 MB TrustZone OS
metadata 64 MB FBE 加密密钥
oem 32 MB × 2 DRM 证书、许可证
rsv 64 MB 保留

4.3 AB 系统 (Seamless OTA)

reservedenvfrpfactorycri_dataparammetadatarsvuserdata 外,所有分区都有 _a 和 _b 两份。这是 Android AB 升级的基础:

  • 当前在 slot A 运行,OTA 写入 slot B
  • 重启后从 slot B 启动,如果 B 失败则自动回滚到 A
  • 用户无感知升级

4.4 8G eMMC 版本

part_table_U_8G_emmc.txt 是针对 8GB eMMC 的备选分区表,主要区别:

  • super 分区从 3200MB 缩小到 2400MB
  • rsv 从 64MB 缩小到 32MB

5. fstab —— 文件系统挂载表

fstab 定义了系统启动时每个分区的挂载点、文件系统类型和挂载参数。这是内核启动后 init 进程读取的第一个配置文件之一。

# fstab 被复制到两个位置:
PRODUCT_COPY_FILES += \
    device/amlogic/ross/fstab.ab_oem.amlogic:$(TARGET_COPY_OUT_VENDOR)/etc/fstab.amlogic \
    device/amlogic/ross/fstab.ab_oem.amlogic:$(TARGET_COPY_OUT_VENDOR_RAMDISK)/first_stage_ramdisk/fstab.amlogic
# 第一份 → vendor/etc/(正常运行用)
# 第二份 → vendor ramdisk(早期 init 挂载用)

关键挂载项

源分区 挂载点 文件系统 关键标志
system /system erofs ro, slotselect, avb=vbmeta_system, logical
vendor /vendor erofs ro, slotselect, avb=vbmeta, logical
product /product erofs ro, slotselect, avb, logical
system_ext /system_ext erofs ro, slotselect, avb=vbmeta_system, logical
/dev/block/by-name/userdata /data f2fs latemount, fileencryption, keydirectory
/dev/block/by-name/metadata /metadata f2fs wait,check,formattable
/dev/block/zram0 swap swap zramsize=33%

关键观察:

  • 所有系统分区都用 EROFS(只读、压缩),Android 14 主推
  • data 用 F2FS(Flash-Friendly File System),Android 的标准数据分区文件系统
  • data 加密fileencryption=aes-256-xts:aes-256-cts:v2+inlinecrypt_optimized
  • ZRAM:33% 的 RAM 作为压缩交换空间
  • AVB 验证:每个系统分区都有 avb 标志

6. 变体产品 —— 同一芯片,不同形态

ross 有 8 个产品变体,体现出 Amlogic 平台的高度复用。

变体 PRODUCT_NAME 特点
ross ross 基础 ATV (Amati Launcher)
ross_atv ross_atv ATV (Waston Launcher)
ross_dongle ross_dongle 电视棒/加密狗 (HDMI-only)
ross_soundbar ross_soundbar 条形音箱形态
ross_hybrid ross_hybrid Hybrid 模式
ross_hybrid_atf ross_hybrid_atf Hybrid + ATF
ross_cbs ross_cbs CBS 广播接收
ross_mxl258c ross_mxl258c MXL258C 调谐器

变体之间的差异很小,通常在 ross.mk 基础上覆盖少量配置:

# ross_dongle.mk —— 只改了连接器类型和 Launcher
$(call inherit-product, device/amlogic/ross/ross.mk)
PRODUCT_NAME := ross_dongle
HWC_PRIMARY_CONNECTOR_TYPE := hdmi-only
ATV_LAUNCHER := amati

构建命令示例

# 基础 ATV 版本
source build/envsetup.sh && lunch ross-userdebug && ./mk ross -v common14-5.15

# ATV 版本(Waston Launcher)
lunch ross_atv-userdebug && ./mk ross_atv -v common14-5.15

# 条形音箱版
lunch ross_soundbar-userdebug && ./mk ross_soundbar -v common14-5.15

7. Kernel 与 Bootloader 选择

7.1 Kernel

# ross.mk
TARGET_BUILD_KERNEL_VERSION ?= 5.15
TARGET_BUILD_KERNEL_USING_14_5.15 ?= true  # Android 14 + kernel 5.15

# BoardConfig.mk
BOARD_BOOT_HEADER_VERSION := 4     # GKI boot header

# kernel_config_build.mk
KERNEL_ROOTDIR := common           # GKI 通用内核目录
include device/amlogic/common/build_kernel_modules.mk

# ross.mk —— 使用预编译 GKI boot.img
BOARD_PREBUILT_BOOTIMAGE := device/amlogic/ross-kernel/5.15/gki/boot-lz4.img
TARGET_NO_KERNEL := true

关键点:ross 使用 GKI(Generic Kernel Image) 方式,即 Google 提供的通用内核。TARGET_NO_KERNEL := true 表示不从源码编译内核,而是直接使用预编译的 boot-lz4.img。内核模块(驱动)通过 vendor_dlkmsystem_dlkm 分区加载。

7.2 Bootloader

# ross.mk 中配置
BUILD_WITH_AVB := true
BOARD_AML_SECUREBOOT_SOC_TYPE := sc2

board-info.txt 显示 bootloader 版本约束:

require board=ross
require version-bootloader=01.01.250821.144210

构建命令:./mk s6_bl201 --vab --avb2

7.3 构建完整镜像的流程

# 1. 编译 bootloader
./mk s6_bl201 --vab --avb2

# 2. 编译 Android + kernel
./mk ross -v common14-5.15

# 3. 生成镜像文件
#    out/target/product/ross/
#    ├── boot.img          (GKI kernel + ramdisk)
#    ├── vendor_boot.img   (vendor ramdisk)
#    ├── super.img         (动态分区:system/vendor/product/...)
#    ├── vbmeta.img        (AVB 验证描述符)
#    ├── dtbo.img          (DT overlay)
#    ├── recovery.img      (Recovery 模式)
#    └── ota_update.zip    (OTA 升级包)

8. Hardware Feature Config —— 配置文件目录

device/amlogic/ross/files/ 是设备硬件配置文件的集散地,这些文件被复制到 vendor 分区,被 HAL 和 Framework 在运行时读取。

8.1 媒体编解码

媒体配置是 Android TV 设备中最复杂的部分:

files/media_codecs.xml                              # 主编解码配置
files/media_codecs_performance.xml                  # 性能配置
files/media_codecs_google_performance_video.xml     # Google 视频性能
files/video/c2/media_codecs_amlogic_video.xml       # Amlogic 视频解码(C2 框架)
files/video/c2/media_codecs_amlogic_performance_video.xml
files/encoder/media_codecs_amlogic_encoder.xml      # Amlogic 视频编码
files/encoder/media_codecs_amlogic_performance_encoder.xml
files/video/dolby_vision/media_codecs_amlogic_dolby_vision.xml  # 杜比视界

8.2 音频

files/audio_effects.conf           # 音效配置
files/mixer_paths.xml              # ALSA mixer 通路配置
files/audio_policy_devices.xml     # 音频设备策略
files/speaker_2.0.xml              # 音箱调优(MS12 tuning)
files/speaker_2.0_0_internal_speaker_48000_6.dat   # 调优数据

8.3 GPU 与显示

files/mali_platform.config         # Mali GPU 配置
files/mesondisplay.cfg             # 显示模块配置
files/aml_afrc_allowlist.config    # AFRC(自适应帧率)白名单

8.4 条件编译控制

# device.mk —— Dolby Vision
ifeq ($(TARGET_BUILD_WITH_DOVI),true)
PRODUCT_COPY_FILES += \
    files/video/dolby_vision/media_codecs_amlogic_dolby_vision.xml
endif

9. 完整构建包含链

ross.mk 到最终系统的完整包含关系:

ross.mk
  │
  ├── product_mbox.mk
  │     └── core_amlogic.mk
  │
  ├── device/amlogic/common/products/mbox/s7d/device.mk
  │     └── 复制 keylayout、init.rc、media_profiles.xml、PQ 配置等
  │
  ├── device/amlogic/common/products/mbox/s7d/s7d.mk
  │     └── s7d 平台 NetFlix/DRM 等通用配置
  │
  ├── device.mk
  │     ├── media_codecs*.xml、mixer_paths.xml、mesondisplay.cfg ...
  │     ├── GPU (Mali)、audio (ALSA、Dolby)、DLGOverlay
  │     └── device/amlogic/common/products/mbox/s7d/device.mk
  │
  ├── vendor_prop.mk               → 蓝牙、媒体缓冲、remotectrl 属性
  ├── product_property.mk          → ro.oem.key1=ATV00100025
  │
  └── vendor/giec/device-giec.mk   ← ★ 厂商定制(之前分析的)
        ├── SELinux 策略
        ├── HIDL 服务 (hwstbcmdservice)
        ├── 预置 APK (OTAClient, BazeportLauncher...)
        ├── Shell 工具脚本
        └── ADB/调试/签名配置

核心理解device/amlogic/ross/ 定义的是"硬件是什么",vendor/giec/ 定义的是"厂商加了什么"。两者通过 Android 构建系统的 inherit-product 机制组合。


10. 学习要点

10.1 一个设备配置回答了哪些问题

问题 答案在哪里
用什么芯片? BoardConfig.mkTARGET_BOARD_PLATFORM := s7d
CPU 几核多快? TARGET_CPU_VARIANT := cortex-a55
多大存储? 分区表 super=3200M, userdata=剩余
Android 版本? PRODUCT_SHIPPING_API_LEVEL := 34
用哪个内核? TARGET_BUILD_KERNEL_VERSION := 5.15
预装哪些应用? ross.mk + device-giec.mk 中的 PRODUCT_PACKAGES
支持哪些视频格式? files/media_codecs_*.xml
有没有 WiFi? CONFIG_WIFI_MODULES := rtl8822cs
有没有 Google 服务? BOARD_COMPILE_GAPPS_TV
安全启动怎么配置? AVB 相关 BOARD_AVB_*
分区 AB 还是非 AB? AB_OTA_UPDATER := true

10.2 理解 GKI

GKI (Generic Kernel Image) 是 Android 14 的标准做法:Google 提供通用内核,芯片厂商通过 vendor 模块和 DLKM 分区加载驱动。

ross 的 GKI 体现在:

  • BOARD_BOOT_HEADER_VERSION := 4 — GKI 要求的 boot header
  • BOARD_PREBUILT_BOOTIMAGE — 使用预编译 GKI boot.img
  • vendor_dlkm / system_dlkm 分区 — 存放内核模块
  • vendor_boot 分区 — 存放 vendor ramdisk

10.3 如何从零创建新设备?

  1. 复制现有设备目录(如 device/amlogic/ross/
  2. 修改 BoardConfig.mk:平台、CPU、分区大小
  3. 修改 device.mk:媒体配置、硬件特性
  4. 创建 产品名.mk:继承关系,定义 PRODUCT_NAME
  5. 更新 AndroidProducts.mk:注册新产品的 lunch 选项
  6. 修改分区表:eMMC 大小不同时调整
  7. 适配 fstab:分区布局不同时修改
  8. 适配硬件配置:files/ 下的编解码、音频、显示配置