Khadas VIM3 开发指南

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

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

受众群体

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

  • 摆弄电子产品和硬件。
  • 通过源代码和其他 CLI 工作流构建 Fuchsia。

在 Khadas VIM3 开发板上安装 Fuchsia

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

前提条件

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

  • 一台 Khadas VIM3 单板计算机。Google 员工应通过 Fuchsia Ops 团队申请董事会。

  • 一台搭载 Linux 且具有 2 个可用 USB 端口的台式机或笔记本电脑。这种计算机称为主机。

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

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

  • USB 转 TTL 串行线。

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

以下为可选操作：

  • 一个散热器。这样可以在 VIM3 上全速运行 2 个 CPU 核心，而不会达到 80°C（20°C 这一临界温度），如果超过 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

您需要先将 VIM3 固件和软件设置为已知良好状态，然后才能安装 Fuchsia。第一步是清空 eMMC。

  1. 按下 VIM3 上的重置按钮。

  2. 在您按下重置按钮后，在 VIM3 启动时反复按空格键。确保光标位于串行控制台上。引导加载程序进程应该会暂停，并且串行控制台应显示 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. 按重置按钮，然后重复按串行控制台中的空格键，即可再次访问 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-* 数据线，并确保该数据线同时支持数据和 Power Delivery。

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

    重要提示： 在使用 Fuchsia 时，请记得
    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 上时使用此工作流。如果您已在 VIM3 上运行了 Fuchsia，请使用更新 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 调用中。
  • 如果您使用永久性本地构建参数，请将 vim3_mcu_fan_default_level=0 添加到 ~/fuchsia/local/args.gn。

确保 VIM3 tryjobs 运行

在提交消息中添加以下行，以确保 VIM3 tryjobs 运行：

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

问题排查

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

问题排查：启动循环

问题：

您查看的是 VIM3 串行日志。日志表明 VIM3 不断重新启动。

根本原因：

未知。Khada 的 Power Delivery 实现似乎存在底层 bug。Fuchsia 解决了问题 122113 中的 bug。

解决方法 1：

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

解决方法 2：

始终使用 USB-C 转 USB-A 数据线。

问题排查：硬件不匹配

问题：

刷写紫红色时出现以下错误：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 闪存
  • 主机模式下的 USB-C
  • 电源管理和 PMIC
  • LAN 唤醒
  • UART 蓝牙

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

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

附录：更新启动启动画面

如需将启动启动画面更新为 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），才能以这种方式播放和捕获音频。 ↩