Merge branch 'dev'

ustc-compiler-principles · Nov 2, 2023 · 392c1f5 · 392c1f5
2 parents f879caf + 198c824
commit 392c1f5
Show file tree

Hide file tree

Showing 5 changed files with 99 additions and 111 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -38,7 +38,7 @@
 - 2023-09-25：第二次作业：3.1a、3.2a、3.10、3.11、3.17、3.19a（教材[<sup>1</sup>](#textbook)），Deadline：**2023 年 10 月 7 日 14:00**
 - 2023-10-05：[Lab2](lab2/index.md) 已发布，注意分阶段 Deadline
 - 2023-10-11：第三次作业：3.27、3.37、4.3、4.5、4.9（教材[<sup>1</sup>](#textbook)），Deadline：**2023 年 10 月 18 日 16:00**
-- 2023-11-01: [lab3](lab3/index.md) 已发布，注意分阶段 Deadline
+- 2023-11-01: [Lab3](lab3/index.md) 已发布，注意分阶段 Deadline
 
 ## 教学课件
 

diff --git a/docs/lab3/framework.md b/docs/lab3/framework.md
@@ -1,27 +1,6 @@
 # 后端框架介绍
 
-本次更新的相关文件如下：
-
-```
-.
-├── ...
-├── include
-│   ├── ...
-│   └── codegen
-│       ├── ASMInstruction.hpp	# 描述汇编指令
-│       ├── CodeGen.hpp			# 后端框架顶层设计
-│       ├── CodeGenUtil.hpp		# 一些辅助函数及宏的定义
-│       └── Register.hpp		# 描述寄存器
-├── src
-│   ├── ...
-│   └── codegen
-│       ├── CMakeLists.txt
-│       ├── CodeGen.cpp		<-- 你需要修改的文件
-│       └── Register.cpp
-└── tests
-    ├── ...
-    └── 3-codegen/*				# lab3 测试
-```
+本篇文档将介绍后端的代码框架。阅读前，你应该浏览下[这里的目录结构](../#同步实验仓库)，对框架的文件布局有总体的印象。
 
 ## 极简框架
 

diff --git a/docs/lab3/guidance.md b/docs/lab3/guidance.md
@@ -1,37 +1,31 @@
 # Lab3 实验指导
 
-一个典型的编译器后端从中间代码获取信息，进行活跃变量分析、寄存器分配、指令选择、指令优化等一系列流程，最终生成高质量的后端代码。
+## 阶段一：预热实验
 
-本次实验，我们将这些复杂的流程简化，仅追求实现的完整性，要求同学们采用栈式分配的策略，完成后端代码生成。
+### 仓库目录结构
 
-## 栈式分配
-
-阅读[栈式分配介绍](stack_allocation.md)章节，了解其思想。
-
-## 实验框架
-
-阅读[后端框架介绍](framework.md)章节，了解实验代码框架设计。
-
-## 实现约定
-
-出于简化实验的目的，我们只考核最核心的功能点，对如下情况不做要求：
-
-- phi 指令：本实验不考核对于 phi 指令的处理
-- 函数调用传参：本次实验只考核使用寄存器传参的情况，即对于超多参数的栈上传参不做要求
-
-此外，存在部分 `void main() {...}` 的样例，其返回值是未定义的，我们要求这样的主函数通过寄存器 `$a0` 返回 0，以顺利进行测评。
-
-## 实验
+与预热实验相关的文件如下：
 
-### 阶段一：预热实验
+```
+.
+├── ...
+├── include
+│   ├── common
+│   └── codegen/*
+└── tests
+    ├── ...
+    └── 3-codegen
+        └── warmup
+            ├── CMakeLists.txt
+            ├── ll_cases          <- 需要翻译的 ll 代码
+            └── stu_cpp           <- 学生需要编写的汇编代码手动生成器
+```
 
-#### 实验内容
+### 实验内容
 
 实验在 `tests/3-codegen/warmup/ll_cases/` 目录下提供了六个 `.ll` 文件。学生需要在 `tests/3-codegen/warmup/stu_cpp/` 目录中，依次完成 `assign_codegen.cpp`、`float_codegen.cpp`、`global_codegen.cpp`、`function_codegen.cpp`、`icmp_codegen.cpp` 和 `fcmp_codegen.cpp` 六个 C++ 程序中的 TODO。这六个程序运行后应该能够生成 `tests/3-codegen/warmup/ll_cases/` 目录下六个 `.ll` 文件对应的汇编程序。
 
-#### 编译、运行、测试
-
-##### 编译
+### 编译
 
 ```shell
 $ cd 2023ustc-jianmu-compiler
@@ -45,7 +39,7 @@ $ make
 
 如果构建成功，你会在 `build` 文件夹下找到 `stu_assign_codegen`, `stu_float_codegen` 等可执行文件。
 
-##### 运行与测试
+### 运行与测试
 
 !!! note
 
@@ -61,28 +55,42 @@ $ echo $?
 
 你可以通过观察原来的 `.ll` 代码来推断 `echo $?` 应该返回的正确结果，也可以直接使用 `lli` 执行 `.ll` 文件来获取正确结果。
 
-#### 仓库目录结构
+## 阶段二：编译器后端
 
-与预热实验相关的文件如下：
+### 仓库目录结构
+
+与实验第二阶段相关的文件如下：
 
 ```
 .
-├── ...
 ├── include
-│   ├── common
-│   └── codegen/*
+│   └── codegen/*					# 相关头文件
+├── src
+│   └── codegen
+│       └── CodeGen.cpp     	<-- 学生需要补全的文件
 └── tests
-    ├── ...
-    └── 3-codegen
-        └── warmup
-            ├── CMakeLists.txt
-            ├── ll_cases          <- 需要翻译的 ll 代码
-            └── stu_cpp           <- 学生需要编写的汇编代码手动生成器
+    ├── 3-codegen
+    │   └── autogen
+    │       ├── eval_lab3.sh	<-- 测评脚本
+    │		└── testcases 		<-- lab3 第二阶段的测例目录一
+    └── testcases_general		<-- lab3 第二阶段的测例目录二
 ```
 
-### 阶段二：编译器后端
+### 实验内容
+
+补全 `src/codegen/CodeGen.cpp` 中的 TODO，并按需修改 `include/codegen/CodeGen.hpp` 等文件，使编译器能够生成正确的汇编代码。
+
+!!! info "实现约定"
 
-#### 编译
+    出于简化实验的目的，我们只考核最核心的功能点，对如下情况不做要求：
+
+    - phi 指令：本实验不考核对于 phi 指令的处理
+
+    - 函数调用传参：本次实验只考核使用寄存器传参的情况，即对于超多参数的栈上传参不做要求
+
+    此外，存在部分 `void main() {...}` 的样例，其返回值是未定义的，我们要求这样的主函数通过寄存器 `$a0` 返回 0，以顺利进行测评。
+
+### 编译
 
 ```shell
 $ cd 2023ustc-jianmu-compiler
@@ -96,28 +104,24 @@ $ make
 $ sudo make install
 ```
 
-如果构建成功，你会在 `build` 文件夹下找到 cminusfc 可执行文件，它能将 cminus 文件输出为龙芯汇编文件。
-
-#### 运行
-
-我们在 `tests/testcases_general` 文件夹中准备了一些通用案例。当需要对 `.cminus` 单个文件测试时，可以这样使用：
-
-##### 情况一：生成 IR 文件
+如果构建成功，你会在 `build` 文件夹下找到 cminusfc 可执行文件，它能将 `.cminus` 文件输出为龙芯汇编文件。
 
 !!! note
 
     为了让 cminusfc 在 `$PATH` 中，一定要 `sudo make install`。
 
+### 运行
+
+完成第二阶段，编译器能够将 `.cminus` 文件翻译成正确的龙芯汇编 `.s` 文件：
+
 ```shell
 # 假设 cminusfc 的路径在你的 $PATH 中，并且你现在在 test.cminus 文件所在目录中
 $ cminusfc test.cminus -S
 ```
 
 此时会在同目录下生成同名的汇编文件，在这里即为 `test.s`。
 
-##### 情况二：生成可执行文件
-
-上面生成的汇编文件用于阅读，如果需要运行，需要调用龙芯交叉编译器编译链接生成二进制文件 `test`
+为了运行得到的汇编文件，需要调用龙芯交叉编译器编译链接生成二进制文件 `test`：
 
 ```shell
 # 假设你位于 2023ustc-jianmu-compiler 目录, 否则你应该修改下面 src/io/io.c 到具体的路径
@@ -131,10 +135,10 @@ $ loongarch64-unknown-linux-gnu-gcc -static test.s src/io/io.c -o test
 然后你可以使用 `qemu-loongarch64` 运行二进制文件 `test`
 
 ```shell
-qemu-loongarch64 ./test
+$ qemu-loongarch64 ./test
 ```
 
-#### 测试
+### 测试
 
 在 `tests/3-codegen/autogen` 目录下，使用我们提供的 `eval_lab3.sh` 进行本地评测，其接受两个**参数**：
 
@@ -150,8 +154,6 @@ qemu-loongarch64 ./test
 
 在结束测评后，你可以使用 `./cleanup.sh` **清空**上述文件/目录，以保持仓库的清爽。
 
-#### 测试示例
-
 以下是评测脚本的**使用示例**：
 
 以 `./testcases` 为测例目录，使用评测脚本 `test` 模式测试（我们使用正确的实现，但是故意在 `13-complex.cminus` 中制造了语法错误）：
@@ -191,7 +193,7 @@ error at line 7 column 5: syntax error
 
 直接使用初始代码尝试评测，每个样例都会报错 `CE: cminusfc compiler error`。
 
-!!! detail "初始代码评测后的 log 文件"
+??? detail "使用初始代码评测后的 log 文件"
 
     ```
     ==========./testcases/0-io.cminus==========

diff --git a/docs/lab3/index.md b/docs/lab3/index.md
@@ -2,6 +2,35 @@
 
 经过 Lab1 和 Lab2，我们的编译器能够将 Cminusf 源代码翻译成 Light IR。本次实验要求同学们将 IR 翻译成龙芯汇编指令。
 
+## 同步实验仓库
+
+在进行实验之前，首先拉取[实验仓库](https://cscourse.ustc.edu.cn/vdir/Gitlab/compiler_staff/2023ustc-jianmu-compiler)的最新代码，具体步骤可以参考[Lab2 中的指导](../lab2/#实验要求)。
+
+本次实验仓库更新的内容如下，每个阶段的文件将在对应文档详细说明：
+
+```
+.
+├── ...
+├── include
+│   ├── ...
+│   └── codegen
+│       ├── ASMInstruction.hpp  # 描述汇编指令
+│       ├── CodeGen.hpp         # 后端框架顶层设计
+│       ├── CodeGenUtil.hpp     # 一些辅助函数及宏的定义
+│       └── Register.hpp        # 描述寄存器
+├── src
+│   ├── ...
+│   └── codegen
+│       ├── CMakeLists.txt
+│       ├── CodeGen.cpp     <-- lab3 第二阶段需要修改的文件
+│       └── Register.cpp
+└── tests
+    ├── ...
+    └── 3-codegen
+        ├── warmup			<-- lab3 第一阶段（代码撰写）
+        └── autogen			<-- lab3 第二阶段的测试
+```
+
 ## 实验内容
 
 <!--TODO 预估时间-->
@@ -10,13 +39,10 @@
 
 此为预热实验，主要引导同学完成环境的配置并学习相关知识。
 
-1. 查阅[后端环境配置](./environment.md)章节，完成龙芯交叉编译工具链的安装。
+1. 阅读[后端环境配置](./environment.md)章节，完成龙芯交叉编译工具链的安装。
 2. 阅读[龙芯汇编介绍](../common/asm_intro.md)章节，了解龙芯汇编的基础知识。
-3. 阅读[Lab3 实验指导](./guidance.md)的[预热实验](./guidance.md#阶段一预热实验)章节，简要了解如何使用提供的 C++ 接口生成汇编指令，进行补全汇编的实验并测试。
-
-<!--TODO 手动补全汇编的样例待确定、是否/如何计分待确定-->
-
-阶段一需要完成 `tests/3-codegen/warmup/stu_cpp` 目录下代码的填写。
+3. 阅读[后端框架介绍](framework.md)中的[指令类介绍](framework.md/#指令类)和[辅助函数（添加指令）介绍](framework.md/#append_inst)，了解如何使用提供的 C++ 接口生成汇编指令。
+4. 阅读 [Lab3 实验指导的预热实验](./guidance.md#阶段一预热实验)章节，了解实验内容，进行补全汇编的实验并测试。
 
 !!! warning "Deadline"
 
@@ -26,43 +52,24 @@
 
 来到本次实验的核心：实现编译器后端，即根据 IR 翻译得到龙芯汇编指令。
 
-在进行实验之前，请确保完成了[阶段一](#阶段一)，并且本地仓库已经与上游仓库同步：
+一个典型的编译器后端从中间代码获取信息，进行活跃变量分析、寄存器分配、指令选择、指令优化等一系列流程，最终生成高质量的后端代码。
 
-```shell
-# 在虚拟机实验仓库的路径下输入命令
-$ git pull upstream master
-```
+本次实验，我们将这些复杂的流程简化，仅追求实现的完整性，要求同学们采用栈式分配的策略，完成后端代码生成。
 
-阅读 [Lab3 实验指导](./guidance.md)，了解实验细节，完成本次实验。
+1. 阅读[栈式分配介绍](stack_allocation.md)章节，了解其思想。
+2. 阅读[后端框架介绍](framework.md)章节，了解实验代码框架设计。
+3. 阅读 [Lab3 实验指导中的阶段二](./guidance.md/#阶段二编译器后端)章节，了解实验细节，完成本次实验。
 
 !!! warning "Deadline"
 
     **2023 年 11 月 24 日 23:59**
 
-## 实验要求
-
-请将[实验仓库](https://cscourse.ustc.edu.cn/vdir/Gitlab/compiler_staff/2023ustc-jianmu-compiler)设置为上游仓库，并获取本次实验更新的内容，具体步骤如下：
-
-将上游仓库设置一个别名（alias），在这里我们用 `upstream`，你也可以改成其他你喜欢的名字。在你 fork 后的本地仓库中：
-
-```shell
-$ git remote add upstream https://cscourse.ustc.edu.cn/vdir/Gitlab/compiler_staff/2023ustc-jianmu-compiler.git
-```
-
-尝试将远程的更新拉取到本地并进行 merge 操作：
-
-```shell
-$ git pull upstream master
-```
+## 提交内容
 
-当 merge 过程出现冲突时，请参考 [Lab0](../lab0/git.md#上下游同步和冲突处理) 来合理的解决冲突。
+阶段一、二：在希冀平台提交你实验仓库的 url（如 `https://cscourse.ustc.edu.cn/vdir/Gitlab/xxx/2023ustc-jianmu-compiler.git`）。
 
-最后你需要将更改同步到你 fork 得到的远程仓库中：
+在提交之前，请确保你 fork 得到的远程仓库与本地同步：
 
 ```shell
 $ git push origin master
 ```
-
-## 提交内容
-
-- 阶段一、二：在希冀平台提交你实验仓库的 url（如 `https://cscourse.ustc.edu.cn/vdir/Gitlab/xxx/2023ustc-jianmu-compiler.git`）。
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -55,9 +55,9 @@ nav:
     - IR 自动化生成: lab2/autogen.md
   - Lab3:
     - Lab3 简介: lab3/index.md
+    - Lab3 实验指导: lab3/guidance.md
     - 后端环境配置: lab3/environment.md
     - 龙芯汇编介绍: common/asm_intro.md
-    - Lab3 实验指导: lab3/guidance.md
     - 栈式分配介绍: lab3/stack_allocation.md
     - 后端框架介绍: lab3/framework.md
   - FAQ: faq/README.md