Add support for eBPF linked lists in KernelScript. Introduce list declaration syntax, operations (push_front, push_back, pop_front, pop_back), and automatic struct modifications for list elements.

Author: congwang-mk

SPEC.md

@@ -2297,6 +2297,174 @@ fn simple_monitor(ctx: *xdp_md) -> xdp_action {
 }
 ```
 
+
+### 5.6 eBPF Linked Lists
+
+KernelScript provides seamless support for eBPF linked lists with Python-like syntax. Lists automatically handle the complex BPF linked list infrastructure while providing a simple, type-safe interface.
+
+#### 5.6.1 List Declaration Syntax
+
+Lists use a simplified syntax compared to maps - no flags or pinning allowed:
+
+```kernelscript
+// Basic list declaration
+var my_list : list<StructType>
+
+// Lists can only contain struct types
+struct PacketInfo {
+    src_ip: u32,
+    dst_ip: u32,
+    size: u16,
+}
+
+var packet_queue : list<PacketInfo>
+```
+
+**List Constraints:**
+- ✅ Only struct types are allowed as list elements
+- ❌ Lists cannot be pinned (no `pin` keyword)
+- ❌ Lists cannot have flags (no `@flags()`)
+- ❌ Primitive types like `u32`, `str`, etc. are not allowed
+
+#### 5.6.2 List Operations
+
+KernelScript provides four core list operations that map directly to eBPF linked list functions:
+
+```kernelscript
+struct EventData {
+    timestamp: u64,
+    event_type: u32,
+}
+
+var event_list : list<EventData>
+
+@helper
+fn process_events() {
+    var event = EventData {
+        timestamp: bpf_ktime_get_ns(),
+        event_type: 1,
+    }
+    
+    // Add elements
+    event_list.push_back(event)    // Add to end of list
+    event_list.push_front(event)   // Add to beginning of list
+    
+    // Remove and return elements
+    var latest = event_list.pop_front()   // Remove from beginning
+    var oldest = event_list.pop_back()    // Remove from end
+    
+    // Check for null (empty list)
+    if (latest != null) {
+        // Process the event
+        if (latest->event_type == 1) {
+            // Handle event
+        }
+    }
+}
+```
+
+#### 5.6.3 Generated eBPF Code
+
+The compiler automatically generates the necessary BPF linked list infrastructure:
+
+##### 1. Helper Function Declarations
+```c
+/* BPF list helper functions are automatically declared */
+extern int bpf_list_push_front(struct bpf_list_head *head, struct bpf_list_node *node) __ksym;
+extern int bpf_list_push_back(struct bpf_list_head *head, struct bpf_list_node *node) __ksym;
+extern struct bpf_list_node *bpf_list_pop_front(struct bpf_list_head *head) __ksym;
+extern struct bpf_list_node *bpf_list_pop_back(struct bpf_list_head *head) __ksym;
+```
+
+##### 2. Automatic Struct Modification
+```c
+/* Original KernelScript struct */
+// struct EventData { timestamp: u64, event_type: u32 }
+
+/* Generated eBPF struct with injected list node */
+struct EventData {
+    __u64 timestamp;
+    __u32 event_type;
+    struct bpf_list_node __list_node;  // Automatically injected
+};
+```
+
+##### 3. List Variable Declaration
+```c
+/* KernelScript: var event_list : list<EventData> */
+struct bpf_list_head event_list;
+```
+
+##### 4. Operation Translation
+```c
+// KernelScript: event_list.push_back(event)
+// Generated eBPF C:
+result = bpf_list_push_back(&event_list, &event.__list_node);
+```
+
+**Complete Operation Mapping:**
+- `list.push_front(item)` → `bpf_list_push_front(&list, &item.__list_node)`
+- `list.push_back(item)` → `bpf_list_push_back(&list, &item.__list_node)`  
+- `list.pop_front()` → `bpf_list_pop_front(&list)`
+- `list.pop_back()` → `bpf_list_pop_back(&list)`
+
+#### 5.6.4 Type Safety
+
+The compiler enforces strict type safety for list operations:
+
+```kernelscript
+struct PacketInfo { src_ip: u32 }
+struct EventData { timestamp: u64 }
+
+var packets : list<PacketInfo>
+var events : list<EventData>
+
+@helper
+fn type_safety_example() {
+    var packet = PacketInfo { src_ip: 1234 }
+    var event = EventData { timestamp: 5678 }
+    
+    packets.push_back(packet)  // ✅ Correct type
+    packets.push_back(event)   // ❌ Compile error: type mismatch
+    
+    var retrieved = packets.pop_front()  // Returns PacketInfo* or null
+}
+```
+
+#### 5.6.5 Integration with eBPF Programs
+
+Lists work seamlessly in all eBPF program types:
+
+```kernelscript
+struct NetworkEvent {
+    src_ip: u32,
+    dst_ip: u32,
+    action: u32,
+}
+
+var network_log : list<NetworkEvent>
+
+@xdp
+fn packet_filter(ctx: *xdp_md) -> xdp_action {
+    var event = NetworkEvent {
+        src_ip: ctx->remote_ip4,
+        dst_ip: ctx->local_ip4,
+        action: XDP_PASS,
+    }
+    
+    network_log.push_front(event)
+    return XDP_PASS
+}
+```
+
+#### 5.6.6 Memory Management
+
+List elements are automatically managed by the eBPF kernel infrastructure:
+- Elements are allocated using `bpf_obj_new()` when created
+- Elements are freed automatically when removed from lists
+- No manual memory management required
+- Built-in protection against memory leaks and use-after-free
+
 ## 6. Assignment Operators
 
 ### 6.1 Simple Assignment
@@ -4304,7 +4472,7 @@ fn print_summary_stats() {
 (* Top-level structure *)
 kernelscript_file = { global_declaration } 
 
-global_declaration = config_declaration | map_declaration | type_declaration | 
+global_declaration = config_declaration | map_declaration | list_declaration | type_declaration | 
                     function_declaration | struct_declaration | impl_declaration |
                     global_variable_declaration | bindings_declaration | import_declaration 
 
@@ -4316,7 +4484,12 @@ map_type = "hash" | "array" | "percpu_hash" | "percpu_array" | "lru_hash"
 map_config = integer_literal [ "," map_config_item { "," map_config_item } ] 
 map_config_item = identifier "=" literal 
 
-flag_expression = identifier | ( identifier { "|" identifier } ) 
+flag_expression = identifier | ( identifier { "|" identifier } )
+
+(* List declarations - global scope *)
+list_declaration = "var" identifier ":" "list" "<" struct_type ">"
+
+struct_type = identifier  (* Must resolve to a struct type, not primitive *) 
 
 (* eBPF program function attributes *)
 attribute_list = attribute { attribute }
@@ -4442,7 +4615,7 @@ unary_operator = "!" | "-" | "*" | "&"
 *)
 
 primary_expression = config_access | identifier | literal | function_call | field_access | 
-                     array_access | parenthesized_expression | struct_literal | match_expression 
+                     array_access | parenthesized_expression | struct_literal | match_expression | list_operation 
 
 config_access = identifier "." identifier 
 
@@ -4460,19 +4633,23 @@ match_expression = "match" "(" expression ")" "{" match_arm { "," match_arm } [
 match_arm = match_pattern ":" expression
 match_pattern = integer_literal | identifier | "default" 
 
+list_operation = primary_expression "." list_method "(" [ argument_list ] ")"
+list_method = "push_front" | "push_back" | "pop_front" | "pop_back" 
+
 (* Type annotations *)
 type_annotation = primitive_type | compound_type | identifier 
 
 primitive_type = "u8" | "u16" | "u32" | "u64" | "i8" | "i16" | "i32" | "i64" | 
                  "bool" | "char" | "void" | "ProgramRef" | string_type 
 
-compound_type = array_type | pointer_type | function_type 
+compound_type = array_type | pointer_type | function_type | list_type 
 
 string_type = "str" "(" integer_literal ")" 
 
 array_type = "[" type_annotation "" integer_literal "]" 
 pointer_type = "*" type_annotation 
-function_type = "fn" "(" [ type_annotation { "," type_annotation } ] ")" [ return_type_spec ] 
+function_type = "fn" "(" [ type_annotation { "," type_annotation } ] ")" [ return_type_spec ]
+list_type = "list" "<" type_annotation ">" 
 
 (* Literals *)
 literal = integer_literal | string_literal | char_literal | boolean_literal | 

examples/simple_list_demo.ks

@@ -0,0 +1,43 @@
+// Simple List Demo - demonstrates KernelScript list functionality
+
+struct SimpleData {
+    id: u32,
+    value: u64,
+}
+
+// List declaration - no flags or pinning allowed
+var data_list : list<SimpleData>
+
+@xdp
+fn simple_processor(ctx: *xdp_md) -> xdp_action {
+    // Create some data
+    var data1 = SimpleData {
+        id : 1,
+        value: 100
+    }
+    var data2 = SimpleData {
+        id : 2,
+        value : 200
+    }
+    
+    // Add data to list using eBPF list operations
+    data_list.push_back(data1)
+    data_list.push_front(data2)
+    
+    // Pop data from list
+    var front_item = data_list.pop_front()
+    if (front_item != none) {
+        // Process the item
+        if (front_item.id > 0) {
+            return XDP_PASS
+        }
+    }
+    
+    var back_item = data_list.pop_back()
+    if (back_item != none) {
+        // Process the back item
+        return XDP_PASS
+    }
+    
+    return XDP_DROP
+} 

src/ast.ml

@@ -72,6 +72,7 @@ and bpf_type =
   | Result of bpf_type * bpf_type
   | Function of bpf_type list * bpf_type
   | Map of bpf_type * bpf_type * map_type
+  | List of bpf_type  (* eBPF linked lists - only struct types allowed *)
   (* Built-in context types *)
   | Xdp_md | UprobeContext 
   | TracepointContext | LsmContext | CgroupSkbContext
@@ -103,6 +104,14 @@ type map_declaration = {
   map_pos: position;
 }
 
+(** List declarations - simpler than maps, no flags or pinning *)
+type list_declaration = {
+  list_name: string;
+  element_type: bpf_type;  (* Must be a struct type *)
+  is_global: bool;
+  list_pos: position;
+}
+
 (** Literal values *)
 type literal =
   | IntLit of int * string option  (* value * original_representation *)
@@ -171,6 +180,20 @@ and expr_desc =
   | Match of expr * match_arm list  (* match (expr) { arms } *)
   | New of bpf_type  (* new Type() - object allocation *)
   | NewWithFlag of bpf_type * expr  (* new Type(gfp_flag) - object allocation with flag *)
+  | ListOperation of list_operation  (* List operations: push_front, pop_back, etc. *)
+
+(** List operations for eBPF linked lists *)
+and list_operation = {
+  list_expr: expr;  (* The list variable being operated on *)
+  operation: list_op_type;
+  op_pos: position;
+}
+
+and list_op_type =
+  | PushFront of expr  (* list.push_front(element) *)
+  | PushBack of expr   (* list.push_back(element) *)
+  | PopFront           (* list.pop_front() - returns element or null *)
+  | PopBack            (* list.pop_back() - returns element or null *)
 
 (** Module function call *)
 and module_call = {
@@ -341,6 +364,7 @@ type declaration =
   | GlobalFunction of function_def
   | TypeDef of type_def
   | MapDecl of map_declaration
+  | ListDecl of list_declaration
   | ConfigDecl of config_declaration
   | StructDecl of struct_def
   | GlobalVarDecl of global_variable_declaration
@@ -458,6 +482,13 @@ let make_map_declaration name key_type value_type map_type config is_global ~is_
   map_pos = pos;
 }
 
+let make_list_declaration name element_type is_global pos = {
+  list_name = name;
+  element_type = element_type;
+  is_global = is_global;
+  list_pos = pos;
+}
+
 let make_struct_def ?(attributes=[]) name fields pos = {
   struct_name = name;
   struct_fields = fields;
@@ -599,6 +630,7 @@ let rec string_of_bpf_type = function
         (string_of_bpf_type key_type)
         (string_of_bpf_type value_type)
         (string_of_map_type map_type)
+  | List t -> Printf.sprintf "list<%s>" (string_of_bpf_type t)
   | Xdp_md -> "xdp_md"
   | UprobeContext -> "UprobeContext"
   | TracepointContext -> "TracepointContext"
@@ -684,6 +716,14 @@ let rec string_of_expr expr =
   | New typ -> Printf.sprintf "new %s()" (string_of_bpf_type typ)
   | NewWithFlag (typ, flag_expr) -> 
       Printf.sprintf "new %s(%s)" (string_of_bpf_type typ) (string_of_expr flag_expr)
+  | ListOperation op ->
+      let op_str = match op.operation with
+        | PushFront arg -> Printf.sprintf "push_front(%s)" (string_of_expr arg)
+        | PushBack arg -> Printf.sprintf "push_back(%s)" (string_of_expr arg)
+        | PopFront -> "pop_front()"
+        | PopBack -> "pop_back()"
+      in
+      Printf.sprintf "%s.%s" (string_of_expr op.list_expr) op_str
 
 and string_of_match_pattern = function
   | ConstantPattern lit -> string_of_literal lit
@@ -827,6 +867,10 @@ let string_of_declaration = function
         md.name
         (string_of_map_type md.map_type)
         (string_of_int md.config.max_entries)
+  | ListDecl ld ->
+      Printf.sprintf "var %s : list<%s>"
+        ld.list_name
+        (string_of_bpf_type ld.element_type)
   | ConfigDecl config_decl ->
       let fields_str = String.concat ",\n    " (List.map (fun field ->
         let default_str = match field.field_default with