Core: Give every symbol kind a common Symbol base class

LocalSymbol, BpfGlobalSymbol and MapSymbol each named the storage behind a
name differently (var, var, sym) and shared no type. They now all derive from
symbols.Symbol, which carries what every symbol has -- the storage pointer
(alloca, GlobalVariable, or None for the context parameter) and its IR type
-- and each subclass adds only what its kind needs: LocalSymbol its metadata
and declared_global flag, BpfGlobalSymbol its ctypes name, MapSymbol its map
type and params. MapSymbol.sym becomes var to match.

local_symbol.py is folded into the new symbols.py. LocalSymbol keeps its
three-field __iter__ for the call sites that tuple-unpack a symbol.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BSDVsZH5NtoASyxB8FCtGU

Author: r41k0u

pythonbpf/allocation_pass.py

@@ -2,7 +2,7 @@
 import logging
 import ctypes
 from llvmlite import ir
-from .local_symbol import LocalSymbol
+from .symbols import LocalSymbol
 from pythonbpf.helper import HelperHandlerRegistry
 from pythonbpf.vmlinux_parser.dependency_node import Field
 from .expr import VmlinuxHandlerRegistry

pythonbpf/context.py

@@ -5,7 +5,7 @@
 if TYPE_CHECKING:
     from pythonbpf.structs.struct_type import StructType
     from pythonbpf.maps.maps_utils import MapSymbol
-    from pythonbpf.globals_pass import BpfGlobalSymbol
+    from pythonbpf.symbols import BpfGlobalSymbol
 
 logger = logging.getLogger(__name__)
 

pythonbpf/globals_pass.py

@@ -1,10 +1,10 @@
 from llvmlite import ir
 import ast
 
-from dataclasses import dataclass
 from logging import Logger
 import logging
 from .type_deducer import ctypes_to_ir
+from .symbols import BpfGlobalSymbol
 from .debuginfo import DebugInfoGenerator
 from .expr import VmlinuxHandlerRegistry
 from .debuginfo import dwarf_constants as dc
@@ -26,20 +26,6 @@
 _C_NAME_BY_WIDTH = {8: "char", 16: "short", 32: "int", 64: "long long"}
 
 
-@dataclass
-class BpfGlobalSymbol:
-    """A mutable BPF global variable declared with @bpfglobal.
-
-    Lands in .bss (zero initializer) or .data (non-zero) and is read with a
-    plain load / written with a plain store; libbpf exposes the sections to
-    userspace as global-data maps.
-    """
-
-    var: ir.GlobalVariable
-    ir_type: ir.Type
-    ctype_name: str
-
-
 def populate_global_symbol_table(tree, compilation_context):
     """
     compilation_context: CompilationContext

pythonbpf/helper/bpf_helper_handler.py

@@ -1111,6 +1111,6 @@ def invoke_helper(method_name, map_ptr=None):
         if not map_sym_tab or map_name not in map_sym_tab:
             raise ValueError(f"Map '{map_name}' not found in symbol table")
 
-        return invoke_helper(method_name, map_sym_tab[map_name].sym)
+        return invoke_helper(method_name, map_sym_tab[map_name].var)
 
     return None

pythonbpf/local_symbol.py

@@ -50,7 +50,12 @@ def create_bpf_map(compilation_context, map_name, map_params):
     map_global.align = 8
 
     logger.info(f"Created BPF map: {map_name} with params {map_params}")
-    return MapSymbol(type=map_params["type"], sym=map_global, params=map_params)
+    return MapSymbol(
+        var=map_global,
+        ir_type=map_global.value_type,
+        type=map_params["type"],
+        params=map_params,
+    )
 
 
 def _parse_map_params(rval, expected_args=None):
@@ -112,7 +117,7 @@ def process_ringbuf_map(map_name, rval, compilation_context):
     map_global = create_bpf_map(compilation_context, map_name, map_params)
     create_ringbuf_debug_info(
         compilation_context,
-        map_global.sym,
+        map_global.var,
         map_name,
         map_params,
     )
@@ -131,7 +136,7 @@ def process_hash_map(map_name, rval, compilation_context):
     # Generate debug info for BTF
     create_map_debug_info(
         compilation_context,
-        map_global.sym,
+        map_global.var,
         map_name,
         map_params,
     )
@@ -150,7 +155,7 @@ def process_perf_event_map(map_name, rval, compilation_context):
     # Generate debug info for BTF
     create_map_debug_info(
         compilation_context,
-        map_global.sym,
+        map_global.var,
         map_name,
         map_params,
     )

pythonbpf/maps/maps_pass.py

@@ -1,16 +1,15 @@
 from collections.abc import Callable
 from dataclasses import dataclass
-from llvmlite import ir
 from typing import Any
 from .map_types import BPFMapType
+from ..symbols import Symbol
 
 
 @dataclass
-class MapSymbol:
-    """Class representing a symbol on the map"""
+class MapSymbol(Symbol):
+    """A BPF map: var is the map's GlobalVariable in the .maps section."""
 
-    type: BPFMapType
-    sym: ir.GlobalVariable
+    type: BPFMapType = BPFMapType.UNSPEC
     params: dict[str, Any] | None = None
 
 

pythonbpf/maps/maps_utils.py

@@ -0,0 +1,53 @@
+"""Symbols: what a name in a BPF program resolves to.
+
+Every symbol table in the compiler maps a name to one of these. The base class
+carries what all of them share -- the storage behind the name and its IR type;
+subclasses add what each kind of name needs on top.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import llvmlite.ir as ir
+
+
+@dataclass
+class Symbol:
+    """The storage a name resolves to, and the type of what is stored there.
+
+    `var` is a pointer to that storage: an alloca for a local, a GlobalVariable
+    for a BPF global or a map, or None for the context parameter (which arrives
+    as func.args[0] rather than living in a slot).
+    """
+
+    var: ir.Value | None
+    ir_type: ir.Type | None
+
+
+@dataclass
+class LocalSymbol(Symbol):
+    """One name visible in a BPF function's scope.
+
+    `declared_global` marks a name bound by a `global` statement: its var is
+    the @bpfglobal's GlobalVariable rather than an alloca.
+    """
+
+    metadata: Any = None
+    declared_global: bool = False
+
+    def __iter__(self):
+        # Three fields on purpose: several call sites tuple-unpack a symbol.
+        yield self.var
+        yield self.ir_type
+        yield self.metadata
+
+
+@dataclass
+class BpfGlobalSymbol(Symbol):
+    """A mutable BPF global variable declared with @bpfglobal.
+
+    Lands in .bss (zero initializer) or .data (non-zero); libbpf exposes the
+    section to userspace as a global-data map.
+    """
+
+    ctype_name: str = ""

pythonbpf/symbols.py

@@ -3,7 +3,7 @@
 import ctypes
 from llvmlite import ir
 
-from pythonbpf.local_symbol import LocalSymbol
+from pythonbpf.symbols import LocalSymbol
 from pythonbpf.vmlinux_parser.assignment_info import AssignmentType
 
 logger = logging.getLogger(__name__)