Add support for extern kernel function declarations in KernelScript.

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

Author: congwang-mk

SPEC.md

@@ -141,6 +141,7 @@ pin         type        struct      enum        if          else
 while       loop        break       continue    return      import
 pub         priv        impl        true        false       null
 try         catch       throw       defer       delete      match
+extern
 ```
 
 **Note**: The `pin` keyword is used for both maps and global variables to enable filesystem persistence.
@@ -1240,11 +1241,113 @@ fn advanced_security_monitor(ctx: LsmContext) -> i32 {
 }
 ```
 
-### 3.7 Helper Functions (@helper)
+### 3.7 External Kernel Functions (extern)
+
+KernelScript supports importing existing kernel functions using the `extern` keyword. These are kernel functions that already exist in the running kernel (discovered via BTF) and can be called directly from eBPF programs without requiring custom kernel modules.
+
+#### 3.7.1 extern Declaration and Usage
+
+External kernel functions are declared using the `extern` keyword and provide type-safe access to kernel-provided kfuncs:
+
+```kernelscript
+// Import existing kernel functions via extern declarations
+extern bpf_ktime_get_ns() -> u64
+extern bpf_trace_printk(fmt: *u8, fmt_size: u32) -> i32
+extern bpf_get_current_pid_tgid() -> u64
+extern bpf_get_current_comm(buf: *u8, buf_size: u32) -> i32
+
+// eBPF programs can call extern functions directly
+@xdp
+fn packet_tracer(ctx: *xdp_md) -> xdp_action {
+    // Get current timestamp using extern kfunc
+    var timestamp = bpf_ktime_get_ns()
+    
+    // Get current process ID using extern kfunc
+    var pid_tgid = bpf_get_current_pid_tgid()
+    var pid = (pid_tgid >> 32) as u32
+    
+    // Get process name
+    var comm: u8[16]
+    bpf_get_current_comm(&comm[0], 16)
+    
+    // Print debug information
+    bpf_trace_printk(&"packet from pid %d\n"[0], 18)
+    
+    return XDP_PASS
+}
+```
+
+#### 3.7.2 extern vs @kfunc Comparison
+
+| Aspect | `extern` | `@kfunc` |
+|--------|----------|----------|
+| **Definition** | Declaration of existing kernel function | User-defined kernel function |
+| **Implementation** | Already exists in kernel | Implemented in generated kernel module |
+| **BTF Registration** | Already registered | Registered by compiler |
+| **Compilation** | Declaration only | Full implementation + module |
+| **Usage** | Import existing kernel APIs | Create custom kernel functionality |
+| **Performance** | Direct kernel function call | BTF-mediated call to module |
+
+#### 3.7.3 extern Declaration Rules
+
+- **Declaration only**: `extern` functions must not have function bodies
+- **Type safety**: Parameter and return types must match kernel BTF signatures
+- **eBPF only**: `extern` functions can only be called from eBPF programs, not userspace
+- **Kernel availability**: Functions must exist in the target kernel version
+
+```kernelscript
+// ✅ Valid extern declaration
+extern bpf_ktime_get_ns() -> u64
+
+// ❌ Invalid - extern cannot have function body
+extern invalid_function() -> u32 {
+    return 42  // Error: extern functions cannot have bodies
+}
+
+// ❌ Invalid - extern functions cannot be called from userspace
+fn userspace_function() -> u64 {
+    return bpf_ktime_get_ns()  // Error: extern kfuncs only callable from eBPF
+}
+```
+
+#### 3.7.4 BTF Integration and Discovery
+
+The compiler can automatically discover available kernel functions from BTF:
+
+```bash
+# Automatic extern generation from kernel BTF
+kernelscript init --kfuncs xdp my_xdp
+
+# Generated extern_kfuncs.ks would contain:
+# extern bpf_ktime_get_ns() -> u64
+# extern bpf_trace_printk(fmt: *u8, fmt_size: u32) -> i32
+# extern bpf_get_current_pid_tgid() -> u64
+# ... (all available kernel kfuncs)
+```
+
+#### 3.7.5 Common extern kfunc Examples
+
+```kernelscript
+extern bpf_ktime_get_ns() -> u64
+extern bpf_get_current_pid_tgid() -> u64
+extern bpf_trace_printk(fmt: *u8, fmt_size: u32) -> i32
+
+@tc("ingress")
+fn network_monitor(ctx: *__sk_buff) -> i32 {
+    var timestamp = bpf_ktime_get_ns()
+    var pid_tgid = bpf_get_current_pid_tgid()
+
+    // Process monitoring logic here
+    bpf_trace_printk("Processing packet at %llu from PID %d\n", 40)
+    return 0  // TC_ACT_OK
+}
+```
+
+### 3.8 Helper Functions (@helper)
 
 KernelScript supports kernel-shared helper functions using the `@helper` attribute. These functions compile to eBPF bytecode and are shared across all eBPF programs within the same compilation unit, providing a way to reuse common logic without duplicating code.
 
-#### 3.7.1 @helper Declaration and Usage
+#### 3.8.1 @helper Declaration and Usage
 
 Helper functions are declared using the `@helper` attribute and can be called from any eBPF program:
 
@@ -1301,7 +1404,7 @@ fn traffic_shaper(ctx: *__sk_buff) -> int {
 }
 ```
 
-#### 3.7.2 @helper vs Other Function Types
+#### 3.8.2 @helper vs Other Function Types
 
 | Aspect | `@helper` | `@kfunc` | `@xdp/@tc/etc` | Regular `fn` |
 |--------|-----------|----------|----------------|--------------|
@@ -1311,7 +1414,7 @@ fn traffic_shaper(ctx: *__sk_buff) -> int {
 | **Shared Across Programs** | Yes | Yes | No | No |
 | **Memory Access** | eBPF-restricted | Unrestricted kernel | eBPF-restricted | Userspace-restricted |
 
-#### 3.7.3 Code Organization Benefits
+#### 3.8.3 Code Organization Benefits
 
 Using `@helper` functions provides several benefits:
 
@@ -1351,11 +1454,11 @@ fn connection_tracker(ctx: *__sk_buff) -> int {
 }
 ```
 
-### 3.8 Private Kernel Module Functions (@private)
+### 3.9 Private Kernel Module Functions (@private)
 
 KernelScript supports private helper functions within kernel modules using the `@private` attribute. These functions execute in kernel space but are internal to the module - they cannot be called by eBPF programs and are not registered via BTF. They serve as utility functions for `@kfunc` implementations.
 
-#### 3.8.1 @private Declaration and Usage
+#### 3.9.1 @private Declaration and Usage
 
 Private functions are declared using the `@private` attribute and can only be called by other functions within the same kernel module:
 
@@ -1446,7 +1549,7 @@ fn packet_filter(ctx: *xdp_md) -> xdp_action {
 }
 ```
 
-#### 3.8.2 Function Visibility and Call Hierarchy
+#### 3.9.2 Function Visibility and Call Hierarchy
 
 ```kernelscript
 // Example showing function call hierarchy
@@ -1486,7 +1589,7 @@ fn traffic_analyzer(ctx: *__sk_buff) -> int {
 }
 ```
 
-#### 3.8.3 @private vs @kfunc Comparison
+#### 3.9.3 @private vs @kfunc Comparison
 
 | Aspect | `@private` | `@kfunc` |
 |--------|-----------|----------|
@@ -1497,7 +1600,7 @@ fn traffic_analyzer(ctx: *__sk_buff) -> int {
 | **Use Case** | Internal implementation details | Public API functions |
 | **Performance** | Direct function call | BTF-mediated call |
 
-#### 3.8.4 Code Organization Benefits
+#### 3.9.4 Code Organization Benefits
 
 Using `@private` functions provides several architectural benefits:
 
@@ -1560,11 +1663,11 @@ fn optimized_packet_check(packet: *u8, len: u32) -> bool {
 }
 ```
 
-### 3.9 Struct_ops and Kernel Module Function Pointers
+### 3.10 Struct_ops and Kernel Module Function Pointers
 
 KernelScript supports eBPF struct_ops through clean impl block syntax that allows implementing kernel interfaces using eBPF programs.
 
-#### 3.9.1 eBPF Struct_ops with Impl Blocks
+#### 3.10.1 eBPF Struct_ops with Impl Blocks
 
 eBPF struct_ops allow implementing kernel interfaces using eBPF programs. KernelScript uses impl blocks for a clean, intuitive syntax:
 
@@ -1629,7 +1732,7 @@ impl my_bbr_congestion_control {
 register(my_bbr_congestion_control)
 ```
 
-#### 3.9.2 Simplified Struct_ops Example
+#### 3.10.2 Simplified Struct_ops Example
 
 ```kernelscript
 // Minimal struct_ops implementation
@@ -1669,7 +1772,7 @@ fn main() -> i32 {
 }
 ```
 
-#### 3.9.3 Registration Function
+#### 3.10.3 Registration Function
 
 The `register()` function is type-aware and generates the appropriate registration code:
 
@@ -4530,7 +4633,8 @@ kernelscript_file = { global_declaration }
 
 global_declaration = config_declaration | map_declaration | type_declaration | 
                     function_declaration | struct_declaration | impl_declaration |
-                    global_variable_declaration | bindings_declaration | import_declaration 
+                    global_variable_declaration | bindings_declaration | import_declaration |
+                    extern_declaration 
 
 (* Map declarations - global scope *)
 map_declaration = [ "pin" ] [ "@flags" "(" flag_expression ")" ] "var" identifier ":" map_type "<" key_type "," value_type ">" "(" map_config ")"
@@ -4717,10 +4821,16 @@ null_literal = "null"
 (* Import declarations - unified syntax for KernelScript and external languages *)
 import_declaration = "import" identifier "from" string_literal 
 
+(* External kernel function declarations - for importing existing kernel kfuncs *)
+extern_declaration = "extern" identifier "(" parameter_list ")" [ "->" type_annotation ]
+
 (* Examples:
    import utils from "./common/utils.ks"          // KernelScript import
    import ml_analysis from "./ml/threat.py"       // Python import (userspace only)
    
+   extern bpf_ktime_get_ns() -> u64               // Import existing kernel kfunc
+   extern bpf_trace_printk(fmt: *u8, fmt_size: u32) -> i32  // Import with parameters
+   
    Import behavior is determined by file extension:
    - .ks files: Import KernelScript symbols (functions, types, maps, configs)  
    - .py files: Import Python functions with automatic FFI bridging (userspace only)

examples/extern_kfunc_demo.ks

@@ -0,0 +1,24 @@
+// External kfunc declarations - these would typically be imported from kernel BTF
+extern bpf_ktime_get_ns() -> u64
+extern bpf_trace_printk(fmt: *u8, fmt_size: u32) -> i32
+extern bpf_get_current_pid_tgid() -> u64
+
+// XDP program that uses external kfuncs
+@xdp
+fn packet_tracer(ctx: *xdp_md) -> xdp_action {
+    // Get current timestamp using external kfunc
+    var timestamp = bpf_ktime_get_ns()
+    
+    // Get current process ID using external kfunc
+    var pid_tgid = bpf_get_current_pid_tgid()
+    
+    // Print debug information (this would need proper string handling in real implementation)
+    var result = bpf_trace_printk(null, 0)
+    
+    // Always pass packets through
+    return 2  // XDP_PASS
+}
+
+fn main() -> i32 {
+    return 0
+}

src/ast.ml

@@ -343,6 +343,14 @@ type import_declaration = {
   import_pos: position;
 }
 
+(** Extern kfunc declaration - for importing kernel functions *)
+type extern_kfunc_declaration = {
+  extern_name: string;
+  extern_params: (string * bpf_type) list;
+  extern_return_type: bpf_type option;
+  extern_pos: position;
+}
+
 (** Top-level declarations *)
 type declaration =
   | AttributedFunction of attributed_function
@@ -354,6 +362,7 @@ type declaration =
   | GlobalVarDecl of global_variable_declaration
   | ImplBlock of impl_block
   | ImportDecl of import_declaration
+  | ExternKfuncDecl of extern_kfunc_declaration
 
 (** Complete AST *)
 type ast = declaration list
@@ -440,6 +449,13 @@ let make_attributed_function attrs func pos = {
   tail_call_dependencies = [];
 }
 
+let make_extern_kfunc_declaration name params return_type pos = {
+  extern_name = name;
+  extern_params = params;
+  extern_return_type = return_type;
+  extern_pos = pos;
+}
+
 let make_type_def def = def
 
 let make_enum_def name values = EnumDef (name, values)
@@ -879,6 +895,15 @@ let string_of_declaration = function
         import_decl.module_name 
         import_decl.source_path 
         source_type_str
+  | ExternKfuncDecl extern_decl ->
+      let params_str = String.concat ", " (List.map (fun (name, typ) ->
+        Printf.sprintf "%s: %s" name (string_of_bpf_type typ)
+      ) extern_decl.extern_params) in
+      let return_str = match extern_decl.extern_return_type with
+        | Some typ -> " -> " ^ string_of_bpf_type typ
+        | None -> ""
+      in
+      Printf.sprintf "extern %s(%s)%s;" extern_decl.extern_name params_str return_str
 
 let string_of_ast ast =
   String.concat "\n\n" (List.map string_of_declaration ast)

src/lexer.mll

@@ -72,6 +72,7 @@
 
   let lookup_keyword = function
     | "fn" -> FN
+    | "extern" -> EXTERN
     | "pin" -> PIN
     | "type" -> TYPE
     | "struct" -> STRUCT

src/parse.ml

@@ -151,6 +151,7 @@ let validate_ast ast =
           | ImplStaticField (_, expr) -> validate_expr expr
         ) impl_block.impl_items
     | ImportDecl _ -> true (* Import declarations are always valid once parsed *)
+    | ExternKfuncDecl _ -> true (* Extern kfunc declarations are always valid once parsed *)
   in
 
   List.for_all validate_declaration ast

src/parser.mly

@@ -39,7 +39,7 @@
 %token NULL NONE
 
 /* Keywords */
-%token FN PIN TYPE STRUCT ENUM IMPL
+%token FN EXTERN PIN TYPE STRUCT ENUM IMPL
 %token U8 U16 U32 U64 I8 I16 I32 I64 BOOL CHAR VOID STR
 %token IF ELSE FOR WHILE RETURN BREAK CONTINUE
 %token VAR CONST CONFIG LOCAL
@@ -97,6 +97,7 @@
 %type <Ast.map_flag> flag_item
 
 %type <Ast.function_def> function_declaration
+%type <Ast.extern_kfunc_declaration> extern_kfunc_declaration
 %type <Ast.return_type_spec option> function_return_type
 %type <(string * Ast.bpf_type) list> parameter_list
 %type <string * Ast.bpf_type> parameter
@@ -170,6 +171,7 @@ declaration:
   | config_declaration { ConfigDecl $1 }
   | attributed_function_declaration { AttributedFunction $1 }
   | function_declaration { GlobalFunction $1 }
+  | extern_kfunc_declaration { ExternKfuncDecl $1 }
   | map_declaration { MapDecl $1 }
   | struct_declaration { StructDecl $1 }
   | enum_declaration { TypeDef $1 }
@@ -211,6 +213,13 @@ function_declaration:
   | FN IDENTIFIER LPAREN parameter_list RPAREN function_return_type LBRACE statement_list RBRACE
     { make_function $2 $4 $6 $8 (make_pos ()) }
 
+/* Extern kfunc declaration: extern name(params) -> return_type; */
+extern_kfunc_declaration:
+  | EXTERN IDENTIFIER LPAREN parameter_list RPAREN ARROW bpf_type
+    { make_extern_kfunc_declaration $2 $4 (Some $7) (make_pos ()) }
+  | EXTERN IDENTIFIER LPAREN parameter_list RPAREN
+    { make_extern_kfunc_declaration $2 $4 None (make_pos ()) }
+
 function_return_type:
   | /* empty */ { None }
   | ARROW bpf_type { Some (make_unnamed_return $2) }