Add detach API for eBPF programs in userspace and enhance related code generation.

Author: congwang-mk

SPEC.md

@@ -812,12 +812,65 @@ fn main() -> i32 {
   - **Cgroup**: target = cgroup path ("/sys/fs/cgroup/test"), flags = unused (0)
 - Returns 0 on success, negative error code on failure
 
+**`detach(handle: ProgramHandle) -> void`**
+- Detaches the program from its current attachment point using its handle
+- Automatically determines the correct detachment method based on program type:
+  - **XDP**: Uses `bpf_xdp_detach()` with stored interface and flags
+  - **TC**: Uses `bpf_tc_detach()` with stored interface and direction
+  - **Kprobe/Tracepoint**: Destroys the stored `bpf_link` handle
+- No return value (void) - logs errors to stderr if detachment fails
+- Safe to call multiple times on the same handle (no-op if already detached)
+- Automatically cleans up internal attachment tracking
+
 **Safety Benefits:**
 - **Compile-time enforcement**: Cannot call `attach()` without first calling `load()` - the type system prevents this
 - **Implementation abstraction**: Users work with `ProgramHandle` instead of raw file descriptors
 - **Resource safety**: Program handles abstract away the underlying resource management
+- **Automatic cleanup**: `detach()` handles all program types uniformly and cleans up tracking data
+- **Idempotent operations**: Safe to call `detach()` multiple times without side effects
+
+#### 3.5.3 Lifecycle Best Practices
+
+**Proper Cleanup Patterns:**
+```kernelscript
+fn main() -> i32 {
+    var prog1 = load(filter)
+    var prog2 = load(monitor)
+    
+    // Attach programs
+    var result1 = attach(prog1, "eth0", 0)
+    var result2 = attach(prog2, "eth0", 1)
+    
+    // Error handling with partial cleanup
+    if (result1 != 0 || result2 != 0) {
+        // Clean up any successful attachments before returning
+        if (result1 == 0) detach(prog1)
+        if (result2 == 0) detach(prog2)
+        return 1
+    }
+    
+    // Normal operation...
+    print("Programs running...")
+    
+    // Proper shutdown: detach in reverse order
+    detach(prog2)  // Last attached, first detached
+    detach(prog1)
+    
+    return 0
+}
+```
+
+**Multi-Program Detachment Order:**
+- Always detach programs in **reverse order** of attachment
+- This ensures dependencies are cleaned up properly
+- Example: if `filter` depends on `monitor`, detach `monitor` first
+
+**Error Recovery:**
+- Use conditional detachment for partial failure scenarios
+- Safe to call `detach()` multiple times on the same handle
+- Always clean up successful attachments before returning error codes
 
-#### 3.5.3 Advanced Usage Patterns
+#### 3.5.4 Advanced Usage Patterns
 
 **Configuration Between Load and Attach:**
 ```kernelscript
@@ -855,6 +908,13 @@ fn main(args: Args) -> i32 {
     
     if (result == 0) {
         print("Filter attached successfully")
+        
+        // Simulate running the program (in real usage, this might be an event loop)
+        print("Filter is processing packets...")
+        
+        // Proper cleanup when shutting down
+        detach(prog_handle)
+        print("Filter detached successfully")
     } else {
         print("Failed to attach filter")
         return 1
@@ -2749,6 +2809,14 @@ fn main() -> i32 {
     attach(filter_handle, "eth0", 0)
     attach(monitor_handle, "eth0", 1)
     
+    print("Multiple programs attached to eth0")
+    print("Running packet processing pipeline...")
+    
+    // Proper cleanup - detach in reverse order (best practice)
+    detach(monitor_handle)
+    detach(filter_handle)
+    print("All programs detached successfully")
+    
     return 0
 }
 ```
@@ -3196,7 +3264,7 @@ fn main() -> i32 {
 fn main() -> i32 {
     try {
         var prog = load(packet_filter)
-    attach(prog, "eth0", 0)
+        attach(prog, "eth0", 0)
         print("Program attached successfully")
         return 0
         
@@ -4085,6 +4153,13 @@ fn main(args: Args) -> i32 {
     
     if (filter_result != 0 || monitor_result != 0) {
         print("Failed to attach programs to interface: ", args.interface)
+        // Clean up any successful attachments
+        if (filter_result == 0) {
+            detach(filter_handle)
+        }
+        if (monitor_result == 0) {
+            detach(monitor_handle)
+        }
         return 1
     }
     
@@ -4099,13 +4174,21 @@ fn main(args: Args) -> i32 {
     }
     
     // Monitor system health using config stats
-    while (true) {
+    var iteration_count = 0
+    while (iteration_count < 100) {  // Run for limited time in example
         if (system.packets_dropped > 1000 && !args.quiet_mode) {
             print("High drop rate detected: ", system.packets_dropped)
         }
         sleep(10000)
+        iteration_count += 1
     }
     
+    // Proper cleanup when shutting down
+    print("Shutting down, detaching programs...")
+    detach(monitor_handle)  // Detach in reverse order
+    detach(filter_handle)
+    print("All programs detached successfully")
+    
     return 0
 }
 ```

examples/basic_match.ks

@@ -95,6 +95,16 @@ fn packet_classifier(ctx: *xdp_md) -> xdp_action {
 fn main() -> i32 {
     var prog = load(packet_classifier)
     attach(prog, "lo", 0)
+    
+    print("Packet classifier attached to loopback interface")
+    print("Processing packets with pattern matching...")
+    
+    // In a real application, the program would run here
+    // For demonstration, we detach after showing the lifecycle
+    detach(prog)
+    print("Packet classifier detached")
+    
+    return 0
 }
 
 

examples/break_continue_unbound.ks

@@ -67,5 +67,12 @@ fn main() -> i32 {
   var prog = load(packet_filter)
   attach(prog, "lo", 0)
 
+  print("Break/continue demo program attached to loopback")
+  print("Demonstrating break and continue functionality...")
+  
+  // Show break/continue working
+  detach(prog)
+  print("Break/continue demo program detached")
+  
   return 0
 } 

examples/import_demo.ks

@@ -34,5 +34,13 @@ fn main() -> i32 {
 
     var prog = load(intelligent_filter)
     attach(prog, "eth0", 0)
+    
+    print("Packet processor with imported utilities attached to eth0")
+    print("Processing packets with external functions...")
+    
+    // Demonstrate the import functionality
+    detach(prog)
+    print("Packet processor detached")
+    
     return 0
 } 

examples/local_global_vars.ks

@@ -54,4 +54,13 @@ fn main() -> i32 {
     packet_count = 666
     print("After assignment packet_count = %u", packet_count)
     attach(prog, "lo", 0)
+    
+    print("Local/global vars demo program attached to loopback")
+    print("Demonstrating local and global variable scoping...")
+    
+    // Show variable scoping working
+    detach(prog)
+    print("Local/global vars demo program detached")
+    
+    return 0
 }

examples/map_operations_demo.ks

@@ -239,5 +239,16 @@ fn main() -> i32 {
     attach(prog3, "sys_enter_open", 0)
     attach(prog4, "vfs_read", 0)
 
+    print("Map operations demo: All programs attached")
+    print("Traffic monitor & stats on eth0, event logger on sys_enter_open, data processor on vfs_read")
+    print("Demonstrating coordinated map operations...")
+    
+    // Detach in reverse order
+    detach(prog4)
+    detach(prog3)
+    detach(prog2)
+    detach(prog1)
+    print("All map operation demo programs detached")
+    
     return 0
 }

examples/maps_demo.ks

@@ -148,5 +148,14 @@ fn main() -> i32 {
   var prog2 = load(packet_analyzer)
   attach(prog1, "lo", 0)
   attach(prog2, "lo", 0)
+  
+  print("Maps demo: Traffic shaper and packet analyzer attached to loopback")
+  print("Demonstrating shared map operations between programs...")
+  
+  // Detach in reverse order
+  detach(prog2)
+  detach(prog1)
+  print("Maps demo programs detached")
+  
   return 0
 }

examples/multi_programs.ks

@@ -63,5 +63,13 @@ fn main() -> i32 {
   attach(prog1, "eth0", 0)
   attach(prog2, "eth0", 0)
 
+  print("Multiple XDP programs attached to eth0")
+  print("Counter and filter working together...")
+  
+  // Detach in reverse order (good practice)
+  detach(prog2)
+  detach(prog1)
+  print("All programs detached")
+  
   return 0
 } 

examples/object_allocation.ks

@@ -85,5 +85,12 @@ fn main() -> i32 {
     var prog = load(packet_inspector)
     attach(prog, "eth0", 0)
 
+    print("Object allocation demo program attached to eth0")
+    print("Demonstrating dynamic memory management...")
+    
+    // Show object allocation working
+    detach(prog)
+    print("Object allocation demo program detached")
+    
     return 0
 } 

examples/packet_filter.ks

@@ -28,5 +28,14 @@ enum xdp_action {
 fn main() -> i32 {
   var prog = load(packet_filter)
   attach(prog, "eth0", 0)
+  
+  print("Packet filter attached to eth0")
+  print("Filtering incoming packets...")
+  
+  // In a real application, this would run indefinitely
+  // For demonstration, we detach after setup
+  detach(prog)
+  print("Packet filter detached")
+  
   return 0
 }