feat: add @perf_event attach and counter helpers

- switch perf_event attachment to the perf_options builtin struct
- add type checking and userspace codegen for attach, perf_read, and perf_print
- update docs, examples, and tests for the new @perf_event workflow

Author: SiyuanSun0736

BUILTINS.md

@@ -83,13 +83,13 @@ fn main() -> i32 {
 
 ---
 
-#### `attach(handle, target, flags)` / `attach(handle, attr)`
+#### `attach(handle, target, flags)` / `attach(handle, opts, flags)`
 **Signature:** `attach(handle: ProgramHandle, target: str(128), flags: u32) -> u32`
-**Signature:** `attach(handle: ProgramHandle, attr: perf_event_attr) -> u32`
+**Signature:** `attach(handle: ProgramHandle, opts: perf_options, flags: u32) -> u32`
 **Variadic:** No
 **Context:** Userspace only
 
-**Description:** Attach a loaded eBPF program to a target interface or attachment point, or attach it to a perf event described by `perf_event_attr`.
+**Description:** Attach a loaded eBPF program to a target interface or attachment point, or to a perf event counter described by `perf_options`. Both forms take three arguments, keeping a uniform call shape across all program types.
 
 **Parameters:**
 - Standard form:
@@ -98,7 +98,8 @@ fn main() -> i32 {
     - `flags`: Attachment flags (context-dependent)
 - Perf event form:
     - `handle`: Program handle returned from `load()`
-    - `attr`: `perf_event_attr` value describing counter, pid, cpu, period, and filter flags
+    - `opts`: `perf_options` value — only `counter` is required; all other fields have defaults
+    - `flags`: Reserved (pass `0`)
 
 **Return Value:**
 - Returns `0` on success
@@ -112,24 +113,17 @@ if (result != 0) {
     print("Failed to attach program")
 }
 
-var perf_attr = perf_event_attr {
-    counter: branch_misses,
-    pid: -1,
-    cpu: 0,
-    period: 1000000,
-    wakeup: 1,
-    inherit: false,
-    exclude_kernel: false,
-    exclude_user: false
-}
-
+// Minimal perf attach — all non-counter fields use defaults:
+// pid=-1 (all procs), cpu=0, period=1_000_000, wakeup=1, flags=false
 var perf_prog = load(on_branch_miss)
-attach(perf_prog, perf_attr)
+attach(perf_prog, perf_options { counter: branch_misses }, 0)
+var count = perf_read(perf_prog)
+detach(perf_prog)
 ```
 
 **Context-specific implementations:**
 - **eBPF:** Not available
-- **Userspace:** Uses `attach_bpf_program_by_fd` for standard targets and `ks_open_perf_event` for perf events
+- **Userspace:** Uses `attach_bpf_program_by_fd` for standard targets and `ks_attach_perf_event` for perf events
 - **Kernel Module:** Not available
 
 ---
@@ -359,7 +353,7 @@ fn main() -> i32 {
 |----------|------|-----------|---------------|-------|
 | `print()` | ✅ | ✅ | ✅ | Different output destinations |
 | `load()` | ❌ | ✅ | ❌ | Program management only |
-| `attach()` | ❌ | ✅ | ❌ | Standard attach and perf_event_attr attach |
+| `attach()` | ❌ | ✅ | ❌ | Standard attach and perf_options attach |
 | `detach()` | ❌ | ✅ | ❌ | Program management only |
 | `register()` | ❌ | ✅ | ❌ | struct_ops registration |
 | `test()` | ❌ | ✅ | ❌ | Testing framework only |

README.md

@@ -270,7 +270,7 @@ fn main() -> i32 {
 
 ### Hardware Performance Counter Programs
 
-Use `@perf_event` to attach eBPF programs to hardware or software performance counters. The userspace side describes the counter via a `perf_event_attr` struct literal and calls `attach(prog, attr)`:
+Use `@perf_event` to attach eBPF programs to hardware or software performance counters. Only `counter` is required in the `perf_options` struct; all other fields have sensible defaults. Call `attach(prog, perf_options { ... }, 0)` and read back the counter with `perf_read(prog)`:
 
 ```kernelscript
 // eBPF program fires on every hardware branch-miss sample
@@ -280,20 +280,16 @@ fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
 }
 
 fn main() -> i32 {
-    var attr = perf_event_attr {
-        counter: branch_misses,   // hardware counter (see perf_counter enum)
-        pid: -1,                  // all processes
-        cpu: 0,                   // CPU 0
-        period: 1000000,          // sample every 1 million events
-        wakeup: 1,
-        inherit: false,
-        exclude_kernel: false,
-        exclude_user: false
-    }
-
     var prog = load(on_branch_miss)
-    attach(prog, attr)    // opens perf_event_open fd, resets, attaches BPF, enables
-    detach(prog)          // disables counter, destroys BPF link, closes fd
+
+    // Minimal form — defaults: pid=-1 (all procs), cpu=0,
+    // period=1_000_000, wakeup=1, all flags=false
+    attach(prog, perf_options { counter: branch_misses }, 0)
+
+    var count = perf_read(prog)   // read counter via program handle
+    print(count)
+
+    detach(prog)   // disables counter, destroys BPF link, closes fd
     return 0
 }
 ```

SPEC.md

@@ -442,7 +442,7 @@ kernelscript init tracepoint/syscalls/sys_enter_read my_syscall_tracer
 
 #### 3.1.3 Perf Event Programs
 
-`@perf_event` programs attach eBPF logic to hardware or software performance counters via `perf_event_open(2)`. The eBPF function is invoked for every counter sample; the userspace side controls which counter to monitor through a `perf_event_attr` struct literal passed to `attach()`.
+`@perf_event` programs attach eBPF logic to hardware or software performance counters via `perf_event_open(2)`. The eBPF function is invoked for every counter sample; the userspace side controls which counter to monitor through a `perf_options` struct literal passed to the standard 3-argument `attach()`.
 
 **Syntax:**
 ```kernelscript
@@ -458,25 +458,41 @@ The context type is always `*bpf_perf_event_data` (from `vmlinux.h`).
 **Userspace lifecycle:**
 ```kernelscript
 fn main() -> i32 {
-    var attr = perf_event_attr {
-        counter: branch_misses,   // perf_counter enum value
-        pid: -1,                  // -1 = all processes; ≥0 = specific PID
-        cpu: 0,                   // ≥0 = specific CPU; -1 = any CPU (pid must be ≥0)
-        period: 1000000,          // sample after this many events (0 → default 1000000)
-        wakeup: 1,                // wake userspace after N samples  (0 → default 1)
-        inherit: false,           // inherit to forked children
-        exclude_kernel: false,    // exclude kernel-mode samples
-        exclude_user: false       // exclude user-mode samples
-    }
-
     var prog = load(my_handler)
-    attach(prog, attr)   // perf_event_open → IOC_RESET → attach BPF → IOC_ENABLE
-    // ... run workload ...
-    detach(prog)         // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
+
+    // Only counter is required; all other fields use language-level defaults:
+    // pid=-1, cpu=0, period=1_000_000, wakeup=1, inherit/exclude_*=false
+    attach(prog, perf_options { counter: branch_misses }, 0)
+
+    // Override specific fields as needed:
+    attach(prog, perf_options {
+        counter: cache_misses,
+        cpu: 2,
+        period: 500000,
+        exclude_kernel: true,
+    }, 0)
+
+    var count = perf_read(prog)   // read counter value via program handle
+    print(count)
+
+    detach(prog)   // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
     return 0
 }
 ```
 
+**`perf_options` fields and defaults:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `counter` | `perf_counter` | *(required)* | Hardware/software counter |
+| `pid` | `i32` | `-1` | -1 = all processes; ≥0 = specific PID |
+| `cpu` | `i32` | `0` | ≥0 = specific CPU; -1 = any CPU (pid must be ≥0) |
+| `period` | `u64` | `1000000` | Sample after this many events |
+| `wakeup` | `u32` | `1` | Wake userspace after N samples |
+| `inherit` | `bool` | `false` | Inherit to forked children |
+| `exclude_kernel` | `bool` | `false` | Exclude kernel-mode samples |
+| `exclude_user` | `bool` | `false` | Exclude user-mode samples |
+
 **`pid` / `cpu` rules enforced at runtime:**
 
 | `pid` | `cpu` | Meaning |
@@ -500,15 +516,17 @@ fn main() -> i32 {
 | `context_switches` | `PERF_COUNT_SW_CONTEXT_SWITCHES` |
 | `cpu_migrations` | `PERF_COUNT_SW_CPU_MIGRATIONS` |
 
-**Generated C helpers (emitted when `attach(prog, attr)` is used):**
+**Generated C helpers (emitted when `attach(prog, perf_options{...}, flags)` is used):**
 
 | Function | Signature | Description |
 |---|---|---|
-| `ks_open_perf_event` | `int (ks_perf_event_attr)` | Calls `perf_event_open(2)`, returns fd |
+| `ks_open_perf_event` | `int (ks_perf_options)` | Calls `perf_event_open(2)`, returns fd |
+| `ks_attach_perf_event` | `int (int prog_fd, ks_perf_options, int flags)` | Full open-reset-attach-enable lifecycle |
 | `ks_read_perf_count` | `int64_t (int perf_fd)` | Reads current 64-bit counter via `read()` |
-| `ks_print_perf_count` | `void (int perf_fd, const char*)` | Prints `[perf] <name>: <count>` to stdout |
+| `ks_perf_read` | `int64_t (int prog_fd)` | High-level read via program handle |
+| `ks_perf_print` | `void (int prog_fd, const char*)` | Prints `[perf] <name>: <count>` to stdout |
 
-**Attach sequence (compiler-generated):**
+**Attach sequence (compiler-generated, inside `ks_attach_perf_event`):**
 1. `ks_attr.attr.disabled = 1` — open counter without starting it  
 2. `syscall(SYS_perf_event_open, ...)` → `perf_fd`  
 3. `ioctl(perf_fd, PERF_EVENT_IOC_RESET, 0)` — zero the counter  
@@ -521,7 +539,8 @@ fn main() -> i32 {
 3. `close(perf_fd)` — release the kernel perf event  
 
 **Compiler implementation:**
-- Detects `attach(prog, perf_event_attr_value)` call (two-argument form) and emits `ks_open_perf_event` + `attach_bpf_program_by_fd` sequence
+- Detects `attach(prog, perf_options_value, flags)` (three-argument form with `perf_options` second arg) and routes to `ks_attach_perf_event`
+- Exposes omitted `perf_options` fields as language-level defaults (partial struct literal)
 - Validates `pid ≥ -1`, `cpu ≥ -1`, and rejects `pid == -1 && cpu == -1` at runtime
 - Emits `PERF_FLAG_FD_CLOEXEC` for safe fd inheritance
 - BPF program section is `SEC("perf_event")`

examples/perf_branch_miss.ks

@@ -9,20 +9,15 @@ fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
 }
 
 fn main() -> i32 {
-    var attr = perf_event_attr {
-        counter: branch_misses,
-        pid: -1,
-        cpu: 0,
-        period: 1000000,
-        wakeup: 1,
-        inherit: false,
-        exclude_kernel: false,
-        exclude_user: false
-    }
-
     var prog = load(on_branch_miss)
-    attach(prog, attr)
-    detach(prog)
 
+    // Only counter is required; pid, cpu, period, wakeup and flag fields
+    // default to: pid=-1 (all procs), cpu=0, period=1_000_000, wakeup=1,
+    // inherit/exclude_kernel/exclude_user=false.
+    attach(prog, perf_options { counter: branch_misses }, 0)
+
+    perf_print(prog, "branch_misses")
+
+    detach(prog)
     return 0
 }

examples/perf_cache_miss.ks

@@ -0,0 +1,23 @@
+// perf_cache_miss.ks
+// Demonstrates @perf_event program type in KernelScript.
+// The eBPF program runs on every hardware cache-miss event.
+// The userspace side opens the perf event and attaches the BPF program.
+
+@perf_event
+fn on_cache_miss(ctx: *bpf_perf_event_data) -> i32 {
+    return 0
+}
+
+fn main() -> i32 {
+    var prog = load(on_cache_miss)
+
+    // Only counter is required; pid, cpu, period, wakeup and flag fields
+    // default to: pid=-1 (all procs), cpu=0, period=1_000_000, wakeup=1,
+    // inherit/exclude_kernel/exclude_user=false.
+    attach(prog, perf_options { counter: cache_misses,period: 10000000, inherit: true }, 0)
+
+    perf_print(prog, "cache_misses")
+
+    detach(prog)
+    return 0
+}

src/btf_parser.ml

@@ -506,7 +506,7 @@ let generate_kernelscript_source ?extra_param ?include_kfuncs template project_n
     | None -> ""
   in
 
-  (* perf_event programs use a completely different main() with attach(prog, attr) *)
+  (* perf_event programs use a completely different main() with attach(prog, opts, 0) *)
   if template.program_type = "perf_event" then
     sprintf {|%s
 // Generated by KernelScript compiler with direct BTF parsing%s
@@ -519,19 +519,14 @@ let generate_kernelscript_source ?extra_param ?include_kfuncs template project_n
 }
 
 fn main() -> i32 {
-    var attr = perf_event_attr {
-        counter: branch_misses,
-        pid: -1,
-        cpu: 0,
-        period: 1000000,
-        wakeup: 1,
-        inherit: false,
-        exclude_kernel: false,
-        exclude_user: false
-    }
-
     var prog = load(%s)
-    attach(prog, attr)
+
+    // Only counter is required; all other fields default to sensible values.
+    attach(prog, perf_options { counter: branch_misses }, 0)
+
+    var count = perf_read(prog)
+    print(count)
+
     detach(prog)
 
     return 0

src/codegen_common.ml

@@ -43,7 +43,7 @@ let rec ir_type_to_c target = function
        | UserspaceStd -> "char") (* Base type for userspace string - size handled in declaration *)
   | IRPointer (inner_type, _) -> sprintf "%s*" (ir_type_to_c target inner_type)
   | IRArray (inner_type, size, _) -> sprintf "%s[%d]" (ir_type_to_c target inner_type) size
-  | IRStruct ("perf_event_attr", _) -> "ks_perf_event_attr"  (* Avoid conflict with linux/perf_event.h *)
+  | IRStruct ("perf_options", _) -> "ks_perf_options"  (* Namespace KS type away from kernel structs *)
   | IRStruct (name, _) -> sprintf "struct %s" name
   | IREnum (name, _) -> sprintf "enum %s" name
   | IRResult (ok_type, _err_type) -> ir_type_to_c target ok_type (* simplified to ok type *)

src/stdlib.ml

@@ -109,17 +109,17 @@ let validate_register_function arg_types ast_context _pos =
     | _ -> 
         (false, Some "register() requires an impl block argument")
 
-(** Validation function for attach() - accepts either standard 3-arg form or perf 2-arg form *)
+(** Validation function for attach() - accepts standard 3-arg form, and perf_options 3-arg form *)
 let validate_attach_function arg_types _ast_context _pos =
   match arg_types with
   | [ProgramHandle; Str _; (U8|U16|U32|U64|I8|I16|I32|I64)] ->
       (* Standard form: attach(prog, target, flags) *)
       (true, None)
-  | [ProgramHandle; Struct "perf_event_attr"] | [ProgramHandle; UserType "perf_event_attr"] ->
-      (* Perf event form: attach(prog, perf_event_attr) - compiler detects and routes appropriately *)
+  | [ProgramHandle; (Struct "perf_options" | UserType "perf_options"); (U8|U16|U32|U64|I8|I16|I32|I64)] ->
+      (* Perf event form: attach(prog, perf_options { ... }, flags) - uniform 3-arg shape *)
       (true, None)
   | _ ->
-      (false, Some "attach() requires either (handle, target, flags) or (handle, perf_event_attr)")
+      (false, Some "attach() requires (handle, target, flags) — target is a string or perf_options { ... }")
 
 (** Standard library built-in functions *)
 let builtin_functions = [
@@ -147,9 +147,9 @@ let builtin_functions = [
   };
   {
     name = "attach";
-    param_types = []; (* Custom validation handles both standard and perf_event forms *)
+    param_types = []; (* Custom validation handles both standard and perf_options forms *)
     return_type = U32; (* Returns 0 on success *)
-    description = "Attach a loaded eBPF program to a target with flags, or to a perf event counter";
+    description = "Attach a loaded eBPF program to a target with flags; target is a string or perf_options { ... }";
     is_variadic = false;
     ebpf_impl = ""; (* Not available in eBPF context *)
     userspace_impl = "bpf_prog_attach";
@@ -222,6 +222,28 @@ let builtin_functions = [
     kernel_impl = ""; (* Not available in kernel context *)
     validate = Some validate_exec_function;
   };
+  {
+    name = "perf_read";
+    param_types = [ProgramHandle];
+    return_type = I64; (* Raw counter value, or -1 on error *)
+    description = "Read the current hardware/software counter value for a perf_event program";
+    is_variadic = false;
+    ebpf_impl = ""; (* Not available in eBPF context *)
+    userspace_impl = "ks_perf_read";
+    kernel_impl = "";
+    validate = None;
+  };
+  {
+    name = "perf_print";
+    param_types = [ProgramHandle; Str 128];
+    return_type = Void;
+    description = "Print the current counter value for a perf_event program with a label";
+    is_variadic = false;
+    ebpf_impl = ""; (* Not available in eBPF context *)
+    userspace_impl = "ks_perf_print";
+    kernel_impl = "";
+    validate = None;
+  };
 
 ]
 
@@ -300,8 +322,9 @@ let builtin_types = [
     ("cpu_migrations",       Some (Ast.Signed64 8L));
   ], builtin_pos));
 
-  (* perf_event_attr: KernelScript struct for specifying perf event configuration *)
-  TypeDef (StructDef ("perf_event_attr", [
+  (* perf_options: configuration bag for @perf_event programs.
+     Only 'counter' is required; all other fields have language-level defaults. *)
+  TypeDef (StructDef ("perf_options", [
     ("counter",        Enum "perf_counter");
     ("pid",            I32);
     ("cpu",            I32);
@@ -313,6 +336,23 @@ let builtin_types = [
   ], builtin_pos));
 ]
 
+(** Default field values for structs that support partial initialisation.
+    Returns [(field_name, default_literal)] for optional fields only.
+    Required fields (e.g. counter in perf_options) are absent from the list,
+    so the type checker will still error if they are omitted. *)
+let get_struct_field_defaults = function
+  | "perf_options" ->
+      Some [
+        ("pid",            IntLit (Signed64 (-1L),      None));
+        ("cpu",            IntLit (Signed64 0L,         None));
+        ("period",         IntLit (Unsigned64 1000000L, None));
+        ("wakeup",         IntLit (Unsigned64 1L,       None));
+        ("inherit",        BoolLit false);
+        ("exclude_kernel", BoolLit false);
+        ("exclude_user",   BoolLit false);
+      ]
+  | _ -> None
+
 (** Get all builtin type definitions *)
 let get_builtin_types () = builtin_types