Skip to content

Readme.md

Latest commit

 

History

History
203 lines (152 loc) · 7.79 KB

Readme.md

File metadata and controls

203 lines (152 loc) · 7.79 KB

FROG logo

Reference LLVM-Oriented Path

Downstream compiler-family proof path for native executable closure in the non-normative FROG reference implementation
FROG — Free Open Graphical Language

Purpose

This directory contains the current LLVM-oriented proof path for the FROG reference implementation workspace. It exists to prove that selected lowered artifacts can be consumed by a native compiler-family path without making LLVM the definition of FROG semantics.

The correct current path is: 

.frog
  -> FIR
  -> lowering
  -> LLVM module / native proof

LLVM consumes lowering artifacts. It does not consume canonical source or FIR directly.

Current LLVM Example Surface

  • examples/01_pure_addition/
  • examples/02_ui_value_roundtrip/
  • examples/03_ui_property_write/
  • examples/04_stateful_feedback_delay/
  • examples/05_bounded_ui_accumulator/

Generic Lowering-to-LLVM Entry Point

python Implementations/Reference/LLVM/tools/emit_lowering_to_llvm.py \
  --lowering Examples/01_pure_addition/main.lowering.json \
  --expected Implementations/Reference/LLVM/examples/01_pure_addition/module.ll \
  --check

The generic emitter dispatches by lowered_units[0].kind.

Runtime Kernel Bridge Relationship

The runtime kernel bridge direction is documented in Implementations/Reference/Runtime/KernelBridge.md. That bridge keeps the runtime compiler-agnostic: the runtime hosts execution and UI, while compiler-family paths produce artifacts that can be consumed through explicit manifests and stable ABI surfaces.

For the first native bridge milestones, LLVM publishes the Example 05 native numeric kernel manifest and the Example 06 native Boolean kernel manifest. That does not make LLVM a runtime dependency. LLVM remains a backend-family producer of native-oriented material, and the runtime consumes the resulting manifest-defined artifact through a compiler-agnostic bridge. 

lowering
  -> LLVM-oriented backend path
       -> native kernel artifact
       -> native kernel manifest

runtime
  -> manifest-declared kernel
  -> ABI call
  -> diagnostics and snapshots

Example 05 And 06 Native Kernel Bridge Artifacts

The current publication surface for the first compiler-agnostic bridge is: 

Implementations/Reference/LLVM/examples/05_bounded_ui_accumulator/native_kernel_manifest.json
Implementations/Reference/LLVM/examples/05_bounded_ui_accumulator/kernel.ll
Implementations/Reference/Runtime/check_example05_native_kernel_bridge.py
Implementations/Reference/Runtime/check_example05_cpp_native_kernel_bridge.py
Implementations/Reference/LLVM/examples/06_boolean_value_roundtrip/native_kernel_manifest.json
Implementations/Reference/LLVM/examples/06_boolean_value_roundtrip/kernel.ll
Implementations/Reference/Runtime/check_example06_native_kernel_bridge.py
Implementations/Reference/Runtime/check_example06_cpp_native_kernel_bridge.py

The Example 05 manifest declares the entry symbol frog_example05_run, the ABI name frog_u16_to_result_status_outptr, the input input_value : u16, the output result : u16, and the overflow diagnostic mapping for error_code = 1. The Example 06 manifest declares the entry symbol frog_example06_run, the ABI name frog_bool_to_result_status_outptr, the input input_value : bool, and the output result : bool. The ABI uses an explicit out-parameter carrier: 

void frog_example05_run(uint16_t input_value, FrogRunResult* out_result)
void frog_example06_run(uint8_t input_value, FrogBoolRunResult* out_result)

The kernel.ll artifact exposes the corresponding LLVM-level ABI shape and writes ok, result, and error_code into the provided result-status pointer. This avoids relying on compiler- or platform-specific struct-return behavior while keeping the result-status model explicit.

The publication surface can be checked with: 

python Implementations/Reference/Runtime/check_example05_native_kernel_bridge.py
python Implementations/Reference/Runtime/check_example06_native_kernel_bridge.py
python Implementations/Reference/check_reference_workspace.py --include-native-kernel-bridge

The optional C++ bridge check compiles kernel.ll with clang, links it into a dedicated C++ test target, and exercises the same NativeKernelBridge path. The baseline runtime build remains independent from LLVM and clang.

Rule Family Documentation

Supported Lowered Unit Kinds

Lowered unit kind Published example Proof posture
pure_addition_kernel01_pure_additionNative proof for pure f64 addition.
ui_value_roundtrip_kernel02_ui_value_roundtripNative proof payload for widget-value arithmetic.
ui_property_write_effect_unit03_ui_property_writeNative proof payload for explicit UI property effect.
stateful_feedback_delay_kernel04_stateful_feedback_delayNative proof for one explicit delay-backed state step.
bounded_accumulator_kernel_with_ui_bindings05_bounded_ui_accumulatorNative proof for bounded u16 accumulation with overflow rejection and optional runtime-bridge closure.

Compatibility Wrappers

python Implementations/Reference/LLVM/tools/emit_examples01_04_llvm_modules.py --check
python Implementations/Reference/LLVM/tools/emit_llvm_module.py --check

These wrappers are kept for continuity, but both now delegate to the generic lowered-unit-kind emitter.

Native Build

python Implementations/Reference/Pipeline/check_examples01_10_full.py --include-llvm-build

The native build path requires clang. It verifies the published native proof dossiers for Examples 01-11 when the toolchain is available.

The optional native-kernel bridge closure can be checked with: 

python Implementations/Reference/Runtime/check_example05_cpp_native_kernel_bridge.py

Boundary

LLVM remains downstream from FROG. These examples are native proof dossiers, not a generalized production backend. The LLVM-oriented path must not redefine canonical source, validated meaning, FIR, lowering law, backend contracts, runtime behavior, widget law, or UI host behavior.

For the native kernel bridge, LLVM remains a compiler-family producer of manifest-declared kernel artifacts rather than becoming part of the runtime definition.