ATSAMD21 Bootloader编译与烧录全攻略：从源码定制到实战调试

1. 项目概述与核心价值

如果你正在玩ATSAMD21系列芯片，比如Arduino Zero或者Adafruit的Feather M0，那你肯定绕不开Bootloader这个话题。Bootloader，简单说就是芯片上电后跑的第一段代码，它的任务是把你的主程序从存储介质（比如Flash）里搬出来，放到该跑的地方，然后跳过去执行。听起来简单，但这段代码决定了你的设备能不能启动、怎么启动，以及未来能不能通过USB或者网络自己给自己更新程序（也就是OTA升级）。原厂或者开发板厂商提供的Bootloader固然能用，但当你需要定制USB的厂商ID（VID）和产品ID（PID）、优化启动速度，或者想集成一些特殊的预初始化功能时，自己动手编译和烧录一个就成了必经之路。

网上关于ATSAMD21 Bootloader的资料不少，但大多比较零散，或是直接给个二进制文件让你烧，至于这文件怎么来的、编译时有哪些坑、烧录失败怎么排查，往往一笔带过。我这篇文章，就是把我自己折腾ATSAMD21 Bootloader编译与烧录的全过程，包括环境搭建、源码获取、编译参数调整、多种烧录工具的使用，以及踩过的各种坑和解决方案，系统地梳理出来。目标很明确：让你看完之后，不仅能照着步骤成功操作，更能理解每一步背后的“为什么”，真正掌握这门技能，以后面对类似的芯片也能举一反三。

2. 编译环境搭建与源码获取

自己编译Bootloader，第一步就是把“厨房”准备好。这里说的厨房，就是你的编译工具链和源代码。

2.1 工具链的选择与安装

Bootloader的编译通常依赖make工具和ARM架构的GCC交叉编译器。对于Windows用户，最省心的方式不是去单独折腾Cygwin或MSys，而是直接使用Arduino IDE为你准备好的环境。

当你通过Arduino IDE的“开发板管理器”安装了“Arduino SAMD Boards”这个核心包时，它已经默默地在你的电脑上安装好了一套完整的编译工具链，包括ARM GCC和必要的工具。你只需要确保这个包已安装。打开Arduino IDE，点击“文件”->“首选项”，在“附加开发板管理器网址”中确保有https://www.arduino.cc/download_handler.php?f=/packages/arduino/package_index.json，然后在“工具”->“开发板”->“开发板管理器”中搜索“SAMD”，安装“Arduino SAMD Boards”即可。

安装好后，工具链的路径通常位于你的用户目录下，例如C:\Users\[你的用户名]\AppData\Local\Arduino15\packages\arduino\tools。你可以把这个路径下的arm-none-eabi-gcc的bin目录（例如...\arm-none-eabi-gcc\7-2017q4\bin）添加到系统的PATH环境变量中，方便在命令行直接调用。不过，对于编译Bootloader，我们更常用的方法是利用Arduino核心包中已经配置好的Makefile，它内部已经指定了工具路径。

注意：强烈不建议在Arduino IDE的安装目录或核心包目录（如arduino15\packages\...\hardware\samd\...）下直接修改和编译Bootloader源码。因为当你更新核心包时，这些修改会被无情地覆盖掉，前功尽弃。正确的做法是“另起炉灶”。

2.2 获取最新Bootloader源码

Bootloader的源代码由Arduino官方维护，存放在GitHub的ArduinoCore-samd仓库中。获取源码有两种推荐方式：

1. 使用Git克隆（推荐）：这是保持与上游同步的最佳方式。打开命令行（Windows的CMD或PowerShell，macOS/Linux的终端），导航到你打算存放代码的目录，执行：

   git clone https://github.com/arduino/ArduinoCore-samd.git

   这会将整个仓库克隆到本地。之后如果需要更新，只需进入该目录执行git pull。

2. 下载ZIP快照：如果你不熟悉Git，或者网络环境受限，可以直接在GitHub仓库页面点击“Code”按钮，选择“Download ZIP”。解压后即可使用。缺点是后续更新麻烦，需要重新下载和解压。

源码仓库的结构中，我们重点关注bootloaders目录。里面针对不同的开发板有不同子目录，例如zero对应Arduino Zero，feather_m0对应Adafruit Feather M0。每个子目录里都包含了该板型Bootloader的特定源代码和Makefile。

2.3 解决编译依赖与首次编译

进入目标板型的目录，例如针对Arduino Zero：

cd ArduinoCore-samd\bootloaders\zero

直接运行make all命令尝试编译。十有八九，你会遇到第一个拦路虎：

fatal error: sam.h: No such file or directory

这个错误的原因是，Bootloader的编译依赖于Atmel（现Microchip）为SAM系列芯片提供的设备描述头文件和外设访问库。这些文件并没有包含在ArduinoCore-samd仓库里，而是随着“Arduino SAMD Boards”核心包一起安装到了你的本地。

解决方案很简单：确保你已经按照2.1节所述，通过Arduino IDE的“开发板管理器”完整安装了“Arduino SAMD Boards”核心包。安装过程会自动下载并部署这些必要的头文件和库文件到arduino15\packages目录下。Makefile里已经写好了查找这些依赖的路径（通常是ARDUINO_CORE_PATH变量），只要核心包安装正确，make命令就能自动找到它们。

解决依赖后，再次运行make all。如果一切顺利，你会在当前目录下看到编译成功的输出，并生成两个关键文件：samd21_sam_ba.hex和samd21_sam_ba.bin。.hex文件是包含地址信息的Intel HEX格式，.bin是纯二进制镜像，两者在后续烧录中根据工具要求选用。

3. 核心配置解析：VID/PID与Makefile定制

编译通过只是第一步，让Bootloader真正为你所用，通常需要修改一些关键配置，其中最重要的就是USB的厂商ID（VID）和产品ID（PID）。

3.1 为什么需要修改VID/PID？

每个USB设备都必须向主机报告一对16位的VID和PID，操作系统根据这对ID来加载对应的驱动程序。Arduino官方为Arduino Zero使用的Bootloader设置了一个特定的VID/PID（例如，Arduino LLC的VID是0x2341）。如果你的产品是基于ATSAMD21的自定义硬件，继续使用Arduino的ID可能会带来问题：

1. 驱动冲突：如果用户电脑上已经安装了Arduino IDE的驱动，你的设备可能会被识别为Arduino Zero，而不是你自己的产品。
2. 无法定制化：在产品化时，使用自己的VID/PID是专业性的体现，也便于管理和分发专属的驱动程序或烧录工具。
3. 功能区分：如果你有多个不同功能的产品，可以通过不同的PID来区分。

因此，在分发或生产你自己板子的Bootloader之前，修改VID/PID是必须的。

3.2 定位与修改Makefile中的关键参数

在bootloaders/zero（或其他板型目录）下，用文本编辑器打开Makefile文件。我们需要找到定义USB描述符的地方。在ATSAMD21的Bootloader（通常是基于SAM-BA协议）中，VID和PID通常在源码或Makefile中定义。

一种常见的方式是在Makefile中通过编译参数（CFLAGS）传递。仔细搜索Makefile，你可能会找到类似这样的行：

CFLAGS += -DUSB_VID=0x2341 CFLAGS += -DUSB_PID=0x0042

或者，它们可能被定义在某个头文件（如board_definitions.h）中，而Makefile包含了该头文件。

修改步骤：

1. 将-DUSB_VID=0x2341中的0x2341替换为你公司或个人申请的合法VID。如果你没有申请，可以在测试阶段使用一些用于测试的VID（如0x1209，这是USB-IF授权的“PID Codes”测试用VID），但产品化前必须使用合法ID。
2. 将-DUSB_PID=0x0042中的0x0042替换为你自定义的PID。
3. 保存Makefile。

重要提示：修改VID/PID后，必须执行make clean，然后再执行make all。make clean会清除之前编译生成的中间文件（.o文件等），确保新的VID/PID定义被重新编译并链接到最终的二进制文件中。如果只运行make all，编译器可能因为依赖关系判断未更新而跳过重编译关键文件，导致修改不生效。

3.3 其他可能的定制项

除了VID/PID，Makefile还可能控制其他编译选项，例如：

• 时钟源配置：CRYSTALLESS选项。ATSAMD21内部有一个8MHz RC振荡器，精度较低但可以节省外部晶振。如果板子上没有焊接外部晶振（如一些超小型设计），需要启用此选项。在Makefile中寻找CFLAGS += -DCRYSTALLESS并取消注释或设置为1。
• LED引脚定义：Bootloader运行时用来指示状态的LED引脚。如果和你板子的硬件设计不符，需要修改对应的LED_PIN定义。
• 串口引脚：用于SAM-BA通信的串口引脚（如果使用UART模式而非USB）。同样需要根据硬件原理图调整。

修改任何配置后，都请遵循“修改 ->make clean->make all”的流程。

4. 烧录方法详解：从EDBG到J-Link

生成.hex或.bin文件后，下一步就是把它“灌”进芯片的Flash存储器。根据你手头的工具和目标板的不同，有几种主流方法。

4.1 方法一：为Arduino Zero更新Bootloader（使用板载EDBG）

这是最简单的情况。Arduino Zero板载了一个叫做EDBG（Embedded Debugger）的调试器，它本身也是一个ATSAMD21芯片，专门负责给主芯片编程。这种方法无需外部工具。

操作步骤：

1. 替换文件：找到你当前Arduino IDE中SAMD核心包Bootloader的存放位置。路径类似C:\Users\[你的用户名]\AppData\Local\Arduino15\packages\arduino\hardware\samd\[版本号]\bootloaders\zero。将你自己编译生成的samd21_sam_ba.bin文件复制到这里，建议先备份原有的同名文件。
2. 连接板子：用USB线连接Arduino Zero的“Programming Port”（通常是靠近复位按钮的那个Micro-USB口）。这个口直接连接到板载的EDBG调试器。
3. 配置IDE：打开Arduino IDE，在“工具”菜单中依次选择：
   • 开发板：Arduino Zero (Programming Port)
   • 编程器：Atmel EDBG
4. 烧录Bootloader：点击“工具”菜单下的“烧录引导程序”。IDE会通过EDBG，使用bossac工具将我们替换的.bin文件写入到主芯片的Bootloader区域（通常是Flash的起始部分）。

这个过程很快，几秒钟就完成。成功后，板子会自动复位。此时，你的Zero就运行着你自定义VID/PID的Bootloader了。你可以尝试上传一个简单的Blink程序，验证Bootloader工作正常。

实操心得：这种方法本质上是“欺骗”了Arduino IDE，让它用自己的编程流程烧写我们自定义的Bootloader。优点是极其方便，缺点是会覆盖核心包的原文件。务必做好备份，并且当Arduino IDE更新SAMD核心包时，这个文件又会被覆盖掉。因此，这更适合一次性修改或测试。

4.2 方法二：使用外部调试器（J-Link/ST-Link）与Atmel Studio

对于没有板载调试器的板子（比如单独的ATSAMD21芯片、自定义底板，或者像Feather M0这样板载调试器接口不开放给主芯片的），我们需要借助外部调试器，如SEGGER J-Link或ST-Link。这里以J-Link和Atmel Studio（现为Microchip Studio）为例。

硬件连接： 将J-Link的SWD接口连接到目标板的对应引脚：

• SWDIO：数据线，连接芯片的PA31引脚（SAMD21的SWDIO）。
• SWCLK：时钟线，连接芯片的PA30引脚（SAMD21的SWCLK）。
• GND：共地。
• VCC（可选）：为J-Link提供目标板电压参考，通常接3.3V。

Atmel Studio 操作流程：

1. 安装与连接：确保已安装Atmel Studio和J-Link的驱动程序。连接J-Link到电脑和目标板，给目标板上电。
2. 打开Device Programming：在Atmel Studio中，点击“Tools” -> “Device Programming”。
3. 选择工具与设备：
   • Tool: 选择J-Link。
   • Device: 选择ATSAMD21G18A（根据你的具体芯片型号选择，G18表示128KB Flash，G17是64KB，J18是256KB等）。
   • Interface: 选择SWD。
   • 点击“Apply”。此时可以点击“Read Device Signature”，如果连接正确，会成功读取到芯片的ID，如0x10010005。
4. 擦除与编程：
   • 切换到“Memories”标签页。
   • 在“Flash”区域，点击“...”浏览按钮，选择你编译生成的samd21_sam_ba.hex文件。
   • 关键一步：在编程前，建议先执行“Erase now”（擦除整个芯片），或者至少确保编程地址从0x00000000开始。因为Bootloader必须位于Flash的起始位置。
   • 点击“Program”按钮。Atmel Studio会先擦除相应扇区，然后写入Bootloader。

烧录深度解析： 为什么Bootloader必须烧在0x00000000？这是由芯片的硬件设计决定的。芯片上电或复位后，程序计数器（PC）指针总是从0x00000000地址开始取指执行。Bootloader作为第一段代码，必须放在这里。它的职责是初始化系统，然后检查是否有“用户程序”需要跳转执行。用户程序（即你的Arduino Sketch）通常被链接到Bootloader之后的地址（例如0x00002000或0x00004000，具体取决于Bootloader大小）。Bootloader末尾会有一个跳转指令，指向用户程序的入口。

4.3 方法三：命令行工具（adalink/OpenOCD）

如果你不喜欢图形界面，或者需要在自动化脚本中集成烧录步骤，命令行工具是更好的选择。

使用 adalink：adalink是一个轻量级的命令行工具，专用于编程Atmel/Microchip的芯片。它支持J-Link、ST-Link等多种调试器。

1. 安装：通常可以通过Python的pip安装：pip install adalink。
2. 烧录命令：

   adalink -v atsamd21g18a -p jlink -h samd21_sam_ba.hex

   • -v: 指定设备型号。
   • -p: 指定编程器类型（jlink,stlink等）。
   • -h: 指定要烧录的hex文件。 这条命令会完成连接、擦除、编程、校验的全过程。

使用 OpenOCD： OpenOCD是一个开源的片上调试器，功能强大，支持众多调试探头。

1. 配置接口文件：你需要一个配置文件（.cfg）来告诉OpenOCD使用什么调试器和目标芯片。例如，一个简单的jlink-samd21.cfg可能包含：

   source [find interface/jlink.cfg] transport select swd source [find target/at91samdXX.cfg]

2. 烧录命令：

   openocd -f jlink-samd21.cfg -c "program samd21_sam_ba.hex verify reset exit"

   这条命令会启动OpenOCD，加载配置，然后执行编程、校验、复位芯片并退出的操作。

命令行工具的优势在于可脚本化、可追溯，适合批量生产或持续集成（CI）环境。

5. 验证、调试与故障排除实录

烧录完成并不代表万事大吉，Bootloader是否能正常工作需要验证，遇到问题更需要知道如何排查。

5.1 验证Bootloader工作

1. USB枚举测试：对于使用USB CDC（虚拟串口）的SAM-BA Bootloader，最直接的验证方法是连接USB到电脑。如果VID/PID修改成功且Bootloader运行正常，电脑的设备管理器（Windows）或lsusb命令（Linux）中应该会出现一个带有你自定义VID/PID的USB设备，通常显示为“USB Serial Device”或“Arduino LLC Arduino Zero”之类的描述（描述符可能还是旧的，但ID变了）。
2. 触发Bootloader模式：大多数SAM-BA Bootloader设计为在上电时检测某个引脚（如复位按钮）的状态，或者通过双击复位按钮进入。以Arduino Zero为例，快速双击复位按钮，板载的“ON”LED会呈现呼吸灯效果，并且USB设备会重新枚举为Bootloader对应的串口。此时，你可以尝试用bossac命令行工具或Arduino IDE（选择正确的端口）进行程序上传测试。
3. 串口通信测试：如果不使用USB，而是使用UART接口的Bootloader，可以通过串口助手发送特定的命令字符串（如#）来测试Bootloader是否响应。

5.2 常见问题与排查技巧

问题1：编译失败，提示“arm-none-eabi-gcc: command not found”

• 原因：交叉编译工具链未安装或未在PATH中。
• 解决：确保已安装“Arduino SAMD Boards”核心包。如果要在独立命令行中使用，需将工具链的bin目录（见2.1节）添加到系统PATH环境变量中，或者直接在Makefile中指定完整的工具路径。

问题2：烧录后芯片无反应，USB不识别

• 排查步骤：
  1. 检查电源：用万用表测量芯片VDD引脚电压是否为3.3V左右且稳定。
  2. 检查时钟：如果Bootloader配置依赖外部晶振（默认），检查晶振是否起振（需用示波器）。可以尝试在Makefile中启用CRYSTALLESS选项，使用内部RC振荡器编译一个版本再烧录测试。
  3. 检查复位引脚：确保复位引脚（RESET）没有被意外拉低。
  4. 检查SWD连接：如果使用外部调试器，确认SWDIO和SWCLK连接正确且上拉电阻（通常4.7k-10kΩ上拉到3.3V）已焊接。这两个引脚同时也是GPIO，如果被其他电路影响可能导致调试器无法连接。
  5. 验证二进制文件：用编程器读取芯片Flash最开始的一小段内容（例如前256字节），与生成的.hex或.bin文件开头部分进行十六进制对比，确认数据已正确写入。
  6. 检查Bootloader大小和偏移：确认你编译的Bootloader大小没有超过芯片预留的Bootloader区域（例如8KB）。如果Bootloader太大，可能会覆盖到应用程序区域或配置区，导致异常。

问题3：能识别USB，但无法通过Arduino IDE上传程序

• 排查步骤：
  1. 检查端口选择：在Bootloader模式下，设备会枚举为一个新的COM端口，确保在Arduino IDE中选择了这个新出现的端口。
  2. 检查bossac工具：Arduino IDE使用bossac工具与SAM-BA Bootloader通信。有时bossac版本不兼容。可以尝试手动使用命令行bossac进行上传。命令格式类似：

     bossac -p COMx -e -w -v -b your_sketch.bin -R

     （-p指定端口，-e擦除，-w写入，-v校验，-b指定文件，-R复位）
  3. 检查Bootloader协议：确保你编译的Bootloader是SAM-BA协议，并且版本与bossac工具兼容。不同版本的Arduino核心包可能对应不同版本的Bootloader。

问题4：芯片被锁死，调试器无法连接

• 原因：这可能是因为芯片的安全位（Security Bit）被意外设置，或者Bootloader区域被错误地写保护。
• 解决：
  1. 使用高压编程器恢复：这是最彻底的方法。使用支持SAM D系列的专用高压编程器（如Atmel-ICE配合高压适配器），通过ERASE命令进行全片擦除，可以清除安全位。
  2. 尝试不同的擦除方式：在Atmel Studio的“Device Programming” -> “Memories”界面，尝试“Chip Erase”而不是“Sector Erase”。有时“Erase and Program”选项可能无法解除保护。
  3. 检查NVM User Row配置：ATSAMD21的NVM用户行（User Row）可以配置写保护。如果之前有程序修改了这里，可能导致Bootloader区域被保护。需要通过调试器在解锁状态下修改用户行配置。

避坑指南：在进行任何Bootloader烧录操作前，尤其是对全新的或不确定状态的芯片，务必先尝试读取芯片的Device Signature和Bootloader区域内容。这能确认调试器连接正常、芯片型号正确、以及当前Bootloader状态。养成这个习惯能避免很多无谓的折腾。

整个流程走下来，从环境搭建到成功烧录验证，你会对ATSAMD21的启动流程、Bootloader的作用、以及底层编程工具有更深刻的理解。这不仅仅是完成一次操作，更是掌握了嵌入式开发中一项基础且重要的技能。当你下次需要为不同的芯片定制Bootloader时，这套思路和方法论依然适用。