简介《阿里平头哥剑池CDK快速上手指南》面向物联网与嵌入式开发初学者以及需要自定义平台SDK的工程师围绕平头哥“1天上手、5天出原型、20天出产品”的1520理念讲解剑池CDK在C-SKY与RISC-V架构芯片上的组件化开发方法。内容从工具划分与端云一体开发方式切入依次覆盖新建组件化SDK工程、创建平台相关组件、修改链接脚本、制作并调试Flash算法文件、增改开发板与芯片组件、离线或在线发布SDK并附常见问题解答便于读者理解目录结构与工程组织逻辑掌握从初始方案到可交付SDK的完整流程。资源包共1个PDF文件约3.18MB适合按章节查阅与对照实践。已有1028人学习可作为快速熟悉剑池CDK、缩短IoT产品开发周期的入门手册。1. 从一次链接报错说起剑池 CDK 到底装的是什么不少人装完剑池 CDK新建工程一路点下一步编译能过一链接就满屏 region overflow换到烧写环节又提示找不到 Flash 算法。代码一行没改问题全出在环境没对齐。剑池 CDK 是面向物联网的集成开发环境图形界面里打包了四块Packages 组件化模块、Editor 编辑器、Debugger 调试器、Analyzer 分析器支持 C-SKY 和 RISC-V 两类架构的芯片默认工程模板却只按 CK802 一套平台铺好。换一块板子链接脚本的存储区间、芯片组件、Flash 算法文件全要跟着换哪一步没对上后面就是连锁翻车。这篇按实际落地顺序走先对齐安装包和驱动再建 Solution Package 初始工程改 LD、做 Flash 算法、替换平台组件最后给一套装完能自检的验证清单。2. 装之前先对齐环境剑池 CDK 安装包、系统版本与驱动装 CDK 这件事麻烦的从来不是安装向导而是装完打不开、打开了连不上板子、连上了下载不了。把这几件事在动手前理清后面能省掉一半返工。2.1 安装包类型与机器要求对照安装包从芯片开放平台的下载页取页面上会标当前版本和适用系统。常见做法是只装一个主版本不要在同一台机器上并存多个 CDK 大版本组件缓存目录会互相覆盖出问题很难查。下面这张表是我自己装机前会先核一遍的清单项目建议配置说明操作系统64 位 Windows 10 及以上老版本 Windows 对 USB 驱动签名要求更严容易卡在识别调试器磁盘预留 10 GB 以上安装包本身不大组件缓存和编译中间文件占空间内存8 GB 起开 Analyzer 做性能分析时更吃内存调试器驱动随安装包或单独提供装完在设备管理器里能看到对应端口串口驱动CH340 / CP210x 一类看开发板用的哪颗 USB 转串口芯片目标架构C-SKY 或 RISC-V建工程时 CPU 类型必须和实际芯片一致提示安装包和组件包的版本尽量同批。组件超市里拉下来的组件如果比主程序新太多工程打开后可能出现组件节点灰掉、配置项读不出来的情况。2.2 安装路径、驱动与串口权限安装路径我一般固定成纯英文、无空格、层级浅的目录。CDK 的组件包路径、编译中间文件路径都会拼在这个根目录下面带中文或者带空格的路径在部分 GCC 工具链调用里会被截断报错信息还特别含糊。# 推荐的目录布局Windows 下对应盘符路径 D:/CDK/ # 主程序安装目录纯英文 D:/CDK/packs/ # 组件包缓存建工程时的 Package Path 默认落这里 D:/workspace/ # 自己的 solution 工程一个工程一个子目录这三个路径各自的作用要分清安装目录只放程序本身升级时整个替换packs 目录是组件仓库同名组件不同版本会在这里并存workspace 放业务工程工程里只留配置和源码不把组件源码复制进来。把这三层分开后面换 CDK 版本时工程不用动。安装完成后第一次启动用管理员权限跑一次让程序把需要的驱动注册进系统。然后打开设备管理器插上开发板看端口有没有正常枚举。如果设备管理器里出现带感叹号的未知设备先装对应驱动别急着在 CDK 里点下载否则报的错会指向“无法连接目标”把方向带偏。# 装完后先确认两件事再打开 IDE # 1. 设备管理器 - 端口能看到类似 COM3 的串口 # 2. 设备管理器 - 通用串行总线设备能看到调试器对应项且无黄色感叹号串口波特率这类参数不用在系统层改进 CDK 的调试配置里设就行。系统层只需要保证端口存在、不被别的串口工具独占。常见翻车是串口助手没关CDK 下载时抢不到端口提示超时。2.3 首次启动组件源与离线兜底剑池 CDK 的一个特点是内部自动对接芯片开放平台启动后会去拉组件索引。网络通的时候新建工程能直接看到组件超市里的条目网络受限时工程视图里组件节点会是空的这时候新建出来的 Solution Package 只有壳编译必然失败。我一般会先做一次连通性自检新建一个空工程看工程视图里默认的 SDK 组件和 chip 组件能不能正常展开。能展开说明组件索引已经拉到本地展不开就去检查 packs 目录是不是空的。空的话有两条路一是换网络环境重试二是用平台提供的离线组件包导入。# 检查组件缓存是否已经落地 ls D:/CDK/packs/ # 正常应能看到按组件名和版本号分层的目录例如 # __SDK_CK802/ __Chip_CK802/ SmartL_Chip/组件缓存目录为空时不要硬建工程。默认组件缺失后面 Create a new SDK 那一步会找不到基础组件弹窗里下拉框是灰的很多人卡在这里以为是软件坏了。把组件源的问题先解决再往下走。3. 创建初始组件化 SDK 工程New SOC Project 的三个字段初始工程这一步决定后面所有组件的存放位置和依赖关系。菜单入口在 Project - New SOC Project弹窗里真正要动脑的只有三个字段工程名、Project Type、Package Path。填错任何一个后面要么组件找不到要么工程挪不动。3.1 Project Type 选 Solution Package 的原因弹窗里的 Project Type 有几个选项做平台 SDK 时选 Solution Package。这个类型建出来的是一份“方案工程”本身只放 main 文件和调试、Flash 初始化脚本真正的芯片启动代码、链接脚本都放在它依赖的组件里。选错类型的典型表现是编译能过但工程视图里没有独立的 SDK 组件节点想替换平台组件时无处下手。新建时的字段对应关系可以按下面这张表理解字段填什么影响工程名平台名加 solution 后缀纯英文决定 .ckdproj 文件名和默认输出名Project TypeSolution Package决定工程骨架是“方案 组件依赖”结构Package Path组件仓库目录新建的 SDK 组件、chip 组件都存在这里建完之后工程视图里应该出现三个节点缺一个都说明没建对my_solution/ # 方案工程节点main 文件、调试初始化脚本、Flash 初始化脚本 __SDK_CK802/ # sdk 类型组件依赖一个 chip 组件存在 Package Path 下 __Chip_CK802/ # chip 类型组件CPU 初始化启动代码 链接脚本存在 Package Path 下方案工程节点里的调试初始化脚本和 Flash 初始化脚本是后面调试器连接和烧写时要读的先不要删。SDK 组件和 chip 组件的实际文件不在工程目录里而在 Package Path 下这一点很关键工程只是引用改组件等于改仓库里的公共文件会影响所有引用它的工程。3.2 Package Path 写错之后的连锁反应Package Path 建议单独建一个目录不要和安装目录混也不要放在桌面或者文档目录下。这个路径会被写进工程配置工程换机器打开时如果路径不存在组件会全部标红。我习惯在 workspace 下再分一层D:/workspace/my_solution/ # 工程目录只放方案本身 D:/workspace/packs/ # Package Path放 SDK 和 chip 组件这样备份和迁移时工程目录和组件目录一起打包换机器解压后只要改一次 Package Path 就能打开。如果组件直接丢在工程目录里多个人协作时每人一份组件副本版本立刻分叉后面合并代码会非常难受。3.3 改链接脚本只动存储区域五个符号不要改默认 LD 文件是按 CK802 模板配的换平台第一件事就是把存储区域改成和实际芯片一致。CDK 对 LD 文件提供了图形化加文本两种修改方式存储段在两段 Flash、两段 RAM 以内的直接在图形界面里填起始地址和长度就行超过两段就得按 GCC 链接脚本的语法手写 MEMORY 段。/* 示例按平台手册替换 ORIGIN 和 LENGTH段名保持工具链约定 */ MEMORY { ROM (rx) : ORIGIN 0x00000000, LENGTH 0x80000 /* Flash 起始与容量 */ RAM (rwx) : ORIGIN 0x20000000, LENGTH 0x10000 /* RAM 起始与容量 */ }ORIGIN 是这段存储的物理起始地址LENGTH 是长度两个值都必须来自平台手册不能照抄模板。改完之后编译一次看 map 文件里代码段和数据段的落点是不是落在新划的区间内落点不对说明还有别的段没改到。默认 LD 里有五个符号是启动代码在用的改存储区域时不要动它们符号作用__s_ram_data_1程序数据区起始位置__e_rom只读数据区结束、按 4 字节对齐的位置__e_ram_data_1程序数据区结束位置__s_ram_bss_1BSS 区起始位置__e_ram_bss_1BSS 区结束位置这五个符号在芯片组件的 src/ck802.c 里被引用负责启动时把数据段从 Flash 搬到 RAM、把 BSS 段清零。名字改了或者删了编译能过运行直接跑飞而且飞得毫无规律是典型的黑匣子问题。真要在调试器里查先看启动文件里这几个符号的地址是不是合理值。3.4 换掉默认组件先建 SDK再建 chip默认的 __SDK_CK802 和 __Chip_CK802 只是模板真正要发布自己平台的 SDK得换成自己的组件。步骤是两步顺序不能反。第一步右击方案工程节点选 Create a new SDK填自己的 SDK 名称基础组件选默认的 __SDK_CK802。这一步产出的是一个 sdk 类型组件它继承模板的依赖关系后面再往里加开发板组件和 common 组件。第二步右击刚建好的 SDK 组件选 Create a new package填芯片组件名比如 SmartL_Chip基础组件仍然指向默认的 SDK 组件。这一步产出 chip 类型组件CPU 启动代码和链接脚本都归它管。# 两步做完后Package Path 下应该多出两个目录 D:/workspace/packs/SmartL_SDK/ # 自己的 SDK 组件 D:/workspace/packs/SmartL_Chip/ # 自己的芯片组件含 src/ck802.c 和 LD 文件建完不要急着删默认组件。默认组件先留着当参照等自己的组件编译、调试、烧写全部验证通过再在工程配置里把依赖切过去。切换的时机太早一旦出问题就分不清是新组件写错还是模板本身就不匹配。3.5 加开发板组件、common 组件与发布平台 SDK 一般分三层芯片组件管启动和链接开发板组件管板级外设和引脚common 组件放和硬件无关的公共代码。开发板组件在 SDK 组件节点下新建建完右击节点选 Add Source Folder把已有的板级代码目录整个导入代码不用复制组件里存的是引用。导入之后要配两处编译选项。Compiler 的 Global Config 里配头文件搜索路径把开发板组件要暴露给外部的头文件目录加进去否则上层应用 include 不到。Debug Level 选带调试信息的档位发布前再改成不带调试信息减小体积。common 组件按同样方式建两个一个放驱动抽象一个放通用工具函数都标成硬件无关。这样后面换板子只换开发板组件common 和芯片组件不动。发布分两种。离线发布是把 SDK 工程连同组件目录打成压缩包对方解压后改 Package Path 就能打开在线发布是推到组件平台别人在组件超市里直接拉。离线包适合内部小范围流转在线发布适合对外。发布前把编译产物清一遍只留源码、LD、算法文件和工程配置中间文件带出去会让包大出一截还容易把本机绝对路径泄进去。4. Flash 算法工程FlashDev.c 描述、Driver.c 实现、main.c 自测有些平台的外置 Flash 不能直接按地址写得靠一段跑在芯片 RAM 里的算法程序去擦写。CDK 的烧写功能就是靠这个算法文件适配不同 Flash 器件的。算法做不对表现是下载进度条卡住、校验失败或者烧完程序不跑。4.1 新建 Flash 工程RAM1 和 CPU 必须与 SDK 一致还是 Project - New SOC ProjectProject Type 这次选 Flash。弹窗里有两项必须和 SDK 工程完全对齐CPU 类型要一致RAM1 要填目标芯片实际的 RAM 区域。算法程序是下载到 RAM 里跑的RAM 区域填错程序加载不进去调试器会直接停在入口之前。建完之后工程里有三个关键文件FlashDev.c 描述 Flash 器件的基本信息Driver.c 实现具体读写擦接口main.c 是算法的主控循环。4.2 FlashDev.c六个字段和一段地址表这个文件里是一个 FlashDevice 结构体描述器件名、CPU、容量、扇区大小。模板给的是示例值必须逐项改成实际硬件参数。/* Flash 器件描述结构体字段顺序不能调 */ struct FlashDevice const FlashDevicesINDEVSECTION { 6, /* 结构体版本描述保留值不要改 */ SmartL_Flash, /* Flash 名称烧写时显示在算法列表里 */ ck802, /* CPU 名称必须小写且与工程 CPU 一致 */ 0x123456, /* Flash ID按器件手册填 */ NorFlash, /* 器件类型 */ 512 * 1024, /* 保留字段按模板填 */ 1, /* 是否可直接按地址访问1 表示可以 */ 1, /* RangeNumbers地址区间个数 */ { /* 起始地址、总容量、扇区大小 */ {0x0, 0x80000, 0x200} } };几个容易填错的地方CPU 名称必须小写写成 CK802 会在烧写时匹配不到算法扇区大小要和器件手册一致填大了擦除会越界填小了擦除次数暴增、速度慢得离谱可直接访问这一项如果器件不支持按地址读要改成 0否则 CDK 会走直接读取路径读回的全是无效数据。4.3 Driver.c八个接口返回值和地址对齐先保证Driver.c 要实现的接口一共八个每个都返回 0 表示成功、非 0 表示失败。CDK 不关心内部怎么实现只认返回值和副作用。接口作用常见坑flashInit编程初始化烧写开始时调用时钟没配好后面所有操作都超时flashUnInit编程结束清理忘了关看门狗芯片复位flashID读器件 ID返回值与 FlashDev.c 里的 ID 对不上flashProgram按目标地址写数据没按页对齐写入被器件丢弃flashRead读回数据器件不可直接读时没实现校验必失败flashErase按扇区擦除长度不是扇区大小整数倍flashChipErase整片擦除大容量器件超时要加等待flashChecksum快速校验算法和烧写镜像的校验方式不一致擦除接口收到的目标地址一定是按 FlashDev.c 里扇区大小对齐的长度也一定是扇区大小的整数倍这一点工具侧已经保证实现里不用再做对齐处理。写入接口则要自己判断页边界跨页写要拆成多次。4.4 main.c 的命令字调试法g_func 从 0 到 6算法工程的 main 不直接烧写而是把一组全局变量当成命令字CDK 下载算法后通过改变量来驱动具体操作。主循环长这样int main(void) { g_error flashInit(); /* 先做器件初始化 */ flashTest(); /* 可选的器件自检 */ do { __bkpt_label(); /* 断点桩调试时程序停在这里等命令 */ switch (g_func) { case 0: g_error flashID(g_flashID); break; case 1: g_error flashProgram((char *)g_dstAddress, (char *)g_rwBuffer, g_length); break; case 2: g_error flashRead((char *)g_rwBuffer, (char *)g_dstAddress, g_length); break; case 3: g_error flashErase((char *)g_dstAddress, g_length); break; case 4: g_error flashChipErase(); break; case 5: g_error flashUnInit(); break; case 6: g_error flashChecksum((char *)g_dstAddress, g_length, g_checksum); break; default: break; } } while (1); }调试前先把编译优化改成 -O0重新编译把算法工程设为 active project启动调试全速运行程序会停在 __bkpt_label 这一行。然后在 Watch 窗口里设 g_func、g_dstAddress、g_length、g_rwBuffer 四个变量。比如验证写入g_func 设 1g_dstAddress 设目标 Flash 地址g_length 设几个字节g_rwBuffer 里填一串特征数据把 PC 设成当前 lr 的值单步进入 flashProgram跑完再读回比对。每个 case 都按这个方式单独验证一遍八个接口全过再谈集成。跳过单步验证直接挂到工程里烧写出问题时根本分不清是算法错还是工程配置错。4.5 从 -O0 到 -O2算法文件怎么挂进 SDK单步全通过后把编译优化从 -O0 改成 -O2重新编译取 Obj 目录下生成的算法 .elf 文件。这个文件才是要挂到 SDK 工程里的产物。挂载位置分两种情况。工程用了芯片组件的把 .elf 拷到芯片组件目录下在组件配置窗口里选中它作为算法文件工程没用芯片组件、或者用的是旧版组件就把 .elf 拷到方案工程根目录和 .ckdproj 文件放在一起然后在工程配置的 Flash 页里选。注意-O0 调通不等于 -O2 能用。优化后延时循环可能被整个删掉Flash 时序对不上表现是烧写偶发失败。涉及硬件的等待循环变量要加 volatile。5. 常见问题排查五类翻车现场与后悔药装环境这件事出问题不可怕怕的是不知道从哪一层查。下面这几条是按“现象、原因、解决”整理的基本都是装 CDK 绕不开的。5.1 装完打不开或者组件节点是空的现象双击图标没反应或者进去了但工程视图里只有方案节点SDK 和 chip 组件展不开。原因一种是安装时缺系统运行库程序启动阶段就退了另一种是组件索引没拉到本地packs 目录是空的。解决先用管理员权限重装一次装完重启再检查 packs 目录有没有内容空的就换网络重试或者导离线组件包。不要在这个状态下硬建工程建出来也是空壳。5.2 新建工程编译报找不到头文件现象刚建完的 Solution Package 一编译就报一堆 include 找不到。原因Package Path 指到了不存在的目录或者路径里带中文、空格组件实际没加载进来。解决把 Package Path 改成纯英文短路径重建工程。已经建好的工程可以在配置里改路径改完刷新一次工程视图。5.3 链接报存储区溢出现象编译通过链接阶段报 region overflow。原因LD 文件还是 CK802 模板的存储区间和自己芯片对不上代码段放不下。解决按平台手册改 MEMORY 段的 ORIGIN 和 LENGTH改完看 map 文件确认段落点。改的时候不要动那五个启动符号。5.4 Flash 算法调通但工程里烧写失败现象算法工程单步每个接口都返回 0挂到 SDK 工程里烧写却卡住或者校验失败。原因算法 .elf 放错位置Flash 页里选到的还是旧文件或者 -O2 之后时序被优化掉。解决确认 .elf 的存放路径和工程配置里选中的路径一致重新编译算法再拷一次硬件等待循环加 volatile必要时对时序函数加禁止优化属性。5.5 发布出去的 SDK 别人打不开现象离线包发出去对方解压后工程标红组件全部找不到。原因工程配置里存的是本机绝对路径对方机器上没有对应目录。解决发布前把 Package Path 改成相对路径或者统一约定路径包里带上组件目录并在说明里写清目录结构。发布前自己换一台机器解压验证一遍这一步能省掉大量来回沟通。6. 装完怎么验证跑通四步自检和一张对照表装完 CDK、建完工程、做完算法最后一定要走一遍验证不然等真正开始写业务代码时问题会混在一起排查成本翻倍。我一般按四步走每步都有明确的通过标准。第一步空工程编译。新建一个 Solution Packagemain 里什么都不写直接编译。通过标准是零错误零警告输出目录里生成可执行文件。这一步验证的是工具链、组件、LD 三者是否对齐。第二步算法自检。把 Flash 算法工程设为 active projectg_func 依次设 0 到 6每个命令跑一遍看返回值和读回数据。通过标准是 flashID 读出的值和 FlashDev.c 里填的一致写入后读回的数据和写入的完全一样。第三步整包烧写。回到方案工程配置好算法文件执行下载。通过标准是进度条走完、校验通过、复位后程序能跑。跑不起来先看复位向量和 LD 里的 ROM 起始地址对不对得上。第四步换机验证。把工程和组件目录打包在另一台机器上解压打开重新编译一次。通过标准是编译和烧写都能复现。这一步最容易被跳过也最容易暴露路径写死的问题。验证项操作通过标准工具链空工程编译零错误生成可执行文件组件加载展开工程视图SDK、chip、board 节点都在链接脚本查 map 文件代码段、数据段落在设定区间Flash 算法g_func 0 到 6 逐个跑返回值全为 0读回数据一致整包烧写工程里执行下载校验通过复位后程序运行迁移换机解压重编编译烧写均可复现这套流程里第二步最值得花时间。算法是烧写的底座底座不稳后面所有调试现象都不可信。从那以后我每次做完新平台的算法都强制把 g_func 从 0 到 6 完整跑一遍再挂进工程宁可多花半小时也不要在业务代码里猜是算法问题还是应用问题。希望这套顺序能帮到你少走几段弯路。本文还有配套的精品资源点击获取