rtos - RTOS底层操作库

以下为关键点梳理

一. rtos 模块核心功能概述

rtos 模块是 LuatOS 中用于实时操作系统（RTOS）相关功能的核心库，提供定时器管理、系统控制、内存监控、路径配置等底层操作接口。

---

二. API 函数分类详解

(1) 系统管理

rtos.reboot()

• 功能：重启设备。
• 参数：无。
• 返回值：无。
• 示例：

rtos.reboot()

rtos.version()

• 功能：获取固件版本号。
• 参数：无。
• 返回值：字符串（如 "V0001"）。
• 示例：

local version = rtos.version()
log.info("Firmware Version", version)

rtos.buildDate()

• 功能：获取固件编译日期。
• 参数：无。
• 返回值：字符串（如 "2023-01-01"）。
• 示例：

local build_date = rtos.buildDate()
log.info("Build Date", build_date)

rtos.bsp()

• 功能：获取硬件 BSP 型号。
• 参数：无。
• 返回值：字符串（如 "Air780EPM"）。
• 示例：

local bsp_model = rtos.bsp()
log.info("BSP Model", bsp_model)

rtos.firmware()

• 功能：返回底层描述信息（格式：LuatOS_$VERSION_$BSP）。
• 参数：无。
• 返回值：字符串。
• 用途：用于 OTA 升级判断底层兼容性。
• 示例：

log.info("Firmware Info", rtos.firmware())

---

(2) 内存管理

rtos.meminfo(type)

• 功能：获取内存使用信息。

• 参数：

• type：内存类型（"sys" 系统内存、"lua" Lua 虚拟机内存、"psram" PSRAM 内存）。默认为 "lua"。

• 返回值：

• 总内存大小（字节）。

• 已使用内存（字节）。
• 历史最高使用内存（字节）。
• 示例：

log.info("Lua Memory", rtos.meminfo())        -- 默认 Lua 内存
log.info("System Memory", rtos.meminfo("sys")) -- 系统内存

rtos.autoCollectMem(period, warning_level, force_level)

• 功能：配置内存自动收集策略（补充 Lua 自动垃圾回收机制）。

• 参数：

  • period：自动收集周期(毫秒)，等同于 receive 调用次数，0~60000。如果是 0，则关闭自动收集功能，默认是 100
  • warning_level：内存使用警戒水位线(百分比)，是总 luavm 内存量的百分比，50~95，内存达到(>=)警戒线时才会开始判断是否要收集。默认是 80
  • force_level：内存使用强制收集水位线(百分比)，是总 luavm 内存量的百分比，50~95，内存达到(>=)强制收集线时会强制收集。默认是 90，必须比警戒水位线 warning_level 大

• 注意：内存自动收集配置，是 lua 本身收集机制的一种补充，不是必要的，而且只在 luavm 空闲时触发。

• 示例：

-- 每 1000ms 检查，内存使用超过 80% 警告，超过 90% 强制回收
rtos.autoCollectMem(1000, 80, 90)

---

(3) 路径配置

rtos.setPaths(pathA, pathB, pathC, pathD)

• 功能：设置自定义 Lua 脚本搜索路径。

• 参数：

  • pathA~pathD：路径模板字符串（支持 %s 占位符）。
  • 返回值：无。
  • 限制：每个路径长度不超过 23 字节。
  • 示例：

-- 挂载 SD 卡后设置路径
rtos.setPaths("/sdcard/%s.luac", "/sdcard/%s.lua")
require("sd_user_main")  -- 尝试加载 /sdcard/sd_user_main.luac 或 .lua

---

(4) 其他底层交互

rtos.receive(timeout)

• 功能：接收并处理底层消息队列。
• 参数：timeout（超时时间，-1 表示无限等待）。
• 返回值：消息 ID（若为定时器消息则包含附加信息）。
• 注意：返回值格式由底层决定，Lua 层不保证兼容性。
• 示例：

local msg_id = rtos.receive(-1)

rtos.nop()

• 功能：空操作函数（无参数、无返回值、无逻辑）。
• 用途：性能测试或调试时使用。
• 示例：

rtos.nop()  -- 仅用于测试 Lua -> C -> Lua 的调用开销

以下为详细介绍

rtos.receive(timeout)

接受并处理底层消息队列.

参数

传入值类型	解释
int	超时时长,通常是-1,永久等待

返回值

返回值类型	解释
msgid	如果是定时器消息,会返回定时器消息id及附加信息, 其他消息由底层决定,不向lua层进行任何保证.

例子

无

---

rtos.reboot()

设备重启

参数

无

返回值

返回值类型	解释
nil	无返回值

例子

无

---

rtos.buildDate()

获取固件编译日期

参数

无

返回值

返回值类型	解释
string	固件编译日期

例子

-- 获取编译日期
local d = rtos.buildDate()

---

rtos.bsp()

获取硬件bsp型号

参数

无

返回值

返回值类型	解释
string	硬件bsp型号

例子

-- 获取硬件bsp型号
local bsp = rtos.bsp()

---

rtos.version()

获取固件版本号

参数

无

返回值

返回值类型	解释
string	固件版本号,例如"V0001"

例子

-- 读取版本号
local luatos_version = rtos.version()

---

rtos.meminfo(type)

获取内存信息

参数

传入值类型	解释
type	"sys"系统内存, "lua"虚拟机内存,"psram"psram内存, 默认为lua虚拟机内存

返回值

返回值类型	解释
int	总内存大小,单位字节
int	当前已使用的内存大小,单位字节
int	历史最高已使用的内存大小,单位字节

例子

-- 打印内存占用
log.info("mem.lua", rtos.meminfo())
log.info("mem.sys", rtos.meminfo("sys"))

---

rtos.firmware()

返回底层描述信息,格式为 LuatOS_$VERSION_$BSP,可用于OTA升级判断底层信息

参数

无

返回值

返回值类型	解释
string	底层描述信息

例子

-- 打印底层描述信息
log.info("firmware", rtos.firmware())

---

rtos.setPaths(pathA, pathB, pathC, pathD)

设置自定义lua脚本搜索路径,优先级高于内置路径

参数

传入值类型	解释
string	路径A, 例如 "/sdcard/%s.luac",若不传值,将默认为"",另外,最大长度不能超过23字节
string	路径B, 例如 "/sdcard/%s.lua"
string	路径C, 例如 "/lfs2/%s.luac"
string	路径D, 例如 "/lfs2/%s.lua"

返回值

无

例子

-- 挂载sd卡或者spiflash后
rtos.setPaths("/sdcard/user/%s.luac", "/sdcard/user/%s.lua")
require("sd_user_main") -- 将搜索并加载 /sdcard/user/sd_user_main.luac 和 /sdcard/user/sd_user_main.lua

---

rtos.nop()

空函数,什么都不做

参数

无

返回值

返回值类型	解释
nil	无返回值

例子

-- 这个函数单纯就是 lua -> c -> lua 走一遍
-- 没有参数,没有返回值,没有逻辑处理
-- 在绝大多数情况下,不会遇到这个函数的调用
-- 它通常只会出现在性能测试的代码里, 因为它什么都不干.
rtos.nop()

---

rtos.autoCollectMem(period, warning_level, force_level)

内存自动收集配置，是lua本身收集机制的一种补充，不是必要的，而且只在luavm空闲时触发

参数

传入值类型	解释
int	自动收集的周期，等同于receive调用次数，0~60000。如果是0，则关闭自动收集功能，默认是100
int	内存使用警戒水位线，是总luavm内存量的百分比，50~95，内存达到(>=)警戒线时才会开始判断是否要收集。默认是80
int	内存使用强制收集水位线，是总luavm内存量的百分比，50~95，内存达到(>=)强制收集线时会强制收集。默认是90，必须比警戒水位线大

返回值

返回值类型	解释
nil	无返回值

例子

rtos.autoCollectMem(100, 80, 90)

---