Crochet新板卡支持完全指南：基于NewBoardExample手把手为FreeBSD添加你的开发板-平芜编程栈

Crochet新板卡支持完全指南：基于NewBoardExample手把手为FreeBSD添加你的开发板

【免费下载链接】crochetBuild FreeBSD images for RaspberryPi, BeagleBone, PandaBoard, and others.项目地址: https://gitcode.com/gh_mirrors/cr/crochet

Crochet 是一款构建可启动 FreeBSD 磁盘镜像的开源工具，已支持 RaspberryPi、BeagleBone、PandaBoard 等 30 多款开发板。本文基于board/NewBoardExample官方模板，手把手教你如何为 Crochet 添加一块新开发板：从创建板卡目录、编写启动配置，到最终生成可烧录的 FreeBSD 镜像。

一、先认识 Crochet：3 分钟了解项目结构

Crochet 的核心用法很简单：准备一个配置文件，运行主脚本，就能得到一张可启动的 FreeBSD 镜像：

git clone https://gitcode.com/gh_mirrors/cr/crochet cd crochet sudo /bin/sh crochet.sh -c <配置文件>

它的关键设计是一块板卡 = 一个目录。所有板卡定义都放在board/目录下，每个子目录就是一个完整板卡，例如：

目录	作用
`board/BeagleBone/`	单镜像 + 独立 FAT 启动分区（ARM 板经典参考）
`board/VersatilePB/`	双镜像：一个引导内核、一个 World
`board/GenericI386/`	单分区、启动部件集成（x86 参考）
`board/NewBoardExample/`	新板卡骨架模板，含完整注释
`lib/`	所有公共辅助函数（分区、U-Boot、FreeBSD 构建等）
`option/`	可插拔功能选项（用户、Swap、NTP 等）

添加新板卡前，建议先通读一遍 board/NewBoardExample/README 和 1 个真实板卡的定义，理解后再动手。

二、板卡定义的核心机制：阶段 + 策略

理解 Crochet 只需掌握一个概念：策略列表（strategy list）。

配置文件通过strategy_add把一个个 shell 函数注册到不同"阶段"，构建时所有函数按阶段顺序执行。阶段定义见lib/strategy.sh，最常用的有：

阶段	时机	典型任务
`PHASE_CHECK`	构建前	检查 U-Boot 源码、交叉编译工具是否就绪
`PHASE_BUILD_OTHER`	FreeBSD 世界与内核编译完之后	编译 U-Boot、ubldr 等第三方部件
`PHASE_PARTITION_LWW`	制作镜像文件时	分区（LWW = 只执行最后注册的一个）
`PHASE_BOOT_INSTALL`	启动分区挂载后（cwd 已在启动分区）	拷贝 bootloader、DTB、ubldr
`PHASE_FREEBSD_BOARD_INSTALL`	FreeBSD 分区安装世界之后	安装内核、放板卡专属文件

💡LWW（Last Write Wins）阶段只能生效一个注册项，分区、挂载这类"只能有一份方案"的步骤都归此类。

一个板卡定义只需要3 个必备变量，写在setup.sh中：

KERNCONF=XXX # 内核配置名（须存在于 FreeBSD 源码树中） TARGET_ARCH=armv7 # 目标架构 IMAGE_SIZE=$((1000 * 1000 * 1000)) # 镜像大小，单位字节

三、第 1 步：复制 NewBoardExample 创建板卡目录

把模板目录复制为新板卡（把MyBoard换成你的板子名）：

cp -r board/NewBoardExample board/MyBoard

标准目录长这样：

board/MyBoard/ ├── setup.sh # 唯一必须文件：板卡定义核心 ├── README # 你这块板卡的烧录/启动说明 ├── files/ # U-Boot 补丁、二进制 blob 等辅助文件 │ ├── uboot_patch10_makefile_lc.patch │ └── uboot_patch11_examples_api_makefile_static.patch └── overlay/ # 会被原样拷贝进 FreeBSD 分区 └── etc/ ├── fstab └── rc.conf

overlay/下的文件会被自动拷贝到镜像里，无需额外代码——这是放置etc/fstab、etc/rc.conf、boot/loader.rc等静态配置的标准方式（机制实现在lib/board.sh）。

四、第 2 步：在各阶段注册操作

打开board/MyBoard/setup.sh，模板里已按阶段分节写好详细注释。以最常用的 ARM 板为例，最小可用骨架大致是：

# 1. 检查阶段：确认 U-Boot 源码就位（会提示你如何获取） strategy_add $PHASE_CHECK myboard_check_uboot # 2. 构建阶段：编译 ubldr（U-Boot 的 FreeBSD 引导器） strategy_add $PHASE_BUILD_OTHER freebsd_ubldr_build UBLDR_LOADADDR=0x2000000 # 3. 分区：MBR + 32MB FAT 启动分区 + 剩余空间 UFS myboard_partition_image ( ) { disk_partition_mbr disk_fat_create 32m 16 disk_ufs_create } strategy_add $PHASE_PARTITION_LWW myboard_partition_image # 4. 填充启动分区（此时 cwd 已在 FAT 分区根） strategy_add $PHASE_BOOT_INSTALL freebsd_ubldr_copy_ubldr . strategy_add $PHASE_BOOT_INSTALL freebsd_install_fdt myboard.dts myboard.dtb # 5. FreeBSD 分区：安装内核 strategy_add $PHASE_FREEBSD_BOARD_INSTALL board_default_installkernel .

几个能省一半工作量的辅助函数（定义在lib/uboot.sh、lib/disk.sh、lib/freebsd.sh）：

uboot_test <变量名> <测试文件>—— 检查 U-Boot 源码，缺失时自动打印获取命令
uboot_patch / uboot_configure / uboot_build—— 打补丁、配置、编译一条龙
disk_partition_mbr / disk_fat_create / disk_ufs_create—— 标准 MBR 分区组合拳
freebsd_install_fdt—— 从 FreeBSD 源码树取.dts并自动编译成.dtb拷贝过去

五、第 3 步：搞定 U-Boot 引导链（ARM 板重点）

FreeBSD/ARM 平台普遍采用U-Boot + ubldr双引导器架构，分工非常清晰：

U-Boot：懂硬件（SD 卡、内存地址、串口）
ubldr：懂 FreeBSD（FreeBSD 源码树自带的 loader(8) 变体，通用代码、无板卡相关逻辑）

要让这条链跑通，U-Boot 通常需要做 3 处改动，模板 README 和files/目录都给了现成答案：

FreeBSD 构建补丁：让 U-Boot 能在 FreeBSD 上编译。files/里的两个补丁（修复cc -print-file-name问题、给PLATFORM_LIBS加-lc）可作起点，按你的 U-Boot 版本微调。
启用 API 和 ELF 加载：在include/configs/<yourboard>.h中加入CONFIG_API、CONFIG_CMD_ELF（ubldr 依赖 U-Boot API 做硬件交互，且以 ELF 方式加载）。
自定义CONFIG_BOOTCOMMAND：让 U-Boot 依次加载 uEnv.txt（允许用户自定义）、DTB、ubldr，最后执行 ubldr。

一个容易踩的坑：ubldr 是 ELF 可执行文件，会链接到固定加载地址，不同板卡内存起始地址不同，所以UBLDR_LOADADDR必须按你的板卡实际调整。另外，开发期间 U-Boot 源码会被原地打补丁，一旦打到一半状态，删掉重新检出源码即可。

六、第 4 步：配置 overlay 文件

把overlay/etc/fstab改成你板卡的真实挂载方案，例如 BeagleBone 把 FAT 启动分区挂到/boot/msdos：

# /boot/msdos 为 FAT 启动分区 /dev/md0 /boot/msdos msdosfs ro 0 0 /dev/ad0s2 / ufs rw 1 1

同时用overlay/etc/rc.conf打开 sshd、串口控制台等服务。这些文件会被自动拷入镜像的对应路径，顺序上是"板卡 overlay → 全局 overlay → work/overlay"层层覆盖，无需一行拷贝代码。

七、第 5 步：构建镜像并上板验证

在 Crochet 根目录写一个只含一行board_setup MyBoard的配置文件（其余可选，参考 config.sh.sample 的丰富注释），然后：

sudo /bin/sh crochet.sh -c myboard.config.sh

脚本会按阶段自动执行，缺什么就明确告诉你怎么补（比如 U-Boot 源码下载地址），补齐后重跑即可。首次完整构建可能耗时数小时；之后 Crochet 会把 world、内核结果缓存在work/目录，只调整镜像布局时几分钟就能出新镜像。

成功后，脚本会给出dd命令，把镜像写入 SD 卡，上电开机。如果启动失败，work/下保留着完整的构建日志，是排查第一站。

八、常见问题速查

🔍 该抄哪个现成板卡？看引导结构：独立启动分区选 BeagleBone，双镜像选 VersatilePB，x86 选 GenericI386——三者结构差异最大，基本能覆盖所有情况（board/NewBoardExample/setup.sh头部注释也给出了这个对照）。

🧩 U-Boot 一定要从源码编译吗？是，Crochet 坚持工具类部件永远从源码构建（二进制 blob 尽量少）。这要求你定义PHASE_CHECK时给出准确的下载指引，Crochet 从不自动下载任何东西，也从不改动宿主系统。

📏 内核配置必须放在 FreeBSD 源码树里吗？目前是的。KERNCONF指向的配置文件需位于源码树内，树外配置仍是社区待办事项。

🤝 跑通之后做什么？写一份board/MyBoard/README说明烧录与串口参数，然后考虑把成果回馈给项目——board/下 30 多款板卡都是这么积累的。

结语

为 FreeBSD 添加新开发板，在 Crochet 里就是"复制模板 → 填 3 个变量 → 注册几个阶段 → 调通 U-Boot"四件事。借助lib/下封装好的分区、U-Boot、ubldr 辅助函数，最难的部分已有标准答案。打开board/NewBoardExample/setup.sh，每一行注释都是一步操作指引，现在就可以开始你的第一块板卡了。

【免费下载链接】crochetBuild FreeBSD images for RaspberryPi, BeagleBone, PandaBoard, and others.项目地址: https://gitcode.com/gh_mirrors/cr/crochet

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考