Enhance TC program support by requiring direction specification.

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

Author: congwang-mk

README.md

@@ -86,7 +86,8 @@ KernelScript supports all major eBPF program types with typed contexts:
 }
 
 // TC program for traffic control
-@tc fn traffic_shaper(ctx: *__sk_buff) -> i32 {
+@tc("ingress")
+fn traffic_shaper(ctx: *__sk_buff) -> i32 {
     if (ctx->len > 1000) {
         return TC_ACT_SHOT  // Drop large packets
     }
@@ -212,7 +213,8 @@ pin var shared_counter : hash<u32, u32>(1024)
 }
 
 // TC program reads counter
-@tc fn packet_reader(ctx: *__sk_buff) -> int {
+@tc("ingress")
+fn packet_reader(ctx: *__sk_buff) -> int {
     var count = shared_counter[1]
     if (count > 1000) {
         return TC_ACT_SHOT  // Rate limiting
@@ -245,7 +247,7 @@ Create a new KernelScript project with template code:
 kernelscript init xdp my_packet_filter
 
 # Create TC project  
-kernelscript init tc my_traffic_shaper
+kernelscript init tc/egress my_traffic_shaper
 
 # Create probe project
 kernelscript init probe/sys_read my_tracer

SPEC.md

@@ -68,7 +68,7 @@ fn monitor(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn analyzer(ctx: *__sk_buff) -> int {
     update_counters(1)  // Same kernel-shared function
     return 0  // TC_ACT_OK
@@ -217,9 +217,49 @@ fn arbitrary_address() -> i32 {
 **Key Benefits:**
 - **Intelligent Probe Selection**: Automatically chooses fprobe for function entrance (better performance) or kprobe for arbitrary addresses
 - **Type Safety**: Function entrance probes have correct types extracted from kernel BTF information
-- **No Magic Numbers**: Direct parameter access for function entrance probes
-- **Self-Documenting**: Function signature matches the actual kernel function for entrance probes
-- **Compile-Time Validation**: Invalid parameter access caught at compile time
+
+#### 3.1.2 Traffic Control (TC) Programs with Direction Support
+
+TC programs must specify traffic direction for proper kernel attachment point selection.
+
+```kernelscript
+// Ingress traffic control (packets entering the interface)
+@tc("ingress")
+fn ingress_filter(ctx: *__sk_buff) -> int {
+    var packet_size = ctx->len
+    
+    // Drop oversized packets at ingress
+    if (packet_size > 1500) {
+        return TC_ACT_SHOT  // Drop packet
+    }
+    
+    return TC_ACT_OK  // Allow packet
+}
+
+// Egress traffic control (packets leaving the interface)  
+@tc("egress")
+fn egress_shaper(ctx: *__sk_buff) -> int {
+    var protocol = ctx->protocol
+    
+    // Shape traffic based on protocol at egress
+    if (protocol == ETH_P_IP) {
+        // Apply rate limiting logic
+        return TC_ACT_PIPE  // Continue processing
+    }
+    
+    return TC_ACT_OK  // Allow packet
+}
+```
+
+**TC Direction Specification:**
+- **@tc("ingress")**: Attaches to ingress hook (packets entering interface)
+- **@tc("egress")**: Attaches to egress hook (packets leaving interface)
+- Direction parameter is **required** - no default direction is assumed
+
+**Key Benefits:**
+- **Explicit Direction Control**: Clear specification of traffic direction for precise attachment
+- **Type Safety**: All TC programs use standard __sk_buff context with compile-time validation
+- **Kernel Integration**: Direct mapping to kernel TC ingress/egress hooks
 
 **Probe Type Selection:**
 - `@probe("function_name")` → Uses **fprobe** for function entrance with direct parameter access
@@ -726,7 +766,7 @@ fn packet_analyzer(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn flow_tracker(ctx: *__sk_buff) -> int {
     // Track flow information using shared config
     if (monitoring.enable_stats && (ctx.hash() % monitoring.sample_rate == 0)) {
@@ -795,7 +835,7 @@ fn packet_filter(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn flow_monitor(ctx: *__sk_buff) -> int {
     return 0  // TC_ACT_OK
 }
@@ -827,7 +867,7 @@ fn main() -> i32 {
 - First parameter must be a ProgramHandle returned from load()
 - Target and flags interpretation depends on program type:
   - **XDP**: target = interface name ("eth0"), flags = XDP attachment flags
-  - **TC**: target = interface name ("eth0"), flags = direction (ingress/egress)
+  - **TC**: target = interface name ("eth0"), direction determined from @tc("ingress"/"egress") attribute
   - **Kprobe**: target = function name ("sys_read"), flags = unused (0)
   - **Cgroup**: target = cgroup path ("/sys/fs/cgroup/test"), flags = unused (0)
 - Returns 0 on success, negative error code on failure
@@ -949,7 +989,7 @@ fn main(args: Args) -> i32 {
 @xdp
 fn ingress_monitor(ctx: *xdp_md) -> xdp_action { return XDP_PASS }
 
-@tc
+@tc("egress")
 fn egress_monitor(ctx: *__sk_buff) -> int { return 0 }  // TC_ACT_OK
 
 // Struct_ops example using impl block approach
@@ -1245,7 +1285,7 @@ fn packet_filter(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn traffic_shaper(ctx: *__sk_buff) -> int {
     var packet = ctx.packet()
     
@@ -1301,7 +1341,7 @@ fn ddos_protection(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn connection_tracker(ctx: *__sk_buff) -> int {
     var tcp_info = extract_tcp_info(ctx)  // Reuse same helper
     if (tcp_info != null) {
@@ -1435,7 +1475,7 @@ fn high_level_filter(packet: *u8, len: u32) -> i32 {
 }
 
 // eBPF usage
-@tc
+@tc("ingress")
 fn traffic_analyzer(ctx: *__sk_buff) -> int {
     var packet = ctx.packet()
     
@@ -2342,7 +2382,7 @@ fn ingress_monitor(ctx: *xdp_md) -> xdp_action {
 }
 
 // Program 2: Automatically has access to the same global maps
-@tc
+@tc("egress")
 fn egress_monitor(ctx: *__sk_buff) -> int {
     var flow_key = extract_flow_key(ctx)?
     
@@ -2802,7 +2842,7 @@ fn packet_filter(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn flow_monitor(ctx: *__sk_buff) -> int {
     // Can call the same kernel-shared functions
     if (!validate_packet(ctx.packet())) {
@@ -2907,7 +2947,7 @@ fn main_filter(ctx: *xdp_md) -> xdp_action {
     return specialized_filter(ctx)   // ✅ Same type (@xdp), return position
 }
 
-@tc
+@tc("ingress")
 fn ingress_handler(ctx: *__sk_buff) -> int {
     return security_check(ctx)       // ✅ Same type (@tc), return position  
 }
@@ -4016,7 +4056,7 @@ mod program {
     // Attach a program to a target with optional flags using its handle
     // - First parameter must be a ProgramHandle returned from load()
     // - For XDP: target is interface name (e.g., "eth0"), flags are XDP attachment flags
-    // - For TC: target is interface name, flags indicate direction (ingress/egress)
+    // - For TC: target is interface name, direction determined from @tc attribute
     // - For Kprobe: target is function name (e.g., "sys_read"), flags are unused (0)
     // - For Cgroup: target is cgroup path (e.g., "/sys/fs/cgroup/test"), flags are unused (0)
     pub fn attach(handle: ProgramHandle, target: string, flags: u32) -> u32
@@ -4120,7 +4160,7 @@ fn simple_filter(ctx: *xdp_md) -> xdp_action {
     return XDP_PASS
 }
 
-@tc
+@tc("ingress")
 fn security_monitor(ctx: *__sk_buff) -> int {
     var packet = ctx.packet()
     if (packet == null) {

examples/map_operations_demo.ks

@@ -139,7 +139,8 @@ struct ArrayElement {
 }
 
 // Program 2: Writer workload demonstrating conflict detection
-@tc fn stats_updater(ctx: *__sk_buff) -> i32 {
+@tc("ingress")
+fn stats_updater(ctx: *__sk_buff) -> i32 {
     var ifindex = ctx->ifindex
 
     // Potential write conflict with other programs

examples/maps_demo.ks

@@ -128,7 +128,8 @@ fn get_timestamp() -> u64 {
 }
 
 // TC program demonstrating different map usage patterns
-@tc fn traffic_shaper(ctx: *__sk_buff) -> int {
+@tc("ingress")
+fn traffic_shaper(ctx: *__sk_buff) -> int {
   var cpu = get_cpu_id()
   var bytes = get_packet_len_tc(ctx)
 

examples/multi_programs.ks

@@ -48,7 +48,8 @@ pin var shared_counter : hash<u32, u32>(1024)
   return XDP_PASS
 }
 
-@tc fn packet_filter(ctx: *__sk_buff) -> i32 {
+@tc("ingress")
+fn packet_filter(ctx: *__sk_buff) -> i32 {
   shared_counter[2] = 200
   return TC_ACT_OK
 }

examples/packet_matching.ks

@@ -283,7 +283,7 @@ fn packet_monitor(ctx: *xdp_md) -> xdp_action {
 
 // Quality of Service (QoS) packet marking
 // Demonstrates match for traffic prioritization
-@tc
+@tc("ingress")
 fn qos_packet_marker(ctx: *__sk_buff) -> int {
     var protocol = get_ip_protocol_tc(ctx)
 

examples/symbols.ks

@@ -91,7 +91,8 @@ fn log_packet(info: PacketInfo) -> u32 {
     }
 }
 
-@tc fn traffic_monitor(ctx: *__sk_buff) -> i32 {
+@tc("ingress")
+fn traffic_monitor(ctx: *__sk_buff) -> i32 {
     var packet_protocol = ctx->protocol
 
     // Access global map (visible from all programs)

src/btf_parser.ml

@@ -284,7 +284,7 @@ let generate_kprobe_function_from_signature func_name signature =
   sprintf "fn %s(%s) -> %s" func_name params_str return_type
 
 (** Generate KernelScript source code from template *)
-let generate_kernelscript_source template project_name =
+let generate_kernelscript_source ?extra_param template project_name =
   let context_comment = match template.program_type with
     | "xdp" -> "// XDP (eXpress Data Path) program for high-performance packet processing"
     | "tc" -> "// TC (Traffic Control) program for network traffic shaping and filtering"
@@ -362,6 +362,12 @@ let generate_kernelscript_source template project_name =
       let func_def = sprintf "fn %s_handler(ctx: %s) -> %s" 
         (String.map (function '/' -> '_' | c -> c) first_event) template.context_type template.return_type in
       (comment, first_event, func_def, Some (sprintf "@tracepoint(\"%s\")" first_event))
+    else if template.program_type = "tc" && extra_param <> None then
+      let direction = match extra_param with Some d -> d | None -> "ingress" in
+      let comment = sprintf "\n// TC %s traffic control program\n" direction in
+      let func_name = sprintf "%s_%s_handler" project_name direction in
+      let func_def = sprintf "fn %s(ctx: %s) -> %s" func_name template.context_type template.return_type in
+      (comment, direction, func_def, Some (sprintf "@tc(\"%s\")" direction))
     else 
       ("", "target_function", sprintf "fn %s_handler(ctx: %s) -> %s" project_name template.context_type template.return_type, None)
   in
@@ -391,9 +397,19 @@ let generate_kernelscript_source template project_name =
     if template.program_type = "kprobe" then target_function_name 
     else if template.program_type = "tracepoint" then 
       String.map (function '/' -> '_' | c -> c) target_function_name ^ "_handler"
+    else if template.program_type = "tc" && extra_param <> None then
+      let direction = match extra_param with Some d -> d | None -> "ingress" in
+      sprintf "%s_%s_handler" project_name direction
     else sprintf "%s_handler" project_name
   in
 
+  let program_description = 
+    if template.program_type = "tc" && extra_param <> None then
+      let direction = match extra_param with Some d -> d | None -> "ingress" in
+      sprintf "TC %s" direction
+    else template.program_type
+  in
+  
   sprintf {|%s
 // Generated by KernelScript compiler with direct BTF parsing
 %s
@@ -421,4 +437,4 @@ fn main() -> i32 {
 
     return 0
 }
-|} context_comment function_signatures_comment type_definitions attribute_line function_definition template.program_type sample_return function_name attach_comment attach_target template.program_type template.program_type
+|} context_comment function_signatures_comment type_definitions attribute_line function_definition template.program_type sample_return function_name attach_comment attach_target program_description program_description

src/btf_parser.mli

@@ -52,4 +52,4 @@ val extract_struct_ops_definitions : string option -> string list -> string list
 val generate_struct_ops_template : string option -> string list -> string -> string
 
 (** Generate KernelScript source code from template *)
-val generate_kernelscript_source : program_template -> string -> string 
+val generate_kernelscript_source : ?extra_param:string -> program_template -> string -> string 

src/context/context_codegen.ml

@@ -43,6 +43,7 @@ type context_codegen = {
   generate_field_access: string -> string -> string; (* ctx_var -> field_name -> C expression *)
   map_action_constant: int -> string option; (* Map integer to action constant *)
   generate_function_signature: (string -> (string * string) list -> string -> string) option; (* func_name -> parameters -> return_type -> signature *)
+  generate_section_name: (string option -> string) option; (* Optional function to generate SEC(...) attribute with target *)
 }
 
 (** Registry for context code generators *)
@@ -232,6 +233,7 @@ let create_context_codegen_from_btf ctx_type_name btf_type_info =
     generate_field_access;
     map_action_constant;
     generate_function_signature = None;
+    generate_section_name = None;
   }
 
 (** Register context codegen from BTF type information *)
@@ -272,4 +274,13 @@ let update_context_codegen_with_btf ctx_type_name btf_type_info =
         ctx_type_name (List.length btf_only_fields)
   | None ->
       (* No existing codegen, create new one from BTF *)
-      register_btf_context_codegen ctx_type_name btf_type_info 
+      register_btf_context_codegen ctx_type_name btf_type_info
+
+(** Generate section name for a context type with optional direction *)
+let generate_context_section_name ctx_type direction =
+  match get_context_codegen ctx_type with
+  | Some codegen -> 
+      (match codegen.generate_section_name with
+       | Some section_fn -> Some (section_fn direction)
+       | None -> None)
+  | None -> None