Add support for perf event group management in BPF

- Introduced `group_fd` field in the perf options structure to allow
  attaching BPF programs to a group of perf events.
- Updated the `ks_open_perf_event` function to accept `group_fd` and
  handle group event management.
- Implemented helper functions for managing active members of perf
  event groups, ensuring that group leaders cannot be detached while
  active members exist.
- Enhanced the generated code to include necessary checks and
  structures for handling multiplexed perf events.
- Added tests to validate the new group management features and
  ensure correct code generation for group-related operations.

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 `perf_type` and `perf_config` are required; all other fields have defaults
+    - `opts`: `perf_options` value — only `perf_type` and `perf_config` are required; all other fields have defaults, including `group_fd=-1`
     - `flags`: Must be `0` for perf attaches; nonzero values are rejected
 
 **Return Value:**
@@ -120,6 +120,16 @@ var perf_att = attach(perf_prog, perf_options { perf_type: perf_type_hardware, p
 var count = read(perf_att)
 detach(perf_att)
 detach(perf_prog)
+
+// Grouped perf events: branch joins cache's leader group. Adding a member restarts the group.
+var cache = attach(perf_prog, perf_options { perf_type: perf_type_hardware, perf_config: cache_misses }, 0)
+var branch = attach(perf_prog, perf_options {
+    perf_type: perf_type_hardware,
+    perf_config: branch_misses,
+    group_fd: cache.perf_fd,
+}, 0)
+detach(branch)
+detach(cache)
 ```
 
 **Context-specific implementations:**
@@ -163,15 +173,17 @@ detach(prog)  // Clean up
 **Variadic:** No
 **Context:** Userspace only
 
-**Description:** Read the current hardware/software counter value from a perf attachment.
+**Description:** Read the current hardware/software counter value from a perf attachment. If the kernel multiplexed the event, the value is scaled with `time_enabled / time_running`.
 
 **Parameters:**
 - `handle`: Perf attachment returned from `attach(handle, perf_options, flags)`
 
 **Return Value:**
-- Returns the raw 64-bit counter value on success
+- Returns the raw 64-bit counter value when no multiplexing occurred
+- Returns a scaled value when `time_running < time_enabled`
 - Returns `-1` on invalid/stale attachment or read failure
 - Reads use the attachment's `perf_fd` directly; the internal token detects copied handles used after detach.
+- Group snapshot reads are not supported yet; read grouped attachments individually.
 
 ---
 

README.md

@@ -306,7 +306,7 @@ fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
 fn main() -> i32 {
     var prog = load(on_branch_miss)
 
-    // Minimal form — defaults: pid=-1 (all procs), cpu=0,
+    // Minimal form — defaults: pid=-1 (all procs), cpu=0, group_fd=-1,
     // period=1_000_000, wakeup=1; perf attach flags must be 0
     var att = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
     var count = read(att)
@@ -318,6 +318,19 @@ fn main() -> i32 {
 }
 ```
 
+Perf events can share a kernel scheduling group by passing the leader attachment's `perf_fd` as `group_fd`:
+
+```kernelscript
+var cache = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: cache_misses }, 0)
+var branch = attach(prog, perf_options {
+    perf_type: perf_type_hardware,
+    perf_config: branch_misses,
+    group_fd: cache.perf_fd,
+}, 0)
+```
+
+Adding a member restarts the whole group from zero. Detach members before detaching their leader. `read(att)` still reads one attachment at a time; it returns a multiplex-scaled count when the kernel reports `time_running < time_enabled`. Group snapshot reads are not part of this first-stage API.
+
 **Available `perf_type` values:**
 
 | Enum value | Hardware/software event |

SPEC.md

@@ -461,7 +461,7 @@ fn main() -> i32 {
     var prog = load(my_handler)
 
     // 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
+    // pid=-1, cpu=0, group_fd=-1, period=1_000_000, wakeup=1, inherit/exclude_*=false
     var misses = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
 
     // Override specific fields as needed:
@@ -473,8 +473,17 @@ fn main() -> i32 {
         exclude_kernel: true,
     }, 0)
 
-    print("misses=%lld cache=%lld", read(misses), read(cache))
+    // Put branch misses in cache's perf event group. Adding a member restarts
+    // the whole group from zero.
+    var branch = attach(prog, perf_options {
+        perf_type: perf_type_hardware,
+        perf_config: branch_misses,
+        group_fd: cache.perf_fd,
+    }, 0)
+
+    print("misses=%lld cache=%lld branch=%lld", read(misses), read(cache), read(branch))
 
+    detach(branch)
     detach(cache)  // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
     detach(misses)
     detach(prog)
@@ -490,6 +499,7 @@ fn main() -> i32 {
 | `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) |
+| `group_fd` | `i32` | `-1` | -1 = standalone event; ≥0 = perf group leader fd |
 | `period` | `u64` | `1000000` | Sample after this many events |
 | `wakeup` | `u32` | `1` | Wake userspace after N samples |
 | `inherit` | `bool` | `false` | Inherit to forked children |
@@ -538,16 +548,29 @@ For event families with a richer config space, such as `perf_type_hw_cache`, pro
 |---|---|---|
 | `ks_open_perf_event` | `int (ks_perf_options)` | Calls `perf_event_open(2)`, returns fd |
 | `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_read_perf_count` | `int64_t (int perf_fd)` | Reads current counter and applies multiplex scaling when needed |
 | `ks_perf_attachment_read` | `int64_t (PerfAttachment)` | Direct fd read through the attachment value with stale-handle detection |
 
-**Attach sequence (compiler-generated, inside `ks_attach_perf_event`):**
+**Attach sequence for standalone events (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`  
+2. `syscall(SYS_perf_event_open, ..., group_fd=-1, ...)` → `perf_fd`  
 3. `ioctl(perf_fd, PERF_EVENT_IOC_RESET, 0)` — zero the counter  
 4. `bpf_program__attach_perf_event(prog, perf_fd)` — link BPF program  
 5. `ioctl(perf_fd, PERF_EVENT_IOC_ENABLE, 0)` — **start counting**  
 
+**Perf event groups:**
+- `group_fd >= 0` opens the new event as a member of that leader fd.
+- Group members are opened disabled, linked to the BPF program, then the leader is disabled, reset, and enabled with `PERF_IOC_FLAG_GROUP`.
+- Adding a member to an already running group restarts the whole group from zero.
+- Detaching a member is allowed. Detaching a leader while live members reference it is rejected; detach members first.
+- Group snapshot reads are not implemented yet; read each `PerfAttachment` separately.
+
+**Counter reads:**
+- Generated perf events request `PERF_FORMAT_TOTAL_TIME_ENABLED | PERF_FORMAT_TOTAL_TIME_RUNNING`.
+- `read(att)` returns the raw value when `time_enabled == time_running`.
+- If multiplexing occurred, `read(att)` returns `value * time_enabled / time_running` using a 128-bit intermediate.
+- If `time_running == 0`, `read(att)` reports an error and returns `-1`.
+
 **Detach sequence (compiler-generated):**
 1. `ioctl(perf_fd, PERF_EVENT_IOC_DISABLE, 0)` — stop counting  
 2. `bpf_link__destroy(link)` — unlink BPF program  
@@ -559,7 +582,7 @@ For event families with a richer config space, such as `perf_type_hw_cache`, pro
 - Returns a first-class `PerfAttachment` value for perf attaches so one program can hold multiple live counters
 - `PerfAttachment` carries `perf_fd` plus an internal generation token; `read(attachment)` avoids global attachment-list scans and rejects copied handles after detach
 - 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
+- Validates `pid ≥ -1`, `cpu ≥ -1`, `group_fd ≥ -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_cache_miss.ks

@@ -11,19 +11,20 @@ fn on_cache_miss(ctx: *bpf_perf_event_data) -> i32 {
 fn main() -> i32 {
     var prog = load(on_cache_miss)
 
-    // Only perf_type + perf_config are required; pid, cpu, period, wakeup and flag fields
+    // Only perf_type + perf_config are required; pid, cpu, group_fd, 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.
+    // group_fd=-1, inherit/exclude_kernel/exclude_user=false.
     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)
+    // branch joins cache's perf event group. Adding a member restarts the whole group from zero.
+    var branch = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses, period: 10000000, inherit: true, group_fd: cache.perf_fd }, 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(cache)
     detach(prog)
     print("Cache-miss and branch-miss perf_event demo detached")
     return 0

examples/perf_page_fault.ks

@@ -14,20 +14,26 @@ 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.
-    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")
+    var page = attach(prog, perf_options { perf_type: perf_type_software, perf_config: page_faults, pid: 0, cpu: -1, period: 1 }, 0)
+    // branch joins cache's perf event group. Adding a member restarts the whole group from zero.
+    var branch = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses, period: 10000000, inherit: true}, 0)
+    
+    print("perf_event demo attached")
 
     // Repeatedly increment a counter; stack/heap activity will generate page faults.
     var x: i64 = 0
     for (i in 0..10000000) {
         x = x + 1
     }
 
-    var count = read(att)
-    print("Page-fault count: %lld", count)
+    var page_fault_count = read(page)
+    print("Page-fault count: %lld", page_fault_count)
+    var branch_count = read(branch)
+    print("Branch-miss count: %lld", branch_count)
 
-    detach(att)
-    print("Page-fault perf_event demo detached")
+    detach(page)
+    detach(branch)
+    print("perf_event demo detached")
     detach(prog)
     return 0
 }

src/stdlib.ml

@@ -349,6 +349,7 @@ let builtin_types = [
     ("perf_config",    U64);
     ("pid",            I32);
     ("cpu",            I32);
+    ("group_fd",       I32);
     ("period",         U64);
     ("wakeup",         U32);
     ("inherit",        Bool);
@@ -374,6 +375,7 @@ let get_struct_field_defaults = function
       Some [
         ("pid",            IntLit (Signed64 (-1L),      None));
         ("cpu",            IntLit (Signed64 0L,         None));
+        ("group_fd",       IntLit (Signed64 (-1L),      None));
         ("period",         IntLit (Unsigned64 1000000L, None));
         ("wakeup",         IntLit (Unsigned64 1L,       None));
         ("inherit",        BoolLit false);