# zerotrap

**Repository Path**: eason-chen13/zerotrap

## Basic Information

- **Project Name**: zerotrap
- **Description**: ZeroTrap - 纯软件x86实模式模拟器。完全用Python实现，通过逐指令解码和模拟提供完全隔离，零主机系统影响。适用于计算机体系结构教学和操作系统开发研究。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 底层, 系统编程, 模拟器

## README

# ZeroTrap - 纯软件 x86 实模式模拟器

**码云 Star 数：** [请为我加星！](https://gitee.com/eason-chen13/zerotrap/stargazers)
[![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![平台](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)]()
[![状态](https://img.shields.io/badge/Status-%E6%B4%BB%E8%B7%83%E5%BC%80%E5%8F%91%E4%B8%AD-brightgreen)]()

### For English README, see this: [README](README.md)

一个完全隔离的 x86 实模式模拟器，通过**逐行指令解码与模拟**，完全用**纯 Python（100%）**实现。对宿主系统零影响。

## 特性

- **完整的 8086 指令集** - 全面的 x86 实模式指令支持
- **纯软件模拟** - 无硬件依赖，100% Python 实现
- **模块化架构** - CPU、内存、总线与设备清晰分离
- **硬件模拟** - PIC8259A、PIT8254 及中断处理
- **教育导向** - 专为计算机体系结构学习设计
- **跨平台** - 能在任何可运行 Python 的环境中运行

## 快速开始

### 安装
```bash
# 克隆仓库
git clone https://gitee.com/eason-chen13/zerotrap.git
cd zerotrap

# 以开发模式安装
pip install -e .
```

### 基本用法
```python
from zerotrap.cpu import ZeroTrapCPU
from zerotrap.bus import SystemBus
from zerotrap.devices.bus.ram import RAMDevice

# 创建一个最小系统
ram = RAMDevice(1024 * 1024)  # 1MB 实模式内存
bus = SystemBus()
cpu = ZeroTrapCPU(bus=bus)

# 连接组件
bus.attach_device(ram, 0x00000, 0xFFFFF)

# 加载并执行代码
code = '\x90\x90\xF4' # NOP, NOP, HLT
ram.load_data(code, 0x07C00)

cpu.set_reg('CS', 0x0000)
cpu.set_reg('IP', 0x7C00)
cpu.run()  # 执行至 HLT 或错误
```

## 项目结构
```text
zerotrap/
|-- src/zerotrap        # 核心模拟器源代码
|  |-- cpu.py           # CPU 核心
|  |-- bus.py           # 系统总线与内存管理
|  |-- iobus.py         # 系统 I/O 总线与端口管理
|  |-- public.py        # 公共类定义
|  |-- devices          # 设备模块
|  |  |-- bus           # 总线设备
|  |  |  |-- ram.py     # RAM 设备
|  |  |  |-- rom.py     # ROM 设备
|  |  |-- io            # I/O 端口设备
|  |  |  |-- pic.py     # PIC859A
|  |  |  |-- pit8254.py # PIT8254
|-- tests               # 测试套件
|-- docs                # 文档
|-- examples            # 使用示例
|-- LICENSE             # Apache 2.0 许可证
|-- pyproject.toml      # 构建配置
```

## 支持的指令

### 数据传送

- MOV, PUSH, POP
- IN, OUT (I/O 操作)

### 算术运算

- ADD, ADC, SUB, SBB, INC, DEC, CMP

### 逻辑运算

- AND, OR, XOR, NOT, TEST

### 控制转移

- JMP, CALL, RET, JCC (所有条件跳转)
- INT, IRET, INTO

### 字符串操作

- MOVSB, MOVSW
- 支持 `REP` 前缀

### 处理器控制

- STI, CLI, STD, CLD, STC, CLC
- HLT, NOP

## 开发

### 运行测试

```bash
# 运行全部测试
pytest

# 运行特定测试模块
pytest tests/test_cpu.py -v
```

### 代码风格

```bash
# 使用 black 格式化代码
black src/

# 使用 mypy 进行类型检查
mypy src/

# 使用 flake8 进行代码检查
flake8 src/
```

## 教育价值

ZeroTrap 作为教育工具，旨在帮助理解：

- **计算机体系结构** - 理解 CPU 内部原理
- **操作系统** - 内核开发与调试
- **x86 汇编** - 学习 x86 指令集
- **模拟器设计** - 虚拟机工作原理
- **二进制分析** - 逆向工程基础

## 文档

**状态：** 文档正与代码库同步积极开发中。

目前，最好的文档是：
1. 源代码本身（注释良好）
2. 展示演进过程的提交历史
3. 演示用法的测试套件

计划中的文档：
- [架构概述](docs/ARCHITECTURE.md) - 系统设计与组件
- [API 参考](docs/API.md) - 详细的模块文档
- [开发指南](docs/DEVELOPMENT.md) - 项目贡献指南

*想提供帮助吗？我们欢迎文档贡献！*

## 贡献指南

欢迎贡献！请随时提交 Pull Request。

1. Fork 本仓库
2. 创建您的功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature''`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

本项目依据 Apache 2.0 许可证授权 - 详见 [LICENSE](LICENSE) 文件。

## 致谢

- Intel® 64 和 IA-32 架构软件开发者手册
- OSDev.org 社区提供的硬件文档
- 所有贡献者与测试者

## 联系

Eason Chen - [https://www.gitee.com/eason_chen13](https://www.gitee.com/eason_chen13)

项目链接: [https://www.gitee.com/eason_chen13/zerotrap](https://www.gitee.com/eason_chen13/zerotrap)