# Maodie OS 1.0.1 使用指南

> 自研增强型 NT 混合内核操作系统 | 版本 1.0.1 | 2026-07-01

---

## 目录

1. [快速启动](#1-快速启动)
2. [Shell 命令参考](#2-shell-命令参考)
3. [内置应用](#3-内置应用)
4. [游戏](#4-游戏)
5. [文件系统](#5-文件系统)
6. [技术架构](#6-技术架构)
7. [键盘输入原理](#7-键盘输入原理)
8. [附录](#8-附录)

---

## 1. 快速启动

### 1.1 环境要求

- **操作系统**: Windows 10/11 (x64)
- **QEMU**: 需要 `qemu-system-x86_64` (v11.0.50+)
- **内核镜像**: `build\bin\maodie-kernel.elf` (约 5.3 MB，随项目提供，无需自行编译)
- **内存**: 建议 512MB

### 1.2 启动命令

> 以下命令假设你已进入项目根目录（即包含 `build` 文件夹的目录）。
> 在 PowerShell 或 CMD 中直接执行即可，**无需任何脚本**。

**图形界面模式** (推荐):

```
qemu-system-x86_64 -kernel build\bin\maodie-kernel.elf -m 512M -display gtk -k en-us
```

**无头模式** (仅串口日志，不开窗口):

```
qemu-system-x86_64 -kernel build\bin\maodie-kernel.elf -m 512M -display none -serial file:build\serial.log
```

> 提示：如果 `qemu-system-x86_64` 未加入系统 PATH，请先安装 QEMU 并将其安装目录（如 `C:\Program Files\qemu`）添加到 PATH，或使用完整路径调用。

### 1.3 参数说明

| 参数 | 说明 |
|------|------|
| `-kernel` | 直接加载 ELF 内核 (PVH 启动) |
| `-m 512M` | 分配 512MB 内存 |
| `-display gtk` | GTK 图形窗口 |
| `-display none` | 无图形界面，仅串口输出 |
| `-k en-us` | 强制 US 键盘布局 (解决中文键盘映射问题，**强烈建议加上**) |
| `-serial file:` | 串口日志输出到文件 |

---

## 2. Shell 命令参考

系统启动后自动进入内核 Shell，提示符为 `>`。

### 2.1 系统命令

| 命令 | 说明 |
|------|------|
| `help` | 显示所有可用命令 |
| `clear` | 清屏 |
| `info` | 系统信息 (架构、内存、视频) |
| `mem` | 内存详情 (通过串口输出) |
| `ver` | 内核版本号 |
| `date` | 显示日期时间 |
| `ps` | 进程列表 (PID/PPID/名称/状态) |
| `reboot` | 重启系统 (通过 8042 键盘控制器) |
| `echo <text>` | 回显文本 |

### 2.2 文件操作

| 命令 | 说明 |
|------|------|
| `dir` | 列出所有文件及大小 |
| `cat <文件名>` | 查看文件内容 |
| `rm <文件名>` | 删除文件 |

文件系统说明:
- 基于 VFS (虚拟文件系统)，最多 16 个文件
- 每个文件最大 2048 字节
- 文件存储在内存中，断电丢失

### 2.3 应用启动

| 命令 | 说明 |
|------|------|
| `calc` | 启动计算器 |
| `notepad` | 启动文本编辑器 |
| `cmd` | 进入次级命令 Shell |
| `games` | 游戏菜单 |
| `snake` | 直接启动贪吃蛇 |
| `2048` | 直接启动 2048 |

---

## 3. 内置应用

### 3.1 计算器 (`calc`)

**功能**: 简单表达式求值器，支持 Shift 输入符号

**使用方式**:
```
calc> 2+3
= 5
calc> 10*4
= 40
calc> 100/3
= 33
calc> q
Calculator closed.
```

**支持的操作**:
- 加法 `+`、减法 `-`、乘法 `*`、除法 `/`
- 支持负数 (如 `-5+3`)
- 输入 `q` 退出
- 支持 Shift 键：按住 Shift 可输入 `+` `*` `(` `)` 等符号

**技术原理**:
- 从左到右解析: `操作数1 操作符 操作数2`
- 使用 `long long` (64位) 整数运算
- 不支持运算优先级，不支持括号

### 3.2 文本编辑器 (`notepad`)

**功能**: 迷你文本编辑器，支持 VFS 文件读写，支持 Shift 输入大写字母和符号

**使用方式**:
1. 输入 `notepad` 启动
2. 输入文件名 (例如 `test.txt`) 按 Enter
3. 进入编辑模式，直接输入文本
4. 按 `F1` 保存，`F2` 重新加载，`ESC` 退出
5. 备选方案: 按 `` ` `` (反引号) 进入命令模式，然后按 `s`/`l`/`q`

**按键说明**:
| 按键 | 功能 |
|------|------|
| F1 / `` `s `` | 保存文件 |
| F2 / `` `l `` | 重新加载文件 |
| ESC / `` `q `` | 退出编辑器 (退出前自动保存) |
| Shift + 字母 | 输入大写字母 |
| Shift + 数字键 | 输入对应符号 (如 `!` `@` `#` `+` `*` 等) |
| Backspace | 删除前一个字符 |
| Enter | 换行 |
| 右上角 `sc=0xXX` | 显示当前按键扫描码 (诊断用) |

> **关于 F1/F2**: QEMU GTK 显示模式下，部分键盘布局可能导致功能键 (F1-F12) 扫描码映射错误。如果按 F1/F2 出现异常字符，请：
> 1. 启动时务必加上 `-k en-us` 参数强制 US 键盘布局
> 2. 使用 `` ` `` (反引号) 命令模式作为备选方案：按 `` ` `` 后再按 `s` 保存、`l` 加载、`q` 退出

**技术原理**:
- 编辑器缓冲区: 2048 字节
- 直接操作 VGA 文本模式显存 (0xB8000)
- 键盘输入通过轮询 PS/2 控制器端口 0x64/0x60
- 文件名输入和编辑器均支持 Shift 键 (正常/Shift 双映射表)
- 命令模式 (`` ` ``) 提供了功能键的可靠替代方案

### 3.3 次级命令 Shell (`cmd`)

**功能**: 模拟 Windows CMD 风格的次级 Shell，支持 Shift 输入符号

**支持命令**:
| 命令 | 说明 |
|------|------|
| `dir` | 列出文件 |
| `cat <文件>` | 查看文件 |
| `echo <文本>` | 回显 |
| `cls` | 清屏 |
| `exit` | 返回主 Shell |
| `help` | 帮助 |

---

## 4. 游戏

### 4.1 贪吃蛇 (`snake`)

**操作**: WASD 移动，ESC 退出

**技术原理**:
- 游戏区域: 10x23 至 69x23 (VGA 字符坐标)
- 蛇身存储: 坐标数组 (最多 200 节)
- 食物位置: 伪随机数生成 (基于分数和长度)
- 速度递增: 每吃一个食物，延时减少 300 周期
- 碰撞检测: 墙壁边界 + 自身碰撞

### 4.2 2048 (`2048`)

**操作**: WASD 移动，ESC 退出

**技术原理**:
- 4x4 网格，每个格子有颜色编码 (根据数值)
- 移动算法: 逐行/列合并相同数值
- 胜利条件: 任意格子达到 2048
- 失败条件: 无法移动 (无空格且无相邻相同值)
- 新方块: 90% 概率生成 2，10% 概率生成 4

---

## 5. 文件系统

### 5.1 VFS 虚拟文件系统

**容量限制**:
- 最大文件数: 16
- 单文件最大字节数: 2048
- 文件名最大长度: 31 字符

**特性**:
- 纯内存文件系统，无持久化
- 断电后文件丢失
- 删除文件时后续文件自动前移
- 支持按名称查找、创建、删除

---

## 6. 技术架构

### 6.1 总体架构

Maodie OS 是一个自研的增强型 NT 混合内核操作系统，采用分层架构:

```
+-----------------------------------------------+
|  Ring 3  User Mode                            |
|  +-- Win32 环境子系统 (CSRSS)                   |
|  +-- NTDLL 系统调用层                           |
|  +-- 用户应用程序                               |
+-----------------------------------------------+
|  Ring 0  Kernel Mode                          |
|  +-- NTOSKRNL 内核执行体                        |
|  |   +-- OB 对象管理器                          |
|  |   +-- MM 虚拟内存管理器                       |
|  |   +-- PS 进程/线程调度器                      |
|  |   +-- IO I/O 管理器                         |
|  |   +-- CM 配置管理器 (注册表)                  |
|  |   +-- SE 安全引用监视器                       |
|  |   +-- EX 执行体支持                          |
|  +-- WDM 驱动框架 + 驱动栈                       |
|  +-- 网络协议栈 (TCP/IP)                        |
|  +-- HAL 硬件抽象层                             |
|      +-- GDT/IDT/TSS                          |
|      +-- APIC/IOAPIC                          |
|      +-- 四级页表 (PML4->PDPT->PD->PT)          |
|      +-- PCI/ACPI                             |
+-----------------------------------------------+
```

### 6.2 内存布局 (64位虚拟地址空间)

```
地址范围                    用途
------------------------------------------------
0x00000000_00000000        空指针保护区
0x00000000_00010000        用户空间起始 (~128 TiB)
0x000007FF_FFFFFFFF        用户空间结束
------------------------------------------------
0xFFFF8000_00000000        内核空间起始
    +-- 内核代码 (.text)
    +-- 内核数据 (.data/.bss)
    +-- 内核堆栈
    +-- 页表自映射
    +-- 内核池 (512MB)
0xFFFFFFFF_FFFFFFFF        内核空间结束
```

### 6.3 启动流程

```
1. QEMU 加载 ELF -> Multiboot2 头验证
2. 32位引导代码 -> 设置页表 -> 切换到 64位长模式
3. 内核入口:
   +-- 初始化串口 (COM1, 115200 8N1)
   +-- 清零 BSS 段
   +-- [1/7] HAL 初始化 (GDT/IDT/APIC/分页)
   +-- [2/7] 对象管理器 (OB)
   +-- [3/7] 内存管理器 (MM) - 512MB 内核池
   +-- [4/7] 进程调度器 (PS)
   +-- [5/7] I/O 管理器 + WDM 驱动
   +-- [6/7] 注册表 + 安全子系统 (SE)
   +-- [7/7] 网络协议栈 + 文件系统
   +-- 进入 Shell 主循环
```

### 6.4 安全机制

- 内核地址空间隔离 (KASLR)
- 非执行页面保护 (NX/DEP)
- 堆栈金丝雀 (Stack Canary)
- 内核池溢出检测
- 驱动签名校验
- SMEP (Supervisor Mode Execution Prevention)
- SMAP (Supervisor Mode Access Prevention)
- NULL 页映射保护

### 6.5 驱动框架

**已实现驱动**:
| 驱动 | 功能 |
|------|------|
| 键盘 | PS/2 键盘输入，扫描码翻译，IRQ1 中断处理 |
| 控制台 | 串口/终端输出 |
| 磁盘 | 物理磁盘读写，分区解析 |
| 网卡 | 以太网帧收发，MAC 管理 |
| 存储 | 存储设备抽象层 |

---

## 7. 键盘输入原理

### 7.1 PS/2 键盘控制器

PS/2 键盘控制器使用两个 I/O 端口:

| 端口 | 方向 | 功能 |
|------|------|------|
| `0x60` | 读/写 | 数据端口 (读取扫描码，发送命令) |
| `0x64` | 读 | 状态端口 (bit 0 = 输出缓冲区满) |
| `0x64` | 写 | 命令端口 |

### 7.2 扫描码集 1 映射表

**正常模式 (无 Shift)**:
```
0x00: 0      0x01: ESC    0x02: '1'   0x03: '2'   0x04: '3'
0x05: '4'    0x06: '5'    0x07: '6'   0x08: '7'   0x09: '8'
0x0A: '9'    0x0B: '0'    0x0C: '-'   0x0D: '='   0x0E: BS
0x0F: TAB    0x10: 'q'    0x11: 'w'   0x12: 'e'   0x13: 'r'
0x14: 't'    0x15: 'y'    0x16: 'u'   0x17: 'i'   0x18: 'o'
0x19: 'p'    0x1A: '['    0x1B: ']'   0x1C: ENTER
0x1D: Ctrl   0x1E: 'a'    0x1F: 's'   0x20: 'd'   0x21: 'f'
0x22: 'g'    0x23: 'h'    0x24: 'j'   0x25: 'k'   0x26: 'l'
0x27: ';'    0x28: '\''   0x29: '`'   0x2A: Shift(L)
0x2B: '\\'   0x2C: 'z'    0x2D: 'x'   0x2E: 'c'   0x2F: 'v'
0x30: 'b'    0x31: 'n'    0x32: 'm'   0x33: ','   0x34: '.'
0x35: '/'    0x36: Shift(R) 0x37: '*'
0x38: Alt    0x39: ' '    0x3A: Caps  0x3B: F1
0x3C: F2     0x3D: F3     0x3E: F4    0x3F: F5
```

**Shift 模式**:
```
0x02: '!'    0x03: '@'    0x04: '#'   0x05: '$'   0x06: '%'
0x07: '^'    0x08: '&'    0x09: '*'   0x0A: '('   0x0B: ')'
0x0C: '_'    0x0D: '+'    0x1A: '{'   0x1B: '}'
0x27: ':'    0x28: '"'    0x29: '~'   0x2B: '|'
0x33: '<'    0x34: '>'    0x35: '?'
字母键 -> 对应大写字母
```

### 7.3 键盘中断 vs 轮询

系统采用两种键盘输入方式:

1. **轮询模式** (Shell/记事本/计算器/CMD): 直接读取端口 0x64/0x60，不依赖中断
2. **中断模式** (键盘驱动): 键盘中断服务例程注册在 IRQ1 (向量 0x21)，通过 IOAPIC 投递

由于 PIC 被屏蔽，Shell 使用轮询方式获取键盘输入，确保在驱动初始化之前也能正常工作。

### 7.4 Shift 键支持

主 Shell、计算器、记事本、CMD 均已支持 Shift 键:

- **Shift 按下**: 扫描码 `0x2A` (左 Shift) 或 `0x36` (右 Shift)
- **Shift 释放**: 扫描码 `0xAA` (左 Shift) 或 `0xB6` (右 Shift)
- 内部维护 Shift 状态变量，查表时在正常映射表和 Shift 映射表之间切换

---

## 8. 附录

### 8.1 故障排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| `Unknown command` | 键盘映射错误 | 检查右上角扫描码显示，确认收到的字符是否正确 |
| F1/F2 打出字母 | QEMU 键盘布局不匹配 | 启动时务必添加 `-k en-us` 参数 |
| Shift 无法输入符号 | 旧版本未支持 | 本版本已全面支持 Shift，请使用最新内核 |
| 记事本无法保存 | 功能键映射问题 | 使用 `` ` `` + `s` 命令模式保存 |
| 计算器无法输入 `+` | 未按住 Shift | `+` 位于数字键 `=` 上方，需按住 Shift 输入 |
| QEMU 无法启动 | 内核文件路径错误 | 确认在项目根目录执行命令，`build\bin\maodie-kernel.elf` 存在 |

### 8.2 项目结构

下载项目后，你只需要关注以下文件即可运行系统:

```
<项目根目录>/
+-- build\
|   +-- bin\
|   |   +-- maodie-kernel.elf   # 内核镜像 (启动用，必需)
|   +-- serial.log              # 串口日志 (运行后自动生成)

> 其余文件为系统内部组件，运行时无需关心。

### 8.3 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-06 | 初始版本，NT 混合内核架构 |
| 1.0.1 | 2026-07 | 修复 LTR TSS 描述符移位 bug，增加内存池到 512MB，全面支持 Shift 键，添加命令模式 |

---

> **Maodie OS** - 自研增强型 NT 混合内核操作系统
> 内核大小: ~5.3 MB | 目标: x86_64 long mode

下载链接：
123云盘