feat: support special variables

Author: swananan

docs/scripting.md

@@ -457,27 +457,29 @@ trace globals_program.c:32 {
 ```
 ```
 
-### Special Variables (In Progress)
+### Special Variables
 
-Special variables start with `$` and provide access to runtime information:
+Special variables start with `$` and expose runtime info from the kernel.
 
-```ghostscope
-// Function arguments (x86_64 calling convention)
-$arg0, $arg1, $arg2, $arg3, $arg4, $arg5
+Supported now:
+
+- `$pid` — current process ID (tgid), from `bpf_get_current_pid_tgid` lower 32 bits.
+- `$tid` — current thread ID, from `bpf_get_current_pid_tgid` upper 32 bits.
+- `$timestamp` — monotonic timestamp in nanoseconds, from `bpf_ktime_get_ns`.
 
-// Process information
-$pid    // Process ID
-$tid    // Thread ID
-$comm   // Process name
+All behave as integers and can be used in comparisons and arithmetic.
 
-// Return value (in return probes)
-$retval
+Examples
 
-// CPU registers (architecture-specific)
-$pc     // Program counter
-$sp     // Stack pointer
+```ghostscope
+trace sample.c:42 {
+    if $pid == 12345 { print "match"; }
+    print "PID:{} TID:{} TS:{}", $pid, $tid, $timestamp;
+}
 ```
 
+Note: Only `$pid`, `$tid` and `$timestamp` are supported at present. Additional register-related specials may be added later.
+
 ### Variable Lookup Order
 
 When a variable is encountered in a script, GhostScope searches in this order:
@@ -510,25 +512,12 @@ trace main {
 }
 ```
 
-### Monitoring Function Arguments
-
-```ghostscope
-trace calculate {
-    print "calculate({}, {})", $arg0, $arg1;
-
-    if $arg0 > 1000 {
-        print "Large input detected";
-        bt;
-    }
-}
-```
-
 ### Conditional Tracing
 
 ```ghostscope
 trace malloc {
-    if $arg0 > 1048576 {  // 1 MB
-        print "Large allocation: {} bytes", $arg0;
+    if size > 1048576 {  // 1 MB
+        print "Large allocation: {} bytes", size;
         backtrace;
     }
 }

docs/zh/scripting.md

@@ -174,27 +174,29 @@ print arr[0].name;
 - 目前“局部变量、参数、全局变量”均已支持自动解引用（无需显式 `*ptr`，也不需要 `->`，统一使用 `.`，在安全范围内会自动加载并解引用指针值，类似于 Rust 的自动解引用）。
 - 数组访问：已支持顶层 `arr[常量]` 与“链尾”`a.b.c[常量]`。暂不支持：链中间索引（如 `a.b[2].c`）、动态下标（`arr[i]`）和多维数组。
 
-### 特殊变量（实现中）
+### 特殊变量
 
-特殊变量以 `$` 开头，提供运行时信息访问：
+特殊变量以 `$` 开头，提供运行时信息访问。
 
-```ghostscope
-// 函数参数（x86_64 调用约定）
-$arg0, $arg1, $arg2, $arg3, $arg4, $arg5
+当前已支持：
+
+- `$pid` — 当前进程 ID（tgid），来自 `bpf_get_current_pid_tgid` 的低 32 位。
+- `$tid` — 当前线程 ID（tid），来自 `bpf_get_current_pid_tgid` 的高 32 位。
+- `$timestamp` — 单调时间戳（纳秒），来自 `bpf_ktime_get_ns`。
 
-// 进程信息
-$pid    // 进程 ID
-$tid    // 线程 ID
-$comm   // 进程名称
+以上均作为整数参与比较与计算。
 
-// 返回值（在返回探针中）
-$retval
+示例
 
-// CPU 寄存器（架构特定）
-$pc     // 程序计数器
-$sp     // 栈指针
+```ghostscope
+trace sample.c:42 {
+    if $pid == 12345 { print "match"; }
+    print "PID:{} TID:{} TS:{}", $pid, $tid, $timestamp;
+}
 ```
 
+提示：目前仅支持 `$pid`、`$tid`、`$timestamp`。后续可能按需加入“寄存器相关”的特殊变量。
+
 ### 变量查找顺序
 
 当脚本中遇到变量时，GhostScope 按以下顺序查找：
@@ -511,25 +513,12 @@ trace main {
 }
 ```
 
-### 监控函数参数
-
-```ghostscope
-trace calculate {
-    print "calculate({}, {})", $arg0, $arg1;
-
-    if $arg0 > 1000 {
-        print "检测到大输入";
-        bt;
-    }
-}
-```
-
 ### 条件追踪
 
 ```ghostscope
 trace malloc {
-    if $arg0 > 1048576 {  // 1 MB
-        print "大内存分配: {} 字节", $arg0;
+    if size > 1048576 {  // 1 MB
+        print "大内存分配: {} 字节", size;
         backtrace;
     }
 }

ghostscope-compiler/src/ebpf/expression.rs

@@ -543,7 +543,11 @@ impl<'ctx> EbpfContext<'ctx> {
                 );
                 self.compile_dwarf_expression(expr)
             }
-            Expr::SpecialVar(name) => self.handle_special_variable(name),
+            Expr::SpecialVar(name) => {
+                // Accept both "$pid" and "pid" forms from the parser
+                let sanitized = name.trim_start_matches('$');
+                self.handle_special_variable(sanitized)
+            }
             Expr::BuiltinCall { name, args } => match name.as_str() {
                 "memcmp" => {
                     if args.len() != 3 {
@@ -850,10 +854,13 @@ impl<'ctx> EbpfContext<'ctx> {
                 let ts = self.get_current_timestamp()?;
                 Ok(ts.into())
             }
-            _ => Err(CodeGenError::NotImplemented(format!(
-                "Special variable ${} not implemented",
-                name
-            ))),
+            _ => {
+                let supported = ["$pid", "$tid", "$timestamp"].join(", ");
+                Err(CodeGenError::NotImplemented(format!(
+                    "Unknown special variable '${}'. Supported: {}",
+                    name, supported
+                )))
+            }
         }
     }
 

ghostscope/tests/complex_types_execution.rs

@@ -515,6 +515,44 @@ trace complex_types_program.c:25 {
     Ok(())
 }
 
+#[tokio::test]
+async fn test_special_vars_pid_tid_timestamp_complex() -> anyhow::Result<()> {
+    init();
+
+    // Build and start complex_types_program (Debug)
+    let binary_path =
+        FIXTURES.get_test_binary_with_opt("complex_types_program", OptimizationLevel::Debug)?;
+    let mut prog = Command::new(&binary_path)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()?;
+    let pid = prog
+        .id()
+        .ok_or_else(|| anyhow::anyhow!("Failed to get PID"))?;
+    tokio::time::sleep(Duration::from_millis(500)).await;
+
+    let script = format!(
+        "trace complex_types_program.c:25 {{\n    print \"PID={} TID={} TS={}\", $pid, $tid, $timestamp;\n    if $pid == {} {{ print \"PID_OK\"; }}\n}}\n",
+        "{}", "{}", "{}", pid
+    );
+
+    let (exit_code, stdout, stderr) = run_ghostscope_with_script_for_pid(&script, 3, pid).await?;
+    let _ = prog.kill().await;
+    assert_eq!(exit_code, 0, "stderr={} stdout={}", stderr, stdout);
+    assert!(
+        stdout.contains("PID_OK"),
+        "Expected PID_OK. STDOUT: {}",
+        stdout
+    );
+    assert!(
+        stdout.contains("PID=") || stdout.contains("PID:"),
+        "Expected PID field in output. STDOUT: {}",
+        stdout
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn test_if_else_if_and_bare_expr_local() -> anyhow::Result<()> {
     init();

ghostscope/tests/globals_execution.rs

@@ -320,6 +320,44 @@ async fn run_ghostscope_with_script_for_target(
     Ok((exit_code, stdout_content, stderr_content))
 }
 
+#[tokio::test]
+async fn test_special_vars_pid_tid_timestamp_globals() -> anyhow::Result<()> {
+    init();
+
+    let binary_path = FIXTURES.get_test_binary("globals_program")?;
+    let bin_dir = binary_path.parent().unwrap().to_path_buf();
+    let mut prog = Command::new(&binary_path)
+        .current_dir(&bin_dir)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()?;
+    let pid = prog
+        .id()
+        .ok_or_else(|| anyhow::anyhow!("Failed to get PID"))?;
+    tokio::time::sleep(Duration::from_millis(500)).await;
+
+    let script = format!(
+        "trace globals_program.c:32 {{\n    print \"PID={} TID={} TS={}\", $pid, $tid, $timestamp;\n    if $pid == {} {{ print \"PID_EQ\"; }}\n}}\n",
+        "{}", "{}", "{}", pid
+    );
+
+    let (exit_code, stdout, stderr) = run_ghostscope_with_script_for_pid(&script, 3, pid).await?;
+    let _ = prog.kill().await;
+    assert_eq!(exit_code, 0, "stderr={} stdout={}", stderr, stdout);
+    assert!(
+        stdout.contains("PID_EQ"),
+        "Expected PID_EQ. STDOUT: {}",
+        stdout
+    );
+    assert!(
+        stdout.contains("PID=") || stdout.contains("PID:"),
+        "Expected PID print. STDOUT: {}",
+        stdout
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn test_trace_address_with_target_shared_library() -> anyhow::Result<()> {
     // Verify address tracing works when session is started with -t <libgvars.so>

ghostscope/tests/script_execution.rs

@@ -174,6 +174,60 @@ pub async fn cleanup_global_test_process() -> anyhow::Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn test_special_pid_in_if_condition() -> anyhow::Result<()> {
+    init();
+    ensure_global_cleanup_registered();
+
+    let opt_level = OptimizationLevel::Debug;
+    let test_pid = get_global_test_pid_with_opt(opt_level).await?;
+
+    // Use $pid in an expression: it should equal the traced process PID
+    let script_content = format!(
+        "trace sample_program.c:16 {{\n    if $pid == {} {{ print \"PID_OK\"; }} else {{ print \"PID_BAD\"; }}\n}}\n",
+        test_pid
+    );
+
+    let (exit_code, stdout, stderr) =
+        run_ghostscope_with_script_opt(&script_content, 3, opt_level).await?;
+
+    assert_eq!(exit_code, 0, "stderr={}", stderr);
+    assert!(
+        stdout.contains("PID_OK"),
+        "Expected PID_OK in output. STDOUT: {}",
+        stdout
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn test_special_tid_and_timestamp_print() -> anyhow::Result<()> {
+    init();
+    ensure_global_cleanup_registered();
+
+    let opt_level = OptimizationLevel::Debug;
+    let _ = get_global_test_pid_with_opt(opt_level).await?;
+
+    // Just print them to ensure they compile, evaluate and render
+    let script_content = r#"
+trace sample_program.c:16 {
+    print "TST:{} {}", $tid, $timestamp;
+}
+"#;
+
+    let (exit_code, stdout, stderr) =
+        run_ghostscope_with_script_opt(script_content, 3, opt_level).await?;
+
+    assert_eq!(exit_code, 0, "stderr={}", stderr);
+    assert!(
+        stdout.contains("TST:"),
+        "Expected TST: with tid/timestamp in output. STDOUT: {}",
+        stdout
+    );
+    Ok(())
+}
+
 // Global cleanup registration - only runs once when the first test calls it
 static GLOBAL_CLEANUP_REGISTERED: Once = Once::new();