Doc: add doc about features

Author: EmbroiderSnow

README.md

@@ -0,0 +1,117 @@
+# RISC-V ISA Simulator
+
+This project is a course assignment for the **Computer Architecture and Organization Lab** at **Peking University** in the **Fall semester of 2025**, developed as an extension of the framework provided by the course.
+
+## ✨ Features
+
+* Implements a majority of the instructions from the RV64IM instruction set.
+* Implements the **`exit`** and **`write`** system calls (with `write` currently supporting output only to **stdout**), and enables the use of **`printf`** within the virtual RISC-V environment.
+* Includes a simple built-in debugger with support for single-stepping, printing registers, and scanning memory.
+* Supports function call tracing (**ftrace**).
+* Supports instruction execution history logging (**itrace**).
+
+```
+.
+├── .github/workflows/    # GitHub CI/CD workflow configurations
+├── build/                # Directory for compiled artifacts
+├── doc/                  # Directory for docs about the implement of some features
+├── sim/                  # Simulator core source code
+│   ├── include/          # Header files
+│   └── src/              # Source files
+├── test/                 # Test cases
+│   ├── include/
+│   ├── lib/        
+│   ├── src/              # Test program source code
+│   └── trm/              # Trap and Run Machine environment
+├── trace/                # Reference trace files for instruction execution
+├── Dockerfile            # Dockerfile for building the development environment
+├── docker-compose.yml    # Docker Compose configuration file
+└── Makefile              # Main project Makefile
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+This project is best built and run using Docker to avoid the complexities of local environment setup.
+
+* [Docker](https://www.docker.com/)
+* [Docker Compose](https://docs.docker.com/compose/)
+
+If you prefer to build locally, you will need to install the RISC-V GNU toolchain and other build tools.
+* `riscv64-unknown-elf-gcc`
+* `make`
+* `gcc`/`g++`
+* lib `llvm` and `libelf`
+
+### Build and Run (Docker)
+
+1.  **Start the Docker container:**
+    This command will build the image and create a container named `simulator_dev` based on `docker-compose.yml`.
+
+    ```bash
+    docker-compose up --build -d
+    ```
+
+2. **Build the project and run all test:**
+
+   ```bash
+   docker-compose exec dev make test_all
+   ```
+
+### Build and Run (Local)
+
+1.  **Install dependencies:**
+    Ensure you have installed all the tools listed in the [Prerequisites](#prerequisites) section.
+
+2.  **Build the project and run all test**
+    Run the `make` command in the project root directory.
+
+    ```bash
+    make test_all
+    ```
+
+## 🎮 Usage
+
+### Running Test Programs
+
+You can run any test program located in the project's root directory. All test programs are compiled into the `test/build` directory.
+
+For example, to run the `quicksort` test:
+```bash
+docker-compose exec dev make T=quicksort
+```
+
+### Debug Mode
+
+Start the simulator in debug mode by the make command below:
+```bash
+docker-compose exec dev make debug T=XXX
+```
+
+In debug mode, you can use the following commands:
+
+- `help`: Print the help message of debug commands
+
+* `si [N]`: Execute a single instruction if `arg N` not provided, or execute N instructions.
+* `c`: Continue execution until the program finishes.
+* `info r`: Print the status of all general-purpose registers (include PC).
+* `x <N> <EXPR>`: Scan `N` 4-byte words of memory starting at address `EXPR`.
+
+### Other Commands
+
+To run the Simulator in `itrace`/`ftrace` mode:
+
+```sh
+docker-compose exec dev make itrace T=XXX
+docker-compose exec dev make ftrace T=XXX
+```
+
+## ✅ Testing
+
+If you want to add your own test cases, place your test source file (`.c` file) in the **`/test/src`** directory.
+ For example, if your test is named **`sample`**, you can run it with the following command:
+
+```bash
+docker-compose exec dev make T=sample
+```

doc/debug.md

@@ -0,0 +1,5 @@
+# debug
+
+The **debug** feature is designed to closely align with the behavior of **GDB**.
+ As anyone who has worked on the **ICS Shell Lab** would know, the debugging functionality is implemented within a **REPL-style framework**.
+ All the commands have been implemented according to the documentation requirements, and you can try them out yourself to see how the debugger performs in action.

doc/ftrace.md

@@ -0,0 +1,11 @@
+# ftrace
+
+The implementation of **ftrace** involves two key components:
+ (1) **loading and parsing the symbol table**, and
+ (2) **identifying `call` and `ret` instructions** — which, unlike in x86, are not represented by explicit opcodes in RISC-V.
+
+I used the **libelf** library to parse the **ELF file’s symbol table** and designed a data structure to store function **(name, address)** tuples. After loading, the addresses are **sorted** to enable efficient lookup during execution.
+
+The **ftrace** implementation is defined in **`sim/include/ftrace.h`** and **`sim/src/ftrace.c`**, where you can check the detailed logic.
+
+Similar to **itrace**, **ftrace** enhances the **debug mode**: the `si` (step instruction) command now supports displaying **which function the current instruction belongs to**, offering improved traceability during debugging.

doc/itrace.md

@@ -0,0 +1,8 @@
+# itrace
+
+Implementing the **itrace** feature is relatively straightforward — the main task is to **disassemble RISC-V machine code**.
+ Initially, I wrote a custom disassembly function, but the documentation suggested that the **LLVM library** could be linked to handle this task. Therefore, I ultimately chose to integrate **LLVM** for the implementation.
+
+This approach has an additional benefit: in **debug mode**, the `si` (step instruction) command can now print the **current instruction being executed**, making debugging much more convenient.
+
+The disassembly implementation is defined in **`sim/include/disasm.h`** and **`sim/src/disasm.c`**.

doc/syscall.md

@@ -0,0 +1,70 @@
+# Syscall
+
+The implementation of system calls involves two key aspects:
+ (1) triggering system calls within the **RISC-V environment**, and
+ (2) handling those system calls inside the **simulator** itself.
+
+Since the provided **RISC-V cross toolchain** targets a **bare-metal environment**, it does not support **glibc** and thus lacks C function definitions for system calls. Therefore, we need to implement them ourselves. In the **`test`** section, I implemented **`syscall.h`** to encapsulate system calls, providing good extensibility for future additions.
+
+```c
+static inline int64_t syscall(int64_t no, int64_t a0, int64_t a1, int64_t a2) {
+    register int64_t a7 asm("a7") = no;
+    register int64_t a0_ asm("a0") = a0;
+    register int64_t a1_ asm("a1") = a1;
+    register int64_t a2_ asm("a2") = a2;
+    asm volatile("ecall"
+                 : "+r"(a0_)
+                 : "r"(a7), "r"(a1_), "r"(a2_)
+                 : "memory");
+    return a0_;
+}
+
+static inline void exit(int64_t code) {
+    syscall(SYSCALL_EXIT, code, 0, 0);
+}
+
+static inline int64_t write(int64_t fd, const void *buf, int64_t count) {
+    return syscall(SYSCALL_WRITE, fd, (int64_t)buf, count);
+}
+```
+
+In the RISC-V environment, system calls are invoked using the **`ecall`** instruction, which differs from the **`trap`** mechanism used in x86. This means that the simulator’s **instruction decoding logic** must handle `ecall` explicitly. Within the `ecall` handler, the simulator interprets the system call according to the **RISC-V ABI specification** and the **system call number**, simulating the corresponding effect on the host machine. (in `sim/src/syscall.c`)
+
+```c
+void handle_syscall(Decode *s) {
+    uint64_t syscall_no = cpu.reg[17]; // a7 register
+    switch (syscall_no) {
+        case SYSCALL_EXIT:
+            printf("Syscall: exit with code %lu\n", cpu.reg[10]); // a0 register
+            halt_trap(s->pc, cpu.reg[10]);
+            break;
+        
+        case SYSCALL_WRITE:
+            {
+                uint64_t fd = cpu.reg[10]; // a0
+                uint64_t buf = cpu.reg[11]; // a1
+                uint64_t count = cpu.reg[12]; // a2
+                if (fd == 1) { // stdout
+                    for (uint64_t i = 0; i < count; i++) {
+                        // printf("Syscall: write byte %02x from addr %016lx\n", mem_read(buf + i, 1), buf + i);
+                        uint8_t byte_to_write = mem_read(buf + i, 1);
+                        putchar(byte_to_write);
+                    }
+                    cpu.reg[10] = count; // return value in a0
+                } else {
+                    printf("Syscall: write to unsupported fd %lu\n", fd);
+                    cpu.reg[10] = -1; // error
+                }
+            }
+            break;
+        
+        default:
+            printf("Unknown syscall: %lu\n", syscall_no);
+            halt_trap(s->pc, -1);
+            break;
+    }
+}
+```
+
+Some system calls involve memory operations, which would require support for **paging**, an **MMU**, and related mechanisms within the simulator. Since that would move the focus toward operating system–level topics—beyond the scope of this course—we only implemented **`exit`** and **`write`**.
+ Other system calls can be easily added by extending the existing framework.