K1 OH5.0 方案添加移植说明

修订记录

修订版本	修订日期	修订说明
001	2025-01-13	初始版本
002	2025-04-11	添加MUSE Pi Pro

1. SDK 目前支持方案

生态产品	MUSE Paper2 （新版硬件） MUSE Paper （旧版硬件）点我了解	MUSE Card 点我了解	MUSE Pi 点我了解	MUSE Pi Pro 点我了解	MUSE Book 点我了解
产品形态	平板电脑	开发板	开发板	开发板	笔记本电脑
启动方式	Emmc tf卡	tf卡	emmc	emmc	nor+ssd
显示输出	MipiDSI	MipiDSI HDMI	MipiDSI HDMI	MipiDSI	MipiDSI转edp
屏幕触摸	√	√	√	√	×
wifi	√	√	√	√	√
BT	√	×	×	×	×
ethnet	√（usb转）	√	√	√	×
USB	√	√	√	√	√
键鼠	√	√	√	√	√
摄像头	√（支持双摄）	×	×	×	×
双屏显示	×	×	×	×	√（接HDMI）

2. 添加定制方案

产品方案定制涉及以下核心代码仓库：

build：添加构建白名单，主要修改文件为：
- compile_standard_whitelist.json
- subsystem_compoents_whitelist.json
vendor/spacemit：进迭厂商定制适配目录
device/board/spacemit：进迭厂商板级适配目录
device/soc/spacemit：进迭厂商芯片适配目录
kernel/linux/spacemit_kernel-6.6：进迭厂商内核

添加定制方案通过以下两种方式实现：

通过修改现有方案进行定制 适用于在现有开发板基础上快速适配新的方案。例如，源码中已包含 deb1 和 MUSE Pi 两款开发板的适配配置，可通过修改其中的参数来支持新的开发板。
- 适配流程简单，开发速度快。
- 注意：新开发板的板号需与原开发板保持一致（例如，仍命名为 deb1）。
通过添加全新方案定制 适用于需要完全独立配置的场景。
- 前期需进行一定的适配工作。
- 不会与现有开发板配置冲突，可灵活进行自定义和修改。

下面分别对两种定制方案的操作进行说明：

2.1 通过修改现有方案定制

2.1.1 定制 U-Boot

在大多数场景下，现有 U-Boot 能够正常引导内核启动，则可忽略此步。若有一些特殊需求，请联系进迭时空。
如遇 U-Boot 无法正常启动的情况（较小概率），因目前 U-Boot 未上传源码，需联系进迭时空进行定制。定制流程：提供完整硬件原理图给进迭时空 → 进迭时空配置并编译 → 获取定制版 U-Boot 相关的 bin 文件。

以下对进迭时空提供的 U-Boot 文件如何添加到系统进行说明。

通用 U-Boot 文件位于 device/soc/spacemit/k1/kernel/boot/ 目录，适用于所有标准方案：

|-- bootfs
|   |-- boot_logo_spacemit_0.bmp
|   |-- boot_logo_spacemit_180.bmp
|   |-- boot_logo_spacemit_270.bmp
|   `-- boot_logo_spacemit_90.bmp
|-- env.bin
|-- factory
|   |-- bootinfo_emmc.bin
|   |-- bootinfo_sd.bin
|   |-- bootinfo_spinand.bin
|   |-- bootinfo_spinor.bin
|   `-- FSBL.bin
|-- fastboot.yaml
|-- fw_dynamic.itb
|-- genimage.cfg
|-- partition_2M.json
|-- partition_flash.json
`-- u-boot.itb

编译过程中常更新的文件包括：

env.bin
FSBL.bin
u-boot.bin

这些文件会在构建阶段通过以下脚本自动拷贝至打包目录：

device/board/spacemit/xxx/kernel/build_kernel.sh

脚本中的拷贝示例如下：

cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/bootfs/boot_logo_spacemit_0.bmp ${OHOS_IMAGES_DIR}/bootfs/bianbu.bmp
cp ${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/boot/bootfs/env_k1-x.txt ${OHOS_IMAGES_DIR}/bootfs/env_k1-x.txt
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/env.bin ${OHOS_IMAGES_DIR}/env.bin
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/u-boot.itb ${OHOS_IMAGES_DIR}/u-boot.itb
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/fw_dynamic.itb ${OHOS_IMAGES_DIR}/fw_dynamic.itb
cp ${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/boot/partition_universal.json ${OHOS_IMAGES_DIR}/partition_universal.json
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/fastboot.yaml ${OHOS_IMAGES_DIR}/fastboot.yaml
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/genimage.cfg ${OHOS_IMAGES_DIR}/genimage.cfg
cp -r ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/factory ${OHOS_IMAGES_DIR}/

若某一方案的 U-Boot 存在专属定制需求，则需将对应的 U-Boot 的 bin 文件单独放置在该方案目录下：

device/board/spacemit/xxx/kernel/boot

同时，应修改 build_kernel.sh 文件，将该方案目录中的 U-Boot 文件拷贝至打包目录。

2.1.2 定制 kernel

2.1.2.1 修改 dts

内核的 dts 文件统一放置在：kernel/linux/spacemit_kernel-6.6/arch/riscv/boot/dts/spacemit，如下所示：

|-- k1-x-camera-reserved-mm.dtsi
|-- k1-x-camera-sdk.dtsi
|-- k1-x-camera-sensor.dtsi
|-- k1-x_deb1.dts
|-- k1-x_deb2.dts
|-- k1-x.dtsi
|-- k1-x-efuse.dtsi
|-- k1-x_evb.dts
|-- k1-x-hdmi.dtsi
|-- k1-x_hs450.dts
|-- k1-x_kx312.dts
|-- k1-x-lcd.dtsi
|-- k1-x_lpi3a.dts
|-- k1-x_milkv-jupiter.dts
|-- k1-x_mingo.dts
|-- k1-x_MINI-PC.dts
|-- k1-x_MUSE-Book.dts
|-- k1-x_MUSE-Card.dts
|-- k1-x_MUSE-N1.dts
|-- k1-x_MUSE-Paper2.dts
|-- k1-x_MUSE-Paper.dts
|-- k1-x_MUSE-Paper-mini-4g.dts
|-- k1-x_MUSE-Pi.dts
|-- k1-x_opp_table.dtsi
|-- k1-x_pinctrl.dtsi
|-- k1-x_SMT001.dts
|-- k1-x_thermal_cooling.dtsi
|-- k1-x_ZT001H.dts
|-- lcd
|   |-- lcd_ft8201sinx101_mipi.dtsi
|   |-- lcd_gc9503v_mipi.dtsi
|   |-- lcd_gx09inx101_mipi.dtsi
|   |-- lcd_icnl9911c_mipi.dtsi
|   |-- lcd_icnl9951r_mipi.dtsi
|   |-- lcd_jd9365dah3_mipi.dtsi
|   |-- lcd_jd9365da_mipi_1280x800.dtsi
|   |-- lcd_lt8911_edp_1920x1080.dtsi
|   |-- lcd_lt8911_edp_1920x1200.dtsi
|   |-- lcd_lt9711_dp_1920x1080.dtsi
|   `-- lcd_orisetech_ota7290b_mipi.dtsi
|-- m1-x_milkv-jupiter.dts
`-- Makefile

可以根据方案名称修改对应的 dts 文件即可，修改完成后，重新编译内核，或者重新编译系统，为避免缓存影响，建议先清理旧的编译缓存：

cd oh5
rm -rf out/kernel

./build.sh --product-name xxx --ccache --no-prebuilt-sdk -T build_kernel
or
./build.sh --product-name xxx --ccache --no-prebuilt-sdk

2.1.2.2 修改 defconfig

内核的 defconfig 文件位于：

kernel/linux/spacemit_kernel-6.6/arch/riscv/configs/k1_defconfig

该 defconfig 是所有方案共用的，修改后，对所有的方案生效。

如果只是针对某个特定方案的修改，需要通过 patch 的形式来修改，过程如下：

生成 patch：fix.patch
将生成的 fix.patch 放置于 device/board/spacemit/xxx/kernel/kernel_patch 中
device/board/spacemit/xxx/kernel/build_kernel.sh 中打 patch，如下：

patch -p1 <${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/kernel_patch/fix.patch

2.1.3 定制 vendor 目录

vendor/spacemit/xxx 目录中主要文件和用途如下：

bluetooth：蓝牙厂商适配层，适配蓝牙模组主要修改该文件夹，目前默认适配 AP6256 的蓝牙
config.json：该方案包含的组件，可以对组件进行增删和组件属性的增删
default_app_config：暂无修改
etc：添加一些系统属性，如 const.product.name="XXX"
hals：目前主要适配音频通路等
hdf_config：方案的 hdf 配置文件
image_conf：暂无修改
ohos.build：添加构建模块
power_config：配置电源管理模式，分为 NORMAL，POWER_SAVE，PERFORMANCE，EXTREME_POWER_SAVE 几种，可以配置每种模式的行为，包括关屏时间，待机时间等
preinstall-config：安装的应用 hap 包管理和权限管理
product.gni：一些属性配置
resourceschedule：暂无修改
security_config：暂无修改
updater_config：暂无修改
window_config：窗口相关配置，比如屏幕旋转方向，过场动画时间配置等

2.1.4 定制 device 目录

device 目录包含 board 和 soc 两部分：

**soc：**针对 K1 芯片平台的适配，是各产品方案通用的部分
**board：**针对各产品方案的适配，是各产品方案不通用的部分

device 下面的目录结构如下所示：

|-- board
|   `-- spacemit
|       |-- common
|       |-- deb1
|       |-- kernel_patches
|       |-- musebook
|       |-- musecard
|       |-- musepaper
|       |-- musepaper2
|       |-- musepapermini4g
|       |-- musepi
|       |-- smt001
|       `-- zt001h
`-- soc
    `-- spacemit
        |-- common
        `-- k1

device/board/spacemit/xxx 下面的主要修改点包括：

cfg/default.para：一些系统配置参数
cfg/fstab.xxx：文件系统挂载配置
cfg/init.xxx.cfg：启动配置
cfg/init.xxx.usb.cfg：USB 启动配置
kernel：内核相关的配置和文件
kernel/boot：U-Boot 相关文件
kernel/build_kernel.sh：内核构建脚本
kernel/kernel_patch：内核补丁
kernel/ko：需要加载的 ko

device/soc/spacemit/k1 下面的主要修改点包括：

hardware：K1 适配硬件的适配层，包括硬件编解码，GPU 等
kernel/boot：U-Boot 相关文件
tools：一些命令行工具

2.2 通过添加全新方案定制

2.2.1 定制 U-boot

在大多数场景下，现有 U-Boot 能够正常引导内核启动，则可忽略此步。若有一些特殊需求，请联系进迭时空。
如遇 U-Boot 无法正常启动的情况（较小概率），因目前 U-Boot 未上传源码，需联系进迭时空进行定制。定制流程：提供完整硬件原理图及方案代号（如 ABC）给进迭时空 → 进迭时空完成配置并编译 → 获取定制版 U-Boot 相关的 bin 文件。

以下对进迭时空提供的 U-Boot 文件如何添加到系统进行说明。

通用 U-Boot 文件位于 device/soc/spacemit/k1/kernel/boot/ 目录，如下：

|-- bootfs
|   |-- boot_logo_spacemit_0.bmp
|   |-- boot_logo_spacemit_180.bmp
|   |-- boot_logo_spacemit_270.bmp
|   `-- boot_logo_spacemit_90.bmp
|-- env.bin
|-- factory
|   |-- bootinfo_emmc.bin
|   |-- bootinfo_sd.bin
|   |-- bootinfo_spinand.bin
|   |-- bootinfo_spinor.bin
|   `-- FSBL.bin
|-- fastboot.yaml
|-- fw_dynamic.itb
|-- genimage.cfg
|-- partition_2M.json
|-- partition_flash.json
`-- u-boot.itb

编译过程中常更新的文件包括：

env.bin
FSBL.bin
u-boot.bin

这些文件会在构建阶段通过以下脚本自动拷贝至打包目录：

cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/bootfs/boot_logo_spacemit_0.bmp ${OHOS_IMAGES_DIR}/bootfs/bianbu.bmp
cp ${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/boot/bootfs/env_k1-x.txt ${OHOS_IMAGES_DIR}/bootfs/env_k1-x.txt
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/env.bin ${OHOS_IMAGES_DIR}/env.bin
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/u-boot.itb ${OHOS_IMAGES_DIR}/u-boot.itb
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/fw_dynamic.itb ${OHOS_IMAGES_DIR}/fw_dynamic.itb
cp ${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/boot/partition_universal.json ${OHOS_IMAGES_DIR}/partition_universal.json
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/fastboot.yaml ${OHOS_IMAGES_DIR}/fastboot.yaml
cp ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/genimage.cfg ${OHOS_IMAGES_DIR}/genimage.cfg
cp -r ${OHOS_SOURCE_ROOT}/device/soc/${DEVICE_BOARD}/k1/kernel/boot/factory ${OHOS_IMAGES_DIR}/

若某一方案的 U-Boot 存在专属定制需求，则需将对应的 U-Boot 的 bin 文件单独放置在该方案目录下：

device/board/spacemit/xxx/kernel/boot

同时，应修改 build_kernel.sh 文件，将该方案目录中的 U-Boot 文件拷贝至打包目录。

2.2.2 定制 Kernel

2.2.2.1 修改 dts

内核的 dts 文件统一放置在：kernel/linux/spacemit_kernel-6.6/arch/riscv/boot/dts/spacemit，目录结构示例如下：

|-- k1-x-camera-reserved-mm.dtsi
|-- k1-x-camera-sdk.dtsi
|-- k1-x-camera-sensor.dtsi
|-- k1-x_deb1.dts
|-- k1-x_deb2.dts
|-- k1-x.dtsi
|-- k1-x-efuse.dtsi
|-- k1-x_evb.dts
|-- k1-x-hdmi.dtsi
|-- k1-x_hs450.dts
|-- k1-x_kx312.dts
|-- k1-x-lcd.dtsi
|-- k1-x_lpi3a.dts
|-- k1-x_milkv-jupiter.dts
|-- k1-x_mingo.dts
|-- k1-x_MINI-PC.dts
|-- k1-x_MUSE-Book.dts
|-- k1-x_MUSE-Card.dts
|-- k1-x_MUSE-N1.dts
|-- k1-x_MUSE-Paper2.dts
|-- k1-x_MUSE-Paper.dts
|-- k1-x_MUSE-Paper-mini-4g.dts
|-- k1-x_MUSE-Pi.dts
|-- k1-x_opp_table.dtsi
|-- k1-x_pinctrl.dtsi
|-- k1-x_SMT001.dts
|-- k1-x_thermal_cooling.dtsi
|-- k1-x_ZT001H.dts
|-- lcd
|   |-- lcd_ft8201sinx101_mipi.dtsi
|   |-- lcd_gc9503v_mipi.dtsi
|   |-- lcd_gx09inx101_mipi.dtsi
|   |-- lcd_icnl9911c_mipi.dtsi
|   |-- lcd_icnl9951r_mipi.dtsi
|   |-- lcd_jd9365dah3_mipi.dtsi
|   |-- lcd_jd9365da_mipi_1280x800.dtsi
|   |-- lcd_lt8911_edp_1920x1080.dtsi
|   |-- lcd_lt8911_edp_1920x1200.dtsi
|   |-- lcd_lt9711_dp_1920x1080.dtsi
|   `-- lcd_orisetech_ota7290b_mipi.dtsi
|-- m1-x_milkv-jupiter.dts
`-- Makefile

可根据方案名称新增对应的 dts 文件，如 k1-x_ABC.dts，添加到上述目录后，在同目录的 Makefile 中加入编译项即可。示例如下：

diff --git a/arch/riscv/boot/dts/spacemit/Makefile b/arch/riscv/boot/dts/spacemit/Makefile
index ea48d28cedda..36beb0761dd7 100644
--- a/arch/riscv/boot/dts/spacemit/Makefile
+++ b/arch/riscv/boot/dts/spacemit/Makefile
@@ -3,5 +3,5 @@ dtb-$(CONFIG_SOC_SPACEMIT_K1X) += k1-x_evb.dtb k1-x_deb2.dtb k1-x_deb1.dtb k1-x_
                                  k1-x_MUSE-Pi.dtb k1-x_milkv-jupiter.dtb m1-x_milkv-jupiter.dtb \
                                  k1-x_MUSE-Book.dtb k1-x_lpi3a.dtb k1-x_MUSE-Card.dtb \
                                  k1-x_MUSE-Paper.dtb k1-x_MUSE-Paper-mini-4g.dtb \
-                                 k1-x_ZT001H.dtb k1-x_MUSE-Paper2.dtb
+                                 k1-x_ZT001H.dtb k1-x_MUSE-Paper2.dtb k1-x_ABC.dtb
 obj-$(CONFIG_BUILTIN_DTB) += $(addsuffix .o, $(dtb-y))

重新编译内核，或者重新编译系统，保险起见，建议删除原来的编译缓存，如下：

cd oh5
rm -rf out/kernel

./build.sh --product-name xxx --ccache --no-prebuilt-sdk -T build_kernel
or
./build.sh --product-name xxx --ccache --no-prebuilt-sdk

2.2.2.2 修改 defconfig

内核的 defconfig 文件位于：

kernel/linux/spacemit_kernel-6.6/arch/riscv/configs/k1_defconfig

该 defconfig 是所有方案共用的，修改后，对所有的方案生效。

如果只是针对某个特定方案的修改，需要通过 patch 的形式来修改，过程如下：

生成 patch：fix.patch
将生成的 fix.patch 放置于 device/board/spacemit/xxx/kernel/kernel_patch 中
device/board/spacemit/xxx/kernel/build_kernel.sh 中打 patch，如下：

patch -p1 <${OHOS_SOURCE_ROOT}/device/board/${DEVICE_BOARD}/${DEVICE_NAME}/kernel/kernel_patch/fix.patch

2.2.3 定制 vendor 目录

vendor 目录的定制和前面章节有差别，由于添加的是全新方案，vendor/spacemit 下尚无对应目录。定制方法为先拷贝一个现有方案目录，再统一修改方案相关名称，最后进行具体内容的定制。

拷贝现有方案：选择一个相似的方案进行拷贝，例如要适配开发板，可选择 deb1；要适配平板，可选择 musepaper。新建方案以开发板 abc 为例，如下：

cd vendor/spacemit
cp -r deb1 abc

统一修改方案名，将所有 deb1 替换为 abc，并修改相应文件名：

# sed -i "s/deb1/abc/g" `grep -rl deb1 ./`
# find . -name *deb1*
./etc/param/product_deb1.para
./etc/param/hardware_deb1.para
# mv ./etc/param/product_deb1.para ./etc/param/product_abc.para
# mv ./etc/param/hardware_deb1.para ./etc/param/hardware_abc.para

删除之前的编译缓存避免编译报错）：

cd abc
rm hdf_config/khdf/.built-in.a.cmd hdf_config/khdf/.hdf_hcs_hex.o.d hdf_config/khdf/.modules.order.cmd hdf_config/khdf/built-in.a hdf_config/khdf/hdf_hcs.hcb hdf_config/khdf/hdf_hcs_hex.o hdf_config/khdf/modules.order

进行修改定制。

2.2.4. 定制 device 目录

device 目录的定制和前面章节有差别，由于添加的是全新方案，device/board/spacemit 下尚无对应目录。定制方法为先拷贝一个现有方案目录，再统一修改方案相关名称，最后进行具体内容的定制。

拷贝现有方案：选择一个相似的方案进行拷贝，例如要适配开发板，可选择 deb1；要适配平板，可选择 musepaper。新建方案以开发板 abc 为例，如下：

cd device/board/spacemit
cp -r deb1 abc

统一修改方案名，将所有 deb1 替换为 abc，并重命名相关文件：

# sed -i "s/deb1/abc/g" `grep -rl deb1 ./`
# find . -name *deb1*
./updater/config/init.deb1.usb.cfg
./cfg/init.deb1.usb.cfg
./cfg/fstab.deb1
./cfg/init.deb1.cfg
# mv ./updater/config/init.deb1.usb.cfg ./updater/config/init.abc.usb.cfg
# mv ./cfg/init.deb1.usb.cfg ./cfg/init.abc.usb.cfg
# mv ./cfg/fstab.deb1 ./cfg/fstab.abc
# mv ./cfg/init.deb1.cfg ./cfg/init.abc.cfg

在 kernel/build_kernel.sh 中更新 dtb 文件名称，使其与内核对应的 dtb 名称一致。
进行修改定制。

2.2.5. build 目录添加权限

在 subsystem_compoents_whitelist.json 中添加方案配置：

diff --git a/subsystem_compoents_whitelist.json b/subsystem_compoents_whitelist.json
index ee125742..a01e2e1c 100644
--- a/subsystem_compoents_whitelist.json
+++ b/subsystem_compoents_whitelist.json
@@ -15,6 +15,7 @@
   "device_smt001" :"device_smt001",
   "device_musepaper" :"device_musepaper",
   "device_musepi" :"device_musepi",
   "device_musecard" :"device_musecard",
+  "device_abc" :"device_abc",
   "device_musepaper2" :"device_musepaper2",
   "device_musepapermini4g" :"device_musepapermini4g",
   "device_zt001h" :"device_zt001h",

在 compile_standard_whitelist.json 中添加模块的白名单：搜索该方案拷贝的原方案的名字，比如 deb1，包含 deb1 的模块都拷贝一份，并将方案名称修改为 abc
在 core/gn/ohos_exec_script_allowlist.gni 中，参考现有方案（如 deb1）的写法，添加新方案 abc 的脚本路径，确保编译时可正常执行相关脚本。

修订记录

1. SDK 目前支持方案

2. 添加定制方案

2.1 通过修改现有方案定制​

2.1.1 定制 U-Boot​

2.1.2 定制 kernel​

2.1.2.1 修改 dts​

2.1.2.2 修改 defconfig​

2.1.3 定制 vendor 目录​

2.1.4 定制 device 目录​

2.2 通过添加全新方案定制​

2.2.1 定制 U-boot​

2.2.2 定制 Kernel​

2.2.2.1 修改 dts​

2.2.2.2 修改 defconfig​

2.2.3 定制 vendor 目录​

2.2.4. 定制 device 目录​

2.2.5. build 目录添加权限​

3. FAQ