LLVM Integration & Backend

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• jazz-hs/package.yaml
• jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/OrcJITC.cpp
• jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/TargetC.cpp
• jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/MetadataC.cpp
• jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/InstructionC.cpp
• jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/Target.h
• jazz-hs/local-deps/llvm-hs-pure/CHANGELOG.md

The LLVM Integration & Backend represents a planned high-performance target for the Jazz functional language. While the core language currently implements strong static typing and type inference for its expression subset, an LLVM-based backend is an aspirational goal intended to provide superior execution performance compared to the current bundled-prelude runtime.

The project currently maintains extensive infrastructure for LLVM bindings, specifically targeting LLVM version 12.0. This includes low-level C++ FFI wrappers for the LLVM OrcJIT (Just-In-Time) compiler, metadata handling, instruction generation, and target machine configuration. These bindings allow the Jazz compiler to interface with LLVM's optimizer and code generation layers to produce efficient machine code.

Sources: README.md:15-20, jazz-hs/local-deps/llvm-hs-pure/CHANGELOG.md:3-5, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/OrcJITC.cpp:1-10

OrcJIT V2 Implementation

The backend utilizes LLVM's OrcJIT (On-Request Compilation JIT) version 2 for dynamic code execution and symbol resolution. This system is organized into layers, including a thread-safe context management system and an object linking layer.

Execution and Symbol Management

The JIT infrastructure revolves around an ExecutionSession which manages JITDylib instances. Symbols are resolved using a MangleAndInterner to handle language-specific naming conventions.

The diagram above shows the relationship between the OrcJIT execution session, the compilation layers, and the symbol interning process used for resolution.

Component	Function	C++ Entry Point
ExecutionSession	Manages JIT state and memory	LLVM_Hs_createExecutionSession
ThreadSafeModule	Wraps LLVM modules for JIT usage	LLVM_Hs_cloneAsThreadSafeModule
IRCompileLayer	Compiles LLVM IR to object files	LLVM_Hs_createIRCompileLayer
ObjectLinkingLayer	Links object files into the process	LLVM_Hs_createRTDyldObjectLinkingLayer

Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/OrcJITC.cpp:52-120, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/OrcJITC.cpp:142-160

Target Machine Configuration

The backend supports sophisticated target machine configuration, allowing the compiler to generate code for specific architectures (e.g., x86_64, ARM) with tailored optimization levels and relocation models.

Machine Options and Flags

Target options are managed through a series of flags covering floating-point math behavior, section naming, and debug information compression.

• Optimization Levels: Supports None, Less, Default, and Aggressive.
• Relocation Models: Includes Static, PIC (Position Independent Code), and DynamicNoPIC.
• Code Models: Supports Small, Medium, Kernel, Large, and JITDefault.

This structure allows the Jazz compiler to query the host CPU features (LLVM_Hs_GetHostCPUFeatures) and set up a corresponding TargetMachine for code emission.

Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/TargetC.cpp:211-250, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/Target.h:1-40, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/TargetC.cpp:387-420

Instruction Generation & Metadata

The integration includes detailed support for LLVM IR instruction properties and DWARF debug metadata. This is critical for both the safety of the generated code (e.g., overflow checks) and the debuggability of Jazz programs.

Instruction Attributes

Specific FFI wrappers expose properties for various instruction types:

• Binary Operators: Support for NoSignedWrap (nsw) and NoUnsignedWrap (nuw) flags.
• Memory Operations: Alignment settings, volatility, and atomic ordering for Load, Store, and Alloca instructions.
• Atomic RMW: Support for synchronization scopes and atomic bin ops.

Debug Metadata (DWARF)

The system implements a wide range of DWARF metadata nodes to describe Jazz source locations and types to debuggers:

• DILocation: Lines and columns.
• DICompileUnit: The top-level compilation unit descriptor.
• DISubprogram: Function metadata, including virtuality and scope lines.
• DIBasicType / DICompositeType: Representation of primitive and complex types (structs, arrays, unions).

Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/InstructionC.cpp:45-80, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/MetadataC.cpp:165-220, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/MetadataC.cpp:350-400

Module Management

The backend handles LLVM modules as the primary unit of code generation. This includes support for inline assembly and named metadata.

The ModuleC interface allows for the retrieval of module identifiers, source file names, and the iteration over global aliases or named metadata nodes.

Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/ModuleC.cpp:10-40, jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/ModuleC.cpp:55-75

Conclusion

The LLVM Integration & Backend provides the technical foundation for Jazz's transition from an interpreted or prelude-based runtime to a high-performance compiled language. By leveraging LLVM 12.0 and OrcJIT V2, the project establishes a robust path for machine code generation, cross-architecture support, and integrated debugging capabilities. While listed as aspirational in the high-level roadmap, the existing FFI infrastructure indicates a significant investment in the low-level plumbing required for this performance target.