build: use include to handle multiple files (#9)

Previously, we passed multiple file to pandoc one by one, which is not
suitable for future more complex document. This also requires that the
heading level of each file should conform to the whole document, rather
than starting from level 1.

This patch introduced pandoc filter include-files to handle document
level automatically. This patch also shifts all files heading to level 1
to adapt the future mkdocs framework.

Makefile

@@ -1,52 +1,43 @@
 VERSION = $(shell git describe --always)
 
-SRCS = 
-SRCS += docs/preface.md
-SRCS += docs/introduction.md
-SRCS += docs/processor.md
-SRCS += docs/instruction-set.md
-SRCS += docs/registers.md
-SRCS += docs/mode-and-csr.md
-SRCS += docs/exception-and-interrupt.md
-SRCS += docs/memory-model.md
-SRCS += docs/memory-subsystem.md
-SRCS += docs/vector.md
-SRCS += docs/interruption-controller.md
-SRCS += docs/bus-interface.md
-SRCS += docs/debug.md
-SRCS += docs/performance-monitor.md
+MAIN_MD = pandoc-main.md
+SRCS = $(wildcard docs/*.md)
 
 SVG_FIGS := $(wildcard docs/figs/*.svg)
-PDF_FIGS := $(patsubst docs/figs/%.svg, build/figs/%.pdf, $(SVG_FIGS))
+PDF_FIGS := $(patsubst docs/figs/%.svg, build/docs/figs/%.pdf, $(SVG_FIGS))
 
 DEPS =
 DEPS += $(wildcard resources/*.lua)
 DEPS += resources/template.tex
 
 PANDOC_FLAGS += --variable=version:"$(VERSION)"
-PANDOC_FLAGS += --from=markdown+table_captions+multiline_tables+grid_tables+header_attributes
-PANDOC_FLAGS += --top-level-division=part
+PANDOC_FLAGS += --from=markdown+table_captions+multiline_tables+grid_tables+header_attributes-implicit_figures
 PANDOC_FLAGS += --table-of-contents
 PANDOC_FLAGS += --number-sections
-PANDOC_FLAGS += --pdf-engine=xelatex
+# PANDOC_FLAGS += --filter pandoc-crossref
+PANDOC_FLAGS += --lua-filter=include-files.lua
+PANDOC_FLAGS += --metadata=include-auto
 PANDOC_FLAGS += --lua-filter=resources/meta_vars.lua
-PANDOC_FLAGS += --lua-filter=resources/svg_to_pdf.lua
 PANDOC_FLAGS += --lua-filter=resources/remove_md_links.lua
-PANDOC_FLAGS += --filter pandoc-crossref
-PANDOC_FLAGS += --template=resources/template.tex
+
+PANDOC_LATEX_FLAGS += --top-level-division=chapter
+PANDOC_LATEX_FLAGS += --pdf-engine=xelatex
+PANDOC_LATEX_FLAGS += --lua-filter=resources/svg_to_pdf.lua
+PANDOC_LATEX_FLAGS += --template=resources/template.tex
+
 
 all: xiangshan-user-guide.pdf
 
 clean:
 	rm -f xiangshan-user-guide.tex xiangshan-user-guide.pdf *.aux *.log *.toc
 	rm -rf build
 
-build/figs/%.pdf: docs/figs/%.svg
-	mkdir -p build/figs
+build/docs/figs/%.pdf: docs/figs/%.svg
+	mkdir -p build/docs/figs
 	rsvg-convert -f pdf -o $@ $<
 
-xiangshan-user-guide.tex: $(SRCS) $(DEPS)
-	pandoc $(SRCS) $(PANDOC_FLAGS) -s -o $@
+xiangshan-user-guide.tex: $(MAIN_MD) $(SRCS) $(DEPS)
+	pandoc $(MAIN_MD) $(PANDOC_FLAGS) $(PANDOC_LATEX_FLAGS) -s -o $@
 	sed -i 's/@{}//g' $@
 
 xiangshan-user-guide.pdf: xiangshan-user-guide.tex $(PDF_FIGS)

docs/bus-interface.md

@@ -3,12 +3,12 @@ file_authors_:
 - Sun Jiru <[email protected]> 
 ---
 
-## 总线接口 {#sec:bus-interface}
+# 总线接口 {#sec:bus-interface}
 
 {{var_processor_name}} 的总线接口具有 256 位宽度，支持 CHI Issue B 或 Issue E.b 的子集。
 关于该协议的详细内容，请参考 AMBA® CHI Architecture Specification。
 
-### 支持的响应类型
+## 支持的响应类型
 
 CHI 协议的 RespErr 可以表示响应正常或是错误。 {{var_processor_name}} 支持的响应类型如下。
 
@@ -20,13 +20,13 @@ CHI 协议的 RespErr 可以表示响应正常或是错误。 {{var_processor_na
 
 由于 {{var_processor_name}} 不具有数据校验码，因此不支持 DERR。
 
-### 不同总线响应下的行为
+## 不同总线响应下的行为
 
 * Normal Okay：普通传输访问成功，或 exclusive 传输访问失败；读传输 exclusive 访问失败代表总线不支持 exclusive 传输，产生访问错误异常，写传输 exclusive 访问失败仅代表抢锁失败，不会返回异常。
 * Exclusive Okay：exclusive 访问成功。
 * NDERR：访问出错，读传输产生访问错误异常，写传输忽略此错误。
 
-### 接口信号
+## 接口信号
 
 CHI 使用不同的通道传输不同的消息，传输的消息包括：
 
@@ -66,7 +66,7 @@ RX 的 linkactiveack 和 linkactivereq 决定了 RX 的状态；TX 的 linkactiv
 | RUN        | 1               | 1               |
 | DEACTIVATE | 0               | 1               |
 
-#### 通道信号
+### 通道信号
 
 Table: RXDAT 通道信号
 
@@ -122,7 +122,7 @@ Table: TXRSP 通道信号
 | chi_tx_rsp_flit     | O   | TXRSP 通道的 flit                             |
 | chi_tx_rsp_flitpend | O   | flit 的 pending 信号，表示接下来会传输一个 flit |
 
-#### flit 格式
+### flit 格式
 
 位宽为空，代表此信号与上一行的信号是共用的。
 信号名后面标注\*，代表此信号仅适用于 CHI Issue E.b。
@@ -233,7 +233,7 @@ Table: Snoop flit
 | RetToSrc             | 1        | 该字段请求 Snoopee 将缓存行的副本返回给 Home。 |
 | TraceTag             | 1        | 标记，用于跟踪。 |
 
-### 支持的 Coherency Transaction 类型
+## 支持的 Coherency Transaction 类型
 
 * SnpShared
 * SnpClean

docs/debug.md

@@ -3,11 +3,11 @@ file_authors_:
 - ChengGuanghui <[email protected]> 
 ---
 
-## 调试 {#sec:debug}
+# 调试 {#sec:debug}
 
 本章是昆明湖的调试模块的设计文档。昆明湖 debug 兼容 RISC-V Debug V0.13 手册标准。对外调试接口支持 JTAG。调试接口是软件与处理器交互的通道。用户可以通过调试接口获取CPU的状态，包括寄存器和存储器内容，以及其他片上设备的信息。支持程序下载。
 
-### Debug Module
+## Debug Module
 如下图所示。昆明湖的 debug 工作是由调试软件（GDB）、调试代理服务程序(openocd)、调试器(debug module wrapper)等组件一起配合完成的，
 其中调试器包括 JtagDTM， DMI， DM。
 调试接口在整个 CPU 调试环境中的位置如下图所示。
@@ -27,7 +27,7 @@ file_authors_:
 * 支持软断点(ebreak 指令)、硬断点（trigger）和内存断点（trigger）。
 * 支持读写CSR和内存，支持 progbuf 和 sysbus 两种访存方式。
 
-### Trigger Module
+## Trigger Module
 当前昆明湖 trigger module 的实现情况如下：
 
 * 昆明湖 trigger module 当前实现的 debug 相关的 CSR 如下表所示。 

docs/exception-and-interrupt.md

@@ -3,9 +3,9 @@ file_authors_:
 - zengjinhong <[email protected]>
 ---
 
-## 异常与中断 {#sec:exception-and-interrupt}
+# 异常与中断 {#sec:exception-and-interrupt}
 
-### 概述
+## 概述
 
 异常和中断是处理器从正常程序执行流跳转到特权模式的一种机制，用于应对各种意外或预期的事件。这些机制帮助处理器解决执行过程中遇到的问题，维护系统的稳定性，处理外部事件的响应。
 
@@ -21,7 +21,7 @@ file_authors_:
   2. 软件中断：由软件触发，用于与操作系统交互或执行某些系统级别的任务。
 * 陷入（Trap）是一种处理器从用户模式或较低特权级别切换到特权模式（如内核模式）处理事件的机制。处理器通过陷入机制捕获异常或中断，保存上下文信息，并跳转到相应的处理程序。处理完成后，处理器通过返回指令（如 mret 或 sret）恢复之前的执行状态，继续执行原来的程序。
 
-### 异常
+## 异常
 
 {{var_processor_name}} 支持多种异常，如下表所示：
 
@@ -61,7 +61,7 @@ Table: {{var_processor_name}} 支持的异常列表
 
 我们以机器模式为例，介绍异常处理的步骤。
 
-#### 异常响应
+### 异常响应
 
 第一步：处理器保存发生异常的 PC 到 mepc 中。
 
@@ -71,15 +71,15 @@ Table: {{var_processor_name}} 支持的异常列表
 
 第四步：根据 mtvec 取对应的指令并执行。
 
-#### 异常返回
+### 异常返回
 
 异常返回通过 mret 指令实现，该指令执行下列操作。
 
 * 根据 mepc 恢复 PC。
 * 根据 mstatus 的 MPIE 位恢复 mstatus 的 MIE 位。
 * 将当前的 Privilege Mode 改为 mstatus 的 MPP 位，且如果 MPP 位为机器模式，则将 Virtual Mode 置为 0，否则置为 mstatus 的 MPV 位。
 
-### 中断
+## 中断
 
 {{var_processor_name}} 支持多种中断，如下表所示：
 
@@ -105,7 +105,7 @@ Table: {{var_processor_name}} 支持的中断列表
 
 我们以机器模式为例，介绍中断处理的步骤
 
-#### 中断优先级
+### 中断优先级
 
 {{var_processor_name}} 的中断优先级，如下表所示：
 
@@ -135,7 +135,7 @@ Table: {{var_processor_name}} 中断优先级
 |            | Custom Group 3 | 51, 25, 50 | 最低优先级 Custom 中断             |
 |    最低    |                | 49, 24, 48 |                                    |
 
-#### 中断响应
+### 中断响应
 
 第一步：处理器执行完当前指令后，将下一条指令的 PC 存入 mepc。
 
@@ -145,7 +145,7 @@ Table: {{var_processor_name}} 中断优先级
 
 第四步：根据 mtvec 取对应的指令并执行。
 
-#### 中断返回
+### 中断返回
 
 * 根据 mepc 恢复 PC。
 * 根据 mstatus 的 MPIE 位恢复 mstatus 的 MIE 位。

docs/preface.md → docs/index.md

@@ -1,39 +1,12 @@
----
-title: "香山开源处理器用户手册"
-title-line1: "香山开源处理器"
-title-line2: "用户手册"
-# title-line1: "XiangShan"
-# title-line2: "Open-Source Processor"
-# title-line3: "User Guide"
-subtitle: "文档版本"
-author: "香山团队·北京开源芯片研究院"
-date: "\\today"
-var_processor_name: "昆明湖V2R2"
-figureTitle: "图"
-tableTitle: "表"
-listingTitle: "代码"
-lofTitle: "# 图目录"
-lotTitle: "# 图目录"
-lolTitle: "# 代码目录"
-figPrefix: "图"
-eqnPrefix: "公式"
-tblPrefix: "表"
-lstPrefix: "代码"
-secPrefix: "§"
-i18n-applicable: "适用于"
-# i18n-applicable: "Applicable to"
----
+# 前言 {-}
 
-## 前言 {-}
-
-
-### 版本信息 {-}
+## 版本信息 {-}
 
 | 日期 | 版本 | 说明       |
 | ---- | ---- | ---------- |
 |      |      | 第一次发布 |
 
-### 版权声明 {-}
+## 声明 {-}
 
 版权所有 © 2024 香山开源处理器团队·北京开源芯片研究院
 

docs/instruction-set.md

@@ -3,9 +3,9 @@ file_authors_:
 - Tang Haojin <[email protected]> 
 ---
 
-## 指令集 {#sec:instruction-set}
+# 指令集 {#sec:instruction-set}
 
-### 支持的指令集扩展
+## 支持的指令集扩展
 
 i, m, a, f, d, c, b, v, h,
 sdtrig, sha, shcounterenw, shgatpa, shlcofideleg, shtvala, shvsatpa, shvstvala,

docs/interruption-controller.md

@@ -3,17 +3,17 @@ file_authors_:
 - Zhao Hong <[email protected]>
 ---
 
-## 中断控制器 {#sec:interruption-controller}
+# 中断控制器 {#sec:interruption-controller}
 
 {{var_processor_name}} 中，中断控制器包括 IMSIC 外部中断控制器，CLINT 本地中断控制器，下面进行详细说明。
 
-### CLINT 中断控制器
+## CLINT 中断控制器
 
-#### 概要
+### 概要
 
 CLINT 为 HART 提供 M 特权级下的软件中断，以及 M 特权级下的 time 定时中断，以及 64bit time 计时器。
 
-#### 寄存器映射
+### 寄存器映射
 
 Table: CLINT 的寄存器排布
 
@@ -30,14 +30,14 @@ Table: CLINT 的寄存器排布
 |  0x0000_BFF8   |  8B   |    RW     |      MTIME 寄存器       |
 
 
-### IMSIC 中断控制器
+## IMSIC 中断控制器
 
-#### 概要
+### 概要
 
 IMSIC 作为 RISCV 的外部中断控制器之一，负责 MSI 中断的接收与传递，涵盖 M, S, VS 特权级下的中断上报 。
 每种特权级下的中断配置通过 IMSIC interrupt file MMIO 空间实现，默认支持 interrupt file 数目 7 个： M, S,5 个 VS interrupt file.默认支持有效中断号：1-255.
 
-#### 寄存器映射
+### 寄存器映射
 
 DEVICE 通过发送中断 ID 到 IMSIC 内部 interrupt file MMIO 空间，从而实现 MSI 的发送。
 RISCV AIA SPEC明确规定，多 interrupt files 场景下, Supervisor-level 只能访问 all Supervisor-level and guest interrupt files,不能访问 Machine-level interrupt files.
@@ -63,7 +63,7 @@ Table: S/VS interrupt file
 | setipnum_le_vs4 | 0x4000   | 32   | WO   | 32'h0  | VS 4 interrupt file 访问寄存器。写入数据为MSI 中断ID，读取值为0.默认支持最高8bit中断ID写入，MSI ID 超过8bit访问，硬件自动截断低8bit. |
 | setipnum_le_vs5 | 0x5000   | 32   | WO   | 32'h0  | VS 5 interrupt file 访问寄存器。写入数据为MSI 中断ID，读取值为0.默认支持最高8bit中断ID写入，MSI ID 超过8bit访问，硬件自动截断低8bit. |
 
-### 核间中断
+## 核间中断
 
 多核间通信可以通过核间中断来完成，核间中断有两种方式可以实现。