Skip to content
wangjianxin-canaan edited this page Sep 19, 2026 · 4 revisions

K230 Linux SDK Wiki

嘉楠 K230 / K230D 系列 RISC-V SoC 的 Linux 系统开发套件,基于 Buildroot 构建。

本页面对应仓库 kendryte/k230_linux_sdk。内容依据仓库源码整理,如与代码冲突请以代码为准。

常用入口


目录

  1. 概览
  2. 快速开始
  3. 支持的开发板与配置
  4. 仓库目录结构
  5. 构建系统原理
  6. make 命令速查
  7. 启动链与镜像布局
  8. 内核与设备树
  9. 驱动与硬件支持
  10. WiFi 与蓝牙
  11. 菜单结构(menuconfig)
  12. AI 开发
  13. Python 开发
  14. 多媒体与图形
  15. 应用开发
  16. Debian / Ubuntu 发行版镜像
  17. CI 与发布流程
  18. 已知限制与常见坑
  19. 参与贡献

1. 概览

K230 系列采用多异构单元加速计算架构,集成 2 个玄铁 C908 RISC-V 核(大核带 RVV 1.0 向量扩展),内置 KPU 智能计算单元,并带有 2D/2.5D 图形、视频编解码(VPU)、ISP 等专用硬件加速单元。

K230 与 K230D 的主要区别:K230D 是 SiP 封装,内部集成 128MB LPDDR4 颗粒;K230 则依赖板级 DDR,常见为 512MB 或 1GB。这个差异直接决定了 CMA 比例、rootfs 大小等配置取舍。

本 SDK 提供什么

层次 内容
构建系统 Buildroot 2025.02.1 + buildroot-overlay/ 覆盖层
启动链 U-Boot 2022.10(含 SPL)+ OpenSBI 1.4
内核 Linux 6.6.36(ruyisdk/linux-xuantie-kernel,固定 commit)+ 42 个 SDK patch
驱动 vvcam/ISP、VPU、VGLite GPU、nonai2d、MMZ、KPU、WiFi/BT 等
运行时 nncase runtime 2.11.0、OpenCV 4.10、FFmpeg 4.4.4、LVGL v9、Python 3.13
应用 48 个 AI demo、YOLO 统一推理、RTSP/WebRTC 推流、UVC gadget、LLM 等
发行版 可选生成 Debian 13 / Ubuntu 24.04 riscv64 镜像

本 SDK 是 纯 Linux 方案。旧版 k230_sdk 中的 RT-Smart 双系统在本仓库中已移除(仅残留少量注释)。但保留了 NuttX 裸机 共存能力,可从 U-Boot 命令行 run bnuttx 启动。


2. 快速开始

2.1 环境要求

已验证系统:Ubuntu 22.04 / 24.04。其它发行版可能遇到构建问题,建议改用下文的 Docker 环境。

2.2 获取代码与安装工具链

git clone --depth=1 https://github.com/kendryte/k230_linux_sdk.git
cd k230_linux_sdk
sudo make toolchain_and_depend

make toolchain_and_depend 会做两件事(脚本:tools/install_toolchain_and_depend.sh,必须 root):

  1. apt-get install 一批依赖:git sed make binutils build-essential diffutils gcc g++ bash patch gzip bzip2 perl tar cpio unzip rsync file bc findutils wget libncurses-dev python3 libssl-dev gawk cmake bison flex bash-completion parted curl xz-utils mtd-utils,以及 pcpp(Ubuntu ≥ 24 走 apt 的 python3-pcpp,否则 pip 安装)。
  2. 下载并解压玄铁工具链 Xuantie-900-gcc-linux-6.6.0-glibc-x86_64-V3.0.2-20250410.tar.gz 到 /opt/toolchain/,最终路径为 /opt/toolchain/Xuantie-900-gcc-linux-6.6.0-glibc-x86_64-V3.0.2/,前缀 riscv64-unknown-linux-gnu-。所有 15 个 defconfig 都硬编码引用这个路径。

RV64ILP32 工具链(可选) —— 仅 k230d_canmv_ilp32_defconfig 和 BPI-CanMV-K230D-Zero_ilp32_defconfig 需要,需手动安装:

wget -c https://github.com/ruyisdk/riscv-gnu-toolchain-rv64ilp32/releases/download/2024.06.25/riscv64ilp32-elf-ubuntu-22.04-gcc-nightly-2024.06.25-nightly.tar.gz
mkdir -p /opt/toolchain/riscv64ilp32-elf-ubuntu-22.04-gcc-nightly-2024.06.25/
tar -xvf riscv64ilp32-elf-ubuntu-22.04-gcc-nightly-2024.06.25-nightly.tar.gz \
    -C /opt/toolchain/riscv64ilp32-elf-ubuntu-22.04-gcc-nightly-2024.06.25/

2.3 Docker 构建环境(推荐用于非 Ubuntu 主机)

# 构建镜像
docker build -f tools/docker/Dockerfile -t k230/build tools/docker

# 进入环境(注意 /opt/toolchain 由宿主机挂载,镜像本身不带工具链)
docker run -it --rm -h k230 \
  -e uid=$(id -u) -e gid=$(id -g) -e user=${USER} \
  -v $(pwd):$(pwd) -v /opt/toolchain:/opt/toolchain \
  -w $(pwd) k230/build:latest

镜像基于 ubuntu:22.04,apt 源替换为清华镜像,入口脚本 tools/docker/entrypoint.sh 会按传入的 uid/gid 创建同名用户,保证 bind mount 出来的文件属主正确。

2.4 编译

三步,按顺序执行:

make k230d_canmv_defconfig   # 1. 选择配置(只需执行一次,结果记录在 .last_conf)
make source                  # 2. 预下载全部源码包(可选)
make                         # 3. 编译

也可以一条命令:make CONF=k230d_canmv_defconfig。

注意 CONF= 的副作用:在命令行显式传 CONF= 会强制重跑 defconfig,从而丢弃你之前用 make menuconfig 做的改动。只在切换板子时用它;日常增量编译请直接 make。

首次编译耗时较长(拉取 Buildroot、内核、全部第三方源码)。不想编译可直接下载 每日构建镜像。

2.5 输出

output/<defconfig>/images/sysimage-sdcard.img.gz

编译结束后 tools/print_images.sh 会把实际生成的镜像路径以绿色打印出来。同时会生成一个带版本信息的软链接,形如:

CanMV-K230_01studio_linux_v1.4_nncase_v2.11.0_e661aa44_sdcard.img.gz
                                                └ git commit  └ 存储介质

2.6 烧录

解压得到 sysimage-sdcard.img 后:

Linux

ls -l /dev/sd*          # 插卡前
ls -l /dev/sd*          # 插卡后,新增的即为 TF 卡
sudo dd if=sysimage-sdcard.img of=/dev/sdX bs=1M oflag=sync

Windows:使用 Rufus 选择镜像并写入。

2.7 串口连接

用 Type-C 线连接开发板与电脑,会枚举出两个串口(CH342 双串口):

系统 节点 用途
Windows USB-Enhanced-SERIAL-A CH342 小核 Linux 调试串口
Windows USB-Enhanced-SERIAL-B CH342 串口 3,暂未使用
Linux /dev/ttyACM0 小核 Linux 调试串口
Linux /dev/ttyACM1 串口 3,暂未使用

串口参数:115200 8N1,无校验,无流控。

  • 不插 TF 卡也能看到串口枚举;按下 reset 会有一行打印,说明 CPU 工作正常。
  • Windows 下串口识别异常请重装 CH343 驱动。
  • 注意各板子控制台串口不完全一致:多数为 ttyS0/ttyS1,k230d_canmv_junroc_ai_cam 使用 ttyS2。

3. 支持的开发板与配置

配置文件位于 buildroot-overlay/configs/,共 15 个。也可运行 make list_def 查看。

defconfig 开发板 芯片 DDR 存储 rootfs WiFi
k230_canmv_defconfig CanMV-K230 1.0/1.1(参考板) K230 512MB SD 400M BCM43438
k230_canmv_v3_defconfig CanMV-K230 V3 K230 1GB SD 400M AIC8800 + RTL8733BS
k230_canmv_01studio_defconfig 01Studio CanMV K230 1GB SD 400M RTL8733BS
k230_canmv_01studio_emmc_defconfig 01Studio CanMV(eMMC 版) K230 1GB eMMC 400M RTL8733BS
k230_canmv_lckfb_defconfig 立创庐山派 LCKFB K230 1GB / 512MB* SD 400M AIC8800
k230_canmv_dongshanpi_defconfig 东山派 DongshanPi K230 1GB SD 400M AIC8800
k230_canmv_gt6700_defconfig GT6700 K230 1GB SD 400M —
k230_canmv_huskylens_defconfig DFRobot HuskyLens K230 1GB SD 712M AIC8800
k230_canmv_mrt_defconfig 邯锻 MRT K230 1GB SD 400M RTL8733BS
k230_evb_defconfig K230 EVB 评估板 K230 512MB SD + SPI-NAND + SPI-NOR 400M —
k230d_canmv_defconfig CanMV-K230D Zero K230D 128MB SD 300M —
k230d_canmv_ilp32_defconfig CanMV-K230D(32 位用户态) K230D 128MB SD 256M —
k230d_canmv_junroc_ai_cam_defconfig 骏罗 AI Cam K230D 128MB SD 300M —
BPI-CanMV-K230D-Zero_defconfig Banana Pi CanMV-K230D-Zero K230D 128MB SD 300M —
BPI-CanMV-K230D-Zero_ilp32_defconfig Banana Pi(32 位用户态) K230D 128MB SD 256M —

* lckfb 的 k230-canmv-lckfb.dts 标注 1GB,而 -lcd 变体标注 512MB;实际生效取决于启动时选中哪个 DTB,详见 8.4。

3.1 关于 ilp32 配置

两个 *_ilp32_defconfig 是 PLCT / RuyiSDK 的 RV64ILP32 ABI 实验配置:

  • 用户态 BR2_RISCV_32=y,用单独的 riscv64ilp32-elf 工具链构建。
  • 内核编译两份:常规 LP64D 的 Image,以及用 k230_defconfig + 64ilp32.config 编译的 Image_ilp32(由 BR2_PACKAGE_LINUX_ILP32 控制,实现见 buildroot-overlay/linux/linux_ilp32/)。
  • 启动时通过 U-Boot 环境变量 blinuxilp32 选择加载哪一个。

4. 仓库目录结构

k230_linux_sdk/
├── Makefile                     # 主入口,包装 Buildroot
├── buildroot-overlay/           # 覆盖到原始 Buildroot 之上的所有 SDK 改动
│   ├── configs/                 # 15 个 defconfig
│   ├── board/canaan/k230-soc/   # 唯一的 board 目录,所有板子共用
│   │   ├── post-build.sh        #   版本戳、生成 S40<CONF> 模块加载脚本
│   │   ├── post-image.sh        #   镜像打包主流程
│   │   ├── genimage_cfg/        #   SD / NAND / NOR 分区表
│   │   ├── env/                 #   U-Boot 环境变量默认值
│   │   ├── fragment/            #   kconfig 片段(按板叠加)
│   │   ├── rootfs_overlay/      #   直接覆盖到 rootfs 的文件(init 脚本等)
│   │   └── distribution/        #   Debian / Ubuntu 镜像生成
│   ├── boot/
│   │   ├── uboot/               #   uboot.mk + u-boot-2022.10-overlay/
│   │   └── opensbi/             #   opensbi.mk + opensbi-1.4-overlay/
│   ├── linux/                   # 42 个内核 patch + linux.mk + linux_ilp32/
│   └── package/                 # Canaan 自有包 + 被改动的上游包
├── tools/                       # 构建脚本、Docker、下载器等
├── docs/                        # 文档(部分内容已过时)
├── dl/                          # 下载缓存(gitignore)
└── output/                      # 全部构建产物(gitignore)
    ├── buildroot-2025.02.1/     #   原始 Buildroot + overlay 合并后的源码树
    └── <defconfig>/             #   每个配置一个独立的 O= 输出目录

test/ 和 df/ 在 .gitignore 中,是开发者本地的临时目录,不属于 SDK。


5. 构建系统原理

理解这一节能省掉大量"改了文件没生效"的困惑。

5.1 核心:下载 + rsync 覆盖,而非 BR2_EXTERNAL

本 SDK 没有使用 Buildroot 的 BR2_EXTERNAL 机制。流程如下(实现见 tools/sync.mk):

  1. 下载:从 BR2_PRIMARY_SITE 或 buildroot.org 下载 buildroot-2025.02.1.tar.xz 到 dl/,校验 sha256(tools/download/buildroot.hash)。
  2. 解压:解压到 output/buildroot-2025.02.1/,随后删除 package/python3 和 package/ffmpeg(overlay 会提供自己的版本)。
  3. 覆盖:
    rsync -a buildroot-overlay/ output/buildroot-2025.02.1/ --exclude "*-overlay" --exclude "linux-6.6.22"
  4. 配置:make -C output/buildroot-2025.02.1 <defconfig> O=$(CURDIR)/output/<defconfig>
  5. 编译:make -C output/<defconfig> all

所以 buildroot-overlay/ 里的每个文件都会按同名路径覆盖原始 Buildroot 的对应文件。改 overlay 后重新 make 会自动重新 rsync。

坑:rsync 没有 --delete。你在 overlay 里删除一个文件,output/ 里的旧副本不会消失,需要 make clean。唯一的例外是 linux/*.patch,sync.mk 有专门的清理逻辑(否则同号 patch 会重复应用导致失败)。

5.2 三套不同的"打补丁"方式

这是本 SDK 最容易混淆的地方——三个组件用了三种机制:

组件 机制 位置
Buildroot 自身 rsync 整目录覆盖 buildroot-overlay/*
Linux 内核 .patch 文件,Buildroot 按字母序自动应用 buildroot-overlay/linux/*.patch(42 个)
U-Boot / OpenSBI rsync 整目录覆盖(整文件替换/新增) boot/uboot/u-boot-2022.10-overlay/、boot/opensbi/opensbi-1.4-overlay/

U-Boot / OpenSBI 的 overlay 由 uboot.mk / opensbi.mk 中额外添加的 .overlay_sync 规则驱动,插在 .stamp_patched 和 .stamp_configured 之间。output/.uboot_overlay_sync、output/.opensbi_overlay_sync 两个 stamp 文件负责触发重编。

5.3 配置粘滞:.last_conf

当前选中的配置记录在仓库根目录的 .last_conf 文件里(内容形如 CONF=k230_canmv_defconfig)。未显式传 CONF= 时,Makefile 会 include 它。默认值是 k230_canmv_defconfig。

5.4 未在 Makefile 中定义的目标会转发给 Buildroot

Makefile 有一条 catch-all 规则:任何它不认识的目标都会原样转发到 make -C output/$(CONF) <目标>。这就是 make linux-rebuild、make menuconfig、make <包名>-dirclean 能工作的原因——它们都是 Buildroot 的标准目标。

5.5 下载镜像源

BR2_PRIMARY_SITE 由 tools/download/get_fast_url.sh 在两个镜像之间测速自动选择:

  • https://ai.b-bug.org/k230/downloads/dl(内网)
  • https://download.kendryte.com/k230/downloads/dl(公网)

可手动覆盖:make BR2_PRIMARY_SITE=https://download.kendryte.com/k230/downloads/dl。


6. make 命令速查

# ---- 配置 ----
make list_def                       # 列出所有可用配置和当前配置
make k230d_canmv_defconfig          # 选择配置
make menuconfig                     # 修改 SDK 配置
make savedefconfig                  # 保存配置回 buildroot-overlay/configs/

# ---- 编译 ----
make source                         # 预下载全部源码包
make                                # 全量编译
make clean                          # 交互确认后 rm -rf output/ 并重新配置

# ---- 单个包 ----
make <pkg>                          # 编译某个包
make <pkg>-rebuild                  # 强制重编
make <pkg>-dirclean                 # 清理该包的构建目录
make <pkg>-reconfigure              # 重新 configure 后编译
make <pkg>-source                   # 只下载源码

# ---- 内核 ----
make linux-menuconfig               # 修改内核配置
make linux-savedefconfig            # 保存内核配置(同时拷贝到 ./linux_defconfig)
make linux-rebuild
make linux-dirclean

# ---- U-Boot ----
make uboot-menuconfig
make uboot-rebuild
make uboot-dirclean

# ---- 发行版 ----
sudo make debian                    # 生成 Debian 13 镜像
sudo make ubuntu                    # 生成 Ubuntu 24.04 镜像
make debian_rootfs                  # 只打印 debootstrap 配方,不构建

# ---- 其它 ----
make toolchain_and_depend           # 安装工具链和依赖(需 sudo)
make ddr_test_img_1024              # 生成 DDR 压力测试镜像(128/512/1024/2048)
make help                           # SDK 帮助 + 完整 Buildroot 帮助

6.1 并行编译与 ccache

  • 并行度:所有 defconfig 都未设置 BR2_JLEVEL,Buildroot 默认使用 nproc+1。顶层 make 不传 -j。如需限制,用 make menuconfig → Build options → Number of jobs。
  • ccache:未默认启用。可在 make menuconfig → Build options → Enable compiler cache 打开,缓存默认在 ~/.buildroot-ccache。

6.2 用外部内核源码树编译

如果你想用自己 clone 的内核源码而不是 Buildroot 拉取的:

echo "LINUX_OVERRIDE_SRCDIR=/path/to/your/linux" > output/<defconfig>/local.mk
make linux-rebuild

7. 启动链与镜像布局

7.1 启动链

BootROM
  └─> SPL (fn_u-boot-spl.bin)              TEXT_BASE 0x80300000,负责 DDR 初始化
        └─> U-Boot (fn_ug_u-boot.bin)      gzip + uImage + K230 固件头
              └─> OpenSBI 1.4 fw_jump      加载到 0x3000000
                    └─> Linux Image        加载到 0x200000,DTB 到 0x2200000
                          bootm 0x3000000 - 0x2200000

SPI-NAND/NOR 启动时,OpenSBI + Linux + DTB 被预先合并为单个 linux_system.bin。

fn_ 前缀由 tools/firmware_gen_no_securiy.py -n 添加的 K230 固件头产生;启用 CONFIG_GEN_SECURITY_IMG 时还会生成 fs_(国密 SM)和 fa_(AES)变体。

7.2 SD / eMMC 分区布局

由 board/canaan/k230-soc/genimage_cfg/genimage.cfg 定义,MBR 分区表:

区域 偏移 大小 内容 在 MBR 表中
uboot_spl_1 1 MiB 文件大小 fn_u-boot-spl.bin 否
uboot_spl_2 1.5 MiB 文件大小 SPL 冗余副本 否
uboot 2 MiB 文件大小 fn_ug_u-boot.bin 否
uboot_env_a 3 MiB 0x20000 env.env 否
uboot_env_b 3.125 MiB 0x20000 env 冗余副本 否
boot 4 MiB 80 MiB boot.ext4 是(p1)
rootfs 128 MiB 剩余全部 rootfs.ext4 是(p2)

设备上即 /dev/mmcblkXp1 = boot 分区,/dev/mmcblkXp2 = 根文件系统。

boot 分区内容:Image(及 Image_ilp32)、全部 *.dtb、fw_jump_add_uboot_head.bin、可选的 logo.yuv 和 NuttX 固件,以及 DTB 选择文件 force_dtb 或 lcd_dtb+hdmi_dtb。

首次启动自动扩容:/etc/init.d/S00resizemmc 会从 /proc/cmdline 解析根设备,写出 /etc/fw_env.config(指向 3MiB 处的 env 分区),然后 parted resizepart 2 + resize2fs 把 rootfs 撑满整张卡,最后删除 /first_boot_flag。

7.3 SPI-NAND 分区布局

genimage_nand.cfg,flash 类型 spinand-128M(pebsize 128K,lebsize 124K,1024 blocks):

分区 偏移 大小 内容
uboot_spl_a/b 0 / 512K 512K each swap_fn_u-boot-spl.bin(字节序交换版)
uboot_a/b 1M / 2M 1M each fn_ug_u-boot.bin
uboot_env_a/b 3M / 3.125M 0x20000 each nand_env.env
linux 4M 16M linux_system.bin
rootfs_ubi 20M 100M rootfs.ubi(内含 96M UBIFS)

与 k230-evb.dts 中的 MTD 表一一对应:rootfs_ubi 是 mtd7,env_a 是 mtd4。NAND 启动的默认 bootargs 为 ubi.mtd=7 rootfstype=ubifs rw root=ubi0_0。

SPI-NOR 镜像(genimage_nor.cfg)当前不会生成 —— post-image.sh 中相关调用已被注释,即使 BR2_CANAAN_GEN_SPI_NOR_IMG=y。

7.4 bootargs 的来源与优先级

内核命令行由 board/canaan/common/k230_img.c: board_fdt_chosen_bootargs() 按以下优先级决定:

  1. U-Boot 环境变量 bootargs(若已设置)
  2. 板级覆盖 fdt_chosen_bootargs() —— 目前只有 k230d_canmv_junroc_ai_cam 用到
  3. 按启动介质的默认值:
    • SDIO0 → root=/dev/mmcblk0p2 rw rootwait rootfstype=ext4 console=ttyS0,115200 earlycon=sbi
    • SDIO1 → 同上,但 mmcblk1p2
    • NAND/NOR → ubi.mtd=7 rootfstype=ubifs rw root=ubi0_0 console=ttyS0,115200 earlycon=sbi

部分 K230D 的内核 DTS 自带 chosen/bootargs;K230 CanMV/EVB/01studio 的 DTS 只设置 stdout-path,完全依赖 U-Boot。

7.5 自定义 U-Boot 命令

实现在 board/canaan/common/k230_board_common.c:

命令 说明
k230_boot <介质> <目标> 介质:auto|sdio0|sdio1|spinor|spinand|mem;目标:auto_boot|linux|uboot|...
k230_set_dtb 运行时选择 DTB,见 8.4
boot_baremetal <core> <addr> <size> 启动裸机固件(NuttX 用它)
k230_gpio GPIO 操作
reboot_to_upgrade 进入 USB 烧录模式

7.6 进入 USB 烧录模式

# 从 Linux
/bin/reboot_to_upgrade          # 等价于 devmem 0x80230000 32 0x5aa5a55a; reboot

# 从 U-Boot
reboot_to_upgrade

configs/ 下的 *_burntool_defconfig 系列 U-Boot 配置就是烧录模式使用的 RAM 常驻镜像(SYS_TEXT_BASE=0x80300000、无 SPL、bootdelay=1 并支持 stop 键中断)。

7.7 网络恢复

U-Boot 下可用 TFTP 刷机:

run upsdimg      # 刷整个 SD 镜像
run upsduboot    # 只刷 U-Boot
run upspiimg     # 刷 SPI flash 镜像
run upspiuboot   # 刷 SPI flash 的 U-Boot

8. 内核与设备树

8.1 内核源码

所有 15 个配置使用同一份内核:

BR2_LINUX_KERNEL_CUSTOM_GIT=y
BR2_LINUX_KERNEL_CUSTOM_REPO_URL="https://github.com/ruyisdk/linux-xuantie-kernel.git"
BR2_LINUX_KERNEL_CUSTOM_REPO_VERSION="7d4e1f444f461dbe3833bd99a4640e7b6c2cd529"
BR2_LINUX_KERNEL_DEFCONFIG="k230"

版本为 Linux 6.6.36,模块安装到设备的 /lib/modules/6.6.36/updates/。

内核 defconfig 也只有一个:arch/riscv/configs/k230_defconfig。板级差异完全靠 DTS + kconfig 片段实现,不存在每板一个 defconfig。

8.2 kconfig 片段

位于 board/canaan/k230-soc/fragment/,由 defconfig 的 BR2_LINUX_KERNEL_CONFIG_FRAGMENT_FILES 叠加:

片段 内容 使用者
linux.fragment 蓝牙=m、USB gadget configfs(FFS/mass-storage/RNDIS/ACM)、V4L2 + videobuf2-dma-contig、PINCTRL_K230_IOMUX、TOUCHSCREEN_ST1232、5 路 8250 串口、UBIFS 所有非 ilp32 配置
linux.led_btn KEYBOARD_GPIO、LEDS_GPIO 带按键/LED 的 K230 板
linux_cam.fragment CONFIG_CMA_SIZE_PERCENTAGE=30(默认 50) 128MB 内存的 K230D 板
busybox.fragment CONFIG_UDHCPD=y 需要 AP 模式的板

两个 ilp32 配置不应用任何片段。

8.3 内核 patch

buildroot-overlay/linux/ 下有 42 个 .patch,由 Buildroot 标准规则按字母序自动应用(没有设置 BR2_LINUX_KERNEL_PATCH)。主要分类:

  • 板级支持:0007-add-gt6700-board、0011-01studio-base-board、0014-01studio-base-emmc-hdmi、0024-add-junroc-board、0028-handuan-mrt、0034-dts-add-k230-canmv-huskylens、0008-zero-enable_wifi
  • Pinctrl:0018-pinctrl-canaan-Add-K230-IOMUX-driver、0019-...-Simplify-driver-by-using-pinctrl_desc
  • 时钟/电源:0014-Add-clock-and-power-domain-support-for-AI-components、0017-clk-k230-Fix-AI-clock-rate-setting-and-multiplexer
  • 显示:0001-modify-lt9611-for-k230(HDMI bridge)、0005-uboot-display-logo、0010-add-ili9881-lcd、0023-add-gdma-vo-rotation
  • 音频:0033-ASoC-canaan-k230-inno-runtime-codec-route-sdi1-capture、0034-ASoC-inno_k230-add-ADC-digital-volume-control、0035-ASoC-canaan-add-PDM-microphone-capture
  • DMA/安全:0029-canaan-add-harden-DMA-address-validation、0032-dma-k230_peridma-allow-special-src-dst-addrs-in-range-check
  • 存储:0034-mtd-nand-spi-add-w25n01gw-support-and-spi-driver-fix、0036-riscv-dts-canaan-swap-mmc0-mmc1-aliases
  • 电源管理:riscv-Introduce-system-suspend-support.patch(SBI SUSP 扩展,无编号,排序最后)

patch 编号存在重复(两个 0010-、两个 0014-、三个 0034- 等)。由于按文件名字母序应用,结果仍然确定,但新增 patch 时要留意。

8.4 设备树:两套命名,别搞混

U-Boot DTS 内核 DTS
位置 boot/uboot/u-boot-2022.10-overlay/arch/riscv/dts/ 内核源码树 arch/riscv/boot/dts/canaan/
命名 下划线,无前缀,如 k230_canmv_01studio.dts 连字符,带 canaan/ 前缀,如 canaan/k230-canmv-01studio.dts
选择方式 U-Boot defconfig 的 CONFIG_DEFAULT_DEVICE_TREE defconfig 的 BR2_LINUX_KERNEL_INTREE_DTS_NAME
修改方式 overlay 整文件替换 buildroot-overlay/linux/*.patch

板子 → 内核 DTS 对照

defconfig BR2_LINUX_KERNEL_INTREE_DTS_NAME
k230_canmv canaan/k230-canmv canaan/k230-canmv-lcd
k230_canmv_v3 canaan/k230-canmv-v3-lcd canaan/k230-canmv-v3
k230_canmv_01studio canaan/k230-canmv-01studio-lcd canaan/k230-canmv-01studio
k230_canmv_01studio_emmc canaan/k230-canmv-01studio-emmc-lcd canaan/k230-canmv-01studio-emmc
k230_canmv_lckfb canaan/k230-canmv-lckfb-lcd canaan/k230-canmv-lckfb
k230_canmv_dongshanpi canaan/k230-canmv-dongshanpi
k230_canmv_gt6700 canaan/k230-canmv-gt6700
k230_canmv_mrt canaan/k230-canmv-mrt-lcd
k230_canmv_huskylens canaan/k230-canmv-huskylens
k230_evb canaan/k230-evb
k230d_canmv(含 ilp32) canaan/k230d-canmv
k230d_canmv_junroc_ai_cam canaan/k230d-canmv-junroc-ai-cam
BPI-CanMV-K230D-Zero(含 ilp32) canaan/bananapi-canmv-k230d-zero

DTB 的运行时选择

当一个板子配置了两个 DTS(通常是 LCD 版和 HDMI 版),post-image.sh 会往 boot 分区写入两个纯文本文件 lcd_dtb 和 hdmi_dtb,各自记录对应的 DTB 文件名;只有一个 DTS 时写 force_dtb。

U-Boot 的 k230_set_dtb 命令在启动时:

  1. 若 boot 分区存在 /force_dtb → 直接使用其中记录的 DTB。
  2. 否则探测 I²C 总线(CONFIG_K230_HDMI_LCD_I2C_BUS,默认 3,CanMV 上为 4):地址 0x38 有响应 → LCD,用 /lcd_dtb;地址 0x3b 有响应 → HDMI,用 /hdmi_dtb;都没有则回退 LCD。
  3. 结果写入 dtb 环境变量并 env_save() 持久化。

8.5 内存布局

没有 reserved-memory 节点 —— 所有大块媒体缓冲都来自 CMA:

  • k230_defconfig:CONFIG_CMA_SIZE_SEL_PERCENTAGE=y,CONFIG_CMA_SIZE_PERCENTAGE=50
  • 128MB 的 K230D 板通过 linux_cam.fragment 降到 30%

此外还有 MMZ(Media Memory Zone):内核内建驱动 drivers/misc/canaan/mmz/mmz.c(CONFIG_K230_MMZ=y),字符设备 /dev/mmz,ioctl MMZ_ALLOC_MEM / MMZ_FREE_MEM。用户态封装是 package/libmmz(静态库 libmmz.a + mmz.h,内含 C908 的 dcache clean/invalidate 内联汇编)。

8.6 NuttX 裸机共存

env/default.env 中定义:

nuttex=nuttx-7000000-uart2.bin
bnuttx=ext4load mmc ${mmc_boot_dev_num}:1 0x7000000 /${nuttex} && boot_baremetal 0 0x${fileaddr} 0x${filesize};

固件随 rootfs overlay 一起放在 boot 分区。默认 bootcmd=run blinux 走 Linux,NuttX 需在 U-Boot 命令行手动 run bnuttx。


9. 驱动与硬件支持

9.1 内核内建的 Canaan 驱动

由 k230_defconfig 默认开启:

配置项 硬件
K230_GNNE_DRIVER KPU / NPU
K230_AI2D_DRIVER AI2D 二维预处理加速器
K230_MMZ 媒体内存池 /dev/mmz
VPU_CANAAN Arm Linlon (MVX) 视频编解码器
GPU_VGLITE VeriSilicon GCNanoLiteV 矢量 GPU
COMMON_CLK_K230 / k230-power-domains 时钟与电源域
GPIO_K230 / PWM_K230 / K230_ADC 基础外设
K230_PERIDMA 外设 DMA
DRM_LONTIUM_LT9611 HDMI 桥接芯片
MMC_SDHCI_OF_DWCMSHC_KENDRYTE SD/eMMC 控制器
SND_SOC_CANAAN_K230_* 音频(I2S + inno codec + 新增 PDM)
k230-gdma 图形 DMA(用于旋转)

9.2 树外内核模块(buildroot 包)

使用 Buildroot kernel-module 基础设施,安装到 /lib/modules/6.6.36/updates/:

包 菜单选项 驱动的硬件 产出模块
vvcam BR2_PACKAGE_VVCAM MIPI CSI-2 接收器 + VeriSilicon ISP8000 vvcam_mipi、vvcam_isp、vvcam_vb、vvcam_video、vvcam_isp_subdev
nonai2d BR2_PACKAGE_NONAI2D K230 非 AI 的 2D 引擎(缩放/旋转/合成,暴露为 V4L2 M2M 设备) nonai2d
k230_noc BR2_PACKAGE_K230_NOC NoC 互联性能探针与 QoS noc
bcmdhd BR2_PACKAGE_BCMDHD Broadcom BCM43438 SDIO WiFi bcmdhd
aic8800 BR2_PACKAGE_AIC8800 AICSemi AIC8800 系列(USB) aic_load_fw、aic8800_fdrv、aic_btusb
aic8800_sdio BR2_PACKAGE_AIC8800_SDIO AIC8800D80(SDIO) aic8800_bsp、aic8800_fdrv
rtl8733bs BR2_PACKAGE_RTL8733BS Realtek RTL8733BS(SDIO WiFi + UART BT) 8733bs

vvcam 比较特殊:它同时是 kernel-module 和 cmake-package,除内核模块外还提供用户态库和 isp_media_server。默认 sensor 由字符串选项 BR2_PACKAGE_VVCAM_DEF_SENSOR 指定(默认 ov5647)。

k230_noc 用法:

modprobe noc
echo kpu > /sys/devices/platform/k230-noc/probe
cat /sys/devices/platform/k230-noc/probe

9.3 纯用户态的硬件相关包

内核侧驱动在树内,这些包只提供用户态库/工具:

包 菜单选项 说明
libmmz BR2_PACKAGE_LIBMMZ /dev/mmz 的用户态封装,静态库
vg_lite BR2_PACKAGE_VG_LITE VGLite GPU 用户态库;_DEMOS 额外装 vglite_drm/tiger/cube 等
mvx_player BR2_PACKAGE_MVX_PLAYER VPU 编解码 demo:mvx_encoder、mvx_decoder(+_multi)
display BR2_PACKAGE_DISPLAY libdrm 抽象层 libdisplay.so,几乎所有 AI demo 都依赖它
vo_init BR2_PACKAGE_VO_INIT 视频输出/DRM plane 初始化,由 S31canaan_isp 拉起
uvc-gadget BR2_PACKAGE_UVC_GADGET USB UVC 摄像头 gadget(带 VPU 编码支持 patch)

9.4 模块开机加载

系统是 BusyBox sysvinit(不是 systemd),没有 /etc/modules 或 /etc/modules-load.d。模块加载分散在 init 脚本里:

脚本 作用
/etc/init.d/S01mdev 启动 mdev -d;mdev_video.sh 为 V4L2 节点创建稳定软链接 /dev/video_nonai_2d、/dev/video_vpu
/etc/init.d/S31canaan_isp 摄像头栈,按依赖顺序 modprobe:vvcam_isp → vvcam_mipi → vvcam_vb → vvcam_isp_subdev → vvcam_video mcm_mask=1 → nonai2d,然后后台启动 isp_media_server 和 vo_init;同时挂载 boot 分区到 /boot
/etc/init.d/S40<CONF> 构建时生成的 WiFi/BT 模块加载脚本,见下
/etc/init.d/S41adb_mtp 加载 libcomposite/usb_f_fs,配置 ADB + MTP USB gadget(VID 0x29F1、PID 0x0105)

S40<CONF> 由 board/canaan/k230-soc/post-build.sh 的 auto_boot_proc() 根据 .config 生成:

启用的包 生成的命令
BR2_PACKAGE_BCMDHD modprobe bcmdhd
BR2_PACKAGE_RTL8733BS modprobe 8733bs
BR2_PACKAGE_AIC8800 modprobe aic_load_fw; modprobe aic8800_fdrv; modprobe aic_btusb
BR2_PACKAGE_AIC8800_SDIO modprobe aic8800_bsp aic_fw_path=/lib/firmware/aic8800D80; modprobe aic8800_fdrv

此外,字符串选项 BR2_CANAAN_AUTO_RUN_CMD(menuconfig → canaan package → auto run cmd)里写的任何命令都会被追加进这个脚本,是最简单的"开机自启"入口。


10. WiFi 与蓝牙

10.1 各板 WiFi 方案

defconfig WiFi 驱动包 芯片 总线 蓝牙
k230_canmv BCMDHD BCM43438 SDIO bluez5-utils
k230_canmv_v3 AIC8800 + RTL8733BS 两者兼容 USB / SDIO bluez5
k230_canmv_01studio RTL8733BS RTL8733BS SDIO BLUEZ_INC + BLUEZ_ALSA,BT 走 ttyS1
k230_canmv_01studio_emmc RTL8733BS RTL8733BS SDIO bluez5
k230_canmv_mrt RTL8733BS RTL8733BS SDIO bluez5
k230_canmv_dongshanpi AIC8800 AIC8800 USB aic_btusb
k230_canmv_lckfb AIC8800 AIC8800 USB aic_btusb
k230_canmv_huskylens AIC8800 AIC8800 USB aic_btusb
k230_canmv_gt6700 / k230_evb — — — —
K230D 系列 — SDIO0 已在 DTS 使能,但未选任何驱动包 SDIO 仅 wpa_supplicant

只有 k230-canmv.dts 在设备树里显式声明了 WiFi 子节点:

&mmc_sd0 {
    io_fixed_1v8;
    rx_delay_line = <0x0d>;
    tx_delay_line = <0x00>;
    bcmdhd_wlan {
        compatible = "android,bcmdhd_wlan";
        gpio_wl_reg_on = <&gpio0_ports 1 GPIO_ACTIVE_HIGH>;
    };
};

其它板子只是通用地 enable mmc_sd0,由厂商模块在运行时探测 SDIO 卡。

10.2 连接 WiFi(STA 模式)

方式一:命令行脚本

sta.sh wlan0 <SSID> <密码>

脚本位于 rootfs overlay 的 /bin/sta.sh,内部通过 wpa_cli 添加网络并连接。

方式二:ifup 自动连接(读 U-Boot 环境变量)

/etc/network/interfaces 中 iface wlan0 inet dhcp 的 pre-up 会在 ifup 时用 fw_printenv 读取 U-Boot 环境变量,动态生成 /tmp/wpa_supplicant.conf:

fw_setenv wlanssid  "你的SSID"
fw_setenv wlanpass  "你的密码"
ifup wlan0

镜像中 wlanssid / wlanpass 带有开发期的默认值,请务必改成自己的。fw_setenv 依赖 /etc/fw_env.config,该文件由 S00resizemmc 在首次启动时自动生成。

10.3 AP 模式

ap.sh wlan0 <SSID> <密码> [g|a|ac|b]

/bin/ap.sh 会拉起 hostapd + udhcpd,DHCP 地址池 192.168.10.20 - 192.168.10.160。

10.4 蓝牙

以 01studio 板为例(脚本 /root/script/bluetooth.sh):

hciattach -s 1500000 /dev/ttyS1 any 1500000 flow nosleep
bluealsa -p a2dp-source -p hsp-hs &
bluetoothctl              # 然后 power on / scan on / pair / connect

AIC8800 走 USB 蓝牙(aic_btusb),无需 hciattach。


11. 菜单结构(menuconfig)

make menuconfig → Target packages → 第一项即 canaan package。全部 Canaan 私有选项都在这里(定义于 buildroot-overlay/package/Config_canaan.in)。

Target packages
└── canaan package
    ├── AI
    │   ├── AI demo
    │   │   ├── [ ] all ai demo                 BR2_PACKAGE_AI_DEMO_ALL
    │   │   └── 48 个单独的 demo 开关
    │   ├── [ ] libmmz
    │   ├── [ ] nncase runtime                  BR2_PACKAGE_LIBNNCASE
    │   ├── [ ] face detect demo
    │   ├── [ ] ai2d kpu test case
    │   ├── [ ] yolo demo
    │   └── [ ] usage_ai2d
    ├── [ ] AIC8800 / AIC8800 SDIO / BCMDHD / RTL8733BS      # WiFi
    ├── [ ] bluez inc
    ├── [ ] helloworld cmake                                # 用户程序模板
    ├── [ ] K230 ISP server                     BR2_PACKAGE_VVCAM
    │       └── ( ov5647 ) default sensor
    ├── [ ] audio demo / audio_rec_play
    ├── [ ] RTSP Server Library / Camera RTSP Demo
    ├── [ ] webrtc (libpeer) / Camera WebRTC Demo
    ├── [ ] mvx player
    ├── [ ] VGLite GPU user-space library / VGLite GPU demos
    ├── [ ] LVGL demo and library
    │       └── ( 97a99a8a… ) lvgl version
    ├── [ ] libdrm abstruct library for display / vo_init
    ├── [ ] k230 noc / nonai2d
    ├── [ ] llama.cpp
    │       ├── [*] Enable tools
    │       ├── [*] Enable server
    │       └── [ ] Vulkan support
    ├── [ ] uvc-gadget
    ├── [ ] python-adafruit-blinka / platformdetect / pureio
    ├── < > python-k230
    ├── [ ] gsl-lite
    ├── (   ) auto run cmd                      BR2_CANAAN_AUTO_RUN_CMD
    ├── [ ] generate spi nand image             (默认 n)
    ├── [ ] generate spi nor image              (默认 n)
    └── [*] generate TF/EMMC image              (默认 y)

注意:LVGL 在 canaan package 下,不在 Graphics 菜单里。OpenCV4 / FFmpeg / Python3 等是被 overlay 打过补丁的上游包,仍在各自的标准菜单位置。


12. AI 开发

12.1 推理运行时:nncase

组件 版本 来源
nncase runtime(C++) 2.11.0 libnncase 包从 nncase releases 下载 nncase_k230_v2.11.0_runtime_linux.tgz
Python 绑定 2.11.0 由 python-k230 自行编译;若未启用 python-k230,则下载预编译 wheel
kmodel 模型包 v2.10.0 ai_demo/common/common.mk 下载 kmodel_v2.10.0.tgz

安装到 staging 后提供 CMake 包 nncaseruntime 和 nncase_rt_modules_k230,应用侧直接 find_package(nncaseruntime) 即可。

版本存在轻微错位:buildroot 内的 kmodel 包是 v2.10.0,而独立构建脚本 ai_demo/build.sh 下载的是 v2.11.0。两者应向后兼容,但如遇奇怪的推理结果可以留意这一点。

12.2 AI demo(48 个)

源码位于 buildroot-overlay/package/ai_demo/。

默认只启用少数 demo:BR2_PACKAGE_AI_DEMO_ALL 在 15 个 defconfig 中全部为 off,只有 object_detect_yolov8n 在 7 块 K230 板上默认开启。其余全部需要手动勾选。

make menuconfig
# Target packages → canaan package → AI → AI demo →
#   [*] all ai demo          # 一次性全开
#   或按需勾选单个 demo

单独编译某个 demo:

make face_detection-dirclean
make face_detection

设备上运行:所有 demo 安装到 /root/app/<demo名>/,目录内含 .elf、.kmodel、测试图片和运行脚本。命名约定:*_image.sh 用静态图片输入,*_isp.sh 用摄像头实时输入。

cd /root/app/face_detection/
ls
# face_detect_image.sh  face_detection_320.kmodel
# face_detect_isp.sh    face_detection_640.kmodel
# face_detection.elf
./face_detect_isp.sh

demo 清单

人脸相关(12)
目录 功能
face_detection 人脸检测(RetinaFace,320/640 两种输入)
face_alignment 3DDFA 三维人脸对齐
face_mesh 三维人脸网格渲染
face_landmark 106 点稠密关键点
face_pose 头部姿态(roll/yaw/pitch)
face_emotion 表情识别
face_gender 性别识别
face_glasses 是否戴眼镜
face_mask 是否戴口罩
face_parse 人脸语义分割
face_verification 1:1 人脸比对(与证件照)
eye_gaze 视线方向估计
手势交互(11)
目录 功能
sq_hand_det 手掌检测
sq_handkp_det 手部关键点检测
sq_handkp_class 基于关键点的静态手势分类
sq_handreco 静态手势识别(专用分类器)
sq_handkp_flower 指向花朵 → 花卉识别
sq_handkp_ocr 手指指向 → OCR 识字
dynamic_gesture 动态手势识别(TSM)
finger_guessing 猜拳游戏
puzzle_game 隔空拼图游戏
space_resize 隔空捏合缩放
virtual_keyboard 隔空虚拟键盘
人体 / 行为(10)
目录 功能
person_detect 行人检测
person_distance 行人检测 + 单目测距
person_attr 行人属性识别(PULC)
head_detection 人头检测与计数(YOLOv8)
pose_detect 人体姿态关键点
fitness 健身动作计数与姿态评估
falldown_detect 跌倒检测
smoke_detect 吸烟行为检测
helmet_detect 安全帽佩戴检测
pphumanseg 人像分割 / 抠图
车辆 / ADAS(6)
目录 功能
licence_det 车牌检测
licence_det_rec 车牌检测 + 车牌识别
vehicle_attr 车辆检测 + 属性识别
traffic_light_detect 红绿灯检测
crosswalk_detect 斑马线检测
yolop_lane_seg YOLOP 车道线 + 可行驶区域分割
通用视觉(6)
目录 功能
object_detect_yolov8n YOLOv8n 目标检测(默认启用)
segment_yolov8n YOLOv8n 实例分割
bytetrack ByteTrack 多目标跟踪
ocr 文字检测(DBNet)+ 识别(CRNN),含中文字库
anomaly_det PatchCore 无监督异常检测(瓶口缺陷)
demo_mix 组合 demo:手势 + 人脸姿态 + NanoTrack 单目标跟踪
语音 / 语言(3)
目录 功能
kws 关键词唤醒(默认唤醒词"小楠")
tts_zh 中文语音合成(FastSpeech ×2 + HiFiGAN)
llamac llama2.c 风格的英文续写(不用 KPU,纯 CPU)

12.3 独立 AI 包

包 说明
yolo 统一 YOLO 推理工具,支持 yolov5 / yolov8 / yolo11 / yolo26 × classify / detect / segment / obb × image / video。模型在树内(yolo/utils/*.kmodel)。见 package/yolo/README.md
face_detect 精简版人脸检测(12/15 配置默认启用),模型在树内
ai2d_kpu AI2D → KPU 串联冒烟测试(14/15 配置默认启用)
usage_ai2d AI2D API 用法示例:affine / crop / pad / resize / shift

12.4 在 Buildroot 之外编译 AI demo

ai_demo/build.sh 提供了脱离 Buildroot 的快速编译路径:它读取 .last_conf,从 output/<CONF>/ 推导工具链和 sysroot,下载 kmodel 包,然后把所有 demo 编译到 ./k230_bin/。适合只改 demo 代码、不想跑整个 Buildroot 的场景。

package/yolo/build_app.sh 和 package/cloudplat_deploy_code_linux/build.sh 同理。

12.5 在线训练平台部署代码

package/cloudplat_deploy_code_linux/ 是嘉楠在线训练平台产出模型的配套部署代码,提供 8 类任务模板:classification、detection、segmentation、ocr_detection、ocr_recognition、ocr(检测+识别)、metric_learning、multilabel_cls。该目录不在 menuconfig 中,用自带的 build.sh 编译。


13. Python 开发

13.1 Python 环境

  • 解释器:Python 3.13.3(package/python3/,overlay 带 8 个补丁)
  • 设备上路径:/usr/lib/python3.13/site-packages
  • 默认启用的模块(以 k230_canmv_defconfig 为例):pip、paho-mqtt、periphery、cv2(OpenCV LIB_PYTHON)、numpy

13.2 python-k230

BR2_PACKAGE_PYTHON_K230 —— 本 SDK 的核心 Python 硬件绑定包,10/15 配置默认启用(k230_evb、gt6700、huskylens 和两个 ilp32 配置除外)。

提供的模块:

模块 能力
nncaseruntime KPU 推理 + AI2D 预处理。Interpreter:load_model / set_input_tensor / run / get_output_tensor / get_input_shape / set_profiling;AI2D:set_crop/shift/pad/resize/affine param + build + run
k230_v4l2_drm 摄像头 + 显示。类 V4l2Drm:drm_init / setup / set_crop / set_rotation / set_flip / get_buffer_array(返回 numpy)/ display_start/stop / dump_frame / OSD 相关 set_osd_format、osd_update
k230_display 简易 DRM 显示:init() / show() / get_width() / get_height() / deinit()
lvgl LVGL v9 Python 绑定:import lvgl as lv,lv.init()、lv.display_create()、lv.screen_active()、控件类、btn.on(lv.EVENT.CLICKED, cb)、lv.run()
k230.iomux 引脚复用配置,通过 /dev/mem mmap 操作 IOMUX 寄存器:get_pin_functions / set_pin_function / set_pin_config(ie/oe/pu/pd/ds/st)。附带命令行工具 k230-iomux

LVGL 版本强绑定:python-k230.mk 硬性要求 BR2_PACKAGE_LVGL_CUSTOM_VERSION 为 97a99a8affe966617f048830a007bbf8bea63da6,否则直接 $(error) 中止编译(它依赖该版本的 lvgl_private 头文件)。

13.3 设备端示例代码

启用 python-k230 后,示例会被安装到设备的 /root/py_demo/(约 111 个文件):

/root/py_demo/
├── ai/                  nncaseruntime_test.py, yolo_display.py,
│                        yolo_v4l2_drm.py, face_detect.py
├── lvgl/
│   ├── basic/           ~25 个控件示例
│   └── quick/           quick_camera_osd.py, quick_camera_rotation.py,
│                        lvgl_yolo_demo.py, lvgl_ai_change.py,
│                        lvgl_python_benchmark.py
├── gpio_led_button/  i2c/  spi/  uart/  pwm/  net/  utest/
├── analog_in.py
└── iomux_test.py

13.4 CircuitPython / Adafruit Blinka(可选)

三个包,默认全部关闭,需在 menuconfig 中手动启用:

包 提供
python-adafruit-blinka CircuitPython 风格 API:board、digitalio、busio、pwmio
python-adafruit-platformdetect 板卡/芯片自动识别(已加 K230 支持补丁)
python-adafruit-pureio 纯 Python 的 ioctl / I2C / SPI 后端

13.5 Python 硬件 API 总览

领域 模块 来源
KPU 推理 nncaseruntime.Interpreter python-k230
AI2D 硬件预处理 nncaseruntime.AI2D python-k230
摄像头 + DRM 显示 + OSD k230_v4l2_drm.V4l2Drm python-k230
GUI lvgl python-k230
引脚复用 k230.iomux / k230-iomux python-k230
GPIO/I²C/SPI/PWM(CircuitPython 风格) board digitalio busio pwmio adafruit-blinka
GPIO/I²C/SPI/PWM(POSIX 风格) periphery python-periphery
计算机视觉 cv2 numpy opencv4 / python-numpy
MQTT paho.mqtt 上游包

14. 多媒体与图形

组件 版本 / 选项 说明
OpenCV 4.10.0,BR2_PACKAGE_OPENCV4 overlay 带玄铁 RVV 优化补丁;默认开启 HIGHGUI、LIB_PYTHON、VIDEO、FFMPEG、V4L、contrib
FFmpeg 4.4.4 13 个补丁,其中 K230 相关的有:VPU 支持、v4l2-m2m 编码、DSL 解码、v4l2 dmabuf、nonai2d OSD filter、VPU v4l2 格式、MJPEG QP
LVGL 默认 commit 97a99a8a…(v9) 三个可选版本分支:8.3.7、59dc7e43…、97a99a8a…。注意菜单在 canaan package 下
VGLite BR2_PACKAGE_VG_LITE 矢量 GPU 用户态库,15/15 配置默认开启 demos
VPU / mvx_player BR2_PACKAGE_MVX_PLAYER Arm Linlon 编解码器,15/15 默认开启
display BR2_PACKAGE_DISPLAY libdrm 抽象层,导出 pkg-config display.pc
RTSP BR2_PACKAGE_LIB_RTSPSERVER + CAMERA_RTSP_DEMO 基于 live555,15/15 默认开启。设备上 /root/app/camera_rtsp_demo
WebRTC BR2_PACKAGE_WEBRTC + CAMERA_WEBRTC_DEMO 内置 libpeer(自带 mbedtls / libsrtp2 / usrsctp),13/15 默认开启。设备上 /root/app/camera_webrtc_demo
UVC gadget BR2_PACKAGE_UVC_GADGET 把板子变成 USB 摄像头;运行脚本在 /root/app/uvc-gadget/
音频 AUDIO_DEMO、AUDIO_REC_PLAY 前者是 ALSA 播放/录音示例;后者带 AEC/3A(webrtc-audio-processing + speexdsp)

14.1 摄像头栈

sensor → MIPI CSI-2 → vvcam_mipi → ISP8000 (vvcam_isp) → vvcam_vb (buffer)
                                                            ↓
                                          V4L2 (/dev/videoX) → 应用
                                                            ↓
                                    nonai2d (缩放/旋转) / AI2D / KPU / DRM 显示

isp_media_server 在后台运行(由 S31canaan_isp 拉起),通过 ISP_MEDIA_SENSOR_DRIVER=/usr/lib/libvvcam.so 加载 sensor 驱动。默认 sensor 由 BR2_PACKAGE_VVCAM_DEF_SENSOR 指定。

/dev 下的稳定软链接(由 mdev_video.sh 创建):

  • /dev/video_nonai_2d → nonai2d 的 V4L2 M2M 节点
  • /dev/video_vpu → VPU 编解码节点

15. 应用开发

15.1 最小示例:编译一个 hello

// hello.c
#include <stdio.h>
int main(void) { printf("Hello, World!\n"); return 0; }
/opt/toolchain/Xuantie-900-gcc-linux-6.6.0-glibc-x86_64-V3.0.2/bin/riscv64-unknown-linux-gnu-gcc \
    hello.c -o hello
scp hello root@<板子IP>:/root/

15.2 使用 RVV 向量扩展

K230 大核 C908 带 RVV 1.0 扩展:

// rvv.c
#include <riscv_vector.h>
#include <stdio.h>
int main(void) {
    int vl = vsetvl_e32m2(70);
    printf("vl: %d\n", vl);
    return 0;
}
riscv64-unknown-linux-gnu-gcc -march=rv64gcv_xtheadc rvv.c -o rvv

SDK 内部统一使用的优化选项(见各 defconfig 的 BR2_TARGET_OPTIMIZATION):

-mcpu=c908v -mtune=c908 -mrvv-v0p10-compatible -mrvv-auto-vectorize

15.3 用 helloworld_cmake 作为模板

package/helloworld_cmake/ 是官方推荐的用户程序模板,示范了:

  • cmake-package 集成方式(SUPPORTS_IN_SOURCE_BUILD = NO)
  • 依赖声明(libgpiod2、libdrm、display)
  • 安装到 /root/app/helloworld
  • 生成 .deb 包(src/deb/DEBIAN/control + HELLOWORLD_CMAKE_BUILD_DEB hook)

src/ 下的子目录同时也是外设编程示例:gpio_led_button/、i2c/、spi/、uart/、pwm/、drm/、opencv_test/、rvv/、lsfile/。

在 k230_evb、gt6700、mrt、01studio(含 emmc)配置中默认启用。

15.4 新增一个自己的 buildroot 包

  1. 在 buildroot-overlay/package/<mypkg>/ 下创建 Config.in 和 <mypkg>.mk
  2. 在 buildroot-overlay/package/Config_canaan.in 中加一行 source "package/<mypkg>/Config.in"
  3. make menuconfig 勾选,然后 make <mypkg>

可参考 helloworld_cmake(CMake 项目)或 ai2d_kpu(普通 Makefile 项目)。

15.5 串口编程示例

设备上串口节点为 /dev/ttyS0 ~ /dev/ttyS4(linux.fragment 使能了 5 路 8250)。标准 POSIX termios 编程即可,docs/linux_sdk快速入门指南.md 中有一份完整的 AT 指令收发示例。

15.6 JTAG 调试

tools/gdbinit 提供玄铁 JTAG 调试的初始化脚本(使能 L1/L2 cache、失效 BTB/BHT):

riscv64-unknown-elf-gdb -ex "target remote <调试器IP>:1026" -x tools/gdbinit

15.7 语音助手应用

应用 说明
package/k230_assistant/ 通过 WebRTC 对接云端 LLM 的实时语音对话客户端(OpenAI Realtime API 风格)。含 ALSA 采集/播放、AEC/NS/AGC。不在 menuconfig 中,用自带 build.sh 编译
kendryte/xiaozhi_assistant 78/xiaozhi-esp32 的 K230 移植版(与百问网合作,GPL-3.0)。双进程架构:ui_and_ai(本地 KWS 唤醒 + 人脸识别 + LVGL UI)与 xiaozhi_client(HTTP 激活 + WebSocket 传输 Opus 音频)。独立仓库,需要额外启用 BR2_PACKAGE_WEBSOCKETPP、BR2_PACKAGE_BOOST 等

15.8 llama.cpp

BR2_PACKAGE_LLAMA_CPP,版本 b8156,默认关闭。子选项 TOOLS(llama-cli、llama-bench)和 SERVER(OpenAI 兼容的 llama-server)默认开启。纯 CPU/RVV 推理,不走 KPU。


16. Debian / Ubuntu 发行版镜像

make k230_canmv_01studio_defconfig
make                    # 先出 buildroot 镜像
sudo make debian        # 再转换成 Debian 13
sudo make ubuntu        # 或 Ubuntu 24.04

产物:output/<CONF>/images/debian.img.gz、ubuntu.img.gz。

16.1 工作原理

这里有两个独立阶段,sudo make debian 只做第二个:

阶段 A —— 生成基础 rootfs 压缩包(离线、手工、很少执行)

make debian_rootfs / make ubuntu_rootfs 不构建任何东西,只把配方脚本打印到终端,让你在真实 Linux 主机(不能在 Docker 里)上手工执行:

  • distribution/rootfs_debian_gen.sh → debootstrap --arch=riscv64 trixie → Debian 13
  • distribution/rootfs_ubuntu_gen.sh → debootstrap --arch=riscv64 noble → Ubuntu 24.04

两者都在 chroot 里配置 root 密码、主机名 k230、locale、openssh-server、时区 Asia/Shanghai、wpasupplicant、首次启动自动扩容的 mount_boot.service、systemd-networkd DHCP、Qt5(QT_QPA_PLATFORM=linuxfb)、python3-opencv 等,最后打成 debian13.tar.gz / ubuntu24.tar.gz 上传到嘉楠镜像站。

阶段 B —— sudo make debian(日常使用的路径)

脚本 board/canaan/k230-soc/distribution/distribution.sh:

  1. 检查 root 权限(dpkg -x、mkfs.ext4 -d、parted、保留属主的拷贝都需要)
  2. 要求 output/<CONF>/images/sysimage-sdcard.img 已存在
  3. 下载并校验 MD5 的 debian13.tar.gz / ubuntu24.tar.gz
  4. 把 buildroot 侧的产物叠加进去:lib/modules、nonai2d.conf modprobe 规则、sta.sh、k230_iomux.py、fw_setenv/fw_printenv、ADB/MTP 相关文件,并启用 vvcam.service
  5. 解包 .deb:Debian 会额外从镜像站 deb/ 目录抓取远程 deb;Ubuntu 只用本地 images/deb/*.deb
  6. 按 ABI 安装 Python wheel:Debian 13 是 cp313,Ubuntu 24.04 是 cp312。Buildroot 只产出 cp313,缺 cp312 时会调用 distribution/cp312-support/build_k230_wheel_py312.sh 交叉构建
  7. mkfs.ext4 -d 重做 rootfs 分区,parted resizepart 调整镜像,dd 写回,gzip

16.2 与 buildroot rootfs 的差异

Buildroot rootfs Debian / Ubuntu
init BusyBox sysvinit systemd
包管理 无 apt
体积 300M ~ 712M 明显更大
Python 3.13(cp313) Debian 13 → cp313;Ubuntu 24.04 → cp312
模块加载 S31canaan_isp 手工排序 /lib/modprobe.d/nonai2d.conf 的 softdep
网络 ifupdown systemd-networkd

17. CI 与发布流程

17.1 GitHub Actions

.github/workflows/build.yml(Build_Test):

  • 触发:向 main 或 dev 提 PR
  • 运行环境:self-hosted runner + 容器 ai.b-bug.org:5000/k230_sdk:latest
  • 构建矩阵:k230_canmv_defconfig、k230d_canmv_defconfig,超时 90 分钟
  • 产物保存到内网 HTTP 与 TFTP 目录
  • test_image job 目前是占位符

17.2 GitLab CI(主流水线)

.gitlab-ci.yml 是真正的发布流水线,阶段为 build_setup → build_src → smoke_test → test → release → update_html_web → send_msg。

场景 构建的配置
MR k230_canmv、k230d_canmv、BPI-CanMV-K230D-Zero
打 tag / 定时(每日) 上述 3 个 + 01studio、01studio_emmc、junroc_ai_cam、mrt、lckfb、v3、dongshanpi,共 10 个
每日/发布构建中的部分配置 额外 sudo make debian + sudo make ubuntu

烟雾测试与日常测试通过 TFTP 刷机后在真实板子上跑(测试脚本来自独立仓库 k230_testscripts)。

发布产物最终同步到 https://download.kendryte.com/k230/release/linux_sdk_images/,daily_build/ 是每日构建,tag 名目录是正式版本。

17.3 仓库镜像

代码在三处同步:GitLab(内部主仓)→ GitHub kendryte/k230_linux_sdk → Gitee kendryte/k230_linux_sdk。


18. 已知限制与常见坑

构建

现象 原因 / 对策
删除了 buildroot-overlay/ 里的文件但没生效 rsync 无 --delete,旧副本残留在 output/ 中。执行 make clean(linux/*.patch 除外,它有专门清理逻辑)
make menuconfig 的改动被冲掉 命令行显式传 CONF= 会强制重跑 defconfig。日常用不带 CONF= 的 make
工具链 MD5 校验失败但构建继续 install_toolchain_and_depend.sh 的校验失败分支只退出了子 shell,不会中止脚本。请留意红色输出
非 Ubuntu 22.04/24.04 主机构建报错 改用 tools/docker/ 提供的容器环境
下载慢 显式指定 make BR2_PRIMARY_SITE=https://download.kendryte.com/k230/downloads/dl

镜像 / 启动

现象 说明
BR2_CANAAN_GEN_SPI_NOR_IMG=y 但没有 NOR 镜像 post-image.sh 中的 NOR 生成调用当前被注释,属于已知的未完成功能
lckfb 板实际可用内存与预期不符 k230-canmv-lckfb.dts 标 1GB,-lcd 变体标 512MB,取决于运行时选中哪个 DTB
SD 卡没有自动扩容 检查 /first_boot_flag 是否还在,以及 S00resizemmc 的日志
fw_setenv 报错 /etc/fw_env.config 由 S00resizemmc 首次启动时生成;若缺失可手工写入 <根设备> 0x300000 0x2000
镜像中 U-Boot 环境带有开发期的 SSID / IP 等默认值 board/canaan/k230-soc/env/default.env 里残留了开发值,量产前请清理

其它

  • env/default_nor.env 中的 root=/dev/mtdblock9 rootfstype=jffs2 与当前代码默认的 ubi.mtd=7 / ubifs 不一致,NOR 路径本就未启用。
  • post-image.sh 会用 sed -i 就地修改被 git 跟踪的 env/default.env;先编 ilp32 配置再编普通配置会让工作区出现改动。
  • BPI-CanMV-K230D-Zero_ilp32_defconfig 中 BR2_TARGET_UBOOT_BOARDNAME="k230d_canmv_bp" 疑似拼写错误(对应的 U-Boot defconfig 名为 k230d_canmv_bpi)。
  • post-build.sh 中仍保留对 BR2_PACKAGE_RTL8189FS 的处理,但仓库中已无此包。
  • AI demo 菜单里 segment_yolov8n 和 person_attr 的提示文字是复制粘贴的错误名称(分别显示为 puzzle_game 和 ocr)。
  • docs/linux_sdk快速入门指南.md 部分内容已过时(例如仍称 Buildroot 2024.02.1、工具链 V2.10.1),请以本 Wiki 和源码为准。

19. 参与贡献

完整流程见仓库的 .github/CONTRIBUTING.md。要点:

  1. 提交 PR 必须关联对应的 issue。若没有,请先建 issue。
  2. Fork 仓库 → 基于 dev 分支创建新分支 → 提交改动。
  3. PR 的 base 选 kendryte/k230_linux_sdk 的 dev 分支。
  4. 按 PR 模板填写描述。

Issue 模板:bug report / feature request / help / other,见 https://github.com/kendryte/k230_linux_sdk/issues。

提交代码前的自查

  • 改了 buildroot-overlay/configs/* 后,用 make savedefconfig 规范化,而不是手写。
  • 新增内核 patch 时注意编号不要与现有文件冲突(当前已有重复编号)。
  • 确认没有把 env/default.env 的本地改动(ipaddr、wlanssid 等)一起提交。

资源链接

Clone this wiki locally