Khadas VIM3 开发指南

Khadas VIM3 是一款基于 ARM64 的单板计算机。可以在 VIM3 上运行 Fuchsia。本指南向 Fuchsia 贡献者介绍了如何在 VIM3 上安装 Fuchsia 以及执行其他常见的开发任务。

如需详细了解 Fuchsia 支持哪些 VIM3 功能，请参阅附录：功能支持。

受众群体

本指南假定您熟悉以下内容：

  • 对电子产品和硬件进行修改。
  • 从源代码构建 Fuchsia 以及其他 CLI 工作流。

在 Khadas VIM3 开发板上安装 Fuchsia

如果您在完成安装流程时遇到任何问题，请参阅问题排查和附录：支持。

前提条件

您需要具备以下所有硬件和软件：

  • Khadas VIM3 单板计算机。Google 员工应通过 Fuchsia Ops 团队申请开发者板块。

  • 一台搭载 Linux 且有 2 个 USB 端口的台式机或笔记本电脑。此计算机称为“主机”。

  • 主机的电源至少为 24W。启用 DVFS 时，VIM3 可以耗用这么多电量。

  • 主机上正常运行的 Fuchsia 开发环境。换句话说，您应该能够在主机上根据 Fuchsia 的源代码构建 Fuchsia。

  • 一根 USB 转 TTL 串行线。

  • 一根同时支持数据传输和电源传输的 USB-C 转 USB-A 线。USB-C 端用于 VIM3。另一端则用于连接主机。

以下是可选的：

  • 散热器。这样，VIM3 上就可以全速运行 2 个 CPU 核心，而不会达到 80°C 的临界温度（超过该温度，核心会被节流）。

如需查看兼容配件的示例，请参阅 Khadas 商店中的 VIM3 系列。

构建 Fuchsia

如果您还没有设置

  1. 下载 Fuchsia 源代码。

  2. 配置和构建 Fuchsia。

    • 配置 build 时，请使用 fx set core.vim3。

您将使用 Fuchsia 开发环境为 VIM3 构建 Fuchsia 映像，并运行树内 CLI 工具，以将 Fuchsia 映像刷写到 VIM3 上。

设置硬件

设置 VIM3 以与主机通信：

  1. 使用 USB-C 转 USB-* 线将 VIM3 和主机连接在一起。 VIM3 上的白色 LED 灯应会亮起。

    此连接用于为 VIM3 供电并使用 fastboot 对其进行刷写。

  2. 将串行线缆的线连接到 VIM3 的 GPIO：

    • GND 连接到引脚 17。

    • TX（从 VIM3 输出）连接到引脚 18。

    • RX（进入 VIM3）到引脚 19。

    • 请勿将串行电源线的电源线连接到任何 VIM3 GPIO。VIM3 通过 USB 线供电。

    如需查看串行线应如何连接到 VIM3 的示例图片，请参阅串行调试工具。

  3. 将串行线的 USB 端连接到宿主机。

验证串行连接

确保您可以查看串行日志：

  1. 打开 Fuchsia 的串行控制台：

    fx serial

  2. 按 VIM3 上的重置按钮。重置按钮是电路板上印有 R 的按钮。如需查看示意图，请参阅 VIM3/3L 硬件。您应该会在串行控制台中看到人类可读的日志。

如果 VIM3 似乎一直在重新启动，请参阅问题排查：启动循环。

擦除 eMMC

在安装 Fuchsia 之前，您需要将 VIM3 固件和软件置于已知良好状态。第一步是擦除 eMMC。

  1. 按 VIM3 上的重置按钮。

  2. 按下重置按钮后，在 VIM3 启动时，开始反复按 Space 键。确保光标聚焦在串行控制台上。引导加载程序进程应暂停，并且串行控制台应显示 kvim3# 提示。现在，您可以通过串行控制台访问 U-Boot shell。

  3. 在 U-Boot shell 中运行以下命令：

    store init 3

    串行控制台日志应能验证 eMMC 是否已正确擦除。

如需了解详情，请参阅擦除 eMMC。

更新 VIM3 上的 Android 映像

现在，您需要将 VIM3 固件和软件恢复到已知的良好状态：

  1. 点击以下网址下载已知可与后续 Fuchsia 安装搭配使用的 Android 映像：https://dl.khadas.com/firmware/vim3/android/VIM3_Pie_V211220.7z

  2. 解压缩压缩的归档文件 (VIM3_Pie_V211220.7z)。解压缩后，您应该会看到一个包含 update.img 文件的 VIM3_Pie_V211220 目录。

  3. 按照将操作系统安装到 eMMC 中的说明操作。运行 aml-burn-tool 时，-i 标志的值应为 update.img 文件的路径。您的命令应如下所示：

    aml-burn-tool -b VIM3 -i ~/Downloads/VIM3_Pie_V211220/update.img

  4. 如果 VIM3 上的白色和红色 LED 指示灯处于关闭状态，而蓝色 LED 指示灯处于开启状态，则表示 VIM3 处于休眠模式。请尝试将 VIM3 重新置于升级模式，然后再次按下重置按钮。

此时，VIM3 上的白色 LED 指示灯应亮起，并且您在按 VIM3 上的重置按钮后，应该会在串行控制台中看到日志。

更新引导加载程序

本部分介绍了如何将预构建版本的 Fuchsia 修改版 U-Boot 刷写到 VIM3 上。如果您希望从源代码构建经过修改的 U-Boot，请参阅以下链接：https://third-party-mirror.googlesource.com/u-boot/+/refs/heads/vim3

  1. 按下重置按钮，然后在串行控制台中反复按 Space 键，即可再次访问 U-Boot SHELL。当串行控制台显示 kvim3# 提示时，表示您已进入 U-Boot shell。

  2. 在 U-Boot shell 中，运行以下命令：

    fastboot

    您应该会在串行控制台中看到以下日志：

    g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot

USB RESET
SPEED ENUM

USB RESET
SPEED ENUM

    如果您看到第一行 (g_dnl_register: g_dnl_driver.name = usb_dnl_fastboot)，但没有看到后面的行，请尝试使用其他 USB-C 转 USB-* 数据线，并确保该数据线同时支持数据传输和电源传输。

  3. 在主机中打开一个新的终端窗口，然后运行以下命令：

    cd ~/fuchsia/prebuilt/third_party/fastboot
./fastboot flashing unlock
./fastboot flashing unlock_critical
./fastboot flash bootloader ~/fuchsia/prebuilt/third_party/firmware/vim3/u-boot.bin.unsigned
./fastboot reboot

将 Fuchsia 刷写到 eMMC（仅限一次）

仅在首次将 Fuchsia 刷写到 VIM3 时使用此工作流。如果 Fuchsia 已在 VIM3 上运行，请使用更新 Fuchsia 映像工作流，因为它速度更快。

  1. 如果您刚刚运行了上一部分中的 ./fastboot reboot 命令，则 VIM3 应该已处于 fastboot 模式。您可以查看 fx serial 日志进行确认。否则，请按重置按钮，然后在 fx serial 控制台中反复按 F 键，直到再次看到 USB RESET 和 SPEED ENUM。

  2. 在宿主机上的另一个终端中，运行以下命令：

    fx flash

您的 VIM3 现在搭载的是 Fuchsia！

更新 Fuchsia 映像

如果 VIM3 上已运行 Fuchsia，并且您想更新 Fuchsia 映像，请完成以下步骤。

  1. 在主机的终端中运行以下命令：

    fx serve

    让此命令保持运行状态。

  2. 在树内 Fuchsia 检出中进行一些更改，然后构建更改。

  3. 打开一个新的终端窗口，然后在 VIM3 上对 Fuchsia 映像执行 OTA 更新：

    fx ota

通过停用 VIM3 的风扇来降低噪音

如果 VIM3 风扇的噪音让您感到困扰，您可以通过以下任一工作流程将其停用：

  • 将 --args vim3_mcu_fan_default_level=0 添加到 fx set 调用中。
  • 如果您使用持久性本地 build 参数，请将 vim3_mcu_fan_default_level=0 添加到 ~/fuchsia/local/args.gn。

确保 VIM3 试行作业运行

在提交消息中添加以下代码行，以确保运行 VIM3 试行作业：

Cq-Include-Trybots: luci.turquoise.global.try:bringup.vim3-debug,core.vim3-debug,core.vim3-vg-debug

问题排查

本部分介绍了常见问题的权宜解决方法。

问题排查：启动循环

问题：

您正在查看 VIM3 串行日志。日志显示 VIM3 会不断重启。

根本原因：

未知。Khada 的电源传输实现中似乎存在一个基本 bug。Fuchsia 解决了问题 122113 中的 bug。

权宜解决方法 1：

拔下 USB 线，然后重新插上。如有必要，请重复 2-3 次。

权宜解决方法 2：

请务必使用 USB-C 转 USB-A 数据线。

问题排查：硬件不匹配

问题：

刷写 Fuchsia 时出现以下错误：Hardware mismatch! Trying to flash images built for vim3 but have 0

解决方案：

返回更新 Android 映像步骤。

附录：修复无法启动的 VIM3

如果您的 VIM3 变砖，并且需要“恢复出厂设置”，请按以下步骤操作：

  1. 擦除 eMMC。
  2. 更新 Android 映像。
  3. 更新引导加载程序。
  4. 将 Fuchsia 刷写到 eMMC（仅限一次）。

附录：支持

附录：功能支持

Fuchsia 目前支持 VIM3 的以下功能：

  • UART 串行调试程序
  • 通过以太网和 USB 进行铺路
  • 存储空间 (eMMC)
  • HDMI 显示屏和帧缓冲区
  • GPU (Mali) 和 Vulkan 图形
  • 以太网
  • SDIO
  • I2C
  • GPIO
  • 温度传感器和 DVFS
  • RTC
  • 时钟
  • 风扇
  • NNA
  • 外围设备模式下的 USB-C
  • USB-A
  • 音频1

以下功能正在开发中，可能不受支持：

  • 视频解码器
  • SPI

不支持以下功能，但未来可能会通过贡献添加：

  • SPI Flash
  • 主机模式下的 USB-C
  • 电源管理和 PMIC
  • LAN 唤醒
  • UART BT

以下功能不受支持，并且不太可能添加：

  • 视频编码（由于非公开固件）
  • 可信执行环境 / 安全启动

附录：更新启动启动画面

如需将启动启动画面更新为 Fuchsia 徽标，请在 VIM3 处于 fastboot 模式时从主机终端运行以下命令：

~/fuchsia/prebuilt/third_party/fastboot/fastboot flash logo \
    ~/fuchsia/zircon/kernel/target/arm64/board/vim3/firmware/logo.img

  1. VIM3 不包含扬声器和麦克风等传感器，除了传感器之外，还需要通过 GPIO 头添加和集成包括 DAC/ADC 在内的外部硬件，才能以这种方式播放和捕获音频。 ↩