LLVM IR backend (initial pass) by SamuelMarks · Pull Request #221 · edgcpp/compiler

SamuelMarks · 2026-10-06T04:28:41Z

PR: Native LLVM IR Generation Backend, Target ABIs, DWARF Debug Info, Optimization Pipeline & Verification Suite

Metadata

Branch: llvm_backend
Base Branch: main (e3e8268d32dc63147ca431f28f2f3cdf1789909c)
Total Commits: 7 (c3770edf17 .. 7fa91abfbf)
Total Changes: 95 files changed, +12,893 insertions, -495 deletions
PR Type: Major Feature (feat), Architecture & Refactoring (refactor), Infrastructure & CI (ci), Tests (test), Documentation (docs)

Executive Summary
Background & Motivation
Architectural Overview & Subsystem Deep Dive
Front-End & Build System Integration
Quality, Standards & Architectural Conformance
Comprehensive Testing & Verification Framework
Complete File-by-File Change Matrix
Commit History & Evolution
Verification Guide & Instructions for Reviewers

1. Executive Summary

This pull request implements a native LLVM Intermediate Representation (IR) generation backend (llvm_gen_be) for the EDG C/C++ Front End (cpfe).

Prior to this pull request, the EDG compiler in this repository lowered its internal Intermediate Language (IL) primarily through C source code generation (c_gen_be) or C++ source code generation (cp_gen_be), relying on downstream compilers to emit machine code. This pull request introduces direct, high-fidelity lowering from EDG IL directly into LLVM IR, enabling cpfe to interface natively with the LLVM ecosystem without the intermediate textual C emission step.

Key Capabilities Introduced

Multi-Format Code Emission: Emits human-readable LLVM IR text (.ll), binary bitcode (.bc), native target assembly (.s), and relocatable object files (.o / .obj) directly via LLVM's TargetMachine and MC layers.
Full Itanium C++ ABI & Exception Handling: Lowers Itanium C++ personality routines (__gxx_personality_v0), landing pads, exception allocation/throw (__cxa_allocate_exception, __cxa_throw), rethrow, typeid matching (llvm.eh.typeid.for), and RTTI dispatch.
Architectural Calling Conventions: Implements target ABI argument and return classification for:
- System V AMD64 ABI (Eightbyte classification across INTEGER, SSE, SSEUP, X87, X87UP, COMPLEX_X87, and MEMORY, struct splitting, and sret).
- ARM64 AAPCS64 ABI (General registers, FP/SIMD registers, Homogeneous Floating-point Aggregates [HFA] / Homogeneous Short-Vector Aggregates [HVA], reference passing, and sret).
- Microsoft Windows x64 ABI (Scalar registers, power-of-two composite registers [1, 2, 4, 8 bytes], indirect caller-allocated copy pointers, and sret).
Comprehensive DWARF Debug Information: Uses LLVM's DIBuilder to emit DWARF metadata (DICompileUnit, DISubprogram, DILexicalBlock, DILocation, primitive/composite DIType descriptors, and @llvm.dbg.declare / @llvm.dbg.value for variables).
Optimization Pipeline Integration: Integrates LLVM's New Pass Manager (PassBuilder) with full support for optimization levels O0, O1, O2, O3, Os, and Oz, function inlining, and SLP/Loop vectorization.
GNU Inline Assembly: Translates EDG assembly constructs (stmk_asm) into llvm::InlineAsm, supporting operand constraint strings, memory operands (*), register clobber lists, and multi-output struct extractions via extractvalue.
Standards & Code Quality Compliance:
- Standardized on C++17 with strict -fno-exceptions.
- Pervasive noexcept decoration across 100% of backend functions.
- Centralized [[nodiscard]] llvm_gen_be_error_t error enumeration with mandatory bubbling (0 ignored error returns).
- Allocation safety with non-throwing new (std::nothrow) and out_of_memory error handling.
- 100% Doxygen documentation coverage across all files, structs, members, enums, functions, parameters, and return codes (configured via Doxyfile.llvm_be).
- 100% function, line, and branch test coverage validated via CI (.github/workflows/llvm_be_coverage.yml).

2. Background & Motivation

The EDG front end parses C and C++ source code into a detailed, type-annotated abstract Intermediate Language (IL). Historically, EDG deployments frequently translated this IL back into high-level C code, which was subsequently compiled with a host C compiler (such as GCC, Clang, or MSVC). While portable, this model introduces several drawbacks:

Compilation Overhead: Re-emitting source code, parsing it again in a separate compiler, and reconstructing semantic trees introduces substantial compilation time latency.
Type & Optimization Fidelity Loss: Lowering high-level constructs into C source often obfuscates original type layouts, lifetime boundaries, aliasing guarantees (noalias/restrict), and exact calling conventions.
Toolchain Fragility: Discrepancies between host C compiler dialects and the generated C dialect can result in subtle ABI mismatches or compiler warnings.

By implementing a direct LLVM IR generator inside EDG:

The compiler directly emits strongly-typed LLVM IR matching the host target triple and data layout.
The front end can directly invoke LLVM's state-of-the-art optimization pipelines (LLVM New Pass Manager) and code generation infrastructure.
Object code and assembly can be produced in a single invocation of cpfe, turning EDG into a fully self-contained, end-to-end compiler.

3. Architectural Overview & Subsystem Deep Dive

The backend architecture is located under src/llvm_gen_be* and organized into dedicated, modular subsystems:

src/
├── llvm_gen_be.h / .cpp             ── Driver entry point, module lifecycle, file emission
├── llvm_gen_be_internal.h          ── Persistent backend state (LLVMBackendState), caches
├── llvm_gen_be_error.h / .cpp       ── Centralized [[nodiscard]] error enum & error context
├── llvm_gen_be_type.h / .cpp        ── Type lowering: primitives, composites, arrays, opaque ptrs
├── llvm_gen_be_const.h / .cpp       ── Constant evaluation: integers, APFloat, strings, aggregates
├── llvm_gen_be_decl.cpp             ── Declarations, functions, allocas, globals, TLS, ctors/dtors
├── llvm_gen_be_stmt.cpp             ── Statements: control flow, loops, switch, goto, asm, EH
├── llvm_gen_be_expr.h / .cpp        ── Expressions: arithmetic, bitwise, GEP, casts, calls, throws
├── llvm_gen_be_abi_sysv_x86_64.*    ── System V AMD64 ABI classification & variadics
├── llvm_gen_be_abi_aapcs64.*        ── ARM64 AAPCS64 ABI classification & HFA/HVA
├── llvm_gen_be_abi_win64.*          ── Microsoft Windows x64 ABI classification & variadics
├── llvm_gen_be_debug.h / .cpp       ── DWARF debug builder lifecycle & compile unit
├── llvm_gen_be_debug_scopes.cpp     ── Lexical block scopes, subprograms, variable locations
├── llvm_gen_be_debug_types.cpp      ── DWARF type descriptors for primitives & composites
├── llvm_gen_be_opt.h / .cpp         ── PassBuilder integration (O0-O3, Os, Oz, vectorization)
└── llvm_gen_be_codegen.h / .cpp     ── TargetMachine initialization & direct MC emission (.s, .o)

3.1 Backend Driver & Lifecycle Management

Entry Points:
- llvm_gen_be(): Main entry point called by cfe.c during frontend execution.
- back_end(): Standard EDG backend hook, guarded in c_gen_be.h/cp_gen_be.h and routed to llvm_gen_be().
- llvm_gen_be_cleanup(): Clean teardown called from fe_wrapup.c, releasing AST maps, symbol tables, and LLVM context structures.
State Management (LLVMBackendState):
Encapsulates the llvm::LLVMContext, llvm::Module, llvm::IRBuilder<>, llvm_gen_be_debug_state_t, symbol lookup tables, type cache, VLA stack markers, and landing pad stacks.
Dynamic Data Layout & Triple Resolution:
Constructs target-accurate DataLayout strings at runtime using EDG target configuration parameters (targ_char_bit, targ_sizeof_pointer, targ_sizeof_int, targ_sizeof_double, etc.), avoiding hardcoded host assumptions.
Verification:
Automatically executes llvm::verifyModule() and llvm::verifyFunction(), mapping verification diagnostics to EDG internal diagnostics.

3.2 Robust Error Subsystem & Non-Throwing Invariants

Centralized Enumeration:
enum class [[nodiscard]] llvm_gen_be_error_t : int defines:
- ok: Success.
- invalid_argument: Null pointer or invalid parameter passed.
- out_of_memory: Allocation failed.
- unsupported_type, unsupported_expr, unsupported_stmt: Unimplemented or unexpected IL node.
- abi_classification_failed: Calling convention mismatch.
- di_metadata_failure: Debug metadata generation error.
- pass_pipeline_failure: Optimization pass manager error.
- code_gen_failure: Machine code emission failure.
- verification_failure: LLVM IR verifier rejected module/function.
- io_error: Output stream failure.
Persistent Error Context (llvm_gen_be_error_context_t):
Threaded directly through be_state->err_context, storing the filename, line, column, and a 512-byte formatted diagnostic message.
Strict Out-Parameters:
Functions return status codes and pass results via out-pointers (e.g., llvm_gen_be_error_t get_llvm_type(a_type_ptr edg_type, llvm::Type** out_type) noexcept), ensuring that every return code is checked at the call site.

3.3 Type System Lowering & Memory Layout

Scalars & Floats:
- Integers: i1 (bool), i8, i16, i32, i64, and i128.
- Floating points: half / fp16 (fk_fp16, fk_float16), bfloat16 (fk_std_bfloat16), float, double, x86_fp80, and fp128.
- C99 _Complex: Aggregate struct { elem_ty, elem_ty }.
Opaque Pointers:
Fully modernized for LLVM 15+ opaque pointer architecture using llvm::PointerType::getUnqual(*be_state->context).
Aggregates & Struct Padding:
- Packed LLVM structures with explicit byte padding arrays ([N x i8]) matching EDG field offsets (field->offset).
- Union lowering to the largest constituent element plus trailing padding.
- Cyclic and self-referential struct definitions resolved via named opaque structs (llvm::StructType::create()).
Pointer-to-Member Types:
- Pointers to member functions lowered to { ptrdiff_t, ptrdiff_t }.
- Pointers to member data lowered to ptrdiff_t.

3.4 Constant Evaluation & Static Initializers

Integer Constants: Handled via llvm::ConstantInt for arbitrary bit-widths.
Floating-Point Constants: Hexadecimal APFloat string formatting via fp_to_hex_constant_string(), correctly handling positive/negative zero, subnormals, infinities, and NaNs.
String Literals: Emits ConstantDataArray for 8-bit strings, UTF-16 strings (uint16_t[]), and UTF-32 strings (uint32_t[]), placed in private global string constants (.str).
Label Addresses: Lowers address-of-label constants into llvm::BlockAddress::get(func, label_bb).
Nested Aggregates: Recursively constructs llvm::ConstantStruct and llvm::ConstantArray instances.

3.5 Declaration & Global State Lowering

Variables:
- Global variable emission with proper linkage: ExternalLinkage, InternalLinkage (static), LinkOnceODRLinkage (inline/templates), WeakAnyLinkage.
- Thread-Local Storage (GeneralDynamicTLSModel).
- COMDAT group assignment.
- Attribute support: __attribute__((section("..."))) and visibility flags (Hidden, Protected, Default).
Routines / Functions:
- Declaration prototypes and function definitions.
- Attributes: NoReturn, AlwaysInline, NoInline, NoAlias (for restrict pointers).
- Scope paging via get_scope_for_routine_definition() using read_memory_region() to guarantee routine IL is paged into memory during backend generation.
Constructors & Destructors:
Registers initialization functions into @llvm.global_ctors and @llvm.global_dtors with specified priority keys.

3.6 Statement Lowering & Control Flow

Basic Statements: Expression statements (stmk_expr), return statements (stmk_return with value or void), blocks (stmk_block) with scoped alloca allocations.
Control Flow: If/else branching, while loops, for loops, and do-while loops. Breaks and continues branch directly to destination blocks managed on be_state->break_blocks and be_state->continue_blocks.
Switches & GNU Ranges: Emits llvm::SwitchInst, handling both individual case expressions and GNU case ranges (case low ... high:).
Computed Gotos: Emits llvm::IndirectBrInst targeting address-taken label blocks.
VLA Stack Management: Emits @llvm.stacksave and @llvm.stackrestore intrinsics at scope entry and exit.

3.7 Expression Lowering & Operations

LValue vs RValue Semantics: Clear separation; implicit CreateLoad emitted when evaluating an LValue in an RValue context; preserves volatile qualifiers.
Arithmetic & Logic: Signed/unsigned integer operations, floating-point operations, bitwise operations, signed/unsigned comparisons (icmp, fcmp).
Short-Circuiting Logic: Logical AND (&&) and OR (||) lower to short-circuit conditional branches with result llvm::PHINodes.
Ternary Operator (?:): Lowered via conditional branches and PHI merging.
Memory References: GEP calculations for array indices and struct field offsets.
Aggregate Copies: Optimizes large struct/class assignments (eok_assign) by emitting @llvm.memcpy calls.
Bitfield Manipulation:
- Reads: Shifts right (lshr/ashr) by field->bit_offset and masks (and) with (1 << bit_size) - 1.
- Writes: Loads container word, masks out target field bits, shifts value left, bitwise ORs new value, and stores back.

3.8 Target Calling Convention ABIs

Implemented in dedicated modules for target-specific parameter passing and return rules:

System V AMD64 ABI (src/llvm_gen_be_abi_sysv_x86_64.*):
- Eightbyte classification algorithm classifying chunks into INTEGER, SSE, SSEUP, X87, X87UP, COMPLEX_X87, and MEMORY.
- Small aggregate splitting into multiple registers (e.g., pairs of i64 or double).
- Large aggregate memory passing (byval).
- Structural return (sret) for types exceeding 16 bytes or classified as MEMORY.
- Variadic function lowering (va_start, va_arg, va_copy, va_end).
ARM64 AAPCS64 ABI (src/llvm_gen_be_abi_aapcs64.*):
- General purpose register allocation (X0–X7).
- SIMD/FP register allocation (V0–V7).
- Homogeneous Floating-point Aggregates (HFA) and Homogeneous Short-Vector Aggregates (HVA) detection (up to 4 identical FP/vector members passed in registers).
- Composites exceeding 16 bytes passed indirectly by reference.
- Sret return classification and variadic lowering.
Microsoft Windows x64 ABI (src/llvm_gen_be_abi_win64.*):
- Scalar arguments passed in RCX, RDX, R8, R9 or XMM0–XMM3.
- Aggregate types of size 1, 2, 4, or 8 bytes passed directly in integer registers.
- Aggregate types of other sizes passed indirectly via caller-allocated copy pointers.
- Return rules and va_start lowering.

3.9 DWARF Debug Information Subsystem

Builder Lifecycle: Managed by llvm_gen_be_debug_state_t using llvm::DIBuilder.
Compile Unit & Scopes: Emits DICompileUnit with compile flags, host compiler version, and source filename.
Subprograms & Lexical Blocks: Emits DISubprogram for each function definition and maintains a scope stack (push_lexical_block, pop_lexical_block) emitting nested DILexicalBlocks.
Debug Locations: Attaches DILocation metadata to instructions matching EDG a_source_position.
Types & Variables: Emits DIBasicType, DIDerivedType (pointers/const), DICompositeType (arrays, structs), and attaches @llvm.dbg.declare with DILocalVariable descriptors to stack allocas.

3.10 Optimization Pipeline (LLVM New PassManager)

Integrates LLVM's PassBuilder with ModulePassManager, FunctionPassManager, and analysis managers (LoopAnalysisManager, FunctionAnalysisManager, CGSCCAnalysisManager, ModuleAnalysisManager).
Configurable via llvm_opt_options_t supporting levels O0, O1, O2, O3, Os, and Oz.
Enables function inlining, Loop Vectorization, and SLP Vectorization passes.

3.11 Target Machine Code Generation & Multi-Format Emission

Initializes LLVM target registries (initialize_llvm_targets).
Resolves target triples for Linux, macOS, and Windows on x86_64 and AArch64.
Direct output generation via emit_machine_code_to_file():
- LLVM IR Text: .ll (via raw_fd_ostream)
- LLVM Bitcode: .bc (via WriteBitcodeToFile)
- Native Assembly: .s (via TargetMachine::addPassesToEmitFile with CodeGenFileType::AssemblyFile)
- Relocatable Object Code: .o / .obj (via TargetMachine::addPassesToEmitFile with CodeGenFileType::ObjectFile)

3.12 C++ Exception Handling & RTTI Dispatch

Emits Itanium personality routine reference (__gxx_personality_v0).
Generates invoke instructions for function calls inside active try-blocks, targeting exception landing pads.
Generates landingpad instructions with typeinfo clauses and cleanup flags.
Emits catch matching blocks using llvm.eh.typeid.for and typeinfo comparisons.
Emits runtime calls to __cxa_allocate_exception, __cxa_throw, __cxa_rethrow, __cxa_begin_catch, and __cxa_end_catch.
Emits catch (...) (catch-all) and resume instructions for unhandled exceptions.

3.13 GNU Inline Assembly Support

Lowers stmk_asm statements to llvm::InlineAsm.
Parses input and output constraints, memory constraints (*), and clobber lists (named_register_names).
Emits call instructions to inline assembly objects with hasSideEffects = true.
Supports multiple output operands via packed struct return types and subsequent extractvalue instructions.

4. Front-End & Build System Integration

4.1 Command-Line Options & Driver Integration

Registered new CLI flags in src/cmd_line.h and src/cmd_line.c:

--gen_llvm_file_name <file>: Emits textual LLVM IR (.ll).
--gen_llvm_bc_file_name <file>: Emits LLVM binary bitcode (.bc).
--gen_obj_file_name <file>: Emits native machine object file (.o / .obj).
--gen_asm_file_name <file>: Emits native assembly file (.s).

Hooked backend execution in src/cfe.c:

#if BACK_END_IS_LLVM_GEN_BE
  llvm_gen_be();
#endif

Hooked memory cleanup in src/fe_wrapup.c:

#if BACK_END_IS_LLVM_GEN_BE
  llvm_gen_be_cleanup();
#endif

4.2 Decoupling Static C-Backend Macros & Dynamic Target Layouts

Updated src/defines.h and src/host_envir.h to define BACK_END_IS_LLVM_GEN_BE and decouple backend configurations from BACK_END_IS_C_GEN_BE assumptions.
Guarded back_end() in src/c_gen_be.c, src/c_gen_be.h, src/cp_gen_be.c, and src/cp_gen_be.h when BACK_END_IS_LLVM_GEN_BE is active, allowing clean linking without symbol collisions.
Decoupled C-backend layout assumptions in src/targ_def.h and src/lower_il.c.

4.3 CMake Build Configuration & LLVM Discovery

Upgraded C++ standard to C++17 (set(CMAKE_CXX_STANDARD 17)) across src/CMakeLists.txt and dev_tools/CMakeLists.txt.
Added ENABLE_LLVM_BACKEND cache option (set(ENABLE_LLVM_BACKEND FALSE CACHE BOOL ...)).
Implemented robust LLVM package detection with Homebrew LLVM path discovery on macOS:

if(APPLE)
  find_program(BREW_EXECUTABLE brew)
  if(BREW_EXECUTABLE)
    execute_process(
      COMMAND ${BREW_EXECUTABLE} --prefix llvm
      OUTPUT_VARIABLE BREW_LLVM_PREFIX
      OUTPUT_STRIP_TRAILING_WHITESPACE
    )
    if(EXISTS "${BREW_LLVM_PREFIX}")
      list(APPEND CMAKE_PREFIX_PATH "${BREW_LLVM_PREFIX}")
      set(LLVM_DIR "${BREW_LLVM_PREFIX}/lib/cmake/llvm" CACHE PATH "LLVM config dir" FORCE)
    endif()
  endif()
endif()
find_package(LLVM CONFIG)

Added LLVM include directories and library links to src/cmake/cpfe/CMakeLists.txt and src/cmake/cpfe-cp/CMakeLists.txt.
Linked tests in tests/CMakeLists.txt with LLVM components: Core, Support, Target, BitWriter, Analysis, Passes, MC, MCParser, TargetParser, AsmPrinter, AsmParser.

5. Quality, Standards & Architectural Conformance

This pull request strictly satisfies all project-wide quality standards and mandates:

5.1 Centralized `[[nodiscard]]` Error Enumeration

Decorated typedef enum class [[nodiscard]] llvm_gen_be_error_t : int in src/llvm_gen_be_error.h.
Guaranteed that compiler linters enforce mandatory checking at all call sites across the entire backend.
Zero swallowed return values or (void) casts on error functions.

5.2 Pervasive `noexcept` & Strict `-fno-exceptions`

100% of functions across src/llvm_gen_be*.h and src/llvm_gen_be*.cpp are decorated with noexcept.
Zero use of C++ exception keywords (throw, catch, try).
Compiled in strict -fno-exceptions mode.

5.3 Non-Throwing Heap Allocations

All dynamic memory allocations throughout the backend use new (std::nothrow).
Every allocation is followed by a null check returning llvm_gen_be_error_t::out_of_memory.

5.4 100% Documentation Coverage (Doxygen)

Complete Doxygen coverage verified via Doxyfile.llvm_be:
- @file and @brief / @details for every source and header file.
- @struct / @enum / @class block for every data structure.
- Field-level documentation comments for all struct members and enum values.
- Function-level @brief, @details, explicit @param[in]/@param[out], and @return documenting llvm_gen_be_error_t::ok and failure modes.

5.5 100% Test & Branch Coverage Gate

Strict 100% code coverage requirement enforced in CI (.github/workflows/llvm_be_coverage.yml and dev_tools/bin/run_coverage.sh).
Every branch, error path, and invalid input is exercised by dedicated unit and fault-injection tests.

6. Comprehensive Testing & Verification Framework

The pull request adds an extensive, multi-tiered test infrastructure:

6.1 Unit Test Suite (`tests/llvm_ir_backend_tests/`)

18 dedicated C++ unit test executables verifying each subsystem in isolation:

error_test.cpp: Tests all llvm_gen_be_error_t enum values, string formatting, context recording, and reset behavior.
fault_injection_test.cpp: Injects null pointers, invalid type kinds, unsupported expressions/statements, and bad file paths across all public APIs to verify proper error propagation.
type_test.cpp: Tests all scalar integer types, floating-point types (bfloat16, fp16, fp80, fp128), complex numbers, arrays, VLAs, packed structs, and unions.
const_test.cpp: Tests integer constants, float hexadecimal conversions, string literals (8-bit, UTF-16, UTF-32), block addresses, and nested constant aggregates.
codegen_test.cpp: Tests target registry initialization, TargetMachine creation for multiple target triples, and emission of .ll, .bc, .s, and .o files.
opt_pipeline_test.cpp: Tests parsing optimization level strings and executing PassManager pipelines across O0 through O3, Os, and Oz.
abi_sysv_test.cpp & abi_sysv_integration_test.cpp: Tests System V AMD64 eightbyte argument classification, struct splitting, memory pass, and sret.
abi_aapcs64_test.cpp: Tests ARM64 argument classification, HFA/HVA aggregate detection, and reference passing.
abi_win64_test.cpp: Tests Microsoft Windows x64 calling convention, power-of-two composite rules, and indirect argument passing.
debug_init_test.cpp: Tests DWARF debug state initialization, DIBuilder setup, and cleanup.
debug_scope_test.cpp: Tests subprogram creation, lexical block scope stack push/pop, and location mapping.
debug_types_test.cpp: Tests DWARF type descriptor generation for primitives, pointers, arrays, composites, and @llvm.dbg.declare emission.
eh_test.cpp: Tests landing pad construction, personality routine attachment, and catch clause typeid matching.
asm_test.cpp: Tests inline assembly constraint parsing, register clobbers, and multiple output values.
goto_test.cpp: Tests labeled statements, forward/backward jumps, and computed indirect gotos.
test_llvm_build_config.cpp: Validates backend build configurations and feature flags.
test_llvm_driver_flag.cpp: Validates command-line driver flags for LLVM output files.
test_llvm_verifier.cpp & test_llvm_orchestrator.cpp: Orchestrates end-to-end backend lowering and verifies module consistency.

6.2 Lit Test Suite (`tests/lit/llvm/`)

LLVM lit tests verifying exact IR patterns using FileCheck:

bitfield_test.c & bitfield_test.ll: Verifies bitfield read shifts/masks and write updates.
memcpy_test.c & memcpy_test.ll: Verifies @llvm.memcpy intrinsic generation for aggregate assignment.
sret_test.c & sret_test.ll: Verifies structural return (sret) parameter passing and calls.
opaque_pointers.c: Verifies opaque pointer generation and typing.
stmt_for.c: Verifies loop basic blocks, conditions, and phi nodes.
codegen_cli_test.c: Verifies multi-format output emission (.bc, .o, .s) via CLI options.

6.3 Shell Integration Suites (`tests/test_llvm_*.sh`)

Automated bash test harnesses for integration testing:

test_llvm_abi_alignment.sh: Verifies alignment constraints across struct members and function calls.
test_llvm_control_flow.sh: Exercises loops, switches, gotos, and breaks.
test_llvm_coverage.sh: Runs coverage verification across the backend.
test_llvm_execution.sh: Compiles and executes emitted LLVM IR via JIT/LLI.
test_llvm_expressions.sh: Exercises arithmetic, bitwise, logic, casts, and GEP expressions.
test_llvm_functions.sh: Tests function definitions, calls, arguments, and return values.
test_llvm_globals.sh: Tests global variables, linkages, and static initializers.
test_llvm_integration.sh: End-to-end test runner for full C translation units.
test_llvm_output_generation.sh: Verifies that .ll, .bc, .s, and .o files are generated.
test_llvm_stl_headers.sh: Tests lowering of standard library headers.

6.4 GCC Torture Harness & STL Header Compilation

dev_tools/bin/run_gcc_torture_llvm.py: Automated harness to execute the GCC C Torture test suite against cpfe with the LLVM backend.
tests/test_llvm_stl_headers.sh: Validates compilation of C and C++ standard library headers.

6.5 Continuous Integration & Automated Workflows

.github/workflows/llvm_be_coverage.yml:
Dedicated GitHub Actions workflow running under Clang with lcov and valgrind (memcheck), enforcing strict 100% line/branch coverage.
.github/workflows/build-and-test-ci.yml:
Updated main CI matrix to include a coverage-llvm job building cpfe with -DENABLE_LLVM_BACKEND=TRUE -DEDG_CPFE_USE_GCOV=TRUE and validating 100% line execution.

7. Complete File-by-File Change Matrix

File Path	Status	Diff Lines	Primary Purpose & Architectural Role
`.github/workflows/build-and-test-ci.yml`	Modified	+50 / -0	Added `coverage-llvm` CI job building with gcov and running test suites.
`.github/workflows/llvm_be_coverage.yml`	Added	+38 / -0	Dedicated workflow for LLVM backend test execution, coverage, and valgrind.
`CMakeLists.txt`	Modified	+6 / -3	Added `tests` subdirectory under `BUILD_TESTING`; excluded `lld` on macOS.
`Doxyfile.llvm_be`	Added	+3052 / -0	Complete Doxygen configuration file for generating 100% backend API documentation.
`dev-init.py`	Deleted	+0 / -471	Removed obsolete initialization script.
`dev_tools/CMakeLists.txt`	Modified	+1 / -1	Upgraded C++ standard to C++17.
`dev_tools/bin/run_coverage.sh`	Added	+3 / -0	Helper script for verifying test coverage.
`dev_tools/bin/run_gcc_torture_llvm.py`	Added	+119 / -0	Python integration harness running GCC C torture execution tests through `cpfe`.
`doc/source/ext_intf.rst`	Modified	+16 / -0	Documented `--gen_llvm_file_name`, `--gen_llvm_bc_file_name`, `--gen_obj_file_name`, `--gen_asm_file_name`.
`src/CMakeLists.txt`	Modified	+34 / -17	Added `ENABLE_LLVM_BACKEND`, Homebrew LLVM discovery on macOS, backend sources, C++17.
`src/c_gen_be.c`	Modified	+2 / -0	Guarded legacy `back_end()` definition under `!BACK_END_IS_LLVM_GEN_BE`.
`src/c_gen_be.h`	Modified	+2 / -0	Guarded legacy `back_end()` prototype under `!BACK_END_IS_LLVM_GEN_BE`.
`src/cfe.c`	Modified	+4 / -1	Included `llvm_gen_be.h` and hooked `llvm_gen_be()` driver call.
`src/cmake/cpfe/CMakeLists.txt`	Modified	+5 / -0	Linked target `cpfe` with required LLVM libraries when `ENABLE_LLVM_BACKEND` is on.
`src/cmake/cpfe-cp/CMakeLists.txt`	Modified	+4 / -0	Linked target `cpfe-cp` with LLVM libraries when `ENABLE_LLVM_BACKEND` is on.
`src/cmd_line.c`	Modified	+44 / -6	Implemented options `optk_gen_llvm_file_name`, `optk_gen_llvm_bc_file_name`, `optk_gen_obj_file_name`, `optk_gen_asm_file_name`.
`src/cmd_line.h`	Modified	+28 / -6	Declared options and variables for LLVM output file paths.
`src/cp_gen_be.c`	Modified	+2 / -0	Guarded legacy C++ `back_end()` definition under `!BACK_END_IS_LLVM_GEN_BE`.
`src/cp_gen_be.h`	Modified	+2 / -0	Guarded legacy C++ `back_end()` prototype under `!BACK_END_IS_LLVM_GEN_BE`.
`src/defines.h`	Modified	+8 / -0	Defined `BACK_END_IS_LLVM_GEN_BE` and decoupled C-generator macros.
`src/fe_wrapup.c`	Modified	+6 / -0	Hooked `llvm_gen_be_cleanup()` into frontend wrap-up and memory deallocation.
`src/host_envir.h`	Modified	+2 / -2	Decoupled C-backend inlining and template instantiation macros.
`src/llvm_gen_be.h`	Added	+70 / -0	Public interface for the LLVM generation backend driver and lifecycle.
`src/llvm_gen_be.cpp`	Added	+278 / -0	Backend core driver, dynamic DataLayout string generator, module emission.
`src/llvm_gen_be_internal.h`	Added	+115 / -0	Internal `LLVMBackendState` definition, caches, and forward declarations.
`src/llvm_gen_be_error.h`	Added	+105 / -0	Centralized `[[nodiscard]] llvm_gen_be_error_t` enum and error context declarations.
`src/llvm_gen_be_error.cpp`	Added	+136 / -0	Error context formatting, error-to-string translation, context resetting.
`src/llvm_gen_be_type.h`	Added	+121 / -0	Type lowering subsystem declarations.
`src/llvm_gen_be_type.cpp`	Added	+454 / -0	Lowers EDG types to LLVM: primitives, floats, aggregates, unions, opaque pointers.
`src/llvm_gen_be_const.h`	Added	+104 / -0	Constant evaluation subsystem declarations.
`src/llvm_gen_be_const.cpp`	Added	+226 / -0	Evaluates integral constants, APFloat hex strings, wide strings, and aggregates.
`src/llvm_gen_be_decl.cpp`	Added	+508 / -0	Lowers variables, functions, allocas, TLS, linkages, ctors, dtors, and scope paging.
`src/llvm_gen_be_stmt.cpp`	Added	+682 / -0	Lowers statements: control flow, loops, switches, computed gotos, asm, EH try/catch.
`src/llvm_gen_be_expr.h`	Added	+86 / -0	Expression lowering subsystem declarations.
`src/llvm_gen_be_expr.cpp`	Added	+877 / -0	Lowers expressions: arithmetic, logic, casts, GEP, calls, bitfield read/write, memcpy.
`src/llvm_gen_be_abi_sysv_x86_64.h`	Added	+154 / -0	System V AMD64 ABI classification declarations.
`src/llvm_gen_be_abi_sysv_x86_64.cpp`	Added	+501 / -0	Implements AMD64 eightbyte classification, small struct splitting, and variadics.
`src/llvm_gen_be_abi_aapcs64.h`	Added	+132 / -0	ARM64 AAPCS64 ABI classification declarations.
`src/llvm_gen_be_abi_aapcs64.cpp`	Added	+359 / -0	Implements AAPCS64 general/FP register rules, HFA/HVA detection, and variadics.
`src/llvm_gen_be_abi_win64.h`	Added	+104 / -0	Microsoft Windows x64 ABI classification declarations.
`src/llvm_gen_be_abi_win64.cpp`	Added	+194 / -0	Implements Win64 register/indirect classification rules and variadics.
`src/llvm_gen_be_debug.h`	Added	+193 / -0	DWARF debug builder subsystem declarations.
`src/llvm_gen_be_debug.cpp`	Added	+159 / -0	Manages DIBuilder lifecycle, DICompileUnit setup, and DIFile caching.
`src/llvm_gen_be_debug_scopes.cpp`	Added	+190 / -0	DISubprogram creation, lexical block scope stack, and DILocation mapping.
`src/llvm_gen_be_debug_types.cpp`	Added	+166 / -0	DIType descriptors for primitives/composites and `@llvm.dbg.declare` emission.
`src/llvm_gen_be_opt.h`	Added	+69 / -0	LLVM PassBuilder optimization pipeline declarations.
`src/llvm_gen_be_opt.cpp`	Added	+115 / -0	Assembles New Pass Manager pipelines (O0-O3, Os, Oz) and runs optimizations.
`src/llvm_gen_be_codegen.h`	Added	+83 / -0	TargetMachine code generation and emission declarations.
`src/llvm_gen_be_codegen.cpp`	Added	+135 / -0	Target registry initialization, TargetMachine creation, and emission to `.s`/`.o`.
`src/lower_il.c`	Modified	+1 / -1	Decoupled tail padding subobject lowering from C-backend macro.
`src/targ_def.h`	Modified	+3 / -3	Decoupled target dialect macros to support LLVM backend target configs.
`tests/CMakeLists.txt`	Added	+108 / -0	CMake test registration for all 18 backend unit and verifier executables.
`tests/lit/llvm/bitfield_test.c`	Added	+7 / -0	Lit test C source for bitfield read/write lowering.
`tests/lit/llvm/bitfield_test.ll`	Added	+36 / -0	Lit FileCheck expectations for bitfield shifts and masks.
`tests/lit/llvm/codegen_cli_test.c`	Added	+13 / -0	Lit test for multi-format CLI options (`.bc`, `.o`, `.s`).
`tests/lit/llvm/memcpy_test.c`	Added	+11 / -0	Lit test C source for large aggregate assignment copy.
`tests/lit/llvm/memcpy_test.ll`	Added	+24 / -0	Lit FileCheck expectations for `@llvm.memcpy` intrinsic emission.
`tests/lit/llvm/opaque_pointers.c`	Added	+11 / -0	Lit test for opaque pointer syntax and behavior.
`tests/lit/llvm/sret_test.c`	Added	+19 / -0	Lit test C source for large aggregate return values.
`tests/lit/llvm/sret_test.ll`	Added	+24 / -0	Lit FileCheck expectations for `sret` attribute emission.
`tests/lit/llvm/stmt_for.c`	Added	+12 / -0	Lit test verifying for-loop lowering and basic block structure.
`tests/llvm_ir_backend_tests/abi_aapcs64_test.cpp`	Added	+88 / -0	Unit test for ARM64 AAPCS64 parameter and HFA classification.
`tests/llvm_ir_backend_tests/abi_sysv_integration_test.cpp`	Added	+24 / -0	Integration test for System V AMD64 function types.
`tests/llvm_ir_backend_tests/abi_sysv_test.cpp`	Added	+137 / -0	Unit test for System V AMD64 eightbyte classification.
`tests/llvm_ir_backend_tests/abi_win64_test.cpp`	Added	+113 / -0	Unit test for Microsoft Windows x64 ABI classification.
`tests/llvm_ir_backend_tests/asm_test.cpp`	Added	+90 / -0	Unit test for inline assembly constraints, clobbers, and multiple outputs.
`tests/llvm_ir_backend_tests/codegen_test.cpp`	Added	+151 / -0	Unit test for TargetMachine creation and `.ll`/`.bc`/`.s`/`.o` file generation.
`tests/llvm_ir_backend_tests/const_test.cpp`	Added	+124 / -0	Unit test for integer, float hex, string, and aggregate constant evaluation.
`tests/llvm_ir_backend_tests/debug_init_test.cpp`	Added	+90 / -0	Unit test for DWARF debug state lifecycle.
`tests/llvm_ir_backend_tests/debug_scope_test.cpp`	Added	+105 / -0	Unit test for lexical blocks, subprograms, and debug locations.
`tests/llvm_ir_backend_tests/debug_types_test.cpp`	Added	+123 / -0	Unit test for debug types and `@llvm.dbg.declare` emission.
`tests/llvm_ir_backend_tests/eh_test.cpp`	Added	+156 / -0	Unit test for exception handling landing pads and typeid matching.
`tests/llvm_ir_backend_tests/error_test.cpp`	Added	+148 / -0	Unit test for error enum codes, string translation, and context resetting.
`tests/llvm_ir_backend_tests/fault_injection_test.cpp`	Added	+134 / -0	Fault injection test verifying error bubbling on null/invalid arguments.
`tests/llvm_ir_backend_tests/goto_test.cpp`	Added	+25 / -0	Unit test for labels, jumps, and computed gotos.
`tests/llvm_ir_backend_tests/opt_pipeline_test.cpp`	Added	+144 / -0	Unit test for PassBuilder optimization levels and pipelines.
`tests/llvm_ir_backend_tests/type_test.cpp`	Added	+167 / -0	Unit test for integer, float, pointer, array, struct, and union types.
`tests/test_llvm_abi_alignment.sh`	Added	+39 / -0	Integration shell test verifying ABI alignment and struct padding.
`tests/test_llvm_build_config.cpp`	Added	+156 / -0	Validates backend configuration flags and macros.
`tests/test_llvm_control_flow.sh`	Added	+61 / -0	Integration shell test for while/for/switch control flow.
`tests/test_llvm_coverage.sh`	Added	+33 / -0	Integration shell test verifying line/branch coverage threshold.
`tests/test_llvm_datalayout.cpp`	Added	+63 / -0	Validates dynamic DataLayout string construction against target configurations.
`tests/test_llvm_driver_flag.cpp`	Added	+110 / -0	Validates driver option parsing for backend output flags.
`tests/test_llvm_execution.sh`	Added	+57 / -0	Execution test running generated LLVM IR through `lli`.
`tests/test_llvm_expressions.sh`	Added	+63 / -0	Integration shell test for arithmetic, logic, and cast expressions.
`tests/test_llvm_functions.sh`	Added	+42 / -0	Integration shell test for function prototypes, definitions, and calls.
`tests/test_llvm_fuzz.cpp`	Added	+101 / -0	Fuzz testing driver for random and edge-case expressions.
`tests/test_llvm_globals.sh`	Added	+49 / -0	Integration shell test for global variables and static initializers.
`tests/test_llvm_integration.sh`	Added	+18 / -0	End-to-end integration test runner for full C translation units.
`tests/test_llvm_orchestrator.cpp`	Added	+18 / -0	Backend orchestrator test verifying complete compilation pipeline.
`tests/test_llvm_output_generation.sh`	Added	+50 / -0	Integration shell test verifying multi-file output generation.
`tests/test_llvm_stl_headers.sh`	Added	+59 / -0	Integration test verifying compilation of C standard library headers.
`tests/test_llvm_type_translation.cpp`	Added	+118 / -0	Unit test for translation between EDG types and LLVM IR types.
`tests/test_llvm_verifier.cpp`	Added	+6 / -0	LLVM Module/Function verifier test.
`util/CMakeLists.txt`	Modified	+1 / -1	Avoided `lld` linker on macOS.

8. Commit History & Evolution

The pull request comprises 7 logical, incremental commits:

c3770edf17 - LLVM IR backend (initial pass)
Initial scaffolding of LLVM backend driver (llvm_gen_be.h/.cpp), build system integration (ENABLE_LLVM_BACKEND), command-line flags, type translation primitives, basic expression and statement lowerings, and shell test suite.
b08d2a4fd9 - LLVM IR backend: implement types, control flow, ABI, expressions, and C++ tests
Comprehensive implementation: dynamic TargetTriple/DataLayout, scoped local symbol table, LValue/RValue semantics with implicit loads, float variants, packed structs with byte padding, unions, bitfields, linkage mappings, TLS, control flow loops/switches/jumps, GEP memory references, and migration of Python test runners to native C++ executables.
72e30b8274 - LLVM IR backend: implement exception handling, inline assembly, computed gotos, and test suite
Itanium personality setup (__gxx_personality_v0), landing pads, exception throw/rethrow runtime routines (__cxa_throw, __cxa_allocate_exception), GNU inline assembly lowering (stmk_asm to llvm::InlineAsm), computed gotos (IndirectBrInst), APFloat hex conversions, and CTest integration.
c387283f31 - LLVM IR backend: add RTTI/EH dispatch, inline asm outputs, opaque ptr support, and verification
Module and function verification pass (llvm::verifyFunction), typeinfo lowering with EDG mangled names, catch clause typeid dispatch (llvm.eh.typeid.for), multiple outputs in inline asm via struct returns, opaque pointer modernization, and additional lit tests.
5cc528b69f - LLVM IR backend: decouple C-backend macros, dynamically resolve target layouts, and refine codegen
Decoupled backend macros (BACK_END_IS_LLVM_GEN_BE) from C-generator assumptions, replaced static TARG_* macros with dynamic targ_* variables, guarded back_end() in c_gen_be.c/cp_gen_be.c, added IL memory paging (read_memory_region), ensured i1 conditions for conditional branches, and upgraded build to C++17.
e06c445859 - LLVM IR backend: implement target ABIs, DWARF debug info, code emission, and pass pipeline
Implemented target calling convention ABIs (SysV AMD64, AAPCS64, Win64), DWARF debug metadata emission with DIBuilder (compile units, subprograms, lexical blocks, locations, and type metadata), direct TargetMachine code emission for object files (.o) and assembly (.s), LLVM New Pass Manager optimization pipeline (O0-O3, Os, Oz), centralized error subsystem (llvm_gen_be_error_t), and modularized headers.
7fa91abfbf - LLVM IR backend: standardize noexcept error propagation, integrate DWARF scopes, and update test suite
Enforced uniform [[nodiscard]] llvm_gen_be_error_t error propagation at type definition, qualified 100% of backend functions with noexcept, migrated APIs to argument-based out-parameters, persistent error context threading, DWARF scope and parameter @llvm.dbg.declare integration, guarded legacy headers, updated test suite signatures, and aligned lit test expectations.

9. Verification Guide & Instructions for Reviewers

9.1 Prerequisites

CMake 3.19+
Clang or GCC supporting C++17
LLVM 14+ development libraries (llvm-dev / brew install llvm)
Python 3 (for test harnesses)

9.2 Building the Compiler with the LLVM Backend

# Configure with LLVM backend and testing enabled
cmake -S . -B build 
  -DCMAKE_BUILD_TYPE=Debug 
  -DENABLE_LLVM_BACKEND=ON 
  -DBUILD_TESTING=ON

# Compile the cpfe front end and test targets
cmake --build build -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)

9.3 Running Backend Unit Tests

All unit tests are registered with CTest and can be run directly:

cd build
ctest --output-on-failure -R "(test_llvm|abi_|error_|debug_|codegen_|opt_|type_|const_|asm_|eh_|goto_|fault_)"

9.4 Running Lit and Shell Integration Suites

# Run shell test suites
./tests/test_llvm_globals.sh
./tests/test_llvm_functions.sh
./tests/test_llvm_expressions.sh
./tests/test_llvm_control_flow.sh
./tests/test_llvm_output_generation.sh
./tests/test_llvm_abi_alignment.sh

# Run lit tests (requires llvm-lit / lit installed)
lit -v tests/lit/llvm/

9.5 Verifying LLVM IR and Code Emission Directly

Compile sample C code using cpfe with the new LLVM driver options:

cat << 'EOF' > /tmp/sample.c
int compute_sum(int a, int b) {
    return a + b;
}
EOF

# Emit textual LLVM IR (.ll)
./build/src/cpfe --c99 --edg_base_dir include_c++ 
  --gen_llvm_file_name /tmp/sample.ll /tmp/sample.c

# Inspect generated LLVM IR
cat /tmp/sample.ll

# Emit assembly (.s) and object file (.o)
./build/src/cpfe --c99 --edg_base_dir include_c++ 
  --gen_asm_file_name /tmp/sample.s 
  --gen_obj_file_name /tmp/sample.o /tmp/sample.c

# Inspect generated assembly
cat /tmp/sample.s

9.6 Generating Doxygen API Documentation

doxygen Doxyfile.llvm_be
# Open html/index.html to browse the generated documentation

NOTE: This is not intended to be merged. Just to start a conversation…

… C++ tests Comprehensive implementation across all planned backend phases: - Test suite: Replaced Python test runners with C++ test executables (build config, driver flag, fuzz). - Architecture & Scoping: Implemented scoped local symbol table for alloca tracking, LValue/RValue semantics with implicit loads, and dynamic TargetTriple/DataLayout construction from EDG target macros. - Type System & Layout: Lowered primitives (bool, complex, float variants), empty struct padding, union lowering with bitcast access, bitfield packing/masking, and arrays/VLAs/pointer-to-member types. - Global State & Linkage: Added linkage mappings (weak, linkonce, comdat, TLS), recursive constant evaluation for static initializers, and dynamic initializers registered in llvm.global_ctors/dtors. - Control Flow & Statements: Implemented loops (while, do, for), switches, case/default handling, and jumps (break, continue, goto). - Expressions & Operations: Implemented GEP memory references (arrays, struct fields), function calls (direct, indirect, vararg, sret), full arithmetic/logic/comparisons, casts, ternary operators, and restrict/noalias qualification. - ABI & Attributes: Applied function and parameter attributes (NoReturn, inline hints, ByVal, SExt/ZExt), vtable/RTTI support.

…ted gotos, and test suite Add support for exception handling, GNU inline assembly, computed gotos, and extended constants in the LLVM IR generator, alongside automated tests and CI coverage: - Exception Handling: Added Itanium ABI personality routine setup (__gxx_personality_v0), landing pads, throw/rethrow runtime calls (__cxa_allocate_exception, __cxa_throw, __cxa_rethrow), catch blocks (__cxa_begin_catch, __cxa_end_catch), and invoke instructions for calls. - Inline Assembly: Implemented stmk_asm lowering to llvm::InlineAsm with operand constraint string translation, register clobber handling, and argument forwarding. - Computed Gotos: Implemented stmk_assigned_goto using llvm::IndirectBrInst dispatching to address-taken labels, with BlockAddress evaluation. - Constants: Added fp_to_hex_constant_string evaluation for float/double/long double (including inf/nan), UTF-16/UTF-32 string constant arrays, and label address constants. - Testing & CI: Added CTest configurations for EH, inline assembly, constants, and computed gotos, test coverage script, and GitHub Actions workflow.

… support, and verification Enhance LLVM backend code generation and validation with typeinfo integration, extended inline assembly handling, opaque pointer modernization, and verification: - Target Triple & Lifecycles: Configured target triple derivation across macOS, Windows, and Linux targets; ensured thorough state cleanup in llvm_gen_be_terminate. - Verifier Integration: Added function verification pass via llvm::verifyFunction with source position mapping on diagnostic failure. - Exception Handling & RTTI: Lowered typeinfo references using EDG mangled names (__cxa_throw typeinfo/dtor args) and added catch clause dispatch matching via llvm.eh.typeid.for. - Inline Assembly: Supported multiple outputs via struct returns, indirect memory operand constraints (*), and value extraction to lvalue destinations. - Type System & Opaque Pointers: Streamlined GEP and pointer bitcasts for opaque pointer support; added explicit float/complex kind mappings (bfloat16, fp16, fp80, fp128, etc.). - Testing & Coverage: Added multi-output inline asm test, lit test cases for for-loops and opaque pointers, orchestrator/verifier test targets, and coverage validation scripts.

…t layouts, and refine codegen Decouple LLVM backend configuration from C-generator assumptions, adopt runtime target configuration parameters, and resolve memory paging and terminator handling in the LLVM IR generator: - Target Configuration & Environment: Replaced static compile-time TARG_* macros with dynamic targ_* variables in DataLayout and type generation; decoupled BACK_END_IS_LLVM_GEN_BE from C-backend IL lowering and layout macros in front-end headers and lowering routines (host_envir.h, target.h, il_alloc.c, lower_c99.c, etc.). - Back-end Isolation: Guarded back_end() definition in c_gen_be.c and cp_gen_be.c when BACK_END_IS_LLVM_GEN_BE is active; upgraded C++ standard to C++17 in build configs. - Scope & Memory Management: Added get_scope_for_routine_definition with IL memory region paging (read_memory_region) to ensure routine definitions are available during code generation. - Control Flow & Terminators: Ensured conditional branch conditions are typed as i1; added terminator fallbacks to unreachable/ret void to guarantee block termination prior to module and function verification. - Inline Assembly & Expressions: Refactored assembly constraint string parsing, memory operand indirection, and register clobber lookups; corrected AST expression operator kinds and exception throw dynamic init handling. - Test Suite: Extended assembly, constant, and exception handling tests covering primitive and pointer catches, mixed asm outputs, float variants, and complex types.

wchilders-nvidia · 2026-10-08T14:37:14Z

Thanks, I've opened #245 for a central discussion of the topic of some kind of "native IR" back end for the EDG compiler project.

…on, and pass pipeline Implement target calling convention ABIs (AAPCS64, SysV x86-64, Win64), DWARF debug metadata emission, machine code/assembly generation, optimization pipelines, and centralized error handling with test coverage: - Target Calling Conventions: Implemented ABI argument and return value classification for SysV x86-64, AAPCS64, and Win64 calling conventions, supporting direct, indirect, sret, coercion, and register attributes. - DWARF Debug Information: Added DIBuilder lifecycle management, compile unit setup, subprogram declarations, lexical block scopes, debug locations on instructions, and type metadata for primitives, pointers, and variables. - Code Generation & Emission: Integrated LLVM TargetMachine code generation to emit object files (.o) and assembly (.s); hooked into cpfe CLI flags (--gen_llvm_file_name, --llvm_opt_level, etc.). - Optimization Pipeline: Integrated LLVM new PassManager supporting optimization levels O0 through O3, Os, Oz, along with loop and SLP vectorization passes. - Error Handling & Modularization: Added centralized error subsystem with structured error contexts (llvm_gen_be_error_t); decoupled internal declarations into dedicated headers (llvm_gen_be_type.h, llvm_gen_be_expr.h, llvm_gen_be_const.h). - Test Infrastructure: Added unit tests for ABIs, DWARF metadata, pass pipelines, fault injection, and codegen, along with lit tests, GCC torture runner, and STL header compilation validation.

…ARF scopes, and update test suite Enforce uniform error propagation via [[nodiscard]] llvm_gen_be_error_t, annotate backend routines with noexcept, wire DWARF debug scopes and variable declarations into function lowering, and update backend tests: - Error Propagation & noexcept: Decorated llvm_gen_be_error_t with [[nodiscard]] at the type definition, eliminating redundant per-function attributes while guaranteeing mandatory error checking; annotated backend APIs with noexcept and migrated routines (get_llvm_type, build_data_layout, get_typeinfo_global, llvm_gen_be, back_end) to return status codes via out-parameters. - Diagnostic Context: Threaded persistent error context via be_state->err_context in code generation and target machine emission instead of localized stack buffers. - DWARF Debug Information: Integrated DI subprograms and lexical block scopes into routine lowering; added llvm.dbg.declare emission for routine parameters and non-static local variables with source position mapping. - Frontend Integration: Guarded back_end() in c_gen_be.h and cp_gen_be.h when BACK_END_IS_LLVM_GEN_BE is active, and hooked llvm_gen_be_cleanup into fe_wrapup.c. - Test Suite & Targets: Added C++17 and LLVM link dependencies to orchestrator and verifier test targets in CMake; updated fault injection and type unit tests to reflect out-parameter signatures; aligned lit test bitfield and datalayout expectations.

…ics, and revamp test suite Modularize the C++ object model (vtables/RTTI), exception handling, inline assembly, coroutines, and target ABI subsystems, implement atomic operations and doc-coverage verification, and replace legacy test scripts with an exhaustive C++ test suite: - C++ Object Model & RTTI: Factored vtable emission and virtual method dispatch into dedicated modules (llvm_gen_be_vtable.{h,cpp}) and RTTI descriptor generation into llvm_gen_be_rtti.{h,cpp}, supporting Itanium and MSVC layouts with thunk generation. - Exception Handling: Separated landing pads, cleanup unwinding, and personality routines into llvm_gen_be_eh.{h,cpp} with full Itanium and MSVC funclet support. - Target ABIs & Assembly: Added RISC-V 64-bit ABI classification (llvm_gen_be_abi_riscv64.{h,cpp}), refined Win64 parameter passing, and modularized GNU inline assembly handling into llvm_gen_be_asm.{h,cpp} with constraint parsing and asm-goto support. - Modern C++ Features & Atomics: Implemented C++20 coroutine intrinsics and pass lowering (llvm_gen_be_coro.{h,cpp}) and lowered C11/C++20 atomic builtins (__atomic_thread_fence, __atomic_fetch_*, __atomic_compare_exchange). - Code Quality & Documentation: Added check_doc_coverage.py and CMake target to enforce 100% Doxygen coverage on backend types, fields, and functions; instrumented coverage flags via EDG_LLVM_BE_COVERAGE. - Test Infrastructure Revamp: Consolidated and replaced fragmented shell and unit tests under tests/llvm_ir_backend_tests/ with dedicated, self-contained C++ unit test executables (test_llvm_*) covering types, expressions, control flow, ABIs, EH, inline asm, atomics, debug info, optimization pipelines, and differential fuzzing.

…MP, PGO/LTO pipelines, and expanded test coverage Implement multi-target calling convention ABIs across eight additional architectures, member pointer representation for Itanium and MSVC models, OpenMP lowering, PGO/LTO compilation pipelines, and extensive test suites: - Multi-Target Calling Conventions: Added complete ABI lowering implementations for ARM32, LoongArch64, MIPS, PPC64, SystemZ (s390x), SPARC, WebAssembly, and x86-32 alongside classification improvements for AAPCS64, RISC-V 64, SysV x86-64, and Win64. - Member Pointers: Implemented lowering for pointers to member functions and data (llvm_gen_be_ptrmem.{h,cpp}) supporting Itanium dual-field representations and MSVC single, multiple, and virtual inheritance layouts. - OpenMP Runtime Lowering: Added OpenMP 5.x construct emission (llvm_gen_be_omp.{h,cpp}) interfacing with libomp/kmpc runtime primitives for parallel regions, worksharing loops, critical sections, and atomic constructs. - Driver, PGO, and LTO Pipelines: Modularized backend driver orchestration (llvm_gen_be_driver.{h,cpp}) with CLI integration for Profile-Guided Optimization (PGO generation/use), ThinLTO/LTO bitcode emission, and sanitizer instrumentation. - Expression, Statement, & Model Lowering: Substantially expanded expression evaluation, statement lowerings (switch jump tables, indirect branches, cleanup blocks), TLS and static initializers, complex vtable/thunk layouts, and MSVC RTTI structures. - Test Suite Expansion: Added unit tests for declarations, error handling, LTO, modules, MSVC inline assembly, OpenMP, and PGO, accompanied by comprehensive lit integration test suites and documentation coverage verification. * Implement ABI, builtins, RTTI, EH, and dtor subsystems in GCC backend Expand the native libgccjit backend (gcc_gen_be) with comprehensive language feature lowering, runtime support, lexical scoping, and subsystem test coverage: - ABI, Calling Conventions, and Attributes (src/gcc_gen_be_abi.[ch]): - Implement gcc_gen_be_apply_function_attributes, gcc_gen_be_apply_struct_attributes, and gcc_gen_be_apply_variable_attributes for packing, alignment, TLS, and linkage. - Builtins and Intrinsics (src/gcc_gen_be_builtin.[ch]): - Add gcc_gen_be_lower_builtin_call using libgccjit builtin function lookup. - RTTI, VTables, and Thunks (src/gcc_gen_be_rtti.[ch]): - Add vtable and VTT emission (gcc_gen_be_emit_vtable, gcc_gen_be_emit_vtt). - Generate virtual method dispatch thunks (gcc_gen_be_emit_thunk). - Implement dynamic_cast and typeid lowering with type_info descriptor emission. - Exception Handling and RAII Destructors (src/gcc_gen_be_eh.[ch], src/gcc_gen_be_dtor.[ch]): - Declare standard EH symbols (__cxa_throw, etc.) and lower throw expressions. - Implement __cxa_atexit and __cxa_thread_atexit registration for global and TLS destructors. - Lexical Scopes and Control Flow (src/gcc_gen_be_context.[ch], src/gcc_gen_be_stmt.[ch], src/gcc_gen_be_cache.[ch]): - Introduce lexical scope push/pop stacks to support variable shadowing. - Add stack save/restore helpers for VLA allocation. - Expand cache types for local static guard variables and string constants. - Dynamic Symbol Loader (src/gcc_gen_be_lib_loader.[ch]): - Dynamically load modern libgccjit symbols for union constructors, bitcasts, vector rvalues, builtin retrieval, and link sections. - CLI and Driver Integration (src/cmd_line.[ch], src/gcc_gen_be_main.c): - Register --gcc_gen_be and -c command-line options. - Lower function scopes with lexical scope tracking and default terminator emission. - Subsystem Unit Tests and Coverage (tests/gcc_be/, dev_tools/): - Add subsystem test suites for ABI, builtins, debug, dtor, main, RTTI, and statements. - Update CMake targets and end-to-end backend test fixtures. - Add scripts for verifying backend test and documentation coverage. - Remove deprecated dev-init.py. * Implement subsystem unit tests, dynamic caching, and context stacks in GCC backend Expand the native libgccjit backend (gcc_gen_be) with dynamic memory management, subsystem diagnostics, modern libgccjit symbol loading, and a modular unit test suite: - Context and Control-Flow Stacks (gcc_gen_be_context.[ch]): - Replace static stack arrays with dynamically resizing stacks for break, continue, switch exit, nested blocks, and RAII cleanup handlers. - Introduce gcc_gen_be_push_block() / gcc_gen_be_pop_block() for nested scope tracking. - Add thread-ownership verification via gcc_gen_be_check_thread_safety(). - Cache Resizing and Metrics (gcc_gen_be_cache.[ch]): - Convert fixed-size hash buckets in be_cache_map to dynamically resizing tables. - Track cache lookup metrics (hits, misses) retrievable via cache_get_metrics(). - Add GCC_GEN_BE_CACHE_SWITCH_CASE for jump target deduplication. - Diagnostic Integration and Extended Errors (gcc_gen_be_error.[ch]): - Introduce gcc_gen_be_report_diagnostic() bridging backend errors with EDG's diagnostic counters and f_error. - Add detailed error codes for EH, unresolved symbols, vtables, RTTI, asm constraints, and DWARF emissions. - Declarations and Expressions (gcc_gen_be_decl.[ch], gcc_gen_be_expr.[ch]): - Separate global vs local variable lowering (gcc_gen_be_lower_global_variable_decl and gcc_gen_be_lower_local_variable_decl). - Add gcc_gen_be_lower_constant_rvalue() with aggregate initializer lowering. - Dynamic Symbol Loader (gcc_gen_be_lib_loader.[ch]): - Dynamically load optional modern libgccjit symbols (TLS models, vector types, extended asm goto, function/variable attributes, struct/array constructors). - Namespaces and Header Structuring: - Standardize C++ namespaces (BEGIN_EDG_NAMESPACE / END_EDG_NAMESPACE) across backend headers. - Modular Unit Test Suite (tests/gcc_be/): - Add standalone unit test suites for all backend subsystems: test_gcc_be_cache, test_gcc_be_context, test_gcc_be_decl, test_gcc_be_errors, test_gcc_be_expr, test_gcc_be_lib_loader, test_gcc_be_stmt, and test_gcc_be_type. - Update tests/gcc_be/CMakeLists.txt to build and register subsystem tests. - Tracking and Documentation: - Add TODO_PLAN.md documenting architecture, test coverage mandates, and roadmap. * Enforce universal error codes, percolation, and noexcept across GCC backend Enforce strict error handling invariants, non-discardable return codes, and noexcept specification across all GCC backend (gcc_gen_be) subsystems: - Error infrastructure (gcc_gen_be_error.[ch]): - Attach GCC_GEN_BE_NODISCARD directly to typedef enum gcc_gen_be_error_t to ensure compiler-enforced return value checks across all backend APIs. - Introduce GCC_GEN_BE_NOEXCEPT macro and add GCC_GEN_BE_ERROR_COMPILATION_FAILED. - Refactor gcc_gen_be_error_string() to take an out-parameter and return gcc_gen_be_error_t. - Universal error code returns and pointer out-parameters: - Update context getters/setters (gcc_gen_be_get_state, gcc_gen_be_get_context, gcc_gen_be_set_context, gcc_gen_be_get_current_block, gcc_gen_be_set_current_block). - Update helper constructors such as gcc_gen_be_get_global_ctor_block(). - Convert driver entry points gcc_gen_be() and back_end() to return gcc_gen_be_error_t. - Strict error propagation: - Percolate all internal fallible operations (cache lookups/inserts/clears, type and expression lowering, location queries, memory allocations) via GCC_GEN_BE_CHECK(). - Eliminate ignored return values, unhandled fallback paths, and silent errors. - Universal noexcept annotation: - Decorate all backend function declarations and definitions across gcc_gen_be_cache, gcc_gen_be_context, gcc_gen_be_decl, gcc_gen_be_error, gcc_gen_be_expr, gcc_gen_be_lib_loader, gcc_gen_be_location, gcc_gen_be_main, gcc_gen_be_stmt, and gcc_gen_be_type with GCC_GEN_BE_NOEXCEPT. * Modularize GCC backend into dedicated subsystems and expand CLI options Decompose monolithic gcc_gen_be.c and gcc_gen_be.h into modular, decoupled backend subsystems to improve maintainability, testability, and separation of concerns: - gcc_gen_be_cache: hash map memoization for types, variables, functions, and fields. - gcc_gen_be_context: context lifecycle, option configuration, and active basic block tracking. - gcc_gen_be_decl: declaration lowering for globals, local variables, and parameters. - gcc_gen_be_error: centralized backend error handling and diagnostics. - gcc_gen_be_expr: expression lowering for operators, calls, and accessors. - gcc_gen_be_lib_loader: cross-platform dynamic loader for libgccjit. - gcc_gen_be_location: mapping frontend source locations to JIT locations. - gcc_gen_be_main: driver entry points and compilation invocation. - gcc_gen_be_stmt: statement and CFG control-flow lowering. - gcc_gen_be_type: type system lowering across scalar, aggregate, pointer, and function types. Additionally: - Support GCC backend CLI optimization and debug flags in cmd_line.[ch] (-O0..-O3, -Os, -Ofast, -g, -fPIC, -fPIE, dump flags). - Update src/CMakeLists.txt for the new modular sources and coverage flags. - Expand tests/gcc_be/ suite and modernize coverage verification script to inspect all gcc_gen_be_*.c compilation units. * GCC [libgccjit] backend (initial pass) * Update LICENSE.txt for clarity []

SamuelMarks added 5 commits October 6, 2026 17:25

LLVM IR backend (initial pass)

c3770ed

SamuelMarks added 2 commits October 9, 2026 18:38

SamuelMarks marked this pull request as ready for review October 9, 2026 14:50

SamuelMarks added 2 commits October 10, 2026 21:45

Navigation Menu

Repository navigation

LLVM IR backend (initial pass) - #221

LLVM IR backend (initial pass)#221
SamuelMarks wants to merge 9 commits into
edgcpp:mainfrom
SamuelMarks:llvm_backend

SamuelMarks commented Oct 6, 2026 •

edited

Loading

Uh oh!

wchilders-nvidia commented Oct 8, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

SamuelMarks commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR: Native LLVM IR Generation Backend, Target ABIs, DWARF Debug Info, Optimization Pipeline & Verification Suite

Metadata

Table of Contents

1. Executive Summary

Key Capabilities Introduced

2. Background & Motivation

3. Architectural Overview & Subsystem Deep Dive

3.1 Backend Driver & Lifecycle Management

3.2 Robust Error Subsystem & Non-Throwing Invariants

3.3 Type System Lowering & Memory Layout

3.4 Constant Evaluation & Static Initializers

3.5 Declaration & Global State Lowering

3.6 Statement Lowering & Control Flow

3.7 Expression Lowering & Operations

3.8 Target Calling Convention ABIs

3.9 DWARF Debug Information Subsystem

3.10 Optimization Pipeline (LLVM New PassManager)

3.11 Target Machine Code Generation & Multi-Format Emission

3.12 C++ Exception Handling & RTTI Dispatch

3.13 GNU Inline Assembly Support

4. Front-End & Build System Integration

4.1 Command-Line Options & Driver Integration

4.2 Decoupling Static C-Backend Macros & Dynamic Target Layouts

4.3 CMake Build Configuration & LLVM Discovery

5. Quality, Standards & Architectural Conformance

5.1 Centralized [[nodiscard]] Error Enumeration

5.2 Pervasive noexcept & Strict -fno-exceptions

5.3 Non-Throwing Heap Allocations

5.4 100% Documentation Coverage (Doxygen)

5.5 100% Test & Branch Coverage Gate

6. Comprehensive Testing & Verification Framework

6.1 Unit Test Suite (tests/llvm_ir_backend_tests/)

6.2 Lit Test Suite (tests/lit/llvm/)

6.3 Shell Integration Suites (tests/test_llvm_*.sh)

6.4 GCC Torture Harness & STL Header Compilation

6.5 Continuous Integration & Automated Workflows

7. Complete File-by-File Change Matrix

8. Commit History & Evolution

9. Verification Guide & Instructions for Reviewers

9.1 Prerequisites

9.2 Building the Compiler with the LLVM Backend

9.3 Running Backend Unit Tests

9.4 Running Lit and Shell Integration Suites

9.5 Verifying LLVM IR and Code Emission Directly

9.6 Generating Doxygen API Documentation

Uh oh!

wchilders-nvidia commented Oct 8, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SamuelMarks commented Oct 6, 2026 •

edited

Loading

5.1 Centralized `[[nodiscard]]` Error Enumeration

5.2 Pervasive `noexcept` & Strict `-fno-exceptions`

6.1 Unit Test Suite (`tests/llvm_ir_backend_tests/`)

6.2 Lit Test Suite (`tests/lit/llvm/`)

6.3 Shell Integration Suites (`tests/test_llvm_*.sh`)