first commit

Author: wu-kan

.github/workflows/publish-gh-pages.yml

@@ -0,0 +1,21 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v2
+        with:  
+          fetch-depth: 0
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TZ: "Asia/Shanghai"

LICENSE

@@ -0,0 +1,3 @@
+# Yat-CPU-Docs
+
+在线阅读：<https://scc.sysu.tech/YatCPU-docs/>

README.md

@@ -0,0 +1,3 @@
+# 前言
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)

docs/README.md

@@ -0,0 +1,3 @@
+# Coming soon
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)

docs/arch/README.md

@@ -0,0 +1,3 @@
+# Coming soon
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)

docs/faq/README.md

@@ -0,0 +1,3 @@
+# Coming soon
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)

docs/lab/README.md

@@ -0,0 +1,3 @@
+# Coming soon
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)

docs/lab/lab1.md

@@ -0,0 +1,55 @@
+# 开发环境
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)
+
+本项目主要搭建在 Linux 或 WSL （Windows Subsystem for Linux）环境中。~~Windows 环境和 MacOS 理论上也可以，但需要读者自行摸索。~~[这里](https://liuhaohua.com/server-programming-guide/appendix/build-env/)给出搭建相关环境的一个参照。
+
+这里假设你使用的 Linux 或 WSL 系统是 Debian 11。对于使用其他 Linux 系统的同学，操作是类似的，相信你有足够的能力参考下面的指令搭建环境。
+
+## 必要工具
+
+```bash
+sudo apt install git  # 用于将本项目 clone 下来
+sudo apt install gcc-riscv64-unknown-elf # 用于生成 risc-v 的测试指令
+sudo apt install make # build-essential
+sudo apt install curl gnupg2 # 下载工具
+sudo apt install scala # 本项目的语言
+sudo apt install libtinfo5 # vivado 需要一个这个，否则启动报错
+```
+
+## 包管理器 SBT
+
+[sbt](https://packages.debian.org/sid/sbt)目前仍然在 Debian 的[不稳定](https://www.debian.org/releases/sid/)版本中。对于不希望使用 sid 系统的同学，可以按照[文档](https://www.scala-sbt.org/1.x/docs/zh-cn/Installing-sbt-on-Linux.html#Ubuntu%E5%92%8C%E5%85%B6%E4%BB%96%E5%9F%BA%E4%BA%8EDebian%E7%9A%84%E5%8F%91%E8%A1%8C%E7%89%88)的指示下载安装。
+
+```bash
+echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
+echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
+curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
+sudo apt update
+sudo apt install sbt
+```
+
+## Vivado
+
+中山大学组成原理实验课使用的 [Basys3](https://www.stepfpga.com/doc/_media/basys3_ss.pdf) 实验板型号为 XC7A35T，需要 Xilinx 的工具进行烧板。这里安装 `Vivado HL WebPACK`即可，不需要许可或激活许可密钥。
+
+中山大学校园网内下载 Vivado 安装包，可以使用我们提供的镜像。
+
+```bash
+curl -O https://mirrors.matrix.moe/software/Xilinx_Unified_2020.1_0602_1208.tar.gz
+# 也可以在 Xilinx 的官网下载
+# <https://china.xilinx.com/support/download/index.html/content/xilinx/zh/downloadNav/vivado-design-tools/archive.html>
+tar -zxf Xilinx_Unified_2020.1_0602_1208.tar.gz
+cd Xilinx_Unified_2020.1_0602_1208
+./xsetup -b ConfigGen
+```
+
+先输入 `2` 再输入 `1`，这时会选中 `Vivado HL WebPACK`。最后会产生一个默认配置文件 `~/.Xilinx/install_config.txt`。
+
+随后再次执行下述指令，安装`Vivado HL WebPACK`。
+
+```bash
+./xsetup -a XilinxEULA,3rdPartyEULA,WebTalkTerms -b Install -c ~/.Xilinx/install_config.txt -l ~/Xilinx
+```
+
+其中`~/Xilinx`是安装目录，可以自行定义。

docs/quick_start/Environment.md

@@ -0,0 +1,31 @@
+# 烧板验证
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)
+
+## 生成二进制文件
+
+假设你的 Vivado 安装目录是 `~/Xilinx`（其他目录自行修改），执行下述指令，可以根据 `verilog/Top.v` 生成二进制文件 `vivado/riscv-basys3/riscv-basys3.runs/impl_1/Top.bit`。
+
+```bash
+cd vivado
+~/Xilinx/Vivado/2020.1/bin/vivado -mode batch -source ./generate_bitstream.tcl
+```
+
+## 烧板
+
+由于 WSL 下暂时不可以使用 USB 设备，因此不可以直接烧板。解决方案有两个。
+
+### 方案一：使用 USB 方式烧板（WIP）
+
+需要一个 Fat32 格式的 U 盘。
+
+### 方案二：在 Windows 下烧板
+
+由于 WSL 下可以调用 powershell，我们可以回到 Windows 下烧板。Windows 下可以只装 Vivado_Lab，和完整版的 Vivado 相比只有烧板功能，精简很多。
+
+```bash
+# 假设你在 vivado 目录下，同时 Windows 下 Vivado_Lab 安装在 `C:\Xilinx`
+powershell.exe 'C:\Xilinx\Vivado_Lab\2020.1\bin\vivado_lab.bat -mode batch -source .\program_device.tcl'
+```
+
+中山大学校园网内下载 Vivado_Lab 安装包，也可以使用我们提供的的镜像。

docs/quick_start/Program.md

@@ -0,0 +1,23 @@
+# 快速测试
+
+By: [:material-github: wu-kan](https://github.com/wu-kan)
+
+执行下述指令可以模拟运行本项目的测试，首次运行时需要联网自动下载必要的组件。
+
+```bash
+# git clone [email protected]:SYSU-SCC/YatCPU.git
+# cd YatCPU
+sbt test
+```
+
+如果成功执行，你会看到类似这样的输出。
+
+```bash
+[success] Total time: 385 s (06:25), completed Dec 15, 2021, 8:45:25 PM
+```
+
+输入如下指令，可以编译生成 verilog 代码 `verilog/Top.v`。
+
+```bash
+sbt run
+```

docs/quick_start/Test.md

@@ -0,0 +1,57 @@
+nav:
+  - 前言: "README.md"
+  - Quick Start:
+    - 开发环境: "quick_start/Environment.md"
+    - 快速测试: "quick_start/Test.md"
+    - 写板验证: "quick_start/Program.md"
+  - 架构: "arch/README.md"
+  - 实验: "lab/README.md"
+    - 实验一: "lab/labs1.md"
+  - Faqs: "faq/README.md"
+
+site_name: YatCPU documentation
+site_url: https://scc.sysu.tech/YatCPU-docs/
+repo_url: https://github.com/SYSU-SCC/YatCPU/
+copyright: |
+  <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
+theme:
+  icon:
+    repo: fontawesome/brands/github
+  name: material
+  custom_dir: docs/overrides
+  language: zh
+  features:
+    - navigation.top
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: 夜间模式
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: 白天模式
+plugins:
+  - search
+  - git-authors
+  - git-revision-date-localized:
+      type: iso_datetime
+      timezone: Asia/Shanghai
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.keys
+  - pymdownx.snippets
+  - pymdownx.inlinehilite
+  - footnotes
+  - admonition
+  - toc:
+      permalink: true
+      slugify: !!python/name:pymdownx.slugs.uslugify
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg

mkdocs.yml

@@ -0,0 +1,5 @@
+mkdocs==1.2.2
+mkdocs-material==7.2.5
+mkdocs-material-extensions==1.0.1
+mkdocs-git-revision-date-localized-plugin==0.9.2
+mkdocs-git-authors-plugin==0.3.3