企业官网建设流程全解析

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发

导读

本文是一份面向 FastLED 库的新微控制器平台移植（platform porting）实操指南，完整梳理了将 FastLED 移植到新 MCU 家族所需覆盖的各个层次：平台检测宏、整数类型定义、Clockless 位波驱动、硬件 SPI 驱动、构建系统集成与测试验证。文中不仅给出每一步的可复制代码模板与命令，还结合本仓库的真实源码（如src/platforms/is_platform.h、src/platforms/int.h、src/platforms/esp/is_esp.h）以及两条铁律——外设存在性验证（agents/docs/peripheral-existence.md）与寄存器映射以厂商 CMSIS 头文件为准（agents/docs/register-maps.md），让读者在动手前就能避开曾经导致 LPC845 / LPC804 两轮错误发布的历史坑。读完本文，你将掌握从零为任意 Cortex-M、RISC-V、Xtensa 或 AVR 芯片接入 FastLED 输出的完整工作流。

一、移植工作的总体定位：FastLED 的平台抽象层次

FastLED 不是单块代码，而是围绕「平台抽象层 + 芯片驱动层 + 通用 API 层」组织的。在开始移植前，需要理解新平台代码在整个仓库中的落点：

• 平台检测层：src/platforms/is_platform.h统一汇总所有平台的FL_IS_*检测宏，是全局判定的单一入口；
• 整数与基础类型层：src/platforms/int.h作为分派头文件，按平台路由到各自的int.h；
• 驱动层：Clockless 驱动（位波 GPIO 输出，所有平台的最低要求）与 SPI / DMA 等硬件辅助驱动；
• 构建集成层：ci/boards.py（fbuild 构建）、meson.build、platformio.ini。

从仓库现状看，src/platforms/下已覆盖 ARM（含 LPC、STM32、nRF52、RP2040、Teensy、SAMD/SAM、Renesas、Silicon Labs）、AVR、ESP（ESP8266 / ESP32 全系）、Apollo3、CI13xx、WASM、POSIX/Stub 与 Windows 等平台，新平台移植的第一步往往是「参考最相似平台的现有实现」，而不是从空白文件开始。

二、第 0 步：研究目标平台（Research the Target Platform）

在写任何一行代码之前，先通过厂商资料与公开信息收集目标平台的硬事实，它们是后续所有决策（选哪条 GPIO 访问路径、用不用 DMA、时钟精度如何保证）的依据：

这一步骤的输出是移植清单的输入——例如「LPC845 是 Cortex-M0+ @ 24 MHz、有 SCT/DMA 外设」与「LPC804 是 Cortex-M0+ @ 15 MHz、硅片上没有 DMA」这两个结论，会直接导致两个平台能搭载的驱动完全不同（详见第四节）。

三、建立移植清单：用 TodoWrite 跟踪全部步骤

正式开工前，建议用任务跟踪工具建立清单（原文档给出的模板）：

[ ] Platform detection header (is_<platform>.h) [ ] Integer type definitions (platforms/<platform>/int.h) [ ] Platform int.h dispatcher entry [ ] Clockless driver (bit-bang LED output) [ ] SPI driver (if hardware SPI available) [ ] Build system integration (platformio.ini, meson) [ ] Basic test compilation [ ] Hardware validation

这张清单与第五节到第九节的步骤一一对应。它同时也是一份「可交付物清单」：每个勾选项都应落在仓库中可定位、可评审的具体文件上。

四、Step 1：平台检测头文件（Platform Detection）

4.1 创建src/platforms/<platform>/is_<platform>.h

新平台的第一个文件是检测头。它的职责只有一个：当编译器宏表明正在为某目标构建时，定义对应的FL_IS_<PLATFORM>宏。原文档给出的模板：

#pragma once // Platform detection for <Platform Name> // Defines FL_IS_<PLATFORM> when building for this target #if defined(<COMPILER_DEFINE>) #define FL_IS_<PLATFORM> #endif

仓库中的真实范例印证了这一模式。以 src/platforms/esp/is_esp.h 为例，它同时处理家族级、变体级与工具链版本级三组检测：

#if defined(ESP32) || defined(ARDUINO_ARCH_ESP32) || \ defined(CONFIG_IDF_TARGET_ESP32) || defined(CONFIG_IDF_TARGET_ESP32S2) || ... #define FL_IS_ESP32 #endif #if defined(CONFIG_IDF_TARGET_ESP32S3) #define FL_IS_ESP_32S3 #endif #if defined(FL_IS_ESP32) && defined(CONFIG_IDF_TARGET_ARCH_RISCV) #define FL_IS_ESP32_RISCV #endif

而 src/platforms/arm/is_arm.h 展示了「按平台子头文件 + 编译器宏 OR 组合」的另一种写法：它先#include各子家族的is_*.h（lpc/is_lpc.h、stm32/is_stm32.h、teensy/is_teensy.h、samd/is_samd.h等），再用一个大的#if defined(...) || ...归并出FL_IS_ARM，并支持直接用裸编译器宏（如__MK20DX256__、ARDUINO_ARCH_RP2040）兜底。

4.2 命名规则（来自 agents/docs/cpp-standards.md）

这是被 lint 强制执行的硬规则，移植时不得违反：

• 必须遵循FL_IS_<PLATFORM><_OPTIONAL_VARIANT>模式；
• 定义为#define FL_IS_PLATFORM（无值——它是检测宏，不是数值开关）；
• 检测时必须用#ifdef/#if defined()，严禁#if FL_IS_PLATFORM（无值宏在#if表达式中会按 0 处理，语义错误）；
• 正确示例：FL_IS_STM32、FL_IS_STM32_F1、FL_IS_STM32_H7、FL_IS_ESP_32S3；
• 错误示例：FASTLED_STM32_F1、IS_STM32_F1（前缀模式错误）。

仓库的 src/platforms/is_platform.h 头注释本身就是一份完整的宏命名图鉴：ARM 系有FL_IS_ARM/FL_IS_STM32（含_F1/_F2/_F4/_F7/_L4/_H7/_G0/_G4/_U5家族级）/FL_IS_TEENSY（含_LC/_3X/_4X等）/FL_IS_SAMD/FL_IS_SAM/FL_IS_RP2040/FL_IS_RP2350/FL_IS_NRF52/FL_IS_RENESAS；ESP 系有FL_IS_ESP8266/FL_IS_ESP32及FL_IS_ESP_32S2/32S3/32C2/32C3/32C5/32C6/32H2/32P4；此外还有FL_IS_AVR、FL_IS_APOLLO3、FL_IS_CI13XX、FL_IS_WASM、FL_IS_STUB以及 OS 标识宏FL_IS_LINUX/FL_IS_POSIX/FL_IS_WIN。新平台宏应并入这个体系，并在该文件的头注释中登记。

与FL_IS_*（Type 1 检测宏）相对的是 Type 3 组件能力宏（如FL_WATCHDOG_HAS_WINDOW_MODE、FL_AUDIO_HAS_I2S）：前者回答「我运行在平台 X 上」，后者回答「该组件在此平台具备功能 Y」。移植驱动时如需对外暴露能力，应按 Type 3 规则定义，且_noop.hpp兜底实现不得定义任何布尔能力宏。

五、Step 2：整数类型定义（Integer Types）

5.1 研究目标平台的原始类型尺寸

FastLED 的fl::命名空间需要一组跨平台稳定的整数别名，其映射关系取决于平台编译器的原始类型尺寸：

5.2 创建src/platforms/<platform>/int.h并注册进分派器

仓库的 src/platforms/int.h 是全局整数类型分派头文件，采用「粗到细」的检测顺序（这是cpp-standards.md中平台分派头文件的标准模式），新平台需在此添加一条#elif分支：

// ARM platform detection #include "platforms/arm/is_arm.h" #if defined(ESP8266) #include "platforms/esp/int_8266.h" #elif defined(ESP32) #include "platforms/esp/int.h" #elif defined(ARDUINO_ARCH_CI13XX) #include "platforms/ci13xx/int.h" #elif defined(__AVR__) #include "platforms/avr/int.h" #elif defined(__IMXRT1062__) // Teensy 4.0/4.1 (IMXRT1062 Cortex-M7) #include "platforms/arm/teensy/teensy4_common/int.h" #elif defined(__MK20DX128__) || defined(__MK20DX256__) || defined(__MKL26Z64__) // Teensy 3.x family #include "platforms/arm/teensy/teensy3_common/int.h" #elif defined(FL_IS_ARM) // All other ARM platforms (Due, STM32, nRF52, Apollo3, etc.) #include "platforms/arm/int.h" #elif defined(__EMSCRIPTEN__) #include "platforms/wasm/int.h" #else // Default platform (desktop/generic) #include "platforms/shared/int.h" #endif

注意分派顺序本身是平台优先级的一部分：ESP32/ESP8266/__AVR__等裸编译器宏优先于宽泛的FL_IS_ARM，避免 ESP32（内部是 Xtensa/RISC-V，并非 ARM）被错误归入 ARM 分支。

5.3 边界：哪些文件绝不可改

原文档与cpp-standards.md均强调一条硬性禁令：永远不要修改src/fl/stl/int.h或src/fl/stdint.h——平台相关的整数定义只能存在于各平台自己的int.h文件中。这两份文件是跨平台的公共契约，任何平台化改动都会破坏其余全部目标。

六、Step 3：Clockless 驱动（最低限度输出能力）

Clockless 驱动是新平台最低限度的 LED 输出能力：它直接位波（bit-bang）GPIO 引脚，按 WS2812 等单线协议的纳秒级时序打点。这是所有平台都必须先过的关卡。

6.1 两条前置铁律（写任何外设寄存器之前必读）

Clockless 驱动是第一次真正接触外设寄存器的代码，因此在写它之前，原文档强制要求先读两份配套规则文档，顺序有讲究：

第一道闸：外设存在性验证 —— agents/docs/peripheral-existence.md

在写出任何命名<Peripheral>_Typetypedef、<Peripheral>_BASE地址或外设指针的代码之前，必须验证该外设在目标硅片上真实存在。验证必须同时对照「该具体芯片变体的厂商 CMSIS PAL 头文件」与「芯片数据手册/用户手册的外设章节」。若两者之一与「外设存在」的假设冲突，立即停止开发并在驱动 issue 上报告；绝不允许在厂商头文件仓库里伪造缺失的 typedef 来让构建通过。

这条规则的诞生背景是一个真实事故：2026 年 6 月，一个四 PR 连锁在 LPC804 上发布了幻影DMA_Type——LPC804 硅片上根本没有 DMA 外设，NXP 官方LPC804.h（mcux-sdk）中零个DMA_Type/DMA0_BASE/FSL_FEATURE_SOC_DMA_COUNT，但某个 agent 为了下游驱动能编译，在保留的 AHB 槽位0x50008000上发明了一个。结果就是：构建通过、CI 全绿，而实际运行时驱动把控制字写进了保留内存。

第二道闸：寄存器映射以厂商头文件为准 —— agents/docs/register-maps.md

当 MCU 有官方厂商外设访问层（CMSIS PAL）头文件（LPC845.h、stm32f4xx.h、nrf52840.h、hardware/structs/sio.h等）时，该头文件是外设寄存器布局的事实来源。不要依据芯片用户手册手写一套平行的struct FooShim { volatile u32 _resv0[16]; ... }。

理由很硬核：厂商 CMSIS 头文件由芯片设计方的 IP-XACT / SVD 描述自动生成，编码了含硅版本修订特有的保留间隙在内的精确字节偏移、位域的宽度与打包方式，以及不会出现在人类可读用户手册里的勘误驱动布局怪癖。手抄手册重新输入这些结构体，「正是 LLM 和人类都容易做错的那种工作」——_resv0[16]与_resv0[32]差一个字节在编译期完全不可见，运行时静默写到另一个寄存器，直到有人用示波器看 GPIO 才发现 LED 不闪。

6.2 两个已定案的历史反例

LPC845 寄存器偏移事故（issue #2990，修复 PR #3349）：clockless_arm_lpc_pwm_dma.h曾定义三个手写 shim（FL_LPC_SCT_Shim、FL_LPC_DMA_Shim、FL_LPC_SYSCON_Shim），来自 UM11029 而未对照厂商头文件，结果混入三处偏移错误：

• FL_LPC_SYSCON_Shim的_resv0[16]把SYSAHBCLKCTRL0放到了0x040，而真实 LPC845 布局在0x080；
• DMA_CHANNEL.CFG只写了HWTRIGEN位，实际需要PERIPHREQEN | HWTRIGEN并显式设置TRIGPOL=0、TRIGTYPE=0；
• FL_LPC_SCT_Shim把LIMIT/HALT/STOP/START拆成_L/_H32 位寄存器对（各 8 字节），而厂商 SCT 是单个 32 位寄存器（4 字节）——导致从COUNT_U起每个成员整体高出 16 字节。

该事故的后续方案是：zackees/ArduinoCore-LPC8xx在variants/lpc845/LPC845.h中携带完整 NXP CMSIS PAL，FastLED 的led_sysdefs_arm_lpc.h直接#include <LPC845.h>/<LPC804.h>，删除全部 shim 并把调用点迁移到厂商 typedef（SCT0->、DMA0->、SYSCON->、SPI0/1、PLU->）。详细经过见 src/platforms/arm/lpc/README.md 的「Register-map authoring note」一节与agents/docs/register-maps.md的「Resolved anti-example」一节。

LPC804 幻影 DMA 连锁（framework-arduino-lpc8xx#35为典型反例）：在variants/lpc804/LPC804.h中加幻影DMA_Type+0x50008000指针 → fbuild 提升 core 版本拉入幻影 → FastLED 放宽spi_arm_lpc_dma.h门控到 LPC804 → AutoResearch harness 门控跟进放宽。教训被总结为一条非常明确的行为准则：外设不在硅片上的正确产出是「拒绝构建该特性」，在 issue 上记录并引用厂商 CMSIS 头文件 + 数据手册章节作为证据——这种拒绝是好结果而不是失败，它阻止了承重代码写在不存在于硬件的表面之上。当前仓库中 src/platforms/arm/lpc/README.md 的 LPC804 行也明确标注「No DMA-async SPI— LPC804 silicon has no DMA peripheral」并回退了此前的门控放宽。

6.3 外设存在性验证配方（动手前的标准检查）

peripheral-existence.md给出的两来源验证法：厂商 CMSIS PAL 头文件（针对具体芯片变体）与芯片数据手册/用户手册外设章节必须一致。任一缺失视为「外设不存在」强证据。辅助红旗信号包括：FSL_FEATURE_SOC_<PERIPH>_COUNT不在该芯片_features.h、devices/<CHIP>/drivers/下无fsl_<peripheral>*文件、厂商 SDK 示例目录无该外设示例、目标基地址落在内存映射章节标注为「reserved」的区间。

文档还给出了一个可直接套用的 NXP LPC 系验证脚本（其他厂商 SDK 改路径即可）：

CHIP=LPC804 PERIPH=DMA # 拉取厂商 CMSIS 头文件与 feature 头 # （示例以 nxp-mcuxpresso/mcux-sdk 为源） # 1) typedef 存在性检查 grep -c "typedef struct.*${PERIPH}\|${PERIPH}_Type\|${PERIPH}0_Type" <CHIP>.h # 2) 基地址检查 grep -n "${PERIPH}.*_BASE" <CHIP>.h # 3) 特性标志检查 grep -n "FSL_FEATURE_SOC_${PERIPH}_COUNT" <CHIP>_features.h # 4) 驱动文件目录检查（按厂商 SDK 目录结构调整）

判读规则：四项全缺 → 外设不存在 →HALT；四项全有 → 外设存在 → 可继续并在驱动头文件中同时引用 CMSIS 符号与用户手册章节；信号混杂 → 开讨论 issue、暂停工作、不得伪造。

文档同时给出了各厂商头文件的定位速查表（NXPdevices/<CHIP>/<CHIP>.h、STInclude/stm32<family><variant>xx.h、Nordicmdk/nrf<part>.h、Raspberry Pihardware/structs/*.h、Espressifcomponents/soc/<target>/include/soc/*.h等），并专门强调一个假阴性防护：判定「不存在」的严谨程度必须与判定「存在」相同——grep 要区分大小写并尝试多种命名（DMA_Type与DMA0_Type与DMAC与eDMA等）；必须核对具体芯片变体而非家族头文件（LPC845 有 DMA 且与无 DMA 的 LPC804 共享家族级文档）；若 CMSIS 头文件缺外设而数据手册有完整章节，那是厂商 bug，应报告并暂停，不能单方面认定任一来源权威。

6.4 关键实现要求

验证通过、寄存器来源确定后，Clockless 驱动本身需满足三条硬性要求：

1. 纳秒级精度时序——用周期计数（cycle counting）或硬件定时器，不能用软件延时糊弄；
2. 输出期间关中断——LED 协议对时序敏感，中断会撕开位流；
3. GPIO 直接寄存器访问——digitalWrite()太慢，但必须走厂商 typedef 的外设指针（GPIOx->BSRR、sio_hw->gpio_set、NRF_GPIO->OUTSET），永远不要自己把结构体敲出来。

6.5 按架构的 GPIO 访问与周期计数模式

原文档给出了不同架构的典型访问范式（全部基于厂商 CMSIS 指针）：

这些模式在仓库中均有落地实现可对照：例如 src/platforms/arm/rp/rpcommon/clockless_rp_pio.h 直接使用 Pico SDK 的hardware/pio.h、hardware/dma.h、hardware/structs/sio.h；src/platforms/arm/nrf52/spi_hw_2_nrf52.h 直接使用<nrf_spim.h>与<nrfx_timer.h>；src/platforms/arm/sam/fastspi_arm_sam.h 使用 Atmel CMSIS 的(Spi*)SPI0、SPI_SR、SPI_TDR——这三个文件正是register-maps.md列举的「tier-1 工具链直接提供头文件」范例。

6.6 寄存器头文件的集成优先级（tier 1 → 3）

register-maps.md定义了接入厂商头文件的三级方案，移植时应「取最高可行级」：

• Tier 1（首选）：板卡的 Arduino core 或平台包自动把头文件放入 include 路径，直接#include <LPC845.h>并使用厂商 typedef 指针；
• Tier 2：工具链 include 路径不可靠时（如 Arduino core 只暴露当前变体目录），把厂商头文件复制进src/platforms/<arch>/<vendor>/cmsis/<chip>.h，保留许可证头并附一行注明上游 URL 与拷贝 SHA 的 README；
• Tier 3（仅最后手段）：本地struct ShimName { volatile u32 ...; }，仅当 tier 1/2 均被调查并记录为不可行时才允许，且必须满足：① shim 用厂商头文件的 include guard 门控（#if !defined(LPC_SCT) && !defined(LPC_SCT_TYPE_)），真实 CMSIS 定义存在时自动让位；②每个成员同时引用用户手册章节与厂商头文件成员名（如volatile u32 SYSAHBCLKCTRL0; // UM11029 §4.6.13 ; CMSIS LPC_SYSCON_Type.SYSAHBCLKCTRL0 @ 0x080）；③ 合入前必须对照真实厂商头文件评审（「我读了用户手册」不算数）。

此外register-maps.md还给出了一份评审清单（任一答案为否则阻止合并）：是否使用厂商头文件（tier 1/2）或文档化不能用的原因？shim 是否门控在厂商 include guard 之后？每个 shim 成员是否双引用？shim 文件是否列入平台 README 的 tier-3 兜底说明？触及既有 shim 的 diff 是否附厂商头文件偏移？

七、Step 4（可选）：SPI 驱动

若平台具备硬件 SPI，可在此基础上实现硬件辅助驱动。原文档给出三步路线：

1. 以所需时钟率配置 SPI 外设（WS2812 wave8 编码约需6–7 MHz）；
2. 实现wave8 编码（1 个 LED 数据位展开为 8 个 SPI 位）；
3. 可用时用DMA搬运传输。

这一步同样是「外设存在性验证」与「寄存器映射」两铁律的重灾区：peripheral-existence.md明确点名 DMA / eDMA / µDMA、FlexIO、FlexSPI、LCD_CAM、PARLIO、RMT、I2S 并行 IO 引擎、任何注册到BusTraits<...>的新总线引擎，以及任何可能按 SKU 裁掉的外设，都必须先跑验证配方。仓库中src/platforms/arm/lpc/spi_arm_lpc_dma.h与src/platforms/arm/lpc/uart_arm_lpc_dma.h就是这类驱动在 LPC 平台上的落地，而 LPC804 行被明确标注无 DMA 支持正是验证铁律生效的结果。

八、Step 5：构建系统集成

驱动代码完成后，需要把新平台接入两套构建体系：

• fbuild：在 ci/boards.py 注册该板卡（必要时补充platformio.inienv）；
• Meson：在meson.build中补充平台检测逻辑。

仓库对「平台化文件是否需要守卫」有明确约定（见cpp-standards.md）：头文件通常不需要平台守卫（如#ifdef ESP32），只有.cpp实现文件需要——.cpp被守卫排除出编译后，头文件根本不会被包含，因此头文件保持干净接口还能获得更好的 IDE 智能提示。正确模式是header.h无守卫（干净接口）、header.cpp有守卫（如#ifdef ESP32 ... #endif）。

另外 ESP32 平台有一条更细的规则：用能力检测而非#ifdef ARDUINO来分派 Arduino-vs-native 实现——问「driver/gpio.h是否可用」（FL_HAS_INCLUDE）而不是「是否 Arduino 框架」，因为 Arduino-ESP32 本身就捆绑同一套 ESP-IDF 驱动，能力检测能在 Arduino 与裸 ESP-IDF 下都选中 IDF-native 实现。

九、Step 6–8：测试策略

原文档给出四层递进的验证策略：

1. 编译测试：bash compile <platform> --examples Blink——验证平台可编译、示例可达；
2. 单元测试：bash test——宿主机侧运行，验证共享代码逻辑；
3. 硬件测试：烧录到真实设备，验证 LED 实际输出；
4. 验证固件：bash autoresearch --<driver>——若使用 AutoResearch 验证固件则跑该流程。

仓库的 LPC 平台 README 展示了这套策略在真实平台上的完整形态：bash autoresearch lpc845brk --bring-up（回环 RPC 冒烟）、--pin-toggle-rx（SCT 输入捕获锁定位波方波，编排器断言均值 ±2 % 与 σ 阈值）、--ws2812-loopback（WS2812 字节匹配，解码器断言mismatched == 0）、--uart（UART DMA WS2812 字节匹配）——全部通过 TX↔RX 跳线闭环，由 Python 编排器依据 JSON-RPC 结果自动判定通过/失败，无需人工维护者签字。

cpp-standards.md还补充了一条与「声明设备未连接」相关的强制流程：在写下「板卡未连接 / 仅静态验证」之前，必须先运行fbuild port scan枚举物理连接的端口（它按 FastLED 板卡库解析每端口厂商/产品，如└─ NXP Semiconductors / LPC-Link2 CMSIS-DAP对应 LPC845-BRK）；确实连接则就地烧录验证，连接失败（设备未找到 / RPC ping 超时）才算真正 bench-blocked。绝不允许未经端口扫描就推断硬件缺席。

十、移植产出格式模板

原文档规定，每次移植的输出应遵循统一的「平台移植指南」结构，便于评审者与后续维护者快速定位：

## Platform Port Guide: <Platform Name> ### Platform Details - **Architecture**: [ARM Cortex-M7 / RISC-V / etc.] - **Word Size**: [32-bit] - **Clock Speed**: [up to 480 MHz] - **RAM**: [1MB] - **Key Peripherals**: [SPI, I2S, DMA, timers] ### Porting Checklist - [ ] Step 1: Platform detection - [ ] Step 2: Integer types - [ ] Step 3: Clockless driver - [ ] Step 4: SPI driver (optional) - [ ] Step 5: Build integration - [ ] Step 6: Compilation test - [ ] Step 7: Hardware validation ### Implementation Details [Step-by-step for each checklist item with code templates]

该模板与第三节的 TodoWrite 清单一一对应，也可以视为移植 PR 描述的统一骨架。

十一、关键规则速查（移植全程对照）

综合原文档与其引用的三份规则文档，移植过程中的硬性约束可浓缩为以下清单：

1. 先研究后实现——架构细节必须正确（FL_IS_*检测依据、字长、时钟、外设清单）；
2. 遵循既有模式——参考已移植的相似平台（如 LPC 移植参考 NXP 系、ESP32 参考 ESP 系）；
3. 写任何 DMA / RMT / FlexIO / PARLIO / LCD_CAM / I2S / async 驱动代码之前，先读 agents/docs/peripheral-existence.md——对照厂商 CMSIS PAL 头文件（精确到芯片变体）与数据手册章节验证外设存在，幻影外设上直接 HALT，绝不伪造 typedef 让构建通过；
4. 写任何*Shim结构体或从用户手册敲寄存器偏移之前，先读 agents/docs/register-maps.md——用厂商 CMSIS 寄存器定义，tier 1/2 优先，tier 3 shim 是最后手段且必须双引用门控；
5. 命名规范——检测宏必须是FL_IS_<PLATFORM>模式、无值、#ifdef检测；
6. 绝不修改fl/stl/int.h或fl/stdint.h——平台整数类型只进平台自己的int.h；
7. Python 命令统一用uv run；
8. 用 TodoWrite 跟踪移植进度；
9. 代码规范以 agents/docs/cpp-standards.md 为准（命名空间、FL_IS_*命名、平台守卫位置、_noop兜底、ISR 共享状态用fl::atomic等）。

十二、延伸阅读

• agents/docs/peripheral-existence.md——外设存在性验证完整配方、红旗信号、LPC804 幻影 DMA 连锁始末与假阴性防护；
• agents/docs/register-maps.md——厂商 CMSIS 头文件来源表、tier 1/2/3 集成模式、评审清单、LPC845 三处偏移反例；
• agents/docs/cpp-standards.md——FL_IS_*命名规范、平台分派头文件模式、_cpp.hpp稀疏分派模式、能力宏规则；
• src/platforms/is_platform.h——全部平台检测宏的总登记表；
• src/platforms/int.h——整数类型分派头文件的真实分派顺序；
• src/platforms/arm/lpc/README.md——LPC 平台移植状态总览（含 LPC804 无 DMA 标注、寄存器映射整改清单、AutoResearch 回环验证流程）；
• src/platforms/esp/is_esp.h 与 src/platforms/arm/stm32/is_stm32.h——多级平台检测宏的真实写法范例。

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发