docs: 添加gvisor测例修复指引 (#1541)

- 新增"测例修复指引"章节，详细说明如何修复gvisor系统调用测试用例
- 包含准备工作、测试执行流程、代码修复流程、白名单管理和黑名单管理等内容
- 提供完整工作流示例和注意事项，帮助开发者快速参与系统调用修复工作

Signed-off-by: longjin <longjin@DragonOS.org>

Author: fslongjin

docs/kernel/ktest/gvisor_syscall_test.rst

@@ -21,13 +21,6 @@ gVisor 是 Google 开发的容器运行时沙箱，包含了大量的系统调
 
 执行`make test-syscall`命令。该命令将启动DragonOS并自动执行gvisor syscall测试套件，测试完成后会退出qemu。同时根据测试用例成功率选择是成功返回还是失败返回，成功率不等于100%则失败返回。该命令的执行流程如下：
 
-1. 执行 `toggle_compile_gvisor.sh enable` 注释 `app-blocklist.toml` 中与 gvisor 测试套件相关的屏蔽配置
-2. 编译DragonOS
-3. 写入镜像
-4. 后台qemu无图形模式启动DragonOS，同时设置环境变量`AUTO_TEST`（自动测试选项，目前仅支持syscall测试）和`SYSCALL_TEST_DIR`（测试套所在目录），这两个环境变量会通过命令行参数传递到DragonOS。然后当busybox init进程执行rcS脚本时，该脚本会通过`AUTO_TEST`选项执行对应的测试
-5. 执行`monitor_test_results.sh`定时查看qemu串口输出内容，并根据测试结果选择成功返回还是失败返回
-6. 执行 `toggle_compile_gvisor.sh disable` 取消 `app-blocklist.toml` 中相关配置的注释，恢复默认屏蔽状态
-
 对应的workflow配置文件为`test-x86.yml`
 
 手动测试
@@ -83,6 +76,320 @@ gVisor 是 Google 开发的容器运行时沙箱，包含了大量的系统调
 
 对于每个测试程序，可以通过 ``blocklists/`` 目录下的文件屏蔽特定的测试用例。这对于跳过暂不支持或不稳定的测试非常有用。
 
+测例修复指引
+============
+
+本部分介绍如何修复gvisor测例，帮助开发者快速参与系统调用修复工作。
+
+准备工作
+--------
+
+1. **首次安装测例**
+
+   在开始修复工作前，需要先执行一次 `make test-syscall` 确保测例已安装到DragonOS系统中：
+
+   .. code-block:: bash
+
+      make test-syscall
+
+   该命令会下载测试套件、编译DragonOS、写入镜像并自动运行测试。首次执行后，测例会安装到DragonOS的 ``/opt/tests/gvisor`` 目录。
+
+2. **克隆测例源代码仓库**
+
+   测例的源代码位于gvisor仓库中，需要克隆到本地以便查看和修复：
+
+   .. code-block:: bash
+
+      git clone https://cnb.cool/DragonOS-Community/gvisor.git
+      cd gvisor
+      git checkout dragonos/release-20250616.0
+
+   测例代码位于 ``test/syscalls/linux`` 目录下，使用gtest框架编写，每个系统调用对应一个或多个 ``.cc`` 文件。
+
+测试执行流程
+------------
+
+1. **进入DragonOS系统**
+
+   使用以下命令以无图形模式启动DragonOS：
+
+   .. code-block:: bash
+
+      make run-nographic
+
+2. **执行测试查看报错**
+
+   在DragonOS系统内，切换到测例目录并执行具体的测试程序：
+
+   .. code-block:: bash
+
+      cd /opt/tests/gvisor
+      ./<test_name>
+
+   例如，要测试socket相关的系统调用：
+
+   .. code-block:: bash
+
+      ./socket_test
+
+   执行测试后，会看到测试结果。失败的测试用例会显示详细的错误信息，包括：
+
+   - 失败的测试用例名称
+   - 错误原因（如系统调用返回错误码、行为不符合预期等）
+
+   如果测例卡住（无响应或长时间不返回），需要查看堆栈跟踪信息来定位问题：
+
+   .. code-block:: bash
+
+      # 在DragonOS运行的情况下，新开一个终端窗口
+      # 在DragonOS项目根目录执行
+      make gdb
+
+   在gdb中，首先需要选择对应的vcpu线程，然后查看堆栈跟踪：
+
+   .. code-block:: gdb
+
+      # 查看所有线程
+      info threads
+      
+      # 选择对应的vcpu线程（例如thread 2）
+      thread 2
+      
+      # 查看堆栈跟踪
+      bt
+      
+      # 或者查看完整的堆栈跟踪（包含局部变量）
+      bt full
+
+   **注意**：DragonOS是多核系统，可能有多个vcpu线程。需要根据实际情况选择正确的线程来查看堆栈跟踪。
+
+3. **记录失败的测试用例**
+
+   将失败的测试用例名称、错误信息和堆栈跟踪信息记录下来，这些信息将用于后续的修复工作。
+
+代码修复流程
+------------
+
+1. **复制测例源代码**
+
+   从克隆的gvisor仓库中，找到对应的测例源代码文件（通常是 ``<test_name>.cc``），复制到DragonOS项目根目录：
+
+   .. code-block:: bash
+
+      cp /path/to/gvisor/test/syscalls/linux/<test_name>.cc /path/to/DragonOS/
+
+   例如，修复socket_test：
+
+   .. code-block:: bash
+
+      cp gvisor/test/syscalls/linux/socket_test.cc /home/jinlong/code/DragonOS/
+
+2. **使用AI助手进行修复**
+
+   将复制的 ``.cc`` 文件提供给AI助手（如Cursor的AI功能），并说明：
+
+   - 测试失败的具体错误信息
+   - 要求AI遵循Linux语义来修复测例
+   - DragonOS的系统调用实现特点（参考Linux 6.6语义）
+
+   AI助手会分析代码，识别问题所在，并提供修复建议或直接修复代码。
+
+   一些小建议：
+   
+   - 如果问题较为复杂，我们建议先使用Plan模式制定修复计划，然后再修复。
+   - 如果AI助手难以定位问题，可以让他在内核的适当位置添加少量日志辅助定位
+   - 如果终端日志被截断，可以到serial_opt.txt去查看完整日志，复制给AI助手
+   - 如果AI助手难以定位问题，那么可以让他在`user/apps/c_unitest`下面写简单的测试程序来修复问题。这些测试程序会被编译安装到DragonOS的bin目录下。
+   - 时刻注意提醒AI助手寻找是否有可以复用的代码、建立合理且适当的抽象。不然代码会很冗余！
+
+3. **验证修复效果**
+
+   修复完成后，需要重新编译DragonOS并测试：
+
+   .. code-block:: bash
+
+      # 在DragonOS项目根目录
+      make run-nographic
+
+   然后在DragonOS内再次执行测试，确认修复是否成功。
+
+白名单管理
+----------
+
+修复完成的测例需要添加到白名单中，才能被测试框架执行。
+
+1. **编辑白名单文件**
+
+   打开 ``user/apps/tests/syscall/gvisor/whitelist.txt`` 文件，添加测试程序名称：
+
+   .. code-block:: text
+
+      # 文件系统相关测试
+      open_test
+      stat_test
+      socket_test  # 新添加的测试
+
+2. **白名单格式说明**
+
+   - 每行一个测试程序名称（不带路径和扩展名）
+   - 以 ``#`` 开头的行是注释，会被忽略
+   - 空行会被忽略
+   - 可以按功能分类组织，使用注释分组
+
+3. **注意事项**
+
+   - 测试程序名称必须与可执行文件名完全一致
+   - 添加后需要重新`make test-syscall`才能生效
+   - 建议在添加前先验证测试能够正常运行
+
+黑名单管理
+----------
+
+如果某个测试程序中的部分测试用例暂时无法修复或不需要支持，可以创建blocklist文件来屏蔽这些测试用例。
+
+1. **何时需要创建blocklist**
+
+   - 测试用例依赖DragonOS暂不支持的功能（如IPv6、某些文件系统特性等）
+   - 测试用例存在已知的不稳定性或竞争条件
+   - 测试用例需要特殊权限或环境配置，当前环境无法满足
+
+2. **创建blocklist文件**
+
+   在 ``user/apps/tests/syscall/gvisor/blocklists/`` 目录下创建与测试程序同名的文件：
+
+   .. code-block:: bash
+
+      # 例如，为socket_test创建blocklist
+      touch user/apps/tests/syscall/gvisor/blocklists/socket_test
+
+3. **blocklist文件格式**
+
+   在文件中添加要屏蔽的测试用例名称，每行一个：
+
+   .. code-block:: text
+
+      # 这是注释行，会被忽略
+      
+      # 屏蔽IPv6相关测试
+      SocketTest.IPv6*
+      SocketTest.IPv6Socket*
+      
+      # 屏蔽需要特殊权限的测试
+      SocketTest.PrivilegedSocket
+      
+      # 屏蔽已知不稳定的测试
+      SocketTest.UnimplementedFeature
+
+4. **格式说明**
+
+   - 支持通配符 ``*`` 匹配任意字符
+   - 测试用例名称格式通常为 ``TestSuite.TestCase``
+   - 以 ``#`` 开头的行是注释
+   - 空行会被忽略
+   - **重要**：必须在文件中注明屏蔽原因，方便后续维护
+
+5. **示例**
+
+   查看现有的blocklist文件作为参考：
+
+   - ``user/apps/tests/syscall/gvisor/blocklists/socket_test`` - socket测试的黑名单
+   - ``user/apps/tests/syscall/gvisor/blocklists/epoll_test`` - epoll测试的黑名单
+
+完整工作流示例
+--------------
+
+以下是一个完整的修复流程示例，以修复 ``open_test`` 为例：
+
+1. **准备工作**
+
+   .. code-block:: bash
+
+      # 首次安装测例（如果还没安装）
+      make test-syscall
+      
+      # 克隆测例源代码
+      git clone https://cnb.cool/DragonOS-Community/gvisor.git
+      cd gvisor
+      git checkout dragonos/release-20250616.0
+
+2. **发现问题**
+
+   .. code-block:: bash
+
+      # 进入DragonOS
+      make run-nographic
+      
+      # 在DragonOS内执行测试
+      cd /opt/tests/gvisor
+      ./open_test
+      
+      # 发现部分测试用例失败，记录错误信息
+
+3. **修复代码**
+
+   .. code-block:: bash
+
+      # 复制源代码到DragonOS根目录
+      cp gvisor/test/syscalls/linux/open_test.cc /home/jinlong/code/DragonOS/
+      
+      # 使用AI助手修复（在Cursor中打开文件并提供错误信息）
+      # AI会分析代码并提供修复方案
+
+4. **验证修复**
+
+   .. code-block:: bash
+
+      # 重新编译
+      make kernel
+      make run-nographic
+      
+      # 再次测试
+      cd /opt/tests/gvisor
+      ./open_test
+      
+      # 确认所有测试用例通过
+
+5. **添加到白名单**
+
+   .. code-block:: bash
+
+      # 编辑白名单文件
+      vim user/apps/tests/syscall/gvisor/whitelist.txt
+      
+      # 添加：open_test
+
+6. **处理无法修复的测试用例**
+
+   如果某些测试用例暂时无法修复（如依赖未实现的功能），创建blocklist：
+
+   .. code-block:: bash
+
+      # 创建blocklist文件
+      vim user/apps/tests/syscall/gvisor/blocklists/open_test
+      
+      # 添加内容：
+      # 屏蔽依赖O_TMPFILE的测试（DragonOS暂不支持）
+      OpenTest.Tmpfile*
+      # 原因：O_TMPFILE需要特定的文件系统支持，当前未实现
+
+7. **最终验证**
+
+   .. code-block:: bash
+
+      # 重新编译并运行完整测试套件
+      make test-syscall
+      
+      # 确认open_test能够正常运行，失败的用例已被blocklist屏蔽
+
+注意事项
+--------
+
+- **符合Linux语义**：修复时要确保系统调用行为符合Linux 6.6的语义，不要使用workaround绕过问题
+- **深入分析**：修复前要深入分析问题根源，结合测例代码、DragonOS实现和Linux行为进行对比
+- **测试验证**：每次修复后都要重新测试，确保修复有效且没有引入新的问题
+- **文档记录**：在blocklist中详细记录屏蔽原因，方便后续维护和重新启用
+- **代码质量**：修复后的代码要符合DragonOS的代码规范，运行 ``make fmt`` 进行格式化
+
 更多详细信息
 ==============