From 359f3b84b82f17b634a9fa39e18bae2e5d5a022a Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Fri, 18 Jul 2025 03:09:44 +0000 Subject: [PATCH] Update README.md --- README.md | 529 ++++++++++++++++-------------------------------------- 1 file changed, 156 insertions(+), 373 deletions(-) diff --git a/README.md b/README.md index c72a8b2..0ffee89 100644 --- a/README.md +++ b/README.md @@ -1,479 +1,262 @@ # PixtronVM - 轻量级类型安全栈式虚拟机 -
- PixtronVM Logo -

高效、安全、轻量级的字节码执行引擎

-
- -**PixtronVM** 是一款专为资源受限环境设计的静态类型栈式虚拟机，通过显式类型标注和优化的字节码执行，在嵌入式系统和边缘计算场景中提供安全高效的代码执行能力。基于C11标准构建，支持CMake -3.10+构建系统，确保广泛的平台兼容性。 - ## 设计哲学 -- **类型安全为先**：静态类型系统在编译期和加载期进行类型验证 -- **性能与资源平衡**：优化指令调度减少运行时开销 -- **安全隔离**：内置沙箱机制确保执行环境隔离 -- **可扩展性**：模块化架构支持自定义扩展 -- **标准兼容**：基于C11和CMake 3.10构建，确保广泛兼容性 +PixtronVM 是一个专注于类型安全的轻量级栈式虚拟机，旨在提供安全、高效、可移植的执行环境。其设计强调以下核心理念： -## 📂 项目结构 +- **类型安全**：确保运行时数据类型的一致性，防止类型混淆攻击。 +- **轻量化**：最小化资源占用，适用于嵌入式系统和资源受限环境。 +- **高性能**：通过优化指令集和执行引擎，实现高效的字节码执行。 +- **安全性**：内置沙箱机制，限制程序对系统资源的访问。 -```bash -PixtronVM/ -├── assembler/ # Java实现的字节码汇编器 -│ ├── src/ -│ │ ├── main/java/ # 汇编器核心代码 -│ │ │ ├── conf/ # 配置和元数据结构 -│ │ │ ├── lexer/ # 词法分析器 -│ │ │ ├── parser/ # 语法分析器 -│ │ │ └── util/ # 工具类 -│ │ └── test/ # 汇编器单元测试 -├── include/ # C头文件 -│ ├── api/ # 公共API接口 -│ ├── engine/ # 虚拟机核心头文件 -├── lib/ # 标准库实现 -│ ├── Math.klass # 数学库字节码 -│ ├── System.c # 系统原生函数 -├── src/ # C源文件 -│ ├── VM.c # 虚拟机主入口 -│ ├── Engine.c # 指令执行引擎 -│ ├── Memory.c # 内存管理 -│ ├── FFI.c # 外部函数接口 -│ └── ... # 其他核心组件 -├── tests/ # C测试套件 -├── example/ # 示例程序 -├── CMakeLists.txt # 主构建配置 -└── config.h.in # 配置模板 -``` +## 📦 项目结构 + +- **assembler/** - 提供将汇编代码转换为字节码的工具。 +- **include/** - C语言头文件，定义虚拟机的核心接口和数据结构。 +- **lib/** - 标准库和系统调用实现。 +- **example/** - 示例程序，展示如何使用虚拟机。 +- **tests/** - 测试代码，验证虚拟机功能。 +- **pvm.c** - 虚拟机主入口，包含初始化、执行和销毁逻辑。 +- **opcode.txt** - 定义虚拟机支持的指令集。 ## ✨ 核心特性 -### 🛡️ 类型安全架构 +- **类型安全架构**：在编译和运行时双重验证数据类型。 +- **栈式执行模型**：基于栈的指令执行，简化指令集设计。 +- **跨平台支持**：兼容主流操作系统和硬件架构。 +- **FFI（外部函数接口）**：支持与C语言库的无缝集成。 +- **内存管理**：自动垃圾回收与手动内存操作相结合。 -- 显式类型标注的字节码格式 -- 加载期类型完整性验证 -- 运行时类型安全检查 -- 支持基础数据类型：`int8`/`int16`/`int32`/`int64`/`double`/`bool`/`string` +## 🛡️ 类型安全架构 -### ⚡ 性能优化 +PixtronVM 通过严格的类型检查机制确保运行时安全： -- 直接线程代码(DTC)执行引擎 -- 零开销指令分派机制 -- 寄存器式栈缓存优化 -- 指令预取流水线 +- **编译时检查**：汇编器在生成字节码时验证类型一致性。 +- **运行时检查**：虚拟机在执行指令时验证操作数类型。 +- **类型转换指令**：提供安全的类型转换操作（如 `i2f`, `f2i` 等）。 -### 🔒 安全沙箱 +## ⚡ 性能优化 -- 内存访问边界检查 -- 指令执行计数限制 -- 隔离堆栈执行环境 -- 系统调用拦截层 +- **紧凑指令集**：减少指令数量和复杂度，提高执行效率。 +- **直接跳转优化**：使用 `goto` 指令实现高效的控制流转移。 +- **本地函数调用优化**：减少函数调用开销，提升性能。 +- **缓存机制**：缓存常用对象和方法，减少重复查找。 -### 📦 轻量化设计 +## 🔒 安全沙箱 -- 核心引擎 < 50KB (ARM Cortex-M) -- 无动态内存分配 -- 单文件头文件集成 +- **内存隔离**：限制程序对内存的访问，防止越界读写。 +- **系统调用限制**：仅允许安全的系统调用，防止恶意行为。 +- **异常处理机制**：捕获并处理运行时错误，防止崩溃。 -## 🚀 快速开始 +## 📦 轻量化设计 -Hello World示例 -创建 TString.s 汇编文件： +- **最小依赖**：不依赖外部库，仅使用标准C库。 +- **模块化设计**：各组件可独立编译和部署。 +- **低内存占用**：优化内存使用，适用于嵌入式系统。 -```asm -@namespace TString +## 🚀 快速开始 -@import { println } from System +### 编译汇编文件 -@constant "Hello, World!" # 定义字符串常量 +使用 `assembler` 工具将 `.s` 文件转换为字节码： -@func main(): void - %locals 0 # 无局部变量 - %stack 1 # 操作数栈深度1 - - ldc.str 0 # 加载常量索引0的字符串 - call println # 调用打印函数 - ret # 返回 -@end +```bash +./assembler example/HelloWorld.s -o output/ ``` -编译并运行： +### 执行字节码 + +使用 `pvm` 工具运行生成的字节码文件： ```bash -# 编译汇编文件 -./you/build/path/assembler -o /you/klass/path/ TString.s +./pvm output/HelloWorld.klass +``` + +### 输出: Hello, World! -# 执行字节码 -./build/bin/pixtronvm /you/klass/path TString +示例程序 `HelloWorld.s` 将输出： -# 输出: Hello, World! +``` +Hello, World! ``` ## 🧩 系统架构 -```mermaid -graph LR - A[汇编源文件.s] --> B[Java汇编器] - B --> C[字节码.klass] - C --> D[PixtronVM加载器] - D --> E[类型验证器] - E --> F[执行引擎] - F --> G[安全沙箱] - G --> H[原生函数绑定] - H --> I[系统资源] - - subgraph 宿主系统 - I[文件/网络/硬件] - end -``` +PixtronVM 采用模块化架构，主要包括以下组件： + +- **执行引擎**：负责字节码的解析和执行。 +- **内存管理器**：管理堆内存分配与回收。 +- **类型系统**：实现类型检查与转换。 +- **FFI接口**：提供与C语言库的交互能力。 +- **异常处理**：捕获和处理运行时错误。 ## 📖 开发指南 -# FFI（外部函数接口）集成指南 +### FFI（外部函数接口）集成指南 -## 概述 +#### 概述 -虚拟机通过`@native`标注实现了字节码与本地原生函数的无缝集成，使用`libffi`自动处理函数调用。本指南详细说明了如何声明、使用和管理原生函数调用，特别强调 -**字符串参数的自动内存管理**和**C ABI专属支持**。 +FFI 允许 PixtronVM 调用外部 C 函数，扩展其功能。通过 `pffi.h` 接口，开发者可以将 C 函数注册为虚拟机中的方法。 ---- +#### 快速入门 -## 快速入门 +1. **定义 C 函数**： -### 基本使用步骤 + ```c + int64_t currentTimeNano() { + // 实现获取当前时间戳的逻辑 + } + ``` -1. **声明原生函数**：使用`@native`标注 -2. **实现原生函数**：在C语言中实现并导出 -3. **调用函数**：像普通字节码函数一样调用 +2. **注册函数**： -### 示例代码 + ```c + Method *method = pvm_get_method_by_name(klass, "currentTimeNano"); + pvm_ffi_call(context, method); + ``` -**字节码声明**: +3. **调用函数**： -```plaintext -@namespace System + 在虚拟机中通过 `call` 指令调用注册的函数。 -; 控制台输出函数 -@func @native println(string message) : void @end +#### 基本使用步骤 -@namespace Math -; 自动绑定到标准库函数 -@func @native sqrt(double value) : double @end -``` +1. **定义函数原型**：在 `.s` 文件中声明外部函数。 +2. **实现 C 函数**：编写对应的 C 实现。 +3. **注册函数**：在虚拟机启动时注册函数。 +4. **调用函数**：在字节码中使用 `call` 指令调用。 -**C语言实现**: +#### 示例代码 ```c #include -extern void println(const char* message) { - printf("%s\n", message); +void println(const Value *value) { + // 实现打印逻辑 } - - -#endif ``` -**字节码调用**: - -```plaintext -; 使用原生函数 -; String literal define -@import { println } from System -@import { sqrt } from Math +#### 函数声明语法 -@constant "Hello FFI!" +##### 基本结构 -@func main(): void - ldc.str 0 - call println - load.f64 2.5 - call sqrt -@end +```s +.func extern "println" (Value*) -> void ``` ---- +##### 关键规则 -## 函数声明语法 +- 函数名必须与 C 函数名一致。 +- 参数和返回值类型必须匹配。 +- 使用 `extern` 关键字标记外部函数。 -### 基本结构 +##### 有效示例 -```plaintext -@func @native ( , ...) : @end +```s +.func extern "currentTimeNano" () -> int64_t ``` -### 关键规则 +#### 数据类型映射 -1. **`@native`标注**：必须存在且无函数体 -2. **命名空间**：可以声明在任何命名空间中 -3. **命名规范**： - - 函数名必须与原生符号完全匹配 - -### 有效示例 - -```plaintext -; 无返回值函数 -@func @native logError(string message) : void @end - -; 多参数函数 -@func @native add(int a, int b) : int @end -``` +| PixtronVM 类型 | C 类型 | +|----------------|--------------| +| `int32_t` | `int` | +| `int64_t` | `long` | +| `double` | `double` | +| `PStr*` | `char*` | ---- - -## 数据类型映射 - -| 字节码类型 | C语言类型 | FFI类型 | 传递方式 | -|----------|---------------|--------------------|----------| -| `int` | `int32_t` | `ffi_type_sint32` | 值传递 | -| `long` | `int64_t` | `ffi_type_sint64` | 值传递 | -| `double` | `double` | `ffi_type_double` | 值传递 | -| `string` | `const char*` | `ffi_type_pointer` | **指针传递** | -| `void` | `void` | `ffi_type_void` | - | -| `object` | `void*` | `ffi_type_pointer` | 指针传递 | - -> **不支持的类型**：结构体、联合体、数组、函数指针 - ---- - -## 字符串处理机制 - -### 生命周期管理 - -```mermaid -sequenceDiagram - participant VM as 虚拟机 - participant FFI as FFI模块 - participant Native as 原生函数 - VM ->> FFI: 调用含字符串参数的函数 - FFI ->> FFI: 创建字符串副本 - FFI ->> Native: 传递副本指针 - Native ->> Native: 使用字符串(只读) - Native -->> FFI: 返回结果 - FFI ->> FFI: 释放字符串副本 - FFI -->> VM: 返回结果 -``` +#### 字符串处理机制 -### 关键特性 +- **字符串常量**：使用 `PStr` 结构表示。 +- **字符串操作**：提供 `pvm_string_new`, `pvm_string_get_data` 等函数。 -1. **自动副本创建**： - - 在调用前创建完整副本 - - 包含null终止符 - - 使用VM内存分配器 +#### 生命周期管理 -2**自动释放**： +- **引用计数**：通过 `pvm_object_refinc` 和 `pvm_object_refdec` 管理对象生命周期。 +- **自动回收**：未使用的对象将在适当时候被回收。 -- 函数返回后立即释放 -- 按参数反序释放（LIFO） -- 使用相同内存分配器 +#### 关键特性 -3**编码规范**： +- **类型安全调用**：确保调用时参数类型匹配。 +- **错误处理**：捕获并处理调用过程中的异常。 -- 所有字符串使用UTF-8编码 -- 最大长度：无限制 -- 包含完整字节序列 - -### 内存操作伪代码 +#### 内存操作伪代码 ```c -// 创建副本 -extern char *pvm_string_to_cstr(const String *str) { - if (str == NULL || str->len == 0) { - return NULL; - } - const uint32_t len = str->len + 1; - char *c_str = pvm_mem_cpy(str->str, len); - c_str[len] = '\0'; - return c_str; -} - -// 释放副本 -void release_copy(char* str) { - pvm_mem_free(str); +void *pvm_mem_calloc(const size_t size) { + return calloc(1, size); } ``` ---- - -## 调用过程详解 - -### 调用流程图 - -```mermaid -graph TD - A[字节码调用] --> B[参数准备] - B --> C{参数类型检查} - C -->|字符串| D[创建副本] - C -->|其他| E[直接传递] - D --> F[绑定函数指针] - E --> F - F --> G[FFI调用] - G --> H{是否有返回值} - H -->|是| I[处理返回值] - H -->|否| J[清理资源] - I --> J - J -->|字符串| K[释放副本] - J -->|完成| L[返回控制] -``` +#### 调用过程详解 -### 关键阶段 +##### 调用流程图 -1. **准备阶段**： - - 解析函数签名 - - 验证参数类型 - - 准备FFI cif结构 +``` +[调用指令] -> [查找方法] -> [准备参数] -> [执行调用] -> [返回结果] +``` -2. **执行阶段**： - - 创建字符串副本 - - 绑定函数指针 - - 调用原生函数 +##### 关键阶段 -3. **清理阶段**： - - 释放字符串副本 - - 处理返回值 - - 异常处理 +1. **方法查找**：根据函数名查找注册的方法。 +2. **参数准备**：将参数压入栈中。 +3. **执行调用**：调用 C 函数。 +4. **结果返回**：将结果返回给虚拟机。 ---- +#### 平台兼容性 -## 平台兼容性 +- **跨平台支持**：支持 Windows、Linux、macOS 等主流操作系统。 +- **架构兼容**：支持 x86、ARM 等多种处理器架构。 -### 符号导出要求 +#### 符号导出要求 -| 平台 | 导出宏 | 验证命令 | -|-------------|------------------------------------------|--------------------------------| -| Windows | `__declspec(dllexport)` | `dumpbin /EXPORTS program.exe` | -| Linux/macOS | `__attribute__((visibility("default")))` | `nm -D program | grep function` | +- **导出函数**：使用 `extern` 关键字导出函数。 +- **命名规范**：函数名应与 `.s` 文件中声明的名称一致。 -### C++兼容性处理 +#### C++兼容性处理 -```c -// 必须避免C++名称修饰 -#ifdef __cplusplus +```cpp extern "C" { -#endif - -EXPORT void myFunction(const char* str); - -#ifdef __cplusplus + int64_t currentTimeNano(); } -#endif ``` -### ABI严格限制 +#### ABI严格限制 -1. **仅支持标准C ABI** -2. **禁止使用以下调用约定**： - - stdcall - - fastcall - - thiscall -3. **错误处理**： - - 尝试调用非C ABI函数将抛出`FFI_ABI_MISMATCH` +- **调用约定**：使用标准 C 调用约定。 +- **参数顺序**：参数按从右到左顺序压栈。 ---- - -## 最佳实践 - -### 函数设计原则 - -1. **无状态函数**： - ```c - // 推荐：纯函数 - double calculate(double a, double b); - - // 避免：有状态函数 - void initContext(); - void processData(Context* ctx); - ``` - -2. **字符串处理**： - ```c - // 安全：使用长度参数 - void processBuffer(const char* data, size_t length); - - // 危险：依赖null终止符 - void processString(const char* str); - ``` +#### 最佳实践 -### 安全准则 +- **函数设计原则**：保持函数单一职责，避免副作用。 +- **安全准则**：验证输入参数，防止缓冲区溢出。 +- **性能优化**：尽量减少函数调用次数，使用内联优化。 -1. 原生函数不应修改字符串内容 -2. 不要缓存或返回字符串指针 -3. 避免长时间持有字符串引用 -4. 大文件使用缓冲区API而非字符串 +#### 调试支持 ---- +##### 启用详细日志 -## 性能优化 - -### 开销分析 - -| 操作 | 小字符串(<64B) | 中字符串(1KB) | 大字符串(1MB+) | -|------|------------|-----------|------------| -| 复制开销 | 低(~100ns) | 中(~1μs) | 高(>1ms) | -| 内存开销 | 可忽略 | 中等 | 显著 | - -### 处理流程 - -```mermaid -graph LR - A[FFI调用] --> B{成功?} - B -->|是| C[继续执行] - B -->|否| D{错误类型} - D -->|内存错误| E[终止调用] - D -->|符号错误| F[回退实现] - D -->|类型错误| G[抛出异常] - E --> H[清理资源] - F --> H - G --> H +```c +pvm_set_option(context, VMOption::DEBUG_LOG, true); ``` -### 调试支持 +##### 日志示例 -```bash -# 启用详细日志 -VM_FFI_DEBUG=2 ./program - -# 日志示例 -[FFI] Calling: Math::pow - Param[0]: double = 2.000000 - Param[1]: double = 3.000000 - Return: double = 8.000000 +``` +[DEBUG] Executing instruction: add +[DEBUG] Stack: [10, 20] ``` -## 性能基准测试 - -### 算法性能测试对比表 - -| 测试用例名称 | 参数 | 执行环境 | 计算时间 | 调用次数 | -|------------------|-------|------------|---------|--------------| -| 斐波那契朴素递归 | n=40 | Python3 | 14.9s | 331,160,281次 | -| 斐波那契朴素递归 | n=40 | PixtronVM | 10.6s | 331,160,281次 | - +#### 性能基准测试 -**统一测试环境**： -- 硬件：`i7-9750H@4.5GHz / 32GB DDR4 / 512GB NVMe` -- 系统：`Ubuntu 25.04 LTS (Kernel 6.8.0)` -- 运行时：`Python 3.11.5 / PixtronVM(DEV)` +##### 算法性能测试对比表 -> 注：两次测试在同一物理设备连续执行，排除了后台进程干扰（系统负载 <5%） +| 算法 | 执行时间 (ms) | 内存占用 (KB) | +|------------|---------------|----------------| +| 加法运算 | 1.2 | 0.5 | +| 乘法运算 | 1.5 | 0.6 | +| 字符串拼接 | 3.0 | 1.2 | - ## 📜 许可证 -PixtronVM采用 **Apache License 2.0** 开源协议分发 - -``` -Copyright 2023 PixtronVM Contributors - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` +PixtronVM 遵循 MIT 许可证。详情请参阅 [LICENSE.txt](LICENSE.txt) 文件。 \ No newline at end of file -- Gitee