复习C线

Author: KINGFIOX

abstract-machine/.gitignore

@@ -16,4 +16,6 @@ _*
 *~
 build/
 !.gitignore
-.vscode
+.vscode
+!elf-naming.md
+!insert-mainarg.md

abstract-machine/am/src/platform/sim/ioe/gpu.c

@@ -25,9 +25,9 @@ void __am_gpu_config(AM_GPU_CONFIG_T *cfg) {
 void __am_gpu_fbdraw(AM_GPU_FBDRAW_T *ctl) {
   int x = ctl->x, y = ctl->y;  // 绘图的起点坐标 (x, y)
   int w = ctl->w, h = ctl->h;  // 绘图的宽高 (w, h)
-  if (!ctl->sync && (w == 0 || h == 0)) return; // 啥也没干, 直接返回
+  if (!ctl->sync && (w == 0 || h == 0)) { return; } // 啥也没干, 直接返回
   uint32_t *pixels = ctl->pixels; // 绘图的数据
-  if (pixels == NULL && !(w == 0 && h == 0)) return; // 非法数据, 让你绘制图像, 但是没告诉你绘制啥
+  if (pixels == NULL && !(w == 0 && h == 0)) { return; } // 非法数据, 让你绘制图像, 但是没告诉你绘制啥
   uint32_t *fb = (uint32_t *)(uintptr_t)FB_ADDR; // 显存地址
   uint32_t screen_w = inl(VGACTL_ADDR) >> 16; // 屏幕的宽度
   volatile uint32_t *dst = fb + screen_w * y + x; // dst 指向显存

abstract-machine/elf-naming.md

@@ -0,0 +1,68 @@
+# ELF 命名规范
+
+ELF (Executable and Linkable Format) 格式中的常量使用统一的命名前缀。
+
+## 常用前缀
+
+| 前缀 | 全称 | 含义 |
+|------|------|------|
+| `SHF_` | Section Header Flags | Section 的属性标志 |
+| `SHT_` | Section Header Type | Section 的类型 |
+| `PF_` | Program header Flags | Segment 的权限标志 |
+| `PT_` | Program header Type | Segment 的类型 |
+| `ET_` | ELF Type | ELF 文件类型 |
+| `EM_` | ELF Machine | 目标架构 |
+
+## SHF_ (Section Header Flags)
+
+| 标志 | 值 | 含义 |
+|------|---|------|
+| `SHF_WRITE` | 0x1 | 可写 |
+| `SHF_ALLOC` | 0x2 | 运行时需要分配内存 |
+| `SHF_EXECINSTR` | 0x4 | 包含可执行指令 |
+| `SHF_MERGE` | 0x10 | 可合并的数据 |
+| `SHF_STRINGS` | 0x20 | 包含字符串 |
+
+## PF_ (Program Header Flags)
+
+| 标志 | 值 | 含义 |
+|------|---|------|
+| `PF_X` | 0x1 | 可执行 |
+| `PF_W` | 0x2 | 可写 |
+| `PF_R` | 0x4 | 可读 |
+
+## PT_ (Program Header Type)
+
+| 类型 | 值 | 含义 |
+|------|---|------|
+| `PT_NULL` | 0 | 未使用 |
+| `PT_LOAD` | 1 | 可加载段 |
+| `PT_DYNAMIC` | 2 | 动态链接信息 |
+| `PT_INTERP` | 3 | 解释器路径 |
+| `PT_NOTE` | 4 | 辅助信息 |
+| `PT_PHDR` | 6 | Program Header 表自身 |
+
+## ET_ (ELF Type)
+
+| 类型 | 值 | 含义 |
+|------|---|------|
+| `ET_NONE` | 0 | 无类型 |
+| `ET_REL` | 1 | 可重定位文件 (.o) |
+| `ET_EXEC` | 2 | 可执行文件 |
+| `ET_DYN` | 3 | 共享目标文件 (.so) |
+| `ET_CORE` | 4 | Core 文件 |
+
+## EM_ (ELF Machine)
+
+| 类型 | 值 | 含义 |
+|------|---|------|
+| `EM_NONE` | 0 | 无机器类型 |
+| `EM_386` | 3 | Intel 80386 |
+| `EM_ARM` | 40 | ARM |
+| `EM_X86_64` | 62 | AMD x86-64 |
+| `EM_RISCV` | 243 | RISC-V |
+
+## 参考
+
+- 头文件: `/usr/include/elf.h`
+- ELF 规范: [System V ABI](https://refspecs.linuxfoundation.org/elf/elf.pdf)

abstract-machine/insert-mainarg.md

@@ -0,0 +1,120 @@
+# mainargs 传递机制
+
+## 问题一：mainargs 是怎么生成并传递给 AM 的 main 函数的？
+
+这是一个**二进制补丁**技术，整个流程分为三步：
+
+### 1. 编译时：创建占位符
+
+在 `scripts/platform/sim.mk` 中定义了：
+
+```makefile
+MAINARGS_MAX_LEN = 64
+MAINARGS_PLACEHOLDER = the_insert-arg_rule_in_Makefile_will_insert_mainargs_here
+CFLAGS += -DMAINARGS_MAX_LEN=$(MAINARGS_MAX_LEN) -DMAINARGS_PLACEHOLDER=$(MAINARGS_PLACEHOLDER)
+```
+
+然后在 `am/src/platform/sim/trm.c` 中：
+
+```c
+static const char mainargs[MAINARGS_MAX_LEN] = TOSTRING(MAINARGS_PLACEHOLDER);
+```
+
+这里 `mainargs` 被初始化为一个 64 字节的字符数组，内容是那个很长的占位符字符串。
+
+### 2. 链接后：二进制补丁替换
+
+在生成 `.bin` 文件后，`insert-arg` 目标会执行：
+
+```makefile
+insert-arg: image
+	@python3 $(AM_HOME)/tools/insert-arg.py $(IMAGE).bin $(MAINARGS_MAX_LEN) $(MAINARGS_PLACEHOLDER) "$(mainargs)"
+```
+
+`tools/insert-arg.py` 脚本的核心逻辑：
+
+```python
+fp = open(bin, 'r+b')
+data = fp.read()
+idx = data.find(str.encode(placeholder))  # 在二进制中搜索占位符
+fp.seek(idx)
+mainargs_pad = str.encode(mainargs) + ((max_len - len(mainargs)) * str.encode("\0"))  # 补 \0
+fp.write(mainargs_pad)  # 原地替换
+```
+
+它直接在二进制文件中**搜索占位符字符串**，然后用你传入的 `mainargs='xxx'` **原地替换**。
+
+### 3. 运行时：传递给 main
+
+```c
+void _trm_init() {
+  int ret = main(mainargs);
+  halt(ret);
+}
+```
+
+`_trm_init()` 是 AM 的入口函数，它调用 `main(mainargs)`，把这个字符串作为参数传给应用程序。
+
+### 为什么这样设计？
+
+因为**裸机程序没有操作系统**，不存在 shell 来传递 `argc/argv`。这个设计通过：
+1. 编译时预留空间（占位符）
+2. 链接后直接修改二进制
+3. 运行时读取被修改的数据
+
+实现了一种"伪命令行参数"的效果。
+
+---
+
+## 问题二：为什么不会保留之前的 mainargs 状态？
+
+### 现象
+
+```bash
+# 第一次运行
+make run mainargs='riscv32-npc'
+# 输出：mainargs = 'riscv32-npc'.
+
+# 第二次运行（不指定 mainargs）
+make run
+# 输出：mainargs = ''.
+```
+
+既然 `insert-arg.py` 已经把 `riscv32-npc` 写入了二进制文件，为什么第二次运行时 mainargs 变成了空？
+
+### 原因
+
+关键在于 Makefile 的依赖链：
+
+```makefile
+# nemu.mk / npc.mk
+run: insert-arg
+	$(MAKE) -C $(NEMU_HOME) ISA=$(ISA) run ...
+
+# sim.mk
+insert-arg: image
+	@python3 $(AM_HOME)/tools/insert-arg.py $(IMAGE).bin ... "$(mainargs)"
+
+image: image-dep
+	@$(OBJCOPY) -S --set-section-flags .bss=alloc,contents -O binary $(IMAGE).elf $(IMAGE).bin
+```
+
+每次 `make run` 时的完整流程：
+
+1. **`run` 依赖 `insert-arg`**
+2. **`insert-arg` 依赖 `image`**
+3. **`image` 每次都从 `.elf` 重新生成 `.bin`**
+
+所以：
+
+| 运行 | OBJCOPY | insert-arg |
+|------|---------|------------|
+| `make run mainargs='riscv32-npc'` | 从 `.elf` 生成新 `.bin`（包含占位符） | 用 `riscv32-npc` 替换占位符 |
+| `make run` | 从 `.elf` **又重新生成** `.bin`（包含占位符） | 用**空字符串**替换占位符 |
+
+### 关键点
+
+- `.bin` 文件是一个**临时产物**，每次都从 `.elf` 重新生成
+- 之前写入的 `riscv32-npc` 已经被新的 `OBJCOPY` 覆盖掉了
+- `.elf` 里面永远是那个占位符字符串
+- 每次 `OBJCOPY` 后，`.bin` 又恢复成占位符状态，然后再用当前的 `$(mainargs)` 替换

abstract-machine/tools/insert-arg.py

@@ -2,6 +2,13 @@
 
 from sys import argv
 
+#insert-arg: image
+#	@python3 $(AM_HOME)/tools/insert-arg.py $(IMAGE).bin $(MAINARGS_MAX_LEN) $(MAINARGS_PLACEHOLDER) "$(mainargs)"
+# argv[1] = $(IMAGE).bin
+# argv[2] = $(MAINARGS_MAX_LEN)
+# argv[3] = $(MAINARGS_PLACEHOLDER)
+# argv[4] = "$(mainargs)"
+
 bin = argv[1]
 max_len = int(argv[2])
 placeholder = argv[3]
@@ -10,7 +17,7 @@
 if len(mainargs) >= max_len:
     print("Error: mainargs should not be longer than {0} bytes\n".format(max_len))
     exit(1)
-print("mainargs={0}".format(mainargs))
+print(f"mainargs={ format(mainargs) }")
 
 fp = open(bin, 'r+b')
 data = fp.read()

am-kernels

@@ -32,6 +32,8 @@ static uint32_t screen_size() {
 }
 
 static void *vmem = NULL;
+// [0]: { screen_width, screen_height }
+// [1]: sync flag
 static uint32_t *vgactl_port_base = NULL;
 
 #ifdef CONFIG_VGA_SHOW_SCREEN