Refactor perf_event handling in KernelScript

- Updated the `perf_options` structure to require `perf_type` and `perf_config` instead of the previous `counter` field.
- Modified examples and tests to reflect the new `perf_type` and `perf_config` usage.
- Removed the `perf_print` function and its references, as it is no longer necessary with the new `perf_read` implementation.
- Enhanced the `ks_open_perf_event` and `ks_perf_read` functions to directly utilize the new `perf_type` and `perf_config` fields.
- Updated documentation in `SPEC.md` to clarify the changes in the `perf_options` structure and the new enums for `perf_type` and `perf_config`.
- Adjusted tests to ensure proper generation of helper functions based on the new `perf_event` API.

Co-authored-by: Copilot <copilot@github.com>

Author: SiyuanSun0736

BUILTINS.md

@@ -98,7 +98,7 @@ fn main() -> i32 {
     - `flags`: Attachment flags (context-dependent)
 - Perf event form:
     - `handle`: Program handle returned from `load()`
-    - `opts`: `perf_options` value — only `counter` is required; all other fields have defaults
+    - `opts`: `perf_options` value — only `perf_type` and `perf_config` are required; all other fields have defaults
     - `flags`: Reserved (pass `0`)
 
 **Return Value:**
@@ -113,11 +113,10 @@ if (result != 0) {
     print("Failed to attach program")
 }
 
-// Minimal perf attach — all non-counter fields use defaults:
+// 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 { counter: branch_misses }, 0)
-var count = perf_read(perf_prog)
+attach(perf_prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
 detach(perf_prog)
 ```
 

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. 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)`:
+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(...)`:
 
 ```kernelscript
 // eBPF program fires on every hardware branch-miss sample
@@ -284,29 +284,41 @@ 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 { counter: branch_misses }, 0)
-
-    var count = perf_read(prog)   // read counter via program handle
-    print(count)
+    attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+    var count = perf_read(prog)
+    print("branch misses: %lld", count)
 
     detach(prog)   // disables counter, destroys BPF link, closes fd
     return 0
 }
 ```
 
-**Available `perf_counter` values:**
+**Available `perf_type` values:**
 
 | Enum value | Hardware/software event |
 |---|---|
-| `cpu_cycles` | `PERF_COUNT_HW_CPU_CYCLES` |
-| `instructions` | `PERF_COUNT_HW_INSTRUCTIONS` |
-| `cache_references` | `PERF_COUNT_HW_CACHE_REFERENCES` |
-| `cache_misses` | `PERF_COUNT_HW_CACHE_MISSES` |
-| `branch_instructions` | `PERF_COUNT_HW_BRANCH_INSTRUCTIONS` |
-| `branch_misses` | `PERF_COUNT_HW_BRANCH_MISSES` |
-| `page_faults` | `PERF_COUNT_SW_PAGE_FAULTS` |
-| `context_switches` | `PERF_COUNT_SW_CONTEXT_SWITCHES` |
-| `cpu_migrations` | `PERF_COUNT_SW_CPU_MIGRATIONS` |
+| `perf_type_hardware` | `PERF_TYPE_HARDWARE` |
+| `perf_type_software` | `PERF_TYPE_SOFTWARE` |
+| `perf_type_tracepoint` | `PERF_TYPE_TRACEPOINT` |
+| `perf_type_hw_cache` | `PERF_TYPE_HW_CACHE` |
+| `perf_type_raw` | `PERF_TYPE_RAW` |
+| `perf_type_breakpoint` | `PERF_TYPE_BREAKPOINT` |
+
+**Common `perf_config` constants:**
+
+| Constant | Intended `perf_type` | Linux config |
+|---|---|---|
+| `cpu_cycles` | `perf_type_hardware` | `PERF_COUNT_HW_CPU_CYCLES` |
+| `instructions` | `perf_type_hardware` | `PERF_COUNT_HW_INSTRUCTIONS` |
+| `cache_references` | `perf_type_hardware` | `PERF_COUNT_HW_CACHE_REFERENCES` |
+| `cache_misses` | `perf_type_hardware` | `PERF_COUNT_HW_CACHE_MISSES` |
+| `branch_instructions` | `perf_type_hardware` | `PERF_COUNT_HW_BRANCH_INSTRUCTIONS` |
+| `branch_misses` | `perf_type_hardware` | `PERF_COUNT_HW_BRANCH_MISSES` |
+| `page_faults` | `perf_type_software` | `PERF_COUNT_SW_PAGE_FAULTS` |
+| `context_switches` | `perf_type_software` | `PERF_COUNT_SW_CONTEXT_SWITCHES` |
+| `cpu_migrations` | `perf_type_software` | `PERF_COUNT_SW_CPU_MIGRATIONS` |
+
+For newer families such as `perf_type_hw_cache`, pass the kernel-compatible encoded `perf_config` value directly.
 
 📖 **For detailed language specification, syntax reference, and advanced features, please read [`SPEC.md`](SPEC.md).**
 

SPEC.md

@@ -460,20 +460,21 @@ The context type is always `*bpf_perf_event_data` (from `vmlinux.h`).
 fn main() -> i32 {
     var prog = load(my_handler)
 
-    // Only counter is required; all other fields use language-level defaults:
+    // 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 { counter: branch_misses }, 0)
+    attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
 
     // Override specific fields as needed:
     attach(prog, perf_options {
-        counter: cache_misses,
+        perf_type: perf_type_hardware,
+        perf_config: cache_misses,
         cpu: 2,
         period: 500000,
         exclude_kernel: true,
     }, 0)
 
-    var count = perf_read(prog)   // read counter value via program handle
-    print(count)
+    var count = perf_read(prog)
+    print("count: %lld", count)
 
     detach(prog)   // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
     return 0
@@ -484,7 +485,8 @@ fn main() -> i32 {
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `counter` | `perf_counter` | *(required)* | Hardware/software counter |
+| `perf_type` | `perf_type` | *(required)* | `perf_event_attr.type` tag |
+| `perf_config` | `u64` | *(required)* | `perf_event_attr.config` value for that type |
 | `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 |
@@ -502,19 +504,32 @@ fn main() -> i32 {
 | -1 | ≥ 0 | All processes on specific CPU (system-wide) |
 | -1 | -1 | **Invalid** — rejected with error |
 
-**`perf_counter` enum:**
+**`perf_type` enum:**
 
 | Value | Linux constant |
 |---|---|
-| `cpu_cycles` | `PERF_COUNT_HW_CPU_CYCLES` |
-| `instructions` | `PERF_COUNT_HW_INSTRUCTIONS` |
-| `cache_references` | `PERF_COUNT_HW_CACHE_REFERENCES` |
-| `cache_misses` | `PERF_COUNT_HW_CACHE_MISSES` |
-| `branch_instructions` | `PERF_COUNT_HW_BRANCH_INSTRUCTIONS` |
-| `branch_misses` | `PERF_COUNT_HW_BRANCH_MISSES` |
-| `page_faults` | `PERF_COUNT_SW_PAGE_FAULTS` |
-| `context_switches` | `PERF_COUNT_SW_CONTEXT_SWITCHES` |
-| `cpu_migrations` | `PERF_COUNT_SW_CPU_MIGRATIONS` |
+| `perf_type_hardware` | `PERF_TYPE_HARDWARE` |
+| `perf_type_software` | `PERF_TYPE_SOFTWARE` |
+| `perf_type_tracepoint` | `PERF_TYPE_TRACEPOINT` |
+| `perf_type_hw_cache` | `PERF_TYPE_HW_CACHE` |
+| `perf_type_raw` | `PERF_TYPE_RAW` |
+| `perf_type_breakpoint` | `PERF_TYPE_BREAKPOINT` |
+
+**Common `perf_config` constants:**
+
+| Value | Intended `perf_type` | Linux constant |
+|---|---|---|
+| `cpu_cycles` | `perf_type_hardware` | `PERF_COUNT_HW_CPU_CYCLES` |
+| `instructions` | `perf_type_hardware` | `PERF_COUNT_HW_INSTRUCTIONS` |
+| `cache_references` | `perf_type_hardware` | `PERF_COUNT_HW_CACHE_REFERENCES` |
+| `cache_misses` | `perf_type_hardware` | `PERF_COUNT_HW_CACHE_MISSES` |
+| `branch_instructions` | `perf_type_hardware` | `PERF_COUNT_HW_BRANCH_INSTRUCTIONS` |
+| `branch_misses` | `perf_type_hardware` | `PERF_COUNT_HW_BRANCH_MISSES` |
+| `page_faults` | `perf_type_software` | `PERF_COUNT_SW_PAGE_FAULTS` |
+| `context_switches` | `perf_type_software` | `PERF_COUNT_SW_CONTEXT_SWITCHES` |
+| `cpu_migrations` | `perf_type_software` | `PERF_COUNT_SW_CPU_MIGRATIONS` |
+
+For event families with a richer config space, such as `perf_type_hw_cache`, provide the encoded kernel `perf_config` value directly instead of relying on a flattened enum.
 
 **Generated C helpers (emitted when `attach(prog, perf_options{...}, flags)` is used):**
 
@@ -524,7 +539,6 @@ fn main() -> i32 {
 | `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_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, inside `ks_attach_perf_event`):**
 1. `ks_attr.attr.disabled = 1` — open counter without starting it  

examples/perf_branch_miss.ks

@@ -11,13 +11,13 @@ fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
 fn main() -> i32 {
     var prog = load(on_branch_miss)
 
-    // Only counter is required; pid, cpu, period, wakeup and flag fields
+    // 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 { counter: branch_misses }, 0)
-
-    perf_print(prog, "branch_misses")
+    attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+    print("Branch-miss perf_event demo attached")
 
     detach(prog)
+    print("Branch-miss perf_event demo detached")
     return 0
 }

examples/perf_cache_miss.ks

@@ -11,13 +11,15 @@ fn on_cache_miss(ctx: *bpf_perf_event_data) -> i32 {
 fn main() -> i32 {
     var prog = load(on_cache_miss)
 
-    // Only counter is required; pid, cpu, period, wakeup and flag fields
+    // 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 { counter: cache_misses,period: 10000000, inherit: true }, 0)
-
-    perf_print(prog, "cache_misses")
+    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)
 
     detach(prog)
+    print("Cache-miss perf_event demo detached")
     return 0
 }

src/btf_parser.ml

@@ -521,11 +521,8 @@ let generate_kernelscript_source ?extra_param ?include_kfuncs template project_n
 fn main() -> i32 {
     var prog = load(%s)
 
-    // 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)
+    // 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)
 
     detach(prog)
 

src/context/perf_event_codegen.ml

@@ -1,5 +1,5 @@
 (*
- * Copyright 2025 Multikernel Technologies, Inc.
+ * Copyright 2026 Siyuan Sun
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/stdlib.ml

@@ -233,18 +233,6 @@ let builtin_functions = [
     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;
-  };
-
 ]
 
 (** Get built-in function definition by name *)
@@ -309,23 +297,38 @@ let builtin_types = [
     ("TC_ACT_TRAP", Some (Ast.Signed64 8L));
   ], builtin_pos));
 
-  (* perf_counter enum: KernelScript abstraction for hardware/software performance counters *)
-  TypeDef (EnumDef ("perf_counter", [
+  (* perf_type mirrors perf_event_attr.type so config stays a tagged 2D space. *)
+  TypeDef (EnumDef ("perf_type", [
+    ("perf_type_hardware",   Some (Ast.Signed64 0L));
+    ("perf_type_software",   Some (Ast.Signed64 1L));
+    ("perf_type_tracepoint", Some (Ast.Signed64 2L));
+    ("perf_type_hw_cache",   Some (Ast.Signed64 3L));
+    ("perf_type_raw",        Some (Ast.Signed64 4L));
+    ("perf_type_breakpoint", Some (Ast.Signed64 5L));
+  ], builtin_pos));
+
+  (* Common config values for PERF_TYPE_HARDWARE. *)
+  TypeDef (EnumDef ("perf_hw_config", [
     ("cpu_cycles",           Some (Ast.Signed64 0L));
     ("instructions",         Some (Ast.Signed64 1L));
     ("cache_references",     Some (Ast.Signed64 2L));
     ("cache_misses",         Some (Ast.Signed64 3L));
     ("branch_instructions",  Some (Ast.Signed64 4L));
     ("branch_misses",        Some (Ast.Signed64 5L));
-    ("page_faults",          Some (Ast.Signed64 6L));
-    ("context_switches",     Some (Ast.Signed64 7L));
-    ("cpu_migrations",       Some (Ast.Signed64 8L));
+  ], builtin_pos));
+
+  (* Common config values for PERF_TYPE_SOFTWARE. *)
+  TypeDef (EnumDef ("perf_sw_config", [
+    ("page_faults",          Some (Ast.Signed64 2L));
+    ("context_switches",     Some (Ast.Signed64 3L));
+    ("cpu_migrations",       Some (Ast.Signed64 4L));
   ], builtin_pos));
 
   (* perf_options: configuration bag for @perf_event programs.
-     Only 'counter' is required; all other fields have language-level defaults. *)
+     Only 'perf_type' and 'perf_config' are required; all other fields have language-level defaults. *)
   TypeDef (StructDef ("perf_options", [
-    ("counter",        Enum "perf_counter");
+    ("perf_type",      Enum "perf_type");
+    ("perf_config",    U64);
     ("pid",            I32);
     ("cpu",            I32);
     ("period",         U64);
@@ -338,7 +341,7 @@ let builtin_types = [
 
 (** 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,
+  Required fields (e.g. perf_type/perf_config 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" ->