Add first-class perf attachments with generic read support

Introduce PerfAttachment as the return value for perf_event attach calls,
allowing multiple perf attachments to coexist for the same loaded program.
Lower read(attachment) to attachment-specific perf counter reads and support
detach(attachment) separately from detach(program).

Update perf attach bookkeeping to track attachment ids, preserve per-attachment
perf fds, and emit more specific attach/detach status messages including the
event config. Also add skeleton cleanup registration so generated userspace
programs destroy the libbpf skeleton on exit.

Refresh docs, examples, and tests for the new read()/PerfAttachment API.

Author: SiyuanSun0736

BUILTINS.md

@@ -85,7 +85,7 @@ fn main() -> i32 {
 
 #### `attach(handle, target, flags)` / `attach(handle, opts, flags)`
 **Signature:** `attach(handle: ProgramHandle, target: str(128), flags: u32) -> u32`
-**Signature:** `attach(handle: ProgramHandle, opts: perf_options, flags: u32) -> u32`
+**Signature:** `attach(handle: ProgramHandle, opts: perf_options, flags: u32) -> PerfAttachment`
 **Variadic:** No
 **Context:** Userspace only
 
@@ -102,8 +102,8 @@ fn main() -> i32 {
     - `flags`: Reserved (pass `0`)
 
 **Return Value:**
-- Returns `0` on success
-- Returns error code on failure
+- Standard form returns `0` on success and an error code on failure
+- Perf event form returns a `PerfAttachment` value with the open counter/link identity
 
 **Examples:**
 ```kernelscript
@@ -116,7 +116,9 @@ if (result != 0) {
 // Minimal perf attach — all non-perf_type/perf_config 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_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+var perf_att = attach(perf_prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+var count = read(perf_att)
+detach(perf_att)
 detach(perf_prog)
 ```
 
@@ -129,13 +131,14 @@ detach(perf_prog)
 
 #### `detach(handle)`
 **Signature:** `detach(handle: ProgramHandle) -> void`
+**Signature:** `detach(handle: PerfAttachment) -> void`
 **Variadic:** No
 **Context:** Userspace only
 
-**Description:** Detach a loaded eBPF program from its current attachment point.
+**Description:** Detach a loaded eBPF program from its current attachment point, or tear down one perf attachment.
 
 **Parameters:**
-- `handle`: Program handle returned from `load()`
+- `handle`: Program handle returned from `load()`, or a `PerfAttachment` returned from perf `attach()`
 
 **Return Value:**
 - No return value (void)
@@ -150,11 +153,27 @@ detach(prog)  // Clean up
 
 **Context-specific implementations:**
 - **eBPF:** Not available
-- **Userspace:** Uses `detach_bpf_program_by_fd` function
+- **Userspace:** Uses `detach_bpf_program_by_fd` for program handles and `ks_detach_perf_attachment` for perf attachments
 - **Kernel Module:** Not available
 
 ---
 
+#### `read(handle)`
+**Signature:** `read(handle: PerfAttachment) -> i64`
+**Variadic:** No
+**Context:** Userspace only
+
+**Description:** Read the current hardware/software counter value from a perf attachment.
+
+**Parameters:**
+- `handle`: Perf attachment returned from `attach(handle, perf_options, flags)`
+
+**Return Value:**
+- Returns the raw 64-bit counter value on success
+- Returns `-1` on error
+
+---
+
 ### 3. Struct Operations (struct_ops)
 
 #### `register(impl_instance)`
@@ -405,4 +424,4 @@ if (result != 0) {
 ## See Also
 
 - **SPEC.md**: Language specification and features
-- **examples/**: Example programs demonstrating builtin function usage
+- **examples/**: Example programs demonstrating builtin function usage

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. `perf_options` keeps the kernel's tagged `perf_type + perf_config` model, so adding new perf event families does not require flattening everything into one enum. Only `perf_type` and `perf_config` are required; all other fields have sensible defaults. If you need the current count in userspace, call `perf_read(prog)` after `attach(...)`:
+Use `@perf_event` to attach eBPF programs to hardware or software performance counters. `perf_options` keeps the kernel's tagged `perf_type + perf_config` model, so adding new perf event families does not require flattening everything into one enum. Only `perf_type` and `perf_config` are required; all other fields have sensible defaults. Perf attaches return a first-class attachment value, so if you need the current count in userspace, call `read(att)`:
 
 ```kernelscript
 // eBPF program fires on every hardware branch-miss sample
@@ -284,11 +284,12 @@ fn main() -> i32 {
 
     // Minimal form — defaults: pid=-1 (all procs), cpu=0,
     // period=1_000_000, wakeup=1, all flags=false
-    attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
-    var count = perf_read(prog)
+    var att = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+    var count = read(att)
     print("branch misses: %lld", count)
 
-    detach(prog)   // disables counter, destroys BPF link, closes fd
+    detach(att)    // disables counter, destroys BPF link, closes fd
+    detach(prog)   // safe cleanup for the loaded program handle
     return 0
 }
 ```

SPEC.md

@@ -462,21 +462,22 @@ fn main() -> i32 {
 
     // Only perf_type + perf_config are 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 { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+    var misses = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
 
     // Override specific fields as needed:
-    attach(prog, perf_options {
+    var cache = attach(prog, perf_options {
         perf_type: perf_type_hardware,
         perf_config: cache_misses,
         cpu: 2,
         period: 500000,
         exclude_kernel: true,
     }, 0)
 
-    var count = perf_read(prog)
-    print("count: %lld", count)
+    print("misses=%lld cache=%lld", read(misses), read(cache))
 
-    detach(prog)   // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
+    detach(cache)  // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
+    detach(misses)
+    detach(prog)
     return 0
 }
 ```
@@ -536,9 +537,9 @@ For event families with a richer config space, such as `perf_type_hw_cache`, pro
 | Function | Signature | Description |
 |---|---|---|
 | `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_attach_perf_event` | `PerfAttachment (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_perf_read` | `int64_t (int prog_fd)` | High-level read via program handle |
+| `ks_perf_attachment_read` | `int64_t (PerfAttachment)` | High-level read via attachment value |
 
 **Attach sequence (compiler-generated, inside `ks_attach_perf_event`):**
 1. `ks_attr.attr.disabled = 1` — open counter without starting it  
@@ -554,6 +555,7 @@ For event families with a richer config space, such as `perf_type_hw_cache`, pro
 
 **Compiler implementation:**
 - Detects `attach(prog, perf_options_value, flags)` (three-argument form with `perf_options` second arg) and routes to `ks_attach_perf_event`
+- Returns a first-class `PerfAttachment` value for perf attaches so one program can hold multiple live counters
 - 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

examples/perf_cache_miss.ks

@@ -14,12 +14,17 @@ fn main() -> i32 {
     // Only perf_type + perf_config are 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 { perf_type: perf_type_hardware, perf_config: cache_misses, period: 10000000, inherit: true }, 0)
-    print("Cache-miss perf_event demo attached")
-    var count = perf_read(prog)
-    print("Cache-miss count: %lld", count)
+    var cache = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: cache_misses, period: 10000000, inherit: true }, 0)
+    var branch = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses, period: 10000000, inherit: true }, 0)
+    print("Cache-miss and branch-miss perf_event demo attached")
+    var cache_count = read(cache)
+    print("Cache-miss count: %lld", cache_count)
+    var branch_count = read(branch)
+    print("Branch-miss count: %lld", branch_count)
 
+    detach(cache)
+    detach(branch)
     detach(prog)
-    print("Cache-miss perf_event demo detached")
+    print("Cache-miss and branch-miss perf_event demo detached")
     return 0
 }

examples/perf_page_fault.ks

@@ -14,7 +14,7 @@ fn main() -> i32 {
     // pid: 0 = current process, cpu: -1 = any CPU (standard per-process monitoring).
     // page_faults (PERF_COUNT_SW_PAGE_FAULTS) is the most reliable software event:
     // every heap/stack allocation triggers minor page faults, no scheduler dependency.
-    attach(prog, perf_options { perf_type: perf_type_software, perf_config: page_faults, pid: 0, cpu: -1, period: 1 }, 0)
+    var att = attach(prog, perf_options { perf_type: perf_type_software, perf_config: page_faults, pid: 0, cpu: -1, period: 1 }, 0)
     print("Page-fault perf_event demo attached")
 
     // Repeatedly increment a counter; stack/heap activity will generate page faults.
@@ -23,10 +23,11 @@ fn main() -> i32 {
         x = x + 1
     }
 
-    var count = perf_read(prog)
+    var count = read(att)
     print("Page-fault count: %lld", count)
 
-    detach(prog)
+    detach(att)
     print("Page-fault perf_event demo detached")
+    detach(prog)
     return 0
 }

src/btf_parser.ml

@@ -522,8 +522,9 @@ fn main() -> i32 {
     var prog = load(%s)
 
     // perf_type + perf_config are required; all other fields default to sensible values.
-    attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+    var att = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
 
+    detach(att)
     detach(prog)
 
     return 0

src/stdlib.ml

@@ -121,6 +121,24 @@ let validate_attach_function arg_types _ast_context _pos =
   | _ ->
       (false, Some "attach() requires (handle, target, flags) — target is a string or perf_options { ... }")
 
+(** Validation function for read() - currently only accepts perf attachment values *)
+let validate_read_function arg_types _ast_context _pos =
+  match arg_types with
+  | [Struct "PerfAttachment"] | [UserType "PerfAttachment"] ->
+      (true, None)
+  | _ ->
+      (false, Some "read() currently requires a PerfAttachment")
+
+(** Validation function for detach() - accepts program handles and perf attachments *)
+let validate_detach_function arg_types _ast_context _pos =
+  match arg_types with
+  | [ProgramHandle]
+  | [Struct "PerfAttachment"]
+  | [UserType "PerfAttachment"] ->
+      (true, None)
+  | _ ->
+      (false, Some "detach() requires a ProgramHandle or PerfAttachment")
+
 (** Standard library built-in functions *)
 let builtin_functions = [
   {
@@ -158,14 +176,14 @@ let builtin_functions = [
   };
   {
     name = "detach";
-    param_types = [ProgramHandle]; (* program handle only *)
+    param_types = []; (* Custom validation handles program handles and perf attachments *)
     return_type = Void; (* void - no return value *)
-    description = "Detach a loaded eBPF program from its current attachment";
+    description = "Detach a loaded eBPF program or perf attachment from its current attachment";
     is_variadic = false;
     ebpf_impl = ""; (* Not available in eBPF context *)
     userspace_impl = "detach_bpf_program_by_fd";
     kernel_impl = "";
-    validate = None;
+    validate = Some validate_detach_function;
   };
   {
     name = "register";
@@ -223,15 +241,15 @@ let builtin_functions = [
     validate = Some validate_exec_function;
   };
   {
-    name = "perf_read";
-    param_types = [ProgramHandle];
+    name = "read";
+    param_types = []; (* Custom validation handles attachment-aware overloads *)
     return_type = I64; (* Raw counter value, or -1 on error *)
-    description = "Read the current hardware/software counter value for a perf_event program";
+    description = "Read the current hardware/software counter value for a perf attachment";
     is_variadic = false;
     ebpf_impl = ""; (* Not available in eBPF context *)
-    userspace_impl = "ks_perf_read";
+    userspace_impl = "ks_perf_attachment_read";
     kernel_impl = "";
-    validate = None;
+    validate = Some validate_read_function;
   };
 ]
 
@@ -337,6 +355,13 @@ let builtin_types = [
     ("exclude_kernel", Bool);
     ("exclude_user",   Bool);
   ], builtin_pos));
+
+  (* PerfAttachment: first-class userspace handle returned by perf_event attach(). *)
+  TypeDef (StructDef ("PerfAttachment", [
+    ("perf_fd", I32);
+    ("link_id", I32);
+    ("prog_fd", I32);
+  ], builtin_pos));
 ]
 
 (** Default field values for structs that support partial initialisation.
@@ -392,4 +417,4 @@ let format_function_args context_type args =
       (* For userspace, printf can handle more flexible formatting *)
       (match args with
        | [] -> ["\"\\n\""] (* Empty print with newline *)
-       | _ -> args) (* Pass arguments as-is *) 
+       | _ -> args) (* Pass arguments as-is *) 

src/type_checker.ml

@@ -321,6 +321,11 @@ let rec unify_types t1 t2 =
       (match unify_types t1 t2 with
        | Some unified -> Some (Pointer unified)
        | None -> None)
+
+  (* Named structs and user types unify when they refer to the same type name. *)
+  | Struct name1, UserType name2
+  | UserType name1, Struct name2 when name1 = name2 ->
+      Some (Struct name1)
 
   (* Result types *)
   | Result (ok1, err1), Result (ok2, err2) ->
@@ -394,6 +399,17 @@ let can_assign to_type from_type =
             | Some _ -> true
             | None -> false))
 
+let builtin_return_type_for_call name arg_types default_return_type =
+  match name, arg_types with
+  | "attach", [ProgramHandle; (Struct "perf_options" | UserType "perf_options"); _] ->
+      Struct "PerfAttachment"
+  | "detach", _ ->
+      Void
+  | "read", _ ->
+      I64
+  | _ ->
+      default_return_type
+
 
 
 (** Helper function to get the type of a literal *)
@@ -642,7 +658,8 @@ let type_check_builtin_call ctx name typed_args arg_types pos =
               | None -> type_error ("Validation failed for function: " ^ name) pos)
            else
              (* Validation passed - accept any number of arguments *)
-             Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = return_type; texpr_pos = pos }
+             let actual_return_type = builtin_return_type_for_call name arg_types return_type in
+             Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = actual_return_type; texpr_pos = pos }
          | Some _ ->
              (* Check if this function has custom validation *)
              let (validation_ok, validation_error) = Stdlib.validate_builtin_call name arg_types ctx.ast_context pos in
@@ -655,11 +672,13 @@ let type_check_builtin_call ctx name typed_args arg_types pos =
                 (* Skip standard type checking if param_types is empty (custom validation handles it) *)
                 if List.length expected_params = 0 then
                   (* Custom validation handled type checking *)
-                  Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = return_type; texpr_pos = pos }
+                  let actual_return_type = builtin_return_type_for_call name arg_types return_type in
+                  Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = actual_return_type; texpr_pos = pos }
                 else if List.length expected_params = List.length arg_types then
                   let unified = List.map2 unify_types expected_params arg_types in
                   if List.for_all (function Some _ -> true | None -> false) unified then
-                    Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = return_type; texpr_pos = pos }
+                    let actual_return_type = builtin_return_type_for_call name arg_types return_type in
+                    Some { texpr_desc = TCall (make_typed_identifier name pos, typed_args); texpr_type = actual_return_type; texpr_pos = pos }
                   else
                     type_error ("Type mismatch in function call: " ^ name) pos
                 else
@@ -3463,4 +3482,3 @@ and populate_multi_program_context ast multi_prog_analysis =
           ) ast
 
 
-