feat: add .gnu_debuglink support for separate debug files

docs/install.md

@@ -97,6 +97,66 @@ If no `.debug_*` sections are found, the binary must be recompiled with debug sy
 
 **Note**: Without debug symbols, GhostScope cannot resolve function names, variables, or source line information.
 
+#### Separate Debug Files (GNU debuglink)
+
+GhostScope also supports loading debug information from separate debug files using the `.gnu_debuglink` mechanism. This is useful when working with stripped binaries in production environments.
+
+**Check for debuglink section:**
+```bash
+# Check if binary has .gnu_debuglink pointing to a separate debug file
+readelf -x .gnu_debuglink your_program
+
+# Example output:
+# Hex dump of section '.gnu_debuglink':
+#   0x00000000 6d795f70 726f6772 616d2e64 65627567 my_program.debug
+#   0x00000010 00000000 12345678                   ....4Vx
+```
+
+**Create separate debug file for a stripped binary:**
+```bash
+# 1. Extract debug information to a separate file
+objcopy --only-keep-debug your_program your_program.debug
+
+# 2. Strip debug information from the binary
+objcopy --strip-debug your_program
+
+# 3. Add a link from the binary to the debug file
+objcopy --add-gnu-debuglink=your_program.debug your_program
+
+# Verify the debuglink was added
+readelf -x .gnu_debuglink your_program
+```
+
+**Debug file search paths (following GDB conventions):**
+
+GhostScope automatically searches for debug files in the following locations:
+1. Same directory as the binary: `/path/to/your_program.debug`
+2. `.debug` subdirectory: `/path/to/.debug/your_program.debug`
+3. Global debug directory: `/usr/lib/debug/path/to/your_program.debug`
+
+**Installing system debug packages:**
+```bash
+# Ubuntu/Debian - install debug symbols for libc
+sudo apt install libc6-dbg
+
+# Fedora/RHEL - install debug symbols
+sudo dnf debuginfo-install glibc
+
+# The debug files are typically installed in /usr/lib/debug/
+```
+
+**Verification:**
+
+GhostScope will automatically detect and use separate debug files. You can verify this in the logs:
+```bash
+# Run with debug logging to see debuglink resolution
+RUST_LOG=debug sudo ghostscope -p $(pidof your_program)
+
+# Look for messages like:
+# "Looking for debug file 'your_program.debug' for binary '/path/to/your_program'"
+# "Found matching debug file: /path/to/your_program.debug (CRC: 0x12345678)"
+```
+
 ## Troubleshooting
 
 ### Permission Denied Errors

docs/zh/install.md

@@ -97,6 +97,66 @@ readelf -S your_program | grep debug
 
 **注意**：没有调试符号，GhostScope 无法解析函数名、变量或源代码行信息。
 
+#### 独立调试文件（GNU debuglink）
+
+GhostScope 支持使用 `.gnu_debuglink` 机制从独立的调试文件加载调试信息。这在生产环境中处理 stripped 二进制文件时非常有用。
+
+**检查 debuglink 段：**
+```bash
+# 检查二进制文件是否有指向独立调试文件的 .gnu_debuglink
+readelf -x .gnu_debuglink your_program
+
+# 示例输出：
+# Hex dump of section '.gnu_debuglink':
+#   0x00000000 6d795f70 726f6772 616d2e64 65627567 my_program.debug
+#   0x00000010 00000000 12345678                   ....4Vx
+```
+
+**为 stripped 二进制创建独立调试文件：**
+```bash
+# 1. 提取调试信息到独立文件
+objcopy --only-keep-debug your_program your_program.debug
+
+# 2. 从二进制文件中删除调试信息
+objcopy --strip-debug your_program
+
+# 3. 在二进制文件中添加指向调试文件的链接
+objcopy --add-gnu-debuglink=your_program.debug your_program
+
+# 验证 debuglink 已添加
+readelf -x .gnu_debuglink your_program
+```
+
+**调试文件搜索路径（遵循 GDB 约定）：**
+
+GhostScope 会自动在以下位置搜索调试文件：
+1. 二进制文件同目录：`/path/to/your_program.debug`
+2. `.debug` 子目录：`/path/to/.debug/your_program.debug`
+3. 全局调试目录：`/usr/lib/debug/path/to/your_program.debug`
+
+**安装系统调试包：**
+```bash
+# Ubuntu/Debian - 安装 libc 的调试符号
+sudo apt install libc6-dbg
+
+# Fedora/RHEL - 安装调试符号
+sudo dnf debuginfo-install glibc
+
+# 调试文件通常安装在 /usr/lib/debug/ 目录下
+```
+
+**验证：**
+
+GhostScope 会自动检测并使用独立调试文件。你可以通过日志验证：
+```bash
+# 启用调试日志以查看 debuglink 解析过程
+RUST_LOG=debug sudo ghostscope -p $(pidof your_program)
+
+# 查找类似以下的消息：
+# "Looking for debug file 'your_program.debug' for binary '/path/to/your_program'"
+# "Found matching debug file: /path/to/your_program.debug (CRC: 0x12345678)"
+```
+
 ## 故障排除
 
 ### 权限被拒绝错误

ghostscope-dwarf/Cargo.toml

@@ -24,3 +24,6 @@ num_cpus = "1.0"
 # For proc mapping parsing (temporary, will extract from ghostscope-binary)
 libc = "0.2"
 
+# For .gnu_debuglink CRC validation
+crc32fast = "1.4"
+