From a1234d5382e8fdc5028c4d58047fa83eaef4a7a0 Mon Sep 17 00:00:00 2001 From: Viper Date: Sun, 19 Jul 2026 12:42:11 +0800 Subject: [PATCH] Add bilingual README --- README.md | 339 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..081cf49 --- /dev/null +++ b/README.md @@ -0,0 +1,339 @@ +# ViperOS + +[English](#english) | [中文](#中文) + +A bare-metal 64-bit operating system written in the [Viper](https://git.gvsds.com/GVSDS/TransPyC) language. Boots via UEFI, ships a self-implemented FAT32 driver, runs ELF-format user applications, and includes a complete user-space SDK. + +用 [Viper](https://git.gvsds.com/GVSDS/TransPyC) 语言编写的裸机 64 位操作系统。UEFI 启动、自研 FAT32 驱动、运行 ELF 格式用户程序，配套完整的用户态 SDK。 + +--- + + + +## 中文 + +### 这是什么 + +`ViperOS` 是 Viper 语言的旗舰演示项目：**一个完整可启动的操作系统**。和"Linux 发行版"或"教学用 mini-OS"不同，ViperOS 用 Viper 写一切——内核、设备驱动、用户程序、库、SDK 都用同一种语言（Viper 的 Python 语法 + LLVM 后端）。 + +主要组成： +- **VKernel** —— 64 位微内核（x86_64-none-elf 目标） +- **UEFI 引导器** —— `boot/boot.c`（GNU-EFI 编译为 `disk/EFI/BOOT/bootx64.efi`） +- **FAT32 驱动** —— 自研实现，支持挂载、目录、文件操作 +- **4 个用户应用** —— HelloWorld / Terminal / Gargantua / Scene3D +- **2 个动态库** —— SerialLogger / VPUI64 +- **ViperPOS SDK** —— 用户态开发库（系统调用、窗口、文件系统、进程） + +### 目录结构 + +``` +ViperOS/ +├── .gitignore # 忽略所有 output/、temp/、构建产物 +├── build.py # 顶层构建入口：构建→打包→启动 QEMU +├── linker.ld # 顶层链接脚本 +├── boot/ # UEFI 引导器 +│ ├── Makefile +│ └── boot.c +├── VKernel/ # 内核 +│ ├── project.json # 内核构建配置 +│ ├── linker.ld +│ └── Kernel/ +│ ├── main.py # 内核入口 +│ ├── bootinfo.py +│ ├── drivers/ # 驱动 +│ │ ├── core/cpu/ # APIC、CPU、FPU +│ │ ├── devfs/ # 设备文件系统 +│ │ ├── fs/fat32/ # FAT32 驱动（自研） +│ │ ├── input/ # 键盘、鼠标 +│ │ ├── serial/ # 8250 UART +│ │ ├── storage/ # IDE +│ │ ├── usb/ # USB HID / UHCI +│ │ └── video/ # VESA Framebuffer + UI +│ ├── execrunner/ # ELF 加载器 +│ ├── intr/ # 中断子系统（GDT/IDT/ISR/Syscall） +│ ├── mm/ # 内存管理 +│ ├── paging/ # 分页 +│ ├── sched/ # 协程、进程、调度 +│ ├── services/ # 内核服务 +│ └── platform/ # 平台相关（PIC/PIT/RTC/Timer） +├── Apps/ # 用户应用（每个子目录一个独立 ELF） +│ ├── HelloWorld/ +│ ├── Terminal/ +│ ├── Gargantua/ +│ └── Scene3D/ +├── Libs/ # 动态库（每个子目录一个 .so） +│ ├── SerialLogger/ +│ └── VPUI64/ +├── vpsdk/ # ViperPOS SDK（应用开发用） +│ ├── __init__.py +│ ├── stdlib.py +│ ├── syscall.py +│ ├── window.py +│ ├── vpui.py +│ ├── fs.py +│ ├── process.py +│ ├── dynlib.py +│ └── wiki/ # SDK 自带 wiki +├── Scripts/ +│ ├── check_disk.py +│ ├── disk.ps1 # ImDisk 打包 FAT32 镜像 +│ └── disk.sh # Linux 等价脚本 +└── disk/ # 被打包进 disk.img 的文件 + ├── EFI/BOOT/bootx64.efi + ├── app/helloworld.asm + ├── apps/ # .elf 拷贝目标（构建时填充） + ├── libs/ # .so 拷贝目标（构建时填充） + └── sys/kernel/x86_64/kernel.bin +``` + +### 前提条件 + +| 工具 | 说明 | +|------|------| +| `python` ≥ 3.10 | 运行 TransPyC 编译器 | +| `llc` | LLVM 静态编译器 | +| `ld.lld` | LLD 链接器（裸机版本） | +| `qemu-system-x86_64` | QEMU 模拟器 | +| `imdisk` | Windows 下创建/挂载磁盘镜像的驱动；Linux 平台用 `disk.sh` 替代 | +| `gnu-efi` 工具链 | 编译 UEFI 引导器（`boot/boot.c`） | +| [TransPyC](https://git.gvsds.com/GVSDS/TransPyC) | 编译器，**必须克隆在与 ViperOS 同级的目录** | + +目录布局要求： + +``` +D:\Users\TermiNexus\Desktop\TransPyC\ +├── TransPyC\ # 编译器仓库 +├── ViperOS\ # 本仓库 +└── ViperTemplateProject\ +``` + +### 快速开始 + +```powershell +# 1. 在 ViperOS 目录下直接运行 +cd D:\Users\TermiNexus\Desktop\TransPyC\ViperOS + +# 2. 完整构建并启动 QEMU +python build.py + +# 3. 串口日志写入 serial.log +``` + +`build.py` 会自动完成： +1. 调用 `Projectrans.py` 编译 VKernel → `VKernel/output/kernel.bin` +2. 编译 2 个动态库（SerialLogger、VPUI64） +3. 编译 4 个应用（HelloWorld、Terminal、Gargantua、Scene3D） +4. 拷贝所有产物到 `disk/apps/`、`disk/libs/`、`disk/sys/kernel/x86_64/` +5. 调用 `Scripts/disk.ps1` 创建 64MB FAT32 镜像 `disk.img` +6. 启动 QEMU（TCG 加速、`-no-reboot` 防止三重错误后重启） + +退出 QEMU 后查看 `serial.log` 可看到内核启动日志。 + +### 常用构建参数 + +```powershell +python build.py --noclean # 不清缓存，保留 temp/ 加速二次构建 +python build.py --kernel-only # 只重编译内核，跳过应用和库 +``` + +⚠ 不支持 `--noqemu`（`build.py` 第 76 行注释明确"不准使用 --noqemu"）。 + +### 添加新应用 + +1. 在 `Apps/` 下新建目录，例如 `Apps/MyApp/` +2. 创建 `App/MyApp/main.py`（参考 `Apps/HelloWorld/main.py`） +3. 创建 `App/MyApp/project.json`（参考 `Apps/HelloWorld/project.json`，注意 `triple = "x86_64-none-elf"`、`linker` 用 `ld.lld` 输出 `.elf`） +4. 在 `build.py` 中追加构建 + 拷贝命令 +5. 在 `disk/apps/MyApp/` 目录放应用需要的资源（运行时通过 vpsdk 访问） + +### 添加新驱动 + +在 `VKernel/Kernel/drivers/<子系统>/<设备>/` 下添加 `<设备>.py`，参考 `fs/fat32/fat32.py`（最大的驱动，自研 FAT32 完整实现）。在 `VKernel/Kernel/main.py` 中注册驱动初始化。 + +### 平台说明 + +| 平台 | 状态 | +|------|------| +| Windows 10/11 + mingw + QEMU | ✅ 主平台，CI 测试覆盖 | +| Linux x86_64 + clang + QEMU | ⚠ 理论可用，需把 `build.py` 改用 `disk.sh`，ld.lld 用系统 lld | +| macOS | ❌ 未测试 | +| 真实硬件 | ❌ 暂未支持（仅 UEFI x86_64） | + +### 调试 + +- **QEMU 串口日志**：`build.py` 启动时把 `-serial file:serial.log`，所有 `printf` 写到该文件 +- **GDB**：`qemu-system-x86_64` 加 `-s -S` 然后用 `gdb` 连 `localhost:1234` +- **崩溃排查**：`build.py` 默认带 `-no-reboot`，避免三重错误后无限重启 + +### 进一步阅读 + +- [TransPyC 编译器仓库](https://git.gvsds.com/GVSDS/TransPyC) +- [Viper 语言概览](https://git.gvsds.com/GVSDS/TransPyC/blob/main/wiki/01-overview.md) +- [ViperOS SDK wiki](vpsdk/wiki/01-overview.md) +- [Viper 模板项目（ViperTemplateProject）](https://git.gvsds.com/GVSDS/Viper_TemplateProject) + +--- + + + +## English + +### What is this + +`ViperOS` is the flagship demo of the [Viper](https://git.gvsds.com/GVSDS/TransPyC) language: a **complete bootable operating system** written in Viper. Unlike a Linux distro or a teaching mini-OS, ViperOS uses one language for everything — kernel, device drivers, user programs, libraries, SDK all use Viper (Python syntax + LLVM backend). + +Main components: +- **VKernel** — 64-bit microkernel (target `x86_64-none-elf`) +- **UEFI bootloader** — `boot/boot.c` (compiled by GNU-EFI to `disk/EFI/BOOT/bootx64.efi`) +- **FAT32 driver** — self-implemented, supports mount/dir/file operations +- **4 user applications** — HelloWorld / Terminal / Gargantua / Scene3D +- **2 dynamic libraries** — SerialLogger / VPUI64 +- **ViperPOS SDK** — user-space development kit (syscall, window, fs, process) + +### Directory layout + +``` +ViperOS/ +├── .gitignore # ignores all output/, temp/, build artifacts +├── build.py # top-level build entry: build -> pack -> QEMU +├── linker.ld # top-level linker script +├── boot/ # UEFI bootloader +│ ├── Makefile +│ └── boot.c +├── VKernel/ # kernel +│ ├── project.json # kernel build config +│ ├── linker.ld +│ └── Kernel/ +│ ├── main.py # kernel entry +│ ├── bootinfo.py +│ ├── drivers/ # device drivers +│ │ ├── core/cpu/ # APIC, CPU, FPU +│ │ ├── devfs/ # device filesystem +│ │ ├── fs/fat32/ # self-implemented FAT32 driver +│ │ ├── input/ # keyboard, mouse +│ │ ├── serial/ # 8250 UART +│ │ ├── storage/ # IDE +│ │ ├── usb/ # USB HID / UHCI +│ │ └── video/ # VESA framebuffer + UI +│ ├── execrunner/ # ELF loader +│ ├── intr/ # GDT/IDT/ISR/syscall +│ ├── mm/ # memory management +│ ├── paging/ # paging +│ ├── sched/ # coroutine, process, scheduler +│ ├── services/ # kernel services +│ └── platform/ # platform glue (PIC/PIT/RTC/Timer) +├── Apps/ # user apps (each subdir = one ELF) +│ ├── HelloWorld/ +│ ├── Terminal/ +│ ├── Gargantua/ +│ └── Scene3D/ +├── Libs/ # shared libraries (each subdir = one .so) +│ ├── SerialLogger/ +│ └── VPUI64/ +├── vpsdk/ # ViperPOS SDK (for user apps) +│ ├── __init__.py +│ ├── stdlib.py +│ ├── syscall.py +│ ├── window.py +│ ├── vpui.py +│ ├── fs.py +│ ├── process.py +│ ├── dynlib.py +│ └── wiki/ # SDK wiki +├── Scripts/ +│ ├── check_disk.py +│ ├── disk.ps1 # ImDisk-based FAT32 image builder +│ └── disk.sh # Linux-equivalent +└── disk/ # files packed into disk.img + ├── EFI/BOOT/bootx64.efi + ├── app/helloworld.asm + ├── apps/ # .elf destination (filled at build time) + ├── libs/ # .so destination (filled at build time) + └── sys/kernel/x86_64/kernel.bin +``` + +### Prerequisites + +| Tool | Notes | +|------|-------| +| `python` ≥ 3.10 | runs TransPyC | +| `llc` | LLVM static compiler | +| `ld.lld` | LLD linker (bare-metal) | +| `qemu-system-x86_64` | QEMU emulator | +| `imdisk` | Windows disk-image mount utility; on Linux use `disk.sh` instead | +| `gnu-efi` toolchain | builds the UEFI bootloader (`boot/boot.c`) | +| [TransPyC](https://git.gvsds.com/GVSDS/TransPyC) | compiler; **must be cloned as a sibling of ViperOS** | + +Required layout: + +``` +D:\Users\TermiNexus\Desktop\TransPyC\ +├── TransPyC\ # compiler repo +├── ViperOS\ # this repo +└── ViperTemplateProject\ +``` + +### Quick start + +```powershell +# 1. From the ViperOS directory +cd D:\Users\TermiNexus\Desktop\TransPyC\ViperOS + +# 2. Full build and launch QEMU +python build.py + +# 3. Serial log is written to serial.log +``` + +`build.py` automatically: +1. Calls `Projectrans.py` to build VKernel -> `VKernel/output/kernel.bin` +2. Builds 2 shared libraries (SerialLogger, VPUI64) +3. Builds 4 applications (HelloWorld, Terminal, Gargantua, Scene3D) +4. Copies all artifacts into `disk/apps/`, `disk/libs/`, `disk/sys/kernel/x86_64/` +5. Calls `Scripts/disk.ps1` to create a 64MB FAT32 image `disk.img` +6. Launches QEMU (TCG accel, `-no-reboot` to prevent reboot on triple fault) + +After quitting QEMU, inspect `serial.log` for kernel boot messages. + +### Common build flags + +```powershell +python build.py --noclean # keep temp/ to speed up subsequent builds +python build.py --kernel-only # only rebuild the kernel, skip apps/libs +``` + +`--noqemu` is **NOT supported** (see comment at line 76 of `build.py`). + +### Adding a new application + +1. Create a directory under `Apps/`, e.g. `Apps/MyApp/` +2. Add `App/MyApp/main.py` (see `Apps/HelloWorld/main.py` for reference) +3. Add `App/MyApp/project.json` (see `Apps/HelloWorld/project.json`; set `triple = "x86_64-none-elf"`, link with `ld.lld` to produce `.elf`) +4. Add build + copy commands in `build.py` +5. Put any runtime resources in `disk/apps/MyApp/` (read at runtime via vpsdk) + +### Adding a new driver + +Add `.py` under `VKernel/Kernel/drivers///`. See `fs/fat32/fat32.py` (largest, full FAT32 implementation). Register the init in `VKernel/Kernel/main.py`. + +### Platform support + +| Platform | Status | +|----------|--------| +| Windows 10/11 + mingw + QEMU | ✅ primary, CI-tested | +| Linux x86_64 + clang + QEMU | ⚠ theoretically works, requires modifying `build.py` to use `disk.sh` and system lld | +| macOS | ❌ untested | +| Real hardware | ❌ not yet (UEFI x86_64 only) | + +### Debugging + +- **QEMU serial log**: `build.py` passes `-serial file:serial.log`; all `printf` output goes there +- **GDB**: add `-s -S` to `qemu-system-x86_64` and attach `gdb` to `localhost:1234` +- **Crash triage**: `build.py` always uses `-no-reboot`, avoiding reboot loops after triple faults + +### Further reading + +- [TransPyC compiler](https://git.gvsds.com/GVSDS/TransPyC) +- [Viper language overview](https://git.gvsds.com/GVSDS/TransPyC/blob/main/wiki/01-overview.md) +- [ViperOS SDK wiki](vpsdk/wiki/01-overview.md) +- [Viper template project (ViperTemplateProject)](https://git.gvsds.com/GVSDS/Viper_TemplateProject)