# 如何使用 Fast Boot 与配置 RT-Smart 自动运行

## 功能说明

RTOS SDK 的 Fast Boot 会把一个 RT-Smart 用户态 ELF 单独打包为 `rtapp.elf.gz`。启动时，U-Boot 从 `rtapp` 分区读取并解压该文件，将加载地址和大小通过 ATAG 传给 RT-Smart；RT-Smart 再通过内部入口 `@preload` 直接启动内存中的 ELF，避免启动后再从文件系统读取应用。

Fast Boot 和自动运行由两组配置共同控制：

- `Fast Boot Configuration` 决定打包哪个 ELF。
- `RT-Smart Configuration > Rtsmart auto execute command string` 决定 RT-Smart 启动后是否运行该 ELF，以及向它传递哪些参数。

只配置其中一项不能完成 Fast Boot 自动运行。目标板的镜像布局还必须包含标记为 `load = true` 的 `rtapp`、`rtapp_a` 或 `rtapp_b` 分区，并使用支持 RT-App 预加载和 ATAG 的 U-Boot。SDK 提供的大多数 SD 卡和 eMMC 板级配置已包含这些设置；使用 SPI NAND 或自定义镜像布局时应先检查对应的 `boards/<board>/genimage-*.cfg`。

## Kconfig 配置项

在 SDK 根目录选择板级 defconfig，然后进入顶层配置菜单：

```bash
make <board>_defconfig
make menuconfig
```

### Fast Boot Configuration

配置项来自 SDK 根目录的 `Kconfig.fastboot`：

| 菜单项 | Kconfig 符号 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `Fast Boot Configuration` | `CONFIG_FAST_BOOT_CONFIGURATION` | `y` | 启用 RT-App 打包。关闭时仍会生成占位的 `rtapp.elf.gz`，但其中没有可运行的 ELF。 |
| `Fast boot file path` | `CONFIG_FAST_BOOT_FILE_PATH` | `${SDK_BUILD_IMAGES_DIR}/sdcard/micropython` | 主机编译环境中待打包 ELF 的路径。支持绝对路径和构建时展开的 `${SDK_*}` 环境变量。 |
| `Delete Origin Fastboot App` | `CONFIG_FAST_BOOT_DELETE_ORIGIIN_FILE` | `y` | 打包后删除源 ELF，避免文件系统和 `rtapp` 分区各保留一份。符号中的 `ORIGIIN` 是当前源码中的实际拼写。 |

`Fast boot file path` 是主机侧路径，不是板端路径。例如，应用编译后被暂存到镜像的 `/sdcard/app/helloworld`，对应的打包路径是：

```text
${SDK_BUILD_IMAGES_DIR}/sdcard/app/helloworld
```

```{warning}
启用 `Delete Origin Fastboot App` 后，打包脚本会直接删除 `Fast boot file path` 指向的文件。如果这里配置的是 SDK 输出目录之外的绝对路径，原始文件也会被删除。此时应关闭该选项，或者先把 ELF 复制到构建输出目录再打包。
```

### RT-Smart 自动运行命令

配置项来自 `src/rtsmart/Kconfig`：

```text
RT-Smart Configuration > Rtsmart auto execute command string
```

其 Kconfig 符号是 `CONFIG_RTT_AUTO_EXEC_CMD`。启用 Fast Boot 时默认值为 `@preload &`，未启用时默认值为空字符串。

按使用场景设置该字符串：

| 场景 | 配置示例 | 行为 |
| --- | --- | --- |
| Fast Boot，无参数 | `@preload` | 运行 U-Boot 已预加载的 RT-App。 |
| Fast Boot，带参数 | `@preload -C 1 -K /sdcard/model.kmodel` | 运行预加载的 RT-App，并将后续参数传给应用。参数中的文件路径是板端路径。 |
| 普通文件系统自启动，未启用 Firmware Secure Boot | `/sdcard/app/helloworld` | 由 `msh` 从文件系统加载并运行 ELF。 |
| 禁止自动运行 | 空字符串 | RT-Smart 启动后不自动执行用户态应用。 |

`@preload` 是 RT-Smart 内部的触发标记，不是文件系统路径，也不是可在 `msh` 中手动执行的命令。该入口直接拆分参数并调用 `exec`，不会解释管道、重定向或 `&` 等 shell 语法。当前实现最多接收 8 个以空格或制表符分隔的字段，其中第一个字段是 `@preload`。应用不需要后台符号即可由自动运行入口启动；无参数时建议明确配置为 `@preload`。

```{warning}
启用 Firmware Secure Boot 后，自动运行命令必须以 `@preload` 为第一个字段。其他命令会被跳过，系统不会回退到文件系统中的 ELF。此时还必须启用 Fast Boot，并确保 U-Boot 实际预加载了有效的 `rtapp` 镜像。
```

## 完整示例：Fast Boot 启动 HelloWorld

### 启用应用

执行 `make menuconfig`，打开：

```text
Applications Configuration > Enable Applications HelloWorld
```

该应用会生成到主机侧的：

```text
${SDK_BUILD_IMAGES_DIR}/sdcard/app/helloworld
```

### 配置 Fast Boot

进入 `Fast Boot Configuration`，设置：

```text
[*] Fast Boot Configuration
Fast boot file path = ${SDK_BUILD_IMAGES_DIR}/sdcard/app/helloworld
[*] Delete Origin Fastboot App
```

保持删除选项开启时，最终文件系统中不会再有 `/sdcard/app/helloworld`；应用只存在于 `rtapp` 分区。

### 配置自动运行

进入 `RT-Smart Configuration`，把 `Rtsmart auto execute command string` 设置为：

```text
@preload
```

保存并退出。可在 SDK 根目录检查最终配置：

```bash
grep -E 'CONFIG_(APP_ENABLE_HELLOWORLD|FAST_BOOT|RTT_AUTO_EXEC_CMD)' .config
```

预期包含：

```text
CONFIG_APP_ENABLE_HELLOWORLD=y
CONFIG_RTT_AUTO_EXEC_CMD="@preload"
CONFIG_FAST_BOOT_CONFIGURATION=y
CONFIG_FAST_BOOT_FILE_PATH="${SDK_BUILD_IMAGES_DIR}/sdcard/app/helloworld"
CONFIG_FAST_BOOT_DELETE_ORIGIIN_FILE=y
```

### 编译和烧录

```bash
make
ls -lh output/<defconfig>/images/rtapp/rtapp.elf.gz
```

`rtapp.elf.gz` 是带镜像头并经过压缩的 RT-App 镜像，不能用文件大小是否为零作为唯一的有效性判断。编译日志中不应出现 `Use fake rtapp` 或 Fast Boot 文件不存在的提示。

将 `output/<defconfig>/images/` 中适合目标板的完整镜像烧录后重启。RT-Smart 启动阶段会执行 `@preload`，串口应看到 HelloWorld 的输出。

如果希望把配置保存到当前板级 defconfig，可在确认 `.config` 后执行：

```bash
make savedefconfig
```

该命令会更新当前选中的 `configs/<defconfig>`，提交前应检查差异。

## 仅配置普通文件系统自启动

如果不需要 Fast Boot，而是希望从文件系统自动运行应用：

1. 关闭 `Fast Boot Configuration`。
1. 确保应用会被复制到文件系统镜像。
1. 将 `Rtsmart auto execute command string` 设置为板端绝对路径和参数，例如：

   ```text
   /sdcard/app/helloworld
   ```

这种方式不使用 `@preload`。启用 Firmware Secure Boot 时，RT-Smart 会拒绝从文件系统加载 ELF，因此不能使用这种配置。

## 常见问题

### 启动时提示预加载镜像不可用

常见日志包括：

```text
Preloaded ELF magic number mismatch
Trusted preload is unavailable: missing or invalid ATAG-preloaded rtapp image
trusted preload image unavailable, enable fast boot and ensure U-Boot preloads rtapp
```

依次检查：

1. `CONFIG_FAST_BOOT_CONFIGURATION=y`。
1. `CONFIG_FAST_BOOT_FILE_PATH` 指向构建时真实存在的 RT-Smart ELF。
1. 编译日志没有 `Use fake rtapp`。当前打包脚本在源文件不存在时会生成占位镜像并继续构建，因此完整镜像生成成功不代表 RT-App 有效。
1. 板级 `genimage` 配置包含 `rtapp` 分区，并设置了 `load = true`。
1. 烧录的是本次构建产生的完整镜像，U-Boot 与 RT-Smart 来自兼容版本。

### 应用依赖的模型或配置文件找不到

Fast Boot 只把所选 ELF 放入 `rtapp` 镜像，不会自动收集它引用的模型、字库或配置文件。这些资源仍需打包到 `/sdcard`、`/data` 等板端文件系统，并在 `CONFIG_RTT_AUTO_EXEC_CMD` 的参数中使用板端路径。

### 文件系统中找不到原来的 ELF

这是 `CONFIG_FAST_BOOT_DELETE_ORIGIIN_FILE=y` 的预期行为。需要同时保留文件系统副本以便手动调试时，关闭 `Delete Origin Fastboot App` 后重新编译镜像。

### 修改后仍运行旧应用

Fast Boot 应用位于独立的 `rtapp` 分区。应烧录包含 `rtapp` 的完整镜像或对应的 RT-App 更新镜像；只更新文件系统分区不会替换已经预加载的应用。