Reject nonzero perf attach flags

Signed-off-by: Cong Wang <cwang@multikernel.io>

Author: congwang-mk

BUILTINS.md

@@ -99,7 +99,7 @@ fn main() -> i32 {
 - 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`)
+    - `flags`: Must be `0` for perf attaches; nonzero values are rejected
 
 **Return Value:**
 - Standard form returns `0` on success and an error code on failure
@@ -114,7 +114,7 @@ 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
+// pid=-1 (all procs), cpu=0, period=1_000_000, wakeup=1; perf attach flags must be 0
 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)

README.md

@@ -307,7 +307,7 @@ 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
+    // 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)
     print("branch misses: %lld", count)

SPEC.md

@@ -555,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`
+- Requires perf attach `flags` to be `0`; nonzero values are rejected instead of being silently ignored
 - 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)

src/userspace_codegen.ml

@@ -4850,7 +4850,11 @@ PerfAttachment ks_attach_perf_event(int prog_fd, ks_perf_options opts, int flags
         .link_id = -1,
         .prog_fd = prog_fd,
     };
-    (void)flags;  /* reserved for future use */
+
+    if (flags != 0) {
+        fprintf(stderr, "ks_attach_perf_event: perf attach flags must be 0, got %d\n", flags);
+        return attachment;
+    }
 
     if (prog_fd < 0) {
         fprintf(stderr, "Invalid program file descriptor: %d\n", prog_fd);

tests/test_perf_event_attach.ml

@@ -332,6 +332,10 @@ let test_perf_attach_event_function_generated () =
     (contains_substr code "find_prog_by_fd");
   check bool "perf attach rejects wrong program type at runtime" true
     (contains_substr code "is not a @perf_event program");
+  check bool "perf attach rejects nonzero flags" true
+    (contains_substr code "perf attach flags must be 0");
+  check bool "perf attach no longer ignores flags" false
+    (contains_substr code "(void)flags");
   check bool "perf attach returns PerfAttachment" true
     (contains_substr code "PerfAttachment ks_attach_perf_event");
   check bool "attachment struct typedef emitted" true