proj332-LoongArch Assembler and Runtime Simulator-龙芯汇编程序运行模拟器

1. 项目介绍

LoongArch Assembler and Runtime Simulator(下面简称LARS)，是支持LoongArch 32精简指令集的汇编程序模拟器。实现汇编程序的编写、编译、运行、调试等功能，并且提供了诸多如数据通路模拟、分支记录等拓展功能，以供LoongArch汇编语言的学习。

更多项目介绍请于项目文档(markdown)或项目文件(PDF)中进行查询。

项目介绍视频请打开百度云盘链接进行查看。

1.1 项目特点

• 基于LoongArch 32位精简指令集实现，同时实现整数型与浮点型指令
• 支持Mars的大部分syscall指令
• 支持LoongArch 32位精简指令集相关的伪指令
• 支持多种拓展工具，如数据通路模拟，分支拓展记录等
• 支持龙芯浮点与非浮点的汇编程序异常处理机制流程，支持异常的捕获和记录

1.2 项目中所使用的开源项目

本项目根据项目需求，使用了相应的开源项目。并且对相应的开源项目文件保留了其原有的开源协议声明。

1.2.1 MIPS Assembler and Runtime Simulator 4.5

MIPS Assembler and Runtime Simulator下面简称Mars，是一个用于 MIPS 汇编语言编程的轻量级交互式开发环境（IDE）。它由 Pete Sanderson 和 Kenneth Vollmar 在 Missouri State University 开发。

本项目基于Mars的框架进行开发，在Mars框架的基础上，修改了其对MIPS的支持，使其能够支持LoongArch 32精简指令集的汇编程序编写、编译、运行和调试等功能。并且本项目针对LoongArch 32精简指令集做了对应的拓展功能支持和处理。

Mars 4.5的开源协议为 MIT 协议。以下是Mars 4.5 的官网链接。

Mars 4.5 官网链接 http://courses.missouristate.edu/KenVollmar/MARS/

1.2.2 Quadruple

Quadruple 是用于四精度浮点运算的 Java 类。其主要作用是进行高精度的浮点运算模拟。

在本项目中，Quadruple主要用于浮点运算处理中，对浮点运算过程中较高精度的中间结果模拟。

Quadruple的开源协议为 Apache 2.0 协议。以下是Quadruple的GitHub仓库链接。

Quadruple Github链接 https://github.com/m-vokhm/Quadruple?tab=readme-ov-file

2. 安装和使用说明

2.1 安装步骤

2.1.1 运行环境安装

本项目代码基于Java语言编写，项目的编译和运行依赖于Java的外部库。以下是编写项目时，JDK外部库依赖需求：

Oracle OpenJDK version 21.0.2

而运行此项目需要至少 Java 8 的环境。

2.1.2 项目克隆

本项目在Gitlab上的远程路径为:https://gitlab.eduxiji.net/T202410287992756/project2210132-236065.git

2.2 使用说明

2.2.1 Jar包运行

本项目已构建好Jar包，在项目根目录下打开Lars.jar文件即可直接打开运行文件。

2.2.2 编译器运行

如果你希望自己构建Jar包或更改项目源码，可以通过git clone克隆本项目路径https://gitlab.eduxiji.net/T202410287992756/project2210132-236065.git

克隆成功后，通过编辑器打开项目根目录下的Lars.java文件，对该类文件进行编译运行以进行使用。

3. 项目示例和代码片段

3.1 使用示例

下面演示利用LARS编写和执行一个基于LoongArch 32精简指令集的斐波那契数列汇编程序。

下面演示对拓展功能LoongArch X-ray数据通路展示的演示：

使用方法：编译程序 ->Tools-> LoongArch X-ray -> Connect to LoongArch -> Step(单步进行)

3.2 代码片段

以add.w为例，展示语句的实现：

                new BasicInstruction("add.w $t1,$t2,$t3",//指令语句描述
                  "Addition without overflow : set $t1 to ($t2 add  $t3) no overflow",//指令功能描述
                  BasicInstructionFormat.THREE_R_TYPE,//指令格式
                  "00000000000100000 ccccc bbbbb aaaaa",//机器码格式
                  new SimulationCode() {//模拟实现
                     public void simulate(ProgramStatement statement) throws ProcessingException {
                        int[] operands = statement.getOperands();
                        int t2 = RegisterFile.getValue(operands[2]);
                        int t1 = RegisterFile.getValue(operands[1]);
                        int sum = t1 + t2;
                        RegisterFile.updateRegister(operands[0], sum);
                     }
                  })

4. 项目结构和文件组织

|————Lars
	|————.idea 	#存放idea项目配置文件
	|————help  	#存放LARS帮助文件中的文档
	|————images	#存放LARS所用到的图片、图标资源
	|————lars	#LARS的主要实现代码
		|————assembler #实现LoongArch 32汇编程序编译过程的代码
		|————loongarch #实现LoongArch 32架构的核心代码，含硬件模拟，指令集模拟
			|————dump          #内存转储模拟代码
			|————hardware      #硬件模拟代码
			|____instructions  #指令集模拟代码
		|————simulator #实现LoongArch 32汇编程序运行过程的代码
		|————tools     #实现拓展工具的代码
		|————util      #自定便于代码编写的方法类代码
		|____venus     #前端GUI实现代码
	|————META-INF	#打包Jar包时自动生成的配置文件
	|————out	    #运行文件
	|————test	    #存放指令集测试汇编程序
	|————docs	    #存放项目文档
		|————picture 	    #存放项目文档所需图片
		|————proj_docs.pdf   #项目文档的pdf格式
		|____proj_docs.md    #项目文档的markdown格式
	|————Lars.jar    #Lars打包的Jar包文件
	|————Lars.java   #Lars的启动主类
	|————LoongArchXRayOpcode.xml  #存放X-ray工具相关的信息
	|____PseudoOps.txt			 #定义伪指令的文件

5. 开源协议

本项目的比赛代码，技术文档，答辩材料均遵循大赛要求的具体协议进行开源。

5.1 源代码开源协议

项目源代码遵循 GPL V3.0 开源协议。

5.2 文档开源协议

项目相关文档材料遵循 CC-BY-SA 4.0 开源协议。

6. 致谢与联系信息

6.1 致谢

本项目是在指导冯老师的支持下，由Mars2Lars_NUAAers的成员进行项目的开发与完成。在此，本项目队伍再次向冯老师致以衷心的感谢。同时，在项目开发的过程中，也有不少同校的同学对项目的完善和修正给予了帮助，我们对他们的帮助和支持也给予衷心的感谢。

同时，感谢您对本项目的使用与支持。

6.2 联系信息

如果在项目的使用过程中，存在问题或建议，请联系本项目的开发小组，以下是联系方式：

Email：junjie_xian@nuaa.edu.cn

QQ：1799364931