在 Mbed OS 上运行 JerryScript:FRDM-K64F 从零构建、烧录与串口验证实战指南

原创2026-09-27 17:56:541,812 阅读
文章标签:编程语言语言运行时解释器嵌入式物联网标准库

在 Mbed OS 上运行 JerryScript:FRDM-K64F 从零构建、烧录与串口验证实战指南

本篇指南围绕 JerryScript 仓库中的 Mbed OS 移植目标(targets/os/mbedos)展开,完整讲解如何在 Ubuntu 20.04 环境下,把超轻量级 JavaScript 引擎 JerryScript 与 ARM Mbed OS 6.15.0 组合编译为 FRDM-K64F 开发板固件,并通过 ST-Link 烧录、串口终端运行出第一行 Hello, World!。读完本文,你将掌握 Mbed OS 移植目标的目录结构、构建参数(板型 / 工具链 / 堆大小)的调整方法、make 构建与烧录的完整命令链,以及移植层 jerry-port.cpp 与主程序 jerry-main.cpp 的底层实现原理。

一、目标平台与整体思路

targets/os/mbedos 是 JerryScript 官方为 FRDM-K64F 开发板 + Mbed OS 实时操作系统 提供的移植目标目录。FRDM-K64F 是恩智浦(NXP)推出的 Kinetis K64F(ARM Cortex-M4F)评估板,通过板载 OpenSDA 调试器以 USB 直连主机;Mbed OS 则是 ARM 主导的物联网嵌入式操作系统,提供串口、定时器等抽象层。

整个移植思路分三步:

  1. 将 JerryScript 引擎源码与 Mbed OS 源码放在同一工作目录(如 jerry-mbedos)下;
  2. 用仓库自带的移植层文件(jerry-main.cpp、jerry-port.cpp)把引擎“接”到 Mbed OS 的串口与时间服务上;
  3. 通过 mbed-tools compile 产出 .bin 固件,烧录进开发板后用串口终端观察 JS 执行结果。

该目录包含 7 个文件,职责划分如下:

文件 作用
Makefile 封装 mbed-tools compile,提供 make / make flash / make clean 目标及板型、工具链、堆大小等参数
Makefile.travis 供 CI(Travis)验证用的构建目标,也适合在本地复现自动化构建
jerry-main.cpp 移植目标的主程序:初始化引擎、注册 print、解析并执行 JS 脚本
jerry-port.cpp 引擎移植层(Port API)实现:致命错误、日志输出、本地时区、当前时间
mbed_lib.json Mbed 库配置,向编译期注入 JerryScript 全局堆大小宏
mbedignore.txt Mbed 构建排除清单,避免把无关目录编入固件
README.md 官方构建与烧录说明(本文主体)

二、搭建构建环境(Step 1)

官方文档验证于 Ubuntu 20.04 操作系统。首先在工作目录下建立 jerry-mbedos 文件夹,并克隆两个项目:JerryScript 本体,以及指定版本分支的 Mbed OS。文档明确给出的最新测试可用版本为 mbed-os-6.15.0。

mkdir jerry-mbedos && cd jerry-mbedos

git clone https://github.com/jerryscript-project/jerryscript.git
git clone https://github.com/ARMmbed/mbed-os.git -b mbed-os-6.15.0

克隆完成后应得到如下目录结构:

jerry-mbedos
  + jerryscript
  |  + targets
  |      + os
  |        + mbedos
  + mbed-os

需要说明的是,克隆 JerryScript 时若使用本仓库(gh_mirrors/je/jerryscript)作为源码根目录,构建时其路径即对应上述结构中的 jerryscript 目录;Makefile 通过 JERRY_ROOT_DIR = $(realpath $(JERRY_TARGET_DIR)/../../..)(见 Makefile)自动定位引擎根目录,因此目录相对位置必须保持:targets/os/mbedos 位于引擎根目录之下,且与 mbed-os 平级。

三、安装构建依赖(Step 2)

在 jerry-mbedos 目录下依次执行依赖安装。首先是 JerryScript 自带的依赖脚本,然后是 ST-Link 烧录工具与 Mbed 命令行工具链:

# Assuming you are in jerry-mbedos folder.
jerryscript/tools/apt-get-install-deps.sh

sudo apt install stlink-tools
pip install --user mbed-cli
# Install Python dependencies of Mbed OS.
pip install --user -r mbed-os/requirements.txt

各依赖的作用如下:

  • tools/apt-get-install-deps.sh:JerryScript 仓库自带的 Ubuntu 依赖安装脚本(位于 tools/apt-get-install-deps.sh),负责安装构建所需的编译工具链等基础软件;
  • stlink-tools:ST-Link / OpenSDA 烧录工具,FRDM-K64F 板载调试器即 OpenSDA,通过该工具完成固件写入;
  • mbed-cli:Mbed 命令行工具(老版本 mbed-cli;新版本项目亦使用 mbed-tools,见 Makefile 中的 mbed-tools compile);
  • mbed-os/requirements.txt:Mbed OS 的 Python 依赖清单,包含编译配置所需的 jsonschema、pyyaml 等包。

此外,CI 流程(Makefile.travis)展示了等效的依赖安装方式:pip3 install mbed-tools setuptools 并安装 ../mbed-os/requirements.txt,可作为脚本化部署的参考。

四、编译固件(Step 3)

依赖就绪后,在 jerry-mbedos 目录下执行:

# Assuming you are in jerry-mbedos folder.
make -C jerryscript/targets/os/mbedos MBED_OS_DIR=${PWD}/mbed-os

MBED_OS_DIR 用于告知 Makefile 去哪里找 Mbed OS 源码。整个构建链路在 Makefile 中清晰可见:

  1. .extra-files-copy:把 mbedignore.txt 复制为引擎根目录下的 .mbedignore、把 mbed_lib.json 复制为根目录下的 mbed_lib.json,让 Mbed 构建系统读取这些配置;
  2. .mbed-build:调用 mbed-tools compile,并携带 --clean --mbed-os-path $(MBED_OS_DIR) --program-path $(JERRY_ROOT_DIR) --toolchain $(TOOLCHAIN) --mbed-target $(BOARD) --app-config $(JERRY_ROOT_DIR)/mbed_lib.json 参数;
  3. .extra-files-remove:构建结束后清理临时复制的两个文件。

构建完成后,固件输出为 jerryscript/build/mbed-os 目录下的 mbedos.bin 文件,可直接用于烧录。

4.1 可调构建参数

Makefile 顶部定义了四个可用变量(Makefile):

变量 默认值 含义
BOARD K64F Mbed 目标板型号,默认 FRDM-K64F,可替换为其他 Mbed 支持板型
TOOLCHAIN GCC_ARM 编译工具链,默认 ARM GCC
BUILD_DIR $(JERRY_ROOT_DIR)/build/mbed-os 构建产物输出目录,可通过命令行覆盖
JERRY_HEAP_SIZE 70 JerryScript 全局内存堆大小(单位 KB)

JERRY_HEAP_SIZE 通过 mbed_lib.json 中的 "macros": <a href="https://link.gitcode.com/i/f24bef7a824cd6e89dfa5d5953aa4182" target="_blank">"JERRY_GLOBAL_HEAP_SIZE=70"] 注入编译宏。从引擎侧看,[config.h 中该宏的默认值是 512(KB),而 Mbed 移植目标将其缩减为 70 KB,这是为适应 K64F 的 256 KB SRAM 所做的内存预算。修改堆大小时只需更改 mbed_lib.json 中的宏值,注意引擎在 config.h 中会校验该宏必须大于 0,堆大小最终通过 CONFIG_MEM_HEAP_SIZE (JERRY_GLOBAL_HEAP_SIZE * 1024)(见 jcontext.h)换算为字节数参与内存分配。

4.2 mbedignore.txt 的作用

Mbed 构建系统默认会扫描程序根目录(即 JerryScript 引擎根目录)下的全部源码,而 JerryScript 仓库含有大量与 Mbed 无关的目录(cmake、docs、tests、tools 等)。mbedignore.txt 通过 cmake/*、docs/*、jerry-main/*、jerry-math/*、targets/*、tests/*、third-party/*、tools/* 这 8 条规则将这些目录排除出编译范围,从而显著缩短编译时间、避免无关代码进入固件。

五、烧录固件(Step 5)

用 Micro-USB 线连接开发板(该接口同时承担充电与烧录功能),在 jerry-mbedos 目录下执行:

# Assuming you are in jerry-mbedos folder.
make -C jerryscript/targets/os/mbedos MBED_OS_DIR=${PWD}/mbed-os flash

flash 目标在 Makefile 中实现:先通过 .mbed-set-flash-flag 给 MBED_CLI_FLAGS 追加 --flash 参数,再执行正常构建;mbed-tools compile --flash 会调用 stlink-tools 把 mbedos.bin 写入板载调试器连接的 K64F 芯片。

六、串口连接与运行验证(Step 5)

烧录完成后,开发板会在宿主机上显示为串口设备 /dev/ttyACM0。使用 minicom 以 115200 波特率连接:

sudo minicom --device=/dev/ttyACM0 --baud=115200

连接后需要做两件事:

  1. 在 minicom 中按组合键 CTRL-A -> Z -> U,打开 Add Carriage Ret(回车符自动追加) 选项——由于移植层日志输出只发送 \n,终端需要该选项才能正确换行;
  2. 按下开发板上的 RESET 按钮,触发固件重新运行。

复位后,串口终端将打印 JerryScript 应用输出:

This test run the following script code: [print ('Hello, World!');]

Hello, World!

第一行是主程序用调试级别日志打印的待执行脚本源码,第二行 Hello, World! 则是脚本中 print 调用在串口上的真实输出,证明 JS 引擎已在 Cortex-M4F 上完整跑通。

七、源码级解析:Hello World 背后的移植实现

7.1 主程序 jerry-main.cpp

jerry-main.cpp 演示了在嵌入式平台上使用 JerryScript C API 的完整生命周期,可视为最小可运行的引擎调用范式:

  1. jerry_init (JERRY_INIT_EMPTY):初始化引擎(空初始化,不启用快照等特性);
  2. jerry_log (JERRY_LOG_LEVEL_DEBUG, "This test run the following script code: [%s]\n\n", script):打印待执行脚本;
  3. jerryx_register_global ("print", jerryx_handler_print):调用 jerry-ext 扩展层(jerryscript-ext/handlers.h)把 print 注册为全局函数,其实现会把参数转成字符串输出;
  4. jerry_parse + jerry_run:先解析脚本生成可执行代码,再在全局作用域执行;
  5. 用 jerry_value_is_exception 判断执行是否出错,据此返回 0(成功)或 1(失败);
  6. jerry_value_free 释放返回值,最后 jerry_cleanup () 清理引擎。

串口输出最终落到 stderr 上——这是由移植层的 jerry_port_log 决定的(见下节),因此在 minicom 中看到的就是 print 与 jerry_log 混排的输出。

另外,jerry-main.cpp 中根据 MBED_MAJOR_VERSION 区分了 Mbed OS 5 与 6 的串口类:版本 5 使用 Serial,版本 6 使用 BufferedSerial,均以 115200 波特率初始化,未支持版本会触发 #error 编译失败。

7.2 移植层 jerry-port.cpp

jerry-port.cpp 实现了 JerryScript 要求宿主机提供的 Port API(接口定义见 jerryscript-port.h),共四个函数:

  • jerry_port_fatal:致命错误处理,直接以错误码调用 exit;
  • jerry_port_log:日志输出实现——逐字符写入 stderr,并在每个 \n 前追加 \r,这正是文档要求在 minicom 中开启 Add Carriage Ret 的原因;若终端侧不补 \r,\n 会被终端解释为仅换行不回车,导致输出错位;
  • jerry_port_local_tza:本地时区偏移,嵌入式环境固定返回 0(即 UTC);
  • jerry_port_current_time:当前时间(毫秒级),是移植中最精妙的部分——它以 time(NULL) 提供秒级基准,以 us_ticker_read() 提供微秒级增量;由于 us_ticker_read() 约每 71 分钟(UINT_MAX 微秒)溢出一次,代码用静态变量记录上一次的 tick 与 time,检测到 tick 回绕时累计 33ms 的校正量 skew(见 jerry-port.cpp),从而在无独立定时器线程的 MCU 上维持可用的毫秒级时钟。

正是 jerry_port_current_time 等底层服务,支撑起 JS 侧 Date 对象、setTimeout 类功能(若上层脚本使用)的时间来源。

八、自动化构建参考(CI 流程)

如需在脚本或 CI 中复现整个流程,可参考 Makefile.travis 的目标拆解:

  • install-mbedos:克隆指定分支的 Mbed OS(示例中使用 mbed-os-6.17.0,README 主体则以 6.15.0 为准),clone 到 ../mbed-os;
  • install-mbedos-deps:安装 mbed-tools、setuptools 及 Mbed OS 的 Python 依赖;
  • script:执行 make -C targets/os/mbedos MBED_OS_DIR=$(realpath ../mbed-os) 完成编译。

注意 CI 使用的是新版 mbed-tools(pip3 install mbed-tools),而 README 中安装的是旧版 mbed-cli;Makefile 的构建命令始终是 mbed-tools compile,因此若你的环境同时存在两者,建议优先使用 mbed-tools 以保证与 Makefile 调用一致。

九、常见问题与调参建议

  • 固件找不到:确认构建命令带有 MBED_OS_DIR=${PWD}/mbed-os 且目录结构符合第二节;产物固定输出在 jerryscript/build/mbed-os/mbedos.bin。
  • 串口无输出:检查是否开启了 minicom 的 Add Carriage Ret(CTRL-A -> Z -> U),并确认波特率为 115200;jerry_port_log 输出走 stderr,某些串口工具需开启“合并 stderr”或直接观察全部输出。
  • 编译缓慢 / 无关代码被编译:确认 .mbedignore 已由 Makefile 自动复制到引擎根目录(mbedignore.txt 内容见 mbedignore.txt);make clean 会清理 build/mbed-os 及临时复制文件。
  • 内存不足 / 脚本过大:调整 mbed_lib.json 中的 JERRY_GLOBAL_HEAP_SIZE(单位 KB,须大于 0,见 config.h),同时权衡 K64F 的 256 KB SRAM 预算。
  • 更换开发板:通过 make ... BOARD=<板型> 覆盖默认的 K64F,并确保该板型在 Mbed OS 中被支持。

至此,你已经完成了从源码克隆、依赖安装、固件编译、烧录到串口运行的全部闭环,并且在源码层面理解了 Mbed OS 移植目标中主程序、移植层与构建脚本的协作方式——这套流程同样适用于后续在 Mbed OS 平台上接入其他 JerryScript 应用逻辑(如 GPIO 控制、传感器读取等物联网场景)的二次开发。

登录后查看全文
jerryscript