Repository navigation
Home
嘉楠 K230 / K230D 系列 RISC-V SoC 的 Linux 系统开发套件,基于 Buildroot 构建。
本页面对应仓库 kendryte/k230_linux_sdk。内容依据仓库源码整理,如与代码冲突请以代码为准。
常用入口
- 官方 SDK 资源中心:https://www.kendryte.com/zh/sdkResource/230linux
- 每日构建镜像(CI Images):https://download.kendryte.com/k230/release/linux_sdk_images/daily_build/
- 主代码仓库:https://github.com/kendryte/k230_linux_sdk
- 社区问答:https://www.kendryte.com/answer/
- 概览
- 快速开始
- 支持的开发板与配置
- 仓库目录结构
- 构建系统原理
- make 命令速查
- 启动链与镜像布局
- 内核与设备树
- 驱动与硬件支持
- WiFi 与蓝牙
- 菜单结构(menuconfig)
- AI 开发
- Python 开发
- 多媒体与图形
- 应用开发
- Debian / Ubuntu 发行版镜像
- CI 与发布流程
- 已知限制与常见坑
- 参与贡献
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启动。
已验证系统:Ubuntu 22.04 / 24.04。其它发行版可能遇到构建问题,建议改用下文的 Docker 环境。
git clone --depth=1 https://github.com/kendryte/k230_linux_sdk.git
cd k230_linux_sdk
sudo make toolchain_and_dependmake toolchain_and_depend 会做两件事(脚本:tools/install_toolchain_and_depend.sh,必须 root):
-
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 安装)。 - 下载并解压玄铁工具链
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/# 构建镜像
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 出来的文件属主正确。
三步,按顺序执行:
make k230d_canmv_defconfig # 1. 选择配置(只需执行一次,结果记录在 .last_conf)
make source # 2. 预下载全部源码包(可选)
make # 3. 编译也可以一条命令:make CONF=k230d_canmv_defconfig。
注意
CONF=的副作用:在命令行显式传CONF=会强制重跑 defconfig,从而丢弃你之前用make menuconfig做的改动。只在切换板子时用它;日常增量编译请直接make。
首次编译耗时较长(拉取 Buildroot、内核、全部第三方源码)。不想编译可直接下载 每日构建镜像。
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 └ 存储介质
解压得到 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=syncWindows:使用 Rufus 选择镜像并写入。
用 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。
配置文件位于 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。
两个 *_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选择加载哪一个。
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。
理解这一节能省掉大量"改了文件没生效"的困惑。
本 SDK 没有使用 Buildroot 的 BR2_EXTERNAL 机制。流程如下(实现见 tools/sync.mk):
-
下载:从
BR2_PRIMARY_SITE或buildroot.org下载buildroot-2025.02.1.tar.xz到dl/,校验 sha256(tools/download/buildroot.hash)。 -
解压:解压到
output/buildroot-2025.02.1/,随后删除package/python3和package/ffmpeg(overlay 会提供自己的版本)。 -
覆盖:
rsync -a buildroot-overlay/ output/buildroot-2025.02.1/ --exclude "*-overlay" --exclude "linux-6.6.22"
-
配置:
make -C output/buildroot-2025.02.1 <defconfig> O=$(CURDIR)/output/<defconfig> -
编译:
make -C output/<defconfig> all
所以 buildroot-overlay/ 里的每个文件都会按同名路径覆盖原始 Buildroot 的对应文件。改 overlay 后重新 make 会自动重新 rsync。
坑:rsync 没有
--delete。你在 overlay 里删除一个文件,output/里的旧副本不会消失,需要make clean。唯一的例外是linux/*.patch,sync.mk有专门的清理逻辑(否则同号 patch 会重复应用导致失败)。
这是本 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 文件负责触发重编。
当前选中的配置记录在仓库根目录的 .last_conf 文件里(内容形如 CONF=k230_canmv_defconfig)。未显式传 CONF= 时,Makefile 会 include 它。默认值是 k230_canmv_defconfig。
Makefile 有一条 catch-all 规则:任何它不认识的目标都会原样转发到 make -C output/$(CONF) <目标>。这就是 make linux-rebuild、make menuconfig、make <包名>-dirclean 能工作的原因——它们都是 Buildroot 的标准目标。
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。
# ---- 配置 ----
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 帮助-
并行度:所有 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。
如果你想用自己 clone 的内核源码而不是 Buildroot 拉取的:
echo "LINUX_OVERRIDE_SRCDIR=/path/to/your/linux" > output/<defconfig>/local.mk
make linux-rebuildBootROM
└─> 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)变体。
由 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。
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。
内核命令行由 board/canaan/common/k230_img.c: board_fdt_chosen_bootargs() 按以下优先级决定:
- U-Boot 环境变量
bootargs(若已设置) - 板级覆盖
fdt_chosen_bootargs()—— 目前只有k230d_canmv_junroc_ai_cam用到 - 按启动介质的默认值:
- 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
- SDIO0 →
部分 K230D 的内核 DTS 自带 chosen/bootargs;K230 CanMV/EVB/01studio 的 DTS 只设置 stdout-path,完全依赖 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 烧录模式 |
# 从 Linux
/bin/reboot_to_upgrade # 等价于 devmem 0x80230000 32 0x5aa5a55a; reboot
# 从 U-Boot
reboot_to_upgradeconfigs/ 下的 *_burntool_defconfig 系列 U-Boot 配置就是烧录模式使用的 RAM 常驻镜像(SYS_TEXT_BASE=0x80300000、无 SPL、bootdelay=1 并支持 stop 键中断)。
U-Boot 下可用 TFTP 刷机:
run upsdimg # 刷整个 SD 镜像
run upsduboot # 只刷 U-Boot
run upspiimg # 刷 SPI flash 镜像
run upspiuboot # 刷 SPI flash 的 U-Boot
所有 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。
位于 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 配置不应用任何片段。
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 时要留意。
| 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 |
当一个板子配置了两个 DTS(通常是 LCD 版和 HDMI 版),post-image.sh 会往 boot 分区写入两个纯文本文件 lcd_dtb 和 hdmi_dtb,各自记录对应的 DTB 文件名;只有一个 DTS 时写 force_dtb。
U-Boot 的 k230_set_dtb 命令在启动时:
- 若 boot 分区存在
/force_dtb→ 直接使用其中记录的 DTB。 - 否则探测 I²C 总线(
CONFIG_K230_HDMI_LCD_I2C_BUS,默认 3,CanMV 上为 4):地址0x38有响应 → LCD,用/lcd_dtb;地址0x3b有响应 → HDMI,用/hdmi_dtb;都没有则回退 LCD。 - 结果写入
dtb环境变量并env_save()持久化。
没有 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 内联汇编)。
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。
由 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(用于旋转) |
使用 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内核侧驱动在树内,这些包只提供用户态库/工具:
| 包 | 菜单选项 | 说明 |
|---|---|---|
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) |
系统是 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)里写的任何命令都会被追加进这个脚本,是最简单的"开机自启"入口。
| 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 卡。
方式一:命令行脚本
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在首次启动时自动生成。
ap.sh wlan0 <SSID> <密码> [g|a|ac|b]/bin/ap.sh 会拉起 hostapd + udhcpd,DHCP 地址池 192.168.10.20 - 192.168.10.160。
以 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 / connectAIC8800 走 USB 蓝牙(aic_btusb),无需 hciattach。
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 打过补丁的上游包,仍在各自的标准菜单位置。
| 组件 | 版本 | 来源 |
|---|---|---|
| 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。两者应向后兼容,但如遇奇怪的推理结果可以留意这一点。
源码位于 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.shdemo 清单
人脸相关(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) |
| 包 | 说明 |
|---|---|
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 |
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 同理。
package/cloudplat_deploy_code_linux/ 是嘉楠在线训练平台产出模型的配套部署代码,提供 8 类任务模板:classification、detection、segmentation、ocr_detection、ocr_recognition、ocr(检测+识别)、metric_learning、multilabel_cls。该目录不在 menuconfig 中,用自带的 build.sh 编译。
- 解释器:Python 3.13.3(
package/python3/,overlay 带 8 个补丁) - 设备上路径:
/usr/lib/python3.13/site-packages - 默认启用的模块(以
k230_canmv_defconfig为例):pip、paho-mqtt、periphery、cv2(OpenCVLIB_PYTHON)、numpy
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头文件)。
启用 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
三个包,默认全部关闭,需在 menuconfig 中手动启用:
| 包 | 提供 |
|---|---|
python-adafruit-blinka |
CircuitPython 风格 API:board、digitalio、busio、pwmio
|
python-adafruit-platformdetect |
板卡/芯片自动识别(已加 K230 支持补丁) |
python-adafruit-pureio |
纯 Python 的 ioctl / I2C / SPI 后端 |
| 领域 | 模块 | 来源 |
|---|---|---|
| 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 |
上游包 |
| 组件 | 版本 / 选项 | 说明 |
|---|---|---|
| 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) |
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 编解码节点
// 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/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 rvvSDK 内部统一使用的优化选项(见各 defconfig 的 BR2_TARGET_OPTIMIZATION):
-mcpu=c908v -mtune=c908 -mrvv-v0p10-compatible -mrvv-auto-vectorize
package/helloworld_cmake/ 是官方推荐的用户程序模板,示范了:
-
cmake-package集成方式(SUPPORTS_IN_SOURCE_BUILD = NO) - 依赖声明(
libgpiod2、libdrm、display) - 安装到
/root/app/helloworld -
生成
.deb包(src/deb/DEBIAN/control+HELLOWORLD_CMAKE_BUILD_DEBhook)
src/ 下的子目录同时也是外设编程示例:gpio_led_button/、i2c/、spi/、uart/、pwm/、drm/、opencv_test/、rvv/、lsfile/。
在 k230_evb、gt6700、mrt、01studio(含 emmc)配置中默认启用。
- 在
buildroot-overlay/package/<mypkg>/下创建Config.in和<mypkg>.mk - 在
buildroot-overlay/package/Config_canaan.in中加一行source "package/<mypkg>/Config.in" -
make menuconfig勾选,然后make <mypkg>
可参考 helloworld_cmake(CMake 项目)或 ai2d_kpu(普通 Makefile 项目)。
设备上串口节点为 /dev/ttyS0 ~ /dev/ttyS4(linux.fragment 使能了 5 路 8250)。标准 POSIX termios 编程即可,docs/linux_sdk快速入门指南.md 中有一份完整的 AT 指令收发示例。
tools/gdbinit 提供玄铁 JTAG 调试的初始化脚本(使能 L1/L2 cache、失效 BTB/BHT):
riscv64-unknown-elf-gdb -ex "target remote <调试器IP>:1026" -x tools/gdbinit| 应用 | 说明 |
|---|---|
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 等 |
BR2_PACKAGE_LLAMA_CPP,版本 b8156,默认关闭。子选项 TOOLS(llama-cli、llama-bench)和 SERVER(OpenAI 兼容的 llama-server)默认开启。纯 CPU/RVV 推理,不走 KPU。
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。
这里有两个独立阶段,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:
- 检查 root 权限(
dpkg -x、mkfs.ext4 -d、parted、保留属主的拷贝都需要) - 要求
output/<CONF>/images/sysimage-sdcard.img已存在 - 下载并校验 MD5 的
debian13.tar.gz/ubuntu24.tar.gz - 把 buildroot 侧的产物叠加进去:
lib/modules、nonai2d.confmodprobe 规则、sta.sh、k230_iomux.py、fw_setenv/fw_printenv、ADB/MTP 相关文件,并启用vvcam.service - 解包
.deb:Debian 会额外从镜像站deb/目录抓取远程 deb;Ubuntu 只用本地images/deb/*.deb -
按 ABI 安装 Python wheel:Debian 13 是
cp313,Ubuntu 24.04 是cp312。Buildroot 只产出 cp313,缺 cp312 时会调用distribution/cp312-support/build_k230_wheel_py312.sh交叉构建 -
mkfs.ext4 -d重做 rootfs 分区,parted resizepart调整镜像,dd写回,gzip
| 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 |
.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_imagejob 目前是占位符
.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 名目录是正式版本。
代码在三处同步:GitLab(内部主仓)→ GitHub kendryte/k230_linux_sdk → Gitee kendryte/k230_linux_sdk。
| 现象 | 原因 / 对策 |
|---|---|
删除了 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 和源码为准。
完整流程见仓库的 .github/CONTRIBUTING.md。要点:
- 提交 PR 必须关联对应的 issue。若没有,请先建 issue。
- Fork 仓库 → 基于
dev分支创建新分支 → 提交改动。 - PR 的 base 选
kendryte/k230_linux_sdk的dev分支。 - 按 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等)一起提交。