📚 课程目录第3章平台描述文件

3. 平台描述文件：理解.repl文件结构，创建第一个Cortex-M4平台

好，我们正式开始动手了。

上一章我们装好了 Renode，跑了个 Hello World。但那个 demo 用的是现成的平台文件。这一章，我们要自己写一个。

说白了，就是告诉 Renode：「我要模拟一块什么样的板子，上面有哪些外设，内存怎么分布，CPU 是什么型号。」

这些信息，都写在一个 .repl 文件里。我习惯叫它「平台描述文件」。你想想看，它就像一张建筑蓝图——画清楚了，模拟器才知道怎么搭。

3.1 .repl 文件到底长什么样？

.repl 是 Renode 自己的脚本语言，语法非常简洁。我刚开始接触时觉得它像 JSON 和 TCL 的混合体，但用多了发现其实更像一种「声明式配置」。

一个典型的 .repl 文件，核心就三块：

CPU 定义：用什么架构、什么型号、有没有 FPU、调试接口怎么连。
内存映射：Flash 多大、SRAM 多大、外设寄存器地址在哪。
外设挂载：UART、GPIO、Timer……一个个挂到对应的地址上。

来看一个最简的 Cortex-M4 平台文件。这是我当年给一个 IoT 项目做原型验证时写的简化版：

using "platforms/cpus/cortex-m4.repl"

sysbus:
    init:
        Register 0x00000000 "flash" 0x00100000
        Register 0x20000000 "sram"  0x00040000

    uart0: UART.Lite @ 0x40001000
        -> cpu@0

嗯，就这么几行。但每一行都有讲究。

核心要点：.repl 文件本质上是 Renode 的「硬件拓扑描述」。它不写逻辑，只写「有什么、在哪、怎么连」。

3.2 逐行拆解：一个 Cortex-M4 平台是怎么搭起来的

我们一行一行来过。别急，我会把每个坑都指出来。

3.2.1 引用 CPU 模板

using "platforms/cpus/cortex-m4.repl"

这一行是「继承」。Renode 已经帮我们把 Cortex-M4 的内核细节封装好了——NVIC、SysTick、调试接口、FPU 配置……都在这个模板里。

我个人习惯先看看这个模板里有什么。你可以用编辑器打开 Renode 安装目录下的 platforms/cpus/cortex-m4.repl，里面大概有 200 多行。别被吓到，大部分是中断向量和调试寄存器的默认配置。

小技巧：如果你用的是 Cortex-M4F（带浮点单元），记得把模板换成 cortex-m4f.repl。我在一个项目中吃过这个亏——FPU 没开，跑浮点运算直接 HardFault。

3.2.2 定义内存空间

sysbus:
    init:
        Register 0x00000000 "flash" 0x00100000
        Register 0x20000000 "sram"  0x00040000

sysbus 是 Renode 里的「系统总线」。所有 CPU 和外设都挂在这条总线上。

Register 命令的格式是：Register 起始地址 "名称" 大小（字节）。

上面这段的意思是：

Flash 从 0x00000000 开始，大小 1MB（0x100000）。
SRAM 从 0x20000000 开始，大小 256KB（0x40000）。

为什么 Flash 从 0x00000000 开始？因为 Cortex-M 系列复位后从 0x00000000 取向量表。这是硬件规定的，不能改。

注意：地址和大小一定要对齐。我曾经把 SRAM 大小写成 0x40001，结果 Renode 直接报错「Memory region not aligned」。嗯，血的教训。

3.2.3 挂载外设

    uart0: UART.Lite @ 0x40001000
        -> cpu@0

这一行做了两件事：

在地址 0x40001000 挂了一个 UART.Lite 外设，命名为 uart0。
把 UART 的中断线连接到 CPU 的 IRQ 0。

-> cpu@0 的意思是「中断连接到第 0 号 CPU 的第 0 号中断」。在多核系统里，你可以指定中断发给哪个核。

UART.Lite 是 Renode 内置的一个轻量级 UART 模型。它只实现了最基本的发送和接收功能，没有硬件流控。对于驱动调试来说，够用了。

3.3 完整的 Cortex-M4 平台文件

我们把上面几块拼起来，再加一个 GPIO 和一个 Timer，就是一个能跑的真实平台了：

using "platforms/cpus/cortex-m4.repl"

sysbus:
    init:
        Register 0x00000000 "flash" 0x00100000
        Register 0x20000000 "sram"  0x00040000

    uart0: UART.Lite @ 0x40001000
        -> cpu@0

    gpio0: GPIO.Lite @ 0x40002000
        -> cpu@1

    timer0: Timer.Lite @ 0x40003000
        -> cpu@2

    led0: LED @ 0x40004000

注意看 led0。它没有中断连接，因为 LED 不需要中断——你写寄存器它就亮，简单粗暴。

关键认知：在 Renode 里，外设模型和真实芯片的外设寄存器接口是一一对应的。你写驱动时操作的是同一个地址，行为也几乎一样。这就是「模拟调试」的价值所在。

3.4 平台描述文件的核心结构图

下面这张图，是我自己画的一个 .repl 文件结构关系。你看一眼，就能明白整个平台的骨架：

3.5 如何验证你的平台文件

写完了别急着跑。先做两件事：

语法检查：在 Renode 里执行 include @"/path/to/your.repl"，如果有语法错误，它会直接报错并告诉你哪一行有问题。
查看平台树：加载成功后，执行 machine 命令，Renode 会打印出当前平台的所有外设和内存区域。对照你的 .repl 文件，看看有没有遗漏。

我的习惯：每加一个外设，就重启一次 Renode 验证。不要一口气写完 50 行再调试——那样你根本不知道是哪个外设配错了。

3.6 常见错误与避坑

错误类型	现象	原因	解决办法
地址重叠	Renode 启动时报错	两个外设注册到了同一个地址	检查地址范围，确保不重叠
中断号越界	外设不响应中断	中断号超过了 CPU 支持的范围	Cortex-M4 支持 240 个外部中断，编号 0-239
模板路径错误	找不到 cortex-m4.repl	相对路径写错了	用绝对路径或确认工作目录
大小不对齐	Register 命令报错	内存大小不是 4KB 对齐	确保大小是 0x1000 的整数倍

我曾经犯过一个最蠢的错误：把 Flash 地址写成了 0x00001000。结果 CPU 复位后找不到向量表，直接卡死。查了整整两个小时……嗯，从那以后我每次写地址都会拿数据手册对照一遍。

3.7 小结

这一章我们做了三件事：

理解了 .repl 文件的三层结构：CPU、内存、外设。
手写了一个完整的 Cortex-M4 平台文件。
学会了验证和排错的基本方法。

现在，你已经有了自己的第一个 Renode 平台。下一章，我们会在这个平台上跑一个真正的嵌入式程序——用 GDB 连上去，单步调试，看寄存器变化。

嗯，那才是真正好戏开始的地方。