Merge pull request #18 from SiyuanSun0736/perf_pr

Add `@perf_event` program type with full attach/detach/count support

Author: congwang-mk

BUILTINS.md

@@ -83,21 +83,27 @@ fn main() -> i32 {
 
 ---
 
-#### `attach(handle, target, flags)`
+#### `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) -> PerfAttachment`
 **Variadic:** No
 **Context:** Userspace only
 
-**Description:** Attach a loaded eBPF program to a target interface or attachment point.
+**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:**
-- `handle`: Program handle returned from `load()`
-- `target`: Target interface name (e.g., "eth0", "lo") or attachment point
-- `flags`: Attachment flags (context-dependent)
+- Standard form:
+    - `handle`: Program handle returned from `load()`
+    - `target`: Target interface name (e.g., "eth0", "lo") or attachment point
+    - `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
+    - `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 and an internal stale-handle token
 
 **Examples:**
 ```kernelscript
@@ -106,24 +112,33 @@ var result = attach(prog, "eth0", 0)
 if (result != 0) {
     print("Failed to attach program")
 }
+
+// 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)
+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)
 ```
 
 **Context-specific implementations:**
 - **eBPF:** Not available
-- **Userspace:** Uses `bpf_prog_attach` system call
+- **Userspace:** Uses `attach_bpf_program_by_fd` for standard targets and `ks_attach_perf_event` for perf events
 - **Kernel Module:** Not available
 
 ---
 
 #### `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)
@@ -138,11 +153,28 @@ 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 invalid/stale attachment or read failure
+- Reads use the attachment's `perf_fd` directly; the internal token detects copied handles used after detach.
+
+---
+
 ### 3. Struct Operations (struct_ops)
 
 #### `register(impl_instance)`
@@ -340,7 +372,7 @@ fn main() -> i32 {
 |----------|------|-----------|---------------|-------|
 | `print()` | ✅ | ✅ | ✅ | Different output destinations |
 | `load()` | ❌ | ✅ | ❌ | Program management only |
-| `attach()` | ❌ | ✅ | ❌ | Program management only |
+| `attach()` | ❌ | ✅ | ❌ | Standard attach and perf_options attach |
 | `detach()` | ❌ | ✅ | ❌ | Program management only |
 | `register()` | ❌ | ✅ | ❌ | struct_ops registration |
 | `test()` | ❌ | ✅ | ❌ | Testing framework only |
@@ -393,4 +425,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

@@ -121,6 +121,13 @@ fn traffic_shaper(ctx: *__sk_buff) -> i32 {
     // Trace system call entry
     return 0
 }
+
+// Perf event program for hardware counter sampling
+@perf_event
+fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
+    // Runs on every hardware branch-miss event
+    return 0
+}
 ```
 
 ### Type System
@@ -285,6 +292,59 @@ 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. 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
+@perf_event
+fn on_branch_miss(ctx: *bpf_perf_event_data) -> i32 {
+    return 0
+}
+
+fn main() -> i32 {
+    var prog = load(on_branch_miss)
+
+    // Minimal form — defaults: pid=-1 (all procs), cpu=0,
+    // period=1_000_000, wakeup=1, all flags=false
+    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(att)    // disables counter, destroys BPF link, closes fd
+    detach(prog)   // safe cleanup for the loaded program handle
+    return 0
+}
+```
+
+**Available `perf_type` values:**
+
+| Enum value | Hardware/software event |
+|---|---|
+| `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).**
 
 🔧 **For complete builtin functions reference, see [`BUILTINS.md`](BUILTINS.md).**
@@ -328,6 +388,7 @@ my_project/
 - `tc` - Traffic control programs  
 - `probe` - Kernel function probing
 - `tracepoint` - Kernel tracepoint programs
+- `perf_event` - Hardware/software performance counter programs
 
 **Available struct_ops:**
 - `tcp_congestion_ops` - TCP congestion control

SPEC.md

@@ -35,7 +35,7 @@ var flows : hash<IpAddress, PacketStats>(1024)
 KernelScript uses a simple and clear scoping model that eliminates ambiguity:
 
 - **`@helper` functions**: Kernel-shared functions - accessible by all eBPF programs, compile to eBPF bytecode
-- **Attributed functions** (e.g., `@xdp`, `@tc`, `@tracepoint`): eBPF program entry points - compile to eBPF bytecode
+- **Attributed functions** (e.g., `@xdp`, `@tc`, `@tracepoint`, `@perf_event`): eBPF program entry points - compile to eBPF bytecode
 - **Regular functions**: User space - functions and data structures compile to native executable
 - **Maps and global configs**: Shared resources accessible from both kernel and user space
 - **No wrapper syntax**: Direct, flat structure without unnecessary nesting
@@ -440,6 +440,134 @@ kernelscript init tracepoint/syscalls/sys_enter_read my_syscall_tracer
 # appropriate KernelScript templates with correct context types
 ```
 
+#### 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_options` struct literal passed to the standard 3-argument `attach()`.
+
+**Syntax:**
+```kernelscript
+@perf_event
+fn <handler_name>(ctx: *bpf_perf_event_data) -> i32 {
+    // runs on every sample
+    return 0
+}
+```
+
+The context type is always `*bpf_perf_event_data` (from `vmlinux.h`).
+
+**Userspace lifecycle:**
+```kernelscript
+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
+    var misses = attach(prog, perf_options { perf_type: perf_type_hardware, perf_config: branch_misses }, 0)
+
+    // Override specific fields as needed:
+    var cache = attach(prog, perf_options {
+        perf_type: perf_type_hardware,
+        perf_config: cache_misses,
+        cpu: 2,
+        period: 500000,
+        exclude_kernel: true,
+    }, 0)
+
+    print("misses=%lld cache=%lld", read(misses), read(cache))
+
+    detach(cache)  // IOC_DISABLE → bpf_link__destroy → close(perf_fd)
+    detach(misses)
+    detach(prog)
+    return 0
+}
+```
+
+**`perf_options` fields and defaults:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `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 |
+| `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 |
+|---|---|---|
+| ≥ 0 | ≥ 0 | Specific process on specific CPU |
+| ≥ 0 | -1 | Specific process on any CPU |
+| -1 | ≥ 0 | All processes on specific CPU (system-wide) |
+| -1 | -1 | **Invalid** — rejected with error |
+
+**`perf_type` enum:**
+
+| Value | Linux constant |
+|---|---|
+| `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):**
+
+| Function | Signature | Description |
+|---|---|---|
+| `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_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`):**
+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  
+4. `bpf_program__attach_perf_event(prog, perf_fd)` — link BPF program  
+5. `ioctl(perf_fd, PERF_EVENT_IOC_ENABLE, 0)` — **start counting**  
+
+**Detach sequence (compiler-generated):**
+1. `ioctl(perf_fd, PERF_EVENT_IOC_DISABLE, 0)` — stop counting  
+2. `bpf_link__destroy(link)` — unlink BPF program  
+3. `close(perf_fd)` — release the kernel perf event  
+
+**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
+- `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
+- Emits `PERF_FLAG_FD_CLOEXEC` for safe fd inheritance
+- BPF program section is `SEC("perf_event")`
+
+**Project Initialization:**
+```bash
+# Initialize a perf_event project
+kernelscript init perf_event my_perf_monitor
+```
+
 ### 3.2 Named Configuration Blocks
 ```kernelscript
 // Named configuration blocks - globally accessible

examples/perf_cache_miss.ks

@@ -0,0 +1,30 @@
+// 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 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.
+    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 and branch-miss perf_event demo detached")
+    return 0
+}