diff --git a/.github/workflows/jit-benchmark.yml b/.github/workflows/jit-benchmark.yml new file mode 100644 index 0000000..819e1c4 --- /dev/null +++ b/.github/workflows/jit-benchmark.yml @@ -0,0 +1,47 @@ +name: Native JIT validation and benchmark + +on: + push: + branches: + - "feat/**" + paths: + - "native/internal/tell/jit*.go" + - "native/internal/tell/jit*.s" + - "native/internal/tell/bytecode.go" + - "native/internal/tell/jit_test.go" + - ".github/workflows/jit-benchmark.yml" + pull_request: + paths: + - "native/internal/tell/jit*.go" + - "native/internal/tell/jit*.s" + - "native/internal/tell/bytecode.go" + - "native/internal/tell/jit_test.go" + - ".github/workflows/jit-benchmark.yml" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: tell-jit-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + linux-amd64: + name: Linux amd64 / JIT tests and benchmark + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version: "1.23.x" + - name: Run native Tell tests and race detector + working-directory: native + run: | + go test ./internal/tell + go test -race ./internal/tell + go vet ./internal/tell + - name: Benchmark interpreter, JIT, and auto mode + working-directory: native + run: | + go test ./internal/tell -run '^$' -bench '^BenchmarkTypedNumericFunctionEngines$' -benchmem -benchtime=250ms -count=1 diff --git a/.github/workflows/native.yml b/.github/workflows/native.yml index 4764787..1c3ba73 100644 --- a/.github/workflows/native.yml +++ b/.github/workflows/native.yml @@ -43,6 +43,38 @@ jobs: go test ./... go test -race ./... go vet ./... + - name: Benchmark interpreter, JIT, and automatic bytecode execution + working-directory: native + run: | + go test ./internal/tell -run '^ + run: ./scripts/build-all.sh + - name: Verify process-level runtime conformance + run: | + python scripts/conformance.py --runtime both --fixtures conformance/smoke-v1.json --native-bin releases/tell-linux-amd64 + python scripts/conformance.py --runtime both --fixtures conformance/runtime-v1.json --native-bin releases/tell-linux-amd64 + - name: Run Tell source examples as tests + run: ./releases/tell-linux-amd64 test examples + - name: Upload native binaries + uses: actions/upload-artifact@v4 + with: + name: tell-native-binaries + path: releases/ + if-no-files-found: error + -bench '^BenchmarkTypedNumericFunctionEngines + run: ./scripts/build-all.sh + - name: Verify process-level runtime conformance + run: | + python scripts/conformance.py --runtime both --fixtures conformance/smoke-v1.json --native-bin releases/tell-linux-amd64 + python scripts/conformance.py --runtime both --fixtures conformance/runtime-v1.json --native-bin releases/tell-linux-amd64 + - name: Run Tell source examples as tests + run: ./releases/tell-linux-amd64 test examples + - name: Upload native binaries + uses: actions/upload-artifact@v4 + with: + name: tell-native-binaries + path: releases/ + if-no-files-found: error + -benchmem -benchtime=250ms -count=1 - name: Build Linux, macOS and Windows binaries run: ./scripts/build-all.sh - name: Verify process-level runtime conformance diff --git a/README.md b/README.md index 5f7f71b..8b2422f 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,24 @@ Typed parameter and return contracts are enforced during normal execution and preserved in bytecode. Existing dynamic Tell programs remain supported without `--typed`; see the [typed Go dialect guide](docs/TYPED_TELL.md). +## Native Go execution engines + +The Go runtime offers direct interpretation, AOT compilation to portable +`.tbc` bytecode, and an initial native JIT tier for hot typed numeric +functions: + +~~~sh +tell program.tell +tell build program.tell +tell --engine jit program.tell +tell --engine auto --jit-threshold 24 --jit-stats program.tell +~~~ + +The JIT currently targets Linux x86-64 and a restricted typed numeric +function subset; everything else keeps running in the interpreter. The +portable `.tbc` build is not a standalone native executable. See the +[execution engine guide](docs/EXECUTION_ENGINES.md) for details and benchmarks. + ## Compile native executables with TellC TellC is an experimental C++ compiler that translates its typed dialect through LLVM into a native executable. Its dialect is separate from the dynamically typed language used by the Go and Python runtimes; programs are not necessarily interchangeable. For example: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3636186..273e531 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -32,7 +32,11 @@ The source interpreter path is shown above. The native CLI also has an early com Tell source -> existing parser -> supported statement/expression compiler -> tell-bytecode-v1 JSON -> Go stack VM ``` -It supports `Let`, `Set`, `Remember` field initialization, output statements, bare expressions, `If`/`Otherwise`, `While`, `Repeat`, `For each`, loop break/continue, `Try`/`If something goes wrong`, `Raise an error saying ...`, recursive embedding of local `.tell` modules, user functions, returns, recursion, named arguments, lexical closures, and the initial class model with constructors, fields, methods, single inheritance, and overrides, plus expressions accepted by the native parser. Repeated module imports share cached module exports in a run. Unsupported statements are rejected. A conservative type-annotation prepass checks expressions with statically known types. A scalar constant-folding pass simplifies safe literal expressions, and a verifier checks instruction references and stack heights across control-flow joins before execution. The compiler still lowers directly from the expression AST to stack bytecode without a distinct typed AST or optimization IR; it has no whole-program type inference, broader optimizer, JIT, or AOT compilation of Tell programs. The Go executable itself is a native-compiled interpreter. +It supports `Let`, `Set`, `Remember` field initialization, output statements, bare expressions, `If`/`Otherwise`, `While`, `Repeat`, `For each`, loop break/continue, `Try`/`If something goes wrong`, `Raise an error saying ...`, recursive embedding of local `.tell` modules, user functions, returns, recursion, named arguments, lexical closures, and the initial class model with constructors, fields, methods, single inheritance, and overrides, plus expressions accepted by the native parser. Repeated module imports share cached module exports in a run. Unsupported statements are rejected. A conservative type-annotation prepass checks expressions with statically known types. A scalar constant-folding pass simplifies safe literal expressions, and a verifier checks instruction references and stack heights across control-flow joins before execution. The compiler still lowers directly from the expression AST to stack bytecode without a distinct typed AST or optimization IR. The Go VM now supports three execution paths: direct source interpretation, AOT lowering to portable `.tbc` bytecode, and an opt-in native JIT tier for a narrow subset of typed numeric functions on Linux/amd64. The JIT caches eligible functions after first use (or after a hot threshold in auto mode); unsupported functions remain in the interpreter. This is not yet native AOT output or a whole-program optimizer. + +## Execution engines + +See [Execution Engines](EXECUTION_ENGINES.md) for the portable-bytecode AOT path, native JIT subset, automatic hot-function tiering, platform limits, and benchmark instructions. ## Persistent sessions diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index ff10a66..7038edc 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -81,6 +81,19 @@ Both runtimes accept `--version`, `--types`, `--max-call-depth N`, and `--max-lo Both runtimes support `tell check --types program.tell` (or `tell --types program.tell`) for conservative static type and declaration checks. Known primitive and class annotations are checked when initializer or reassigned value types can be inferred; unresolved dynamic expressions remain checked at runtime. `tell build` performs the native conservative checks automatically. +The native Go CLI also accepts `--engine interp|jit|auto` when running source or +`.tbc` files. `interp` is the default. `jit` attempts native compilation on +first function call; `auto` warms functions in the interpreter before +compiling eligible typed numeric functions. The initial native backend is +Linux x86-64 only; unsupported functions and other platforms use the +interpreter. Use `--jit-threshold N` to change auto mode's default 24-call +threshold and `--jit-stats` to report compiled functions and execution +counts. See [Execution Engines](EXECUTION_ENGINES.md) for the eligible +instruction subset and fallback rules. + +`tell build` is AOT compilation to portable `.tbc` bytecode. It does not +currently emit standalone native machine-code executables. + ## Not implemented yet There is no package-management CLI, debugger, or language server. `tell new` and `tell init` scaffold a runnable project but do not resolve or install dependencies. The initial `build` command compiles only the documented native subset. `tell format` is a source formatter, not a compiler. diff --git a/docs/EXECUTION_ENGINES.md b/docs/EXECUTION_ENGINES.md new file mode 100644 index 0000000..03b86f8 --- /dev/null +++ b/docs/EXECUTION_ENGINES.md @@ -0,0 +1,131 @@ +# Tell execution engines + +The native Go runtime has three execution paths. Select a path with +`--engine` when running a source program or a `.tbc` artifact. + +## Interpreter + +The interpreter remains the compatibility default: + +~~~sh +tell program.tell +tell --engine interp program.tell +tell --engine interp program.tbc +~~~ + +Source is parsed and evaluated directly by the existing Go runtime. This path +supports the full Go-interpreter language implementation and is the fallback +for bytecode functions that cannot be safely compiled by the current JIT. + +## AOT: portable bytecode + +The build command compiles source ahead of execution into the versioned, +portable `tell-bytecode-v1` artifact: + +~~~sh +tell build program.tell +tell build program.tell --output build/program.tbc +tell run build/program.tbc +~~~ + +This is AOT compilation to the Go VM's portable stack bytecode. It avoids +parsing and lowering source at each run and embeds compiled local modules. +It is **not** native machine-code AOT and does not produce a standalone OS +executable. The artifact is still run by the Go runtime. + +## JIT: native hot-function compilation + +Run either source or bytecode with: + +~~~sh +tell --engine jit program.tell +tell --engine jit program.tbc +~~~ + +The first native backend is Linux x86-64 only. It lazily compiles eligible +functions when they are called. The compiled machine code is cached for the +duration of the process. Executable memory follows a write-then-execute +transition: pages are writable while emitted, then changed to read/execute. + +The initial native code generator is deliberately conservative. A function +is eligible only when: + +- every parameter is explicitly typed as `number` or `decimal`; +- its return type is `number` or `decimal`; +- it is not a method, variadic function, or function with default arguments; +- the body is a straight-line expression using numeric constants, parameter + loads, unary `+`/`-`, binary `+`, `-`, `*`, and a return. + +Division is deliberately left in the interpreter because Tell reports +division-by-zero as a language error, while a raw floating-point divide would +produce an infinity. Control flow, recursion, dynamic values, strings, +collections, I/O, calls, comparisons, and other operations are not +machine-compiled yet. Those functions execute through the existing bytecode +interpreter, even in `jit` mode. This preserves behavior while the JIT's +supported subset grows. + +The initial backend is implemented with a small Linux/amd64 code emitter. It +does not add an LLVM or CGo build dependency. Other operating systems and CPU +architectures use the interpreter fallback; explicit `--engine jit` reports +that the native backend is unavailable there. + +## Automatic tiering + +Use automatic mode for a mixed program: + +~~~sh +tell --engine auto --jit-threshold 24 program.tell +tell --engine auto --jit-threshold 24 program.tbc +~~~ + +Eligible functions run in the interpreter during warm-up. After the configured +number of calls, the runtime compiles the function once and routes subsequent +calls to native code. Unsupported functions remain interpreted. The default +threshold is 24 calls. + +To inspect what actually ran: + +~~~sh +tell --engine auto --jit-stats program.tell +~~~ + +The report shows compiled functions, native calls, and interpreted calls. A +function being declared as typed does not automatically make its body JIT +eligible; the body must match the supported numeric subset. + +## Validation and performance + +The Go test suite compares native and interpreted results, verifies the +automatic hot threshold, and verifies interpreter fallback for control flow +and division-by-zero semantics. A benchmark is available: + +~~~sh +cd native +go test ./internal/tell -run '^ + -bench BenchmarkTypedNumericFunctionEngines -benchmem +~~~ + +### Initial CI benchmark sample + +One Linux amd64 CI run (Ubuntu 24.04, Go 1.23.x, 250 ms per sub-benchmark) +measured the warmed-up execution of the same typed function containing 159 +numeric arithmetic operations: + +| Engine | Time per call | Allocations per call | +| --- | ---: | ---: | +| Interpreter | 6,362 ns | 167 | +| Native JIT | 608 ns | 9 | +| Auto (after warm-up) | 623 ns | 9 | + +This is a synthetic, compute-heavy function benchmark. The harness excludes +one-time JIT compilation from the timed section and calls the compiled +function directly; it does not measure source parsing, whole-program startup, +I/O, dynamic code, or end-to-end application performance. Treat the numbers +as an initial reference for this specific supported subset, not a universal +speedup guarantee. Benchmark representative applications before making +product-wide performance claims. + +The JIT is an initial execution tier, not yet a whole-program optimizing +compiler. True native AOT output, additional CPU backends, register +allocation, inlining, deoptimization, and broader typed code generation remain +future work. diff --git a/docs/TYPED_TELL.md b/docs/TYPED_TELL.md index ba971f1..46873cb 100644 --- a/docs/TYPED_TELL.md +++ b/docs/TYPED_TELL.md @@ -59,17 +59,25 @@ A runnable native example is available at [native/examples/native-typed.tell](.. ## Performance status -This first Go typed-dialect increment adds validation and runtime contract -checks; it does not yet specialize the VM's dynamic value representation. -Go execution still uses the existing general-purpose runtime and bytecode -operations. Do not treat this change as a measured speedup in execution, -memory use, or compilation time. - -The next performance phase should use typed semantic information to lower -verified functions to specialized bytecode operations and compact value -representations where benchmarks justify them. Any such change should retain -a dynamic compatibility path and be measured against representative Tell -programs before performance claims are made. +The production .tbc VM now has an initial native JIT tier for a narrow subset +of typed numeric functions on Linux/amd64. Eligible straight-line functions +with number/decimal parameters and return values can be emitted as native +x86-64 floating-point instructions. The runtime caches compiled functions; +auto mode waits for a hot-call threshold before compiling. Unsupported +functions continue through the existing interpreter. + +This JIT does not yet specialize the VM's general dynamic value representation +or compile control flow, recursion, collections, I/O, or dynamic calls. It is +a small native-code backend, not LLVM ORC. Division remains interpreted so the +JIT preserves Tell's division-by-zero error semantics. Do not assume a speedup +until the benchmark is run on representative workloads. See +[Execution Engines](EXECUTION_ENGINES.md) for supported instructions and +benchmark instructions. + +Future work includes a typed IR, broader native code generation, register +allocation, deoptimization, additional CPU backends, and true standalone +native AOT output. The portable .tbc build remains ahead-of-time compilation +to VM bytecode, not a native executable. ## Migration diff --git a/native/cmd/tell/main.go b/native/cmd/tell/main.go index 6c8a550..65fe6ab 100644 --- a/native/cmd/tell/main.go +++ b/native/cmd/tell/main.go @@ -21,6 +21,9 @@ func main() { check := flag.Bool("check", false, "parse the program without running it") typeCheck := flag.Bool("types", false, "check statically knowable type annotations") typedMode := flag.Bool("typed", false, "require explicit variable, parameter, and return types") + engine := flag.String("engine", "interp", "execution engine: interp, jit, or auto") + jitThreshold := flag.Int("jit-threshold", 24, "calls per function before auto mode compiles it") + jitStats := flag.Bool("jit-stats", false, "print native JIT compilation and fallback counts") showVersion := flag.Bool("version", false, "print the Tell version") quietREPL := flag.Bool("quiet-repl", false, "omit terminal prompts and banner (for IDE integrations)") buildOutput := flag.String("output", "", "write compiled bytecode to this path") @@ -84,8 +87,11 @@ func main() { fmt.Printf("Tell %s (native Go runtime)\n", version) return } - if *maxCallDepth < 1 || *maxLoopIterations < 1 { - exitWithDiagnostic(fmt.Errorf("execution limits must be positive integers"), "", diagnostic.UsageError) + if *maxCallDepth < 1 || *maxLoopIterations < 1 || *jitThreshold < 1 { + exitWithDiagnostic(fmt.Errorf("execution limits and JIT threshold must be positive integers"), "", diagnostic.UsageError) + } + if !tell.ValidExecutionEngine(*engine) { + exitWithDiagnostic(fmt.Errorf("unknown execution engine %q (expected interp, jit, or auto)", *engine), "", diagnostic.UsageError) } limits := tell.ExecutionLimits{MaxFunctionCallDepth: *maxCallDepth, MaxLoopIterations: *maxLoopIterations} if projectMode != "" { @@ -186,6 +192,9 @@ func main() { return } if buildMode { + if *engine != "interp" || *jitStats { + exitWithDiagnostic(fmt.Errorf("tell build creates portable AOT bytecode; --engine and --jit-stats apply to execution"), "", diagnostic.UsageError) + } if filename == "-" && *buildOutput == "" { exitWithDiagnostic(fmt.Errorf("tell build - requires --output"), "", diagnostic.UsageError) } @@ -209,9 +218,13 @@ func main() { return } if strings.EqualFold(filepath.Ext(filename), ".tbc") { - if err := tell.RunBytecodeWithLimits(data, filename, os.Stdin, os.Stdout, limits); err != nil { + stats, err := tell.RunBytecodeWithEngine(data, filename, os.Stdin, os.Stdout, limits, *engine, *jitThreshold) + if err != nil { exitWithDiagnostic(err, filename, diagnostic.RuntimeError) } + if *jitStats { + printJITStats(stats) + } return } if *check { @@ -248,11 +261,35 @@ func main() { exitWithDiagnostic(err, runName, diagnostic.TypeError) } } + if *engine != "interp" { + compiled, compileErr := tell.Compile(string(data), runName) + if compileErr != nil { + if *engine == "jit" { + exitWithDiagnostic(fmt.Errorf("cannot prepare source for JIT execution: %w (this source may be outside the current bytecode compiler subset)", compileErr), runName, diagnostic.SyntaxError) + } + } else { + stats, runErr := tell.RunBytecodeWithEngine(compiled, runName, os.Stdin, os.Stdout, limits, *engine, *jitThreshold) + if runErr != nil { + exitWithDiagnostic(runErr, runName, diagnostic.RuntimeError) + } + if *jitStats { + printJITStats(stats) + } + return + } + } if err := tell.NewSessionWithLimits(os.Stdin, os.Stdout, limits).Exec(string(data), runName); err != nil { exitWithDiagnostic(err, runName, diagnostic.RuntimeError) } } +func printJITStats(stats tell.EngineStats) { + fmt.Fprintf(os.Stderr, + "execution engines: JIT compiled %d function(s), executed %d native call(s), interpreted %d call(s)\n", + stats.JITCompiledFunctions, stats.JITInvocations, stats.InterpretedCalls, + ) +} + func exitWithDiagnostic(err error, filename string, kind diagnostic.Kind) { os.Exit(reportDiagnostic(os.Stderr, err, filename, kind)) } diff --git a/native/examples/jit-numeric.tell b/native/examples/jit-numeric.tell new file mode 100644 index 0000000..ed14b00 --- /dev/null +++ b/native/examples/jit-numeric.tell @@ -0,0 +1,6 @@ +to weighted(number: left, number: right) out number: + give back left * 3 + right * 2 +end function + +let number result be weighted(4, 6) +say result diff --git a/native/internal/tell/bytecode.go b/native/internal/tell/bytecode.go index 568487f..bc07313 100644 --- a/native/internal/tell/bytecode.go +++ b/native/internal/tell/bytecode.go @@ -52,6 +52,7 @@ type BytecodeFunction struct { HasVariadic bool `json:"has_variadic,omitempty"` Receiver bool `json:"receiver,omitempty"` Instructions []BytecodeInstruction `json:"instructions"` + jitKey [32]byte } // BytecodeClass describes the constructor and methods for a compiled Tell class. @@ -1148,43 +1149,71 @@ func RunBytecode(data []byte, filename string, input io.Reader, output io.Writer return RunBytecodeWithLimits(data, filename, input, output, DefaultExecutionLimits()) } -// RunBytecodeWithLimits executes an artifact under the same resource limits as source execution. +// RunBytecodeWithLimits executes an artifact with the portable bytecode interpreter. func RunBytecodeWithLimits(data []byte, filename string, input io.Reader, output io.Writer, limits ExecutionLimits) error { + _, err := RunBytecodeWithEngine(data, filename, input, output, limits, "interp", 24) + return err +} + +// RunBytecodeWithEngine executes a .tbc artifact using the requested engine. +// "jit" compiles eligible functions on first call; "auto" compiles them after +// the hot threshold; unsupported functions continue through the interpreter. +func RunBytecodeWithEngine(data []byte, filename string, input io.Reader, output io.Writer, limits ExecutionLimits, engine string, hotThreshold int) (EngineStats, error) { + var stats EngineStats + engine = strings.ToLower(strings.TrimSpace(engine)) + if !validExecutionEngine(engine) { + return stats, fail("unknown execution engine %q (expected interp, jit, or auto)", engine) + } + if engine == "jit" && !NativeJITAvailable() { + return stats, fail("native JIT is unavailable on this platform; use --engine interp or --engine auto") + } + if hotThreshold < 1 { + hotThreshold = 24 + } var program BytecodeProgram if err := json.Unmarshal(data, &program); err != nil { - return fail("invalid bytecode: %v", err) + return stats, fail("invalid bytecode: %v", err) } if program.Format != bytecodeFormat || len(program.Instructions) == 0 { - return fail("unsupported or empty Tell bytecode artifact") + return stats, fail("unsupported or empty Tell bytecode artifact") } compiledModules := make(map[string]BytecodeProgram, len(program.Modules)) for _, module := range program.Modules { if module.Path == "" || module.Program.Format != bytecodeFormat || len(module.Program.Instructions) == 0 { - return fail("invalid embedded bytecode module") + return stats, fail("invalid embedded bytecode module") } if _, duplicate := compiledModules[module.Path]; duplicate { - return fail("duplicate embedded bytecode module %q", module.Path) + return stats, fail("duplicate embedded bytecode module %q", module.Path) } if len(module.Program.Modules) != 0 { - return fail("nested module tables are not valid in embedded bytecode") + return stats, fail("nested module tables are not valid in embedded bytecode") } compiledModules[module.Path] = module.Program } if err := validateModuleReferences(program, compiledModules); err != nil { - return err + return stats, err } if err := validateExecutableBytecode(program); err != nil { - return err + return stats, err } for path, module := range compiledModules { if err := validateExecutableBytecode(module); err != nil { - return fail("invalid embedded module %q: %v", path, err) + return stats, fail("invalid embedded module %q: %v", path, err) } } + assignBytecodeJITKeys(&program, filename) + for path, module := range compiledModules { + assignBytecodeJITKeys(&module, filename+"::"+path) + compiledModules[path] = module + } r := newRuntime(filename, input, output, limits) r.bytecodeModules = compiledModules - _, err := executeBytecodeCode(r, program.Instructions, program.Functions, program.Classes) - return err + r.executionEngine = engine + r.jitHotThreshold = hotThreshold + _, executionErr := executeBytecodeCode(r, program.Instructions, program.Functions, program.Classes) + stats = r.jitStats + r.closeJIT() + return stats, executionErr } func validateExecutableBytecode(program BytecodeProgram) error { @@ -2092,9 +2121,15 @@ func callBytecodeFunction(r *runtime, function BytecodeFunction, closure *env, f previous := r.global r.global = local defer func() { r.global = previous }() - result, err := executeBytecodeCode(r, function.Instructions, functions, classes) - if err != nil { - return nil, err + result, ranNative, jitErr := r.runJITFunction(function, local) + if jitErr != nil { + return nil, jitErr + } + if !ranNative { + result, err = executeBytecodeCode(r, function.Instructions, functions, classes) + if err != nil { + return nil, err + } } if function.ReturnType != "" { if strings.EqualFold(function.ReturnType, "void") { diff --git a/native/internal/tell/engine_api.go b/native/internal/tell/engine_api.go new file mode 100644 index 0000000..9867c84 --- /dev/null +++ b/native/internal/tell/engine_api.go @@ -0,0 +1,4 @@ +package tell + +// ValidExecutionEngine reports whether engine names a supported execution policy. +func ValidExecutionEngine(engine string) bool { return validExecutionEngine(engine) } diff --git a/native/internal/tell/jit.go b/native/internal/tell/jit.go new file mode 100644 index 0000000..a74a5f3 --- /dev/null +++ b/native/internal/tell/jit.go @@ -0,0 +1,125 @@ +package tell + +import ( + "crypto/sha256" + "encoding/binary" + "encoding/json" + "strings" +) + +// EngineStats reports how a bytecode run was tiered. InterpretedCalls includes +// warm-up calls in auto mode and functions that are not eligible for native JIT. +type EngineStats struct { + JITCompiledFunctions int + JITInvocations int + InterpretedCalls int +} + +// nativeCode owns one executable mapping. The platform backend is responsible +// for allocating it with write permissions, then switching it to read/execute. +type nativeCode struct { + entry uintptr + mapping []byte +} + +func NativeJITAvailable() bool { return nativeJITAvailable() } + +func assignJITFunctionKey(function *BytecodeFunction, namespace string, index int) { + if function == nil { + return + } + name := function.Name + buffer := make([]byte, len(namespace)+1+8+len(name)) + position := copy(buffer, namespace) + buffer[position] = 0 + position++ + binary.LittleEndian.PutUint64(buffer[position:position+8], uint64(index)) + position += 8 + copy(buffer[position:], name) + function.jitKey = sha256.Sum256(buffer) +} + +func assignBytecodeJITKeys(program *BytecodeProgram, namespace string) { + if program == nil { + return + } + for index := range program.Functions { + assignJITFunctionKey(&program.Functions[index], namespace, index) + } +} + +func validExecutionEngine(engine string) bool { + switch strings.ToLower(strings.TrimSpace(engine)) { + case "interp", "jit", "auto": + return true + default: + return false + } +} + +func (r *runtime) runJITFunction(function BytecodeFunction, local *env) (any, bool, error) { + if r.executionEngine == "" || r.executionEngine == "interp" { + return nil, false, nil + } + key := function.jitKey + var err error + if key == ([32]byte{}) { + keyData, err := json.Marshal(function) + if err != nil { + return nil, false, err + } + key = sha256.Sum256(keyData) + } + + if r.jitUnsupported[key] { + r.jitStats.InterpretedCalls++ + return nil, false, nil + } + + code, exists := r.jitCache[key] + if r.executionEngine == "auto" && !exists { + r.jitCalls[key]++ + if r.jitCalls[key] < r.jitHotThreshold { + r.jitStats.InterpretedCalls++ + return nil, false, nil + } + } + if !exists { + code, err = compileNativeJIT(function) + if err != nil { + // Unsupported constructs are expected during tiered execution. Cache + // the result so we do not repeatedly try compiling the same function. + r.jitUnsupported[key] = true + r.jitStats.InterpretedCalls++ + return nil, false, nil + } + r.jitCache[key] = code + r.jitStats.JITCompiledFunctions++ + } + + var arguments [7]float64 + for index, name := range function.Parameters { + value, exists := local.values[name] + if !exists { + value, err = local.get(name) + if err != nil { + return nil, true, err + } + } + arguments[index], err = numberValue(value) + if err != nil { + return nil, true, fail("native JIT argument %q is not numeric: %v", name, err) + } + } + // The machine-code ABI takes a pointer even for a zero-argument function. + result := callNativeJIT(code.entry, &arguments[0]) + r.jitStats.JITInvocations++ + return result, true, nil +} + +func (r *runtime) closeJIT() { + for key, code := range r.jitCache { + releaseNativeJIT(code) + delete(r.jitCache, key) + } +} diff --git a/native/internal/tell/jit_fallback.go b/native/internal/tell/jit_fallback.go new file mode 100644 index 0000000..089ac15 --- /dev/null +++ b/native/internal/tell/jit_fallback.go @@ -0,0 +1,15 @@ +//go:build !linux || !amd64 + +package tell + +import "fmt" + +func nativeJITAvailable() bool { return false } + +func compileNativeJIT(function BytecodeFunction) (*nativeCode, error) { + return nil, fmt.Errorf("native JIT backend is currently available only on linux/amd64") +} + +func callNativeJIT(entry uintptr, arguments *float64) float64 { return 0 } + +func releaseNativeJIT(code *nativeCode) {} diff --git a/native/internal/tell/jit_linux_amd64.go b/native/internal/tell/jit_linux_amd64.go new file mode 100644 index 0000000..4843ac5 --- /dev/null +++ b/native/internal/tell/jit_linux_amd64.go @@ -0,0 +1,169 @@ +//go:build linux && amd64 + +package tell + +import ( + "encoding/binary" + "fmt" + "math" + "strings" + "syscall" + "unsafe" +) + +func nativeJITAvailable() bool { return true } + +//go:noescape +func callNativeJIT(entry uintptr, arguments *float64) float64 + +func releaseNativeJIT(code *nativeCode) { + if code == nil || len(code.mapping) == 0 { + return + } + _ = syscall.Munmap(code.mapping) + code.mapping = nil + code.entry = 0 +} + +func compileNativeJIT(function BytecodeFunction) (*nativeCode, error) { + if function.Receiver || function.HasVariadic || len(function.Defaults) != 0 { + return nil, fmt.Errorf("methods, variadic parameters, and default arguments are not supported by the native JIT") + } + if !strings.EqualFold(function.ReturnType, "number") && !strings.EqualFold(function.ReturnType, "decimal") { + return nil, fmt.Errorf("native JIT currently requires a number or decimal return type") + } + if len(function.ParameterTypes) != len(function.Parameters) || len(function.Parameters) > 7 { + return nil, fmt.Errorf("native JIT requires up to seven explicitly typed numeric parameters") + } + parameterIndex := make(map[string]int, len(function.Parameters)) + for index, name := range function.Parameters { + typeName := strings.ToLower(strings.TrimSpace(function.ParameterTypes[index])) + if typeName != "number" && typeName != "decimal" { + return nil, fmt.Errorf("native JIT parameter %q is not numeric", name) + } + parameterIndex[name] = index + } + + code := make([]byte, 0, len(function.Instructions)*12) + stackDepth := 0 + returned := false + for _, instruction := range function.Instructions { + if returned { + break + } + switch instruction.Op { + case "PUSH": + number, ok := numericConstant(instruction.Value) + if !ok { + return nil, fmt.Errorf("native JIT only accepts numeric constants") + } + if stackDepth >= 7 { + return nil, fmt.Errorf("native JIT expression exceeds seven live numeric values") + } + register := byte(stackDepth) + code = append(code, 0x48, 0xB8) // movabs rax, imm64 + var bits [8]byte + binary.LittleEndian.PutUint64(bits[:], math.Float64bits(number)) + code = append(code, bits[:]...) + code = append(code, 0x66, 0x48, 0x0F, 0x6E, 0xC0|(register<<3)) // movq xmmN, rax + stackDepth++ + case "LOAD": + index, ok := parameterIndex[instruction.Name] + if !ok { + return nil, fmt.Errorf("native JIT cannot load non-parameter %q", instruction.Name) + } + if stackDepth >= 7 { + return nil, fmt.Errorf("native JIT expression exceeds seven live numeric values") + } + register := byte(stackDepth) + displacement := int32(index * 8) + code = append(code, 0xF2, 0x0F, 0x10, 0x87|(register<<3)) // movsd xmmN, [rdi+disp32] + var bits [4]byte + binary.LittleEndian.PutUint32(bits[:], uint32(displacement)) + code = append(code, bits[:]...) + stackDepth++ + case "UNARY": + if stackDepth < 1 { + return nil, fmt.Errorf("native JIT encountered unary stack underflow") + } + register := byte(stackDepth - 1) + switch instruction.Name { + case "+": + // Unary plus leaves the value unchanged. + case "-": + // Reserve xmm7 as a scratch register for the IEEE-754 sign bit. + code = append(code, 0x48, 0xB8) + var bits [8]byte + binary.LittleEndian.PutUint64(bits[:], uint64(1)<<63) + code = append(code, bits[:]...) + code = append(code, 0x66, 0x48, 0x0F, 0x6E, 0xF8) // movq xmm7, rax + code = append(code, 0x66, 0x0F, 0x57, 0xC0|(register<<3)|0x07) // xorpd xmmN, xmm7 + default: + return nil, fmt.Errorf("native JIT does not support unary operator %q", instruction.Name) + } + case "BINARY": + if stackDepth < 2 { + return nil, fmt.Errorf("native JIT encountered binary stack underflow") + } + left := byte(stackDepth - 2) + right := byte(stackDepth - 1) + var opcode byte + switch instruction.Name { + case "+": + opcode = 0x58 // addsd + case "-": + opcode = 0x5C // subsd + case "*": + opcode = 0x59 // mulsd + default: + return nil, fmt.Errorf("native JIT does not support binary operator %q", instruction.Name) + } + code = append(code, 0xF2, 0x0F, opcode, 0xC0|(left<<3)|right) + stackDepth-- + case "RETURN": + if stackDepth != 1 { + return nil, fmt.Errorf("native JIT return requires exactly one numeric value") + } + code = append(code, 0xC3) // ret; result is already in xmm0 + returned = true + default: + return nil, fmt.Errorf("native JIT does not support %s instructions", instruction.Op) + } + } + if !returned { + return nil, fmt.Errorf("native JIT function has no return") + } + + mapping, err := syscall.Mmap( + -1, 0, len(code), + syscall.PROT_READ|syscall.PROT_WRITE, + syscall.MAP_PRIVATE|syscall.MAP_ANON, + ) + if err != nil { + return nil, fmt.Errorf("allocate native code page: %w", err) + } + copy(mapping, code) + if err := syscall.Mprotect(mapping, syscall.PROT_READ|syscall.PROT_EXEC); err != nil { + _ = syscall.Munmap(mapping) + return nil, fmt.Errorf("make native code executable: %w", err) + } + entry := uintptr(unsafe.Pointer(&mapping[0])) + return &nativeCode{entry: entry, mapping: mapping}, nil +} + +func numericConstant(value any) (float64, bool) { + switch number := value.(type) { + case float64: + return number, true + case float32: + return float64(number), true + case int: + return float64(number), true + case int32: + return float64(number), true + case int64: + return float64(number), true + default: + return 0, false + } +} diff --git a/native/internal/tell/jit_linux_amd64.s b/native/internal/tell/jit_linux_amd64.s new file mode 100644 index 0000000..71706ed --- /dev/null +++ b/native/internal/tell/jit_linux_amd64.s @@ -0,0 +1,13 @@ +//go:build linux && amd64 + +#include "textflag.h" + +// callNativeJIT bridges Go's stack-based ABI to the System V amd64 ABI used by +// the generated leaf functions. Generated code receives *float64 in RDI and +// returns a float64 in XMM0. +TEXT ·callNativeJIT(SB), NOSPLIT, $0-24 + MOVQ entry+0(FP), AX + MOVQ arguments+8(FP), DI + CALL AX + MOVSD X0, ret+16(FP) + RET diff --git a/native/internal/tell/jit_test.go b/native/internal/tell/jit_test.go new file mode 100644 index 0000000..49995b0 --- /dev/null +++ b/native/internal/tell/jit_test.go @@ -0,0 +1,308 @@ +package tell + +import ( + "bytes" + "encoding/json" + "io" + "strconv" + "strings" + "testing" +) + +const jitNumericSource = `to weighted(number: left, number: right) out number: + give back left * 3 + right * 2 +end function +` + +func compiledJITFunction(t *testing.T) BytecodeFunction { + t.Helper() + artifact, err := Compile(jitNumericSource, "jit-numeric.tell") + if err != nil { + t.Fatalf("compile typed numeric function: %v", err) + } + var program BytecodeProgram + if err := json.Unmarshal(artifact, &program); err != nil { + t.Fatalf("decode compiled program: %v", err) + } + for _, function := range program.Functions { + if function.Name == "weighted" { + return function + } + } + t.Fatal("compiled bytecode did not contain weighted") + return BytecodeFunction{} +} + +func TestNativeJITMatchesInterpreterForTypedNumericFunction(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + function := compiledJITFunction(t) + for _, engine := range []string{"interp", "jit"} { + t.Run(engine, func(t *testing.T) { + r := newRuntime("jit-numeric.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = engine + result, err := callBytecodeFunction(r, function, r.global, []BytecodeFunction{function}, nil, []any{4.0, 6.0}, nil, nil) + if err != nil { + t.Fatalf("%s execution failed: %v", engine, err) + } + number, err := numberValue(result) + if err != nil { + t.Fatalf("result is not numeric: %v", err) + } + if number != 24 { + t.Fatalf("unexpected result: got %v, want 24", number) + } + if engine == "jit" { + if r.jitStats.JITCompiledFunctions != 1 || r.jitStats.JITInvocations != 1 { + t.Fatalf("native JIT was not used: %+v", r.jitStats) + } + } + r.closeJIT() + }) + } +} + +func TestAutoEngineCompilesAfterHotThreshold(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + function := compiledJITFunction(t) + r := newRuntime("jit-hot.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = "auto" + r.jitHotThreshold = 3 + + for index := 0; index < 3; index++ { + result, err := callBytecodeFunction(r, function, r.global, []BytecodeFunction{function}, nil, []any{2.0, 8.0}, nil, nil) + if err != nil { + t.Fatalf("call %d failed: %v", index+1, err) + } + number, _ := numberValue(result) + if number != 22 { + t.Fatalf("call %d returned %v, want 22", index+1, number) + } + if index < 2 && r.jitStats.JITInvocations != 0 { + t.Fatalf("JIT ran before hot threshold: %+v", r.jitStats) + } + } + if r.jitStats.JITCompiledFunctions != 1 || r.jitStats.JITInvocations != 1 || r.jitStats.InterpretedCalls != 2 { + t.Fatalf("unexpected tiering stats: %+v", r.jitStats) + } + r.closeJIT() +} + +func TestNativeJITPreservesDivisionByZeroSemantics(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + source := `to divide(number: numerator, number: denominator) out number: + give back numerator / denominator +end function +` + artifact, err := Compile(source, "jit-division.tell") + if err != nil { + t.Fatalf("compile division function: %v", err) + } + var program BytecodeProgram + if err := json.Unmarshal(artifact, &program); err != nil { + t.Fatal(err) + } + var function BytecodeFunction + found := false + for index := range program.Functions { + if program.Functions[index].Name == "divide" { + assignJITFunctionKey(&program.Functions[index], "jit-division", index) + function, found = program.Functions[index], true + break + } + } + if !found { + t.Fatal("compiled bytecode did not contain divide") + } + r := newRuntime("jit-division.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = "jit" + _, err = callBytecodeFunction(r, function, r.global, program.Functions, program.Classes, []any{1.0, 0.0}, nil, nil) + if err == nil || !strings.Contains(err.Error(), "division by zero") { + t.Fatalf("expected interpreter division-by-zero error, got %v", err) + } + if r.jitStats.JITCompiledFunctions != 0 || r.jitStats.InterpretedCalls != 1 { + t.Fatalf("division function should have used interpreter fallback: %+v", r.jitStats) + } + r.closeJIT() +} + +func TestExecutionEngineOptionsAreValidated(t *testing.T) { + if ValidExecutionEngine("interp") == false || !ValidExecutionEngine("jit") || !ValidExecutionEngine("auto") { + t.Fatal("known execution engine names were rejected") + } + if ValidExecutionEngine("llvm") || ValidExecutionEngine("") { + t.Fatal("unknown execution engine name was accepted") + } + _, err := RunBytecodeWithEngine(nil, "empty.tbc", nil, io.Discard, DefaultExecutionLimits(), "unknown", 24) + if err == nil || !strings.Contains(err.Error(), "unknown execution engine") { + t.Fatalf("expected unknown execution engine error, got %v", err) + } +} + +func TestNativeJITFallsBackForControlFlowFunctions(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + source := `to absolute(number: value) out number: + if value < 0: + give back 0 - value + end if + give back value +end function +` + artifact, err := Compile(source, "jit-fallback.tell") + if err != nil { + t.Fatalf("compile fallback function: %v", err) + } + var program BytecodeProgram + if err := json.Unmarshal(artifact, &program); err != nil { + t.Fatal(err) + } + var function BytecodeFunction + found := false + for _, candidate := range program.Functions { + if candidate.Name == "absolute" { + function, found = candidate, true + break + } + } + if !found { + t.Fatal("compiled bytecode did not contain absolute") + } + r := newRuntime("jit-fallback.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = "jit" + result, err := callBytecodeFunction(r, function, r.global, program.Functions, program.Classes, []any{-9.0}, nil, nil) + if err != nil { + t.Fatalf("interpreter fallback failed: %v", err) + } + number, _ := numberValue(result) + if number != 9 { + t.Fatalf("unexpected fallback result: got %v, want 9", number) + } + if r.jitStats.JITCompiledFunctions != 0 || r.jitStats.InterpretedCalls != 1 { + t.Fatalf("unsupported function did not fall back: %+v", r.jitStats) + } + r.closeJIT() +} + +func TestRunBytecodeWithEngineReportsJITUse(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + source := jitNumericSource + "say weighted(4, 6)\n" + artifact, err := Compile(source, "jit-runner.tell") + if err != nil { + t.Fatal(err) + } + var output bytes.Buffer + stats, err := RunBytecodeWithEngine(artifact, "jit-runner.tbc", bytes.NewReader(nil), &output, DefaultExecutionLimits(), "jit", 24) + if err != nil { + t.Fatalf("run bytecode with JIT: %v", err) + } + if output.String() != "24\n" { + t.Fatalf("unexpected output: %q", output.String()) + } + if stats.JITCompiledFunctions != 1 || stats.JITInvocations != 1 { + t.Fatalf("expected one compiled function and one native invocation, got %+v", stats) + } +} + +func jitBenchmarkSource() string { + terms := make([]string, 0, 80) + for index := 1; index <= 40; index++ { + terms = append(terms, "left * "+strconv.Itoa(index*2-1)) + terms = append(terms, "right * "+strconv.Itoa(index*2)) + } + return "to weighted(number: left, number: right) out number:\n give back " + + strings.Join(terms, " + ") + "\nend function\n" +} + +func TestNativeJITMatchesInterpreterForLongNumericExpression(t *testing.T) { + if !NativeJITAvailable() { + t.Skip("native JIT backend is available only on linux/amd64") + } + artifact, err := Compile(jitBenchmarkSource(), "jit-long-expression.tell") + if err != nil { + t.Fatalf("compile long numeric expression: %v", err) + } + var program BytecodeProgram + if err := json.Unmarshal(artifact, &program); err != nil { + t.Fatal(err) + } + var function BytecodeFunction + found := false + for index := range program.Functions { + if program.Functions[index].Name == "weighted" { + assignJITFunctionKey(&program.Functions[index], "jit-long-expression", index) + function, found = program.Functions[index], true + break + } + } + if !found { + t.Fatal("compiled bytecode did not contain weighted") + } + for _, engine := range []string{"interp", "jit"} { + r := newRuntime("jit-long-expression.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = engine + result, err := callBytecodeFunction(r, function, r.global, program.Functions, nil, []any{4.0, 6.0}, nil, nil) + if err != nil { + t.Fatalf("%s failed: %v", engine, err) + } + number, err := numberValue(result) + if err != nil || number != 16240 { + t.Fatalf("%s returned %v (%v), want 16240", engine, number, err) + } + r.closeJIT() + } +} + +func BenchmarkTypedNumericFunctionEngines(b *testing.B) { + artifact, err := Compile(jitBenchmarkSource(), "jit-benchmark.tell") + if err != nil { + b.Fatal(err) + } + var program BytecodeProgram + if err := json.Unmarshal(artifact, &program); err != nil { + b.Fatal(err) + } + var function BytecodeFunction + for index := range program.Functions { + if program.Functions[index].Name == "weighted" { + assignJITFunctionKey(&program.Functions[index], "jit-benchmark", index) + function = program.Functions[index] + break + } + } + arguments := []any{4.0, 6.0} + for _, engine := range []string{"interp", "jit", "auto"} { + b.Run(engine, func(b *testing.B) { + r := newRuntime("jit-benchmark.tell", bytes.NewReader(nil), io.Discard, DefaultExecutionLimits()) + r.executionEngine = engine + r.jitHotThreshold = 24 + defer r.closeJIT() + b.ReportAllocs() + warmupCalls := 0 + if engine == "jit" { + warmupCalls = 1 + } else if engine == "auto" { + warmupCalls = r.jitHotThreshold + } + for index := 0; index < warmupCalls; index++ { + if _, err := callBytecodeFunction(r, function, r.global, program.Functions, program.Classes, arguments, nil, nil); err != nil { + b.Fatal(err) + } + } + b.ResetTimer() + for index := 0; index < b.N; index++ { + if _, err := callBytecodeFunction(r, function, r.global, program.Functions, program.Classes, arguments, nil, nil); err != nil { + b.Fatal(err) + } + } + }) + } +} diff --git a/native/internal/tell/runtime.go b/native/internal/tell/runtime.go index b230fcc..f6caf2c 100644 --- a/native/internal/tell/runtime.go +++ b/native/internal/tell/runtime.go @@ -89,6 +89,13 @@ type runtime struct { modules map[string]map[string]any bytecodeModules map[string]BytecodeProgram loading map[string]bool + + executionEngine string + jitHotThreshold int + jitCalls map[[32]byte]int + jitCache map[[32]byte]*nativeCode + jitUnsupported map[[32]byte]bool + jitStats EngineStats } func typeMatches(typeName string, value any, e *env) (bool, error) { @@ -269,7 +276,19 @@ func newRuntime(filename string, input io.Reader, output io.Writer, limits Execu if limits.MaxLoopIterations <= 0 { limits.MaxLoopIterations = defaults.MaxLoopIterations } - r := &runtime{filename: filename, reader: reader, output: output, limits: limits, modules: make(map[string]map[string]any), loading: make(map[string]bool)} + r := &runtime{ + filename: filename, + reader: reader, + output: output, + limits: limits, + modules: make(map[string]map[string]any), + loading: make(map[string]bool), + executionEngine: "interp", + jitHotThreshold: 24, + jitCalls: make(map[[32]byte]int), + jitCache: make(map[[32]byte]*nativeCode), + jitUnsupported: make(map[[32]byte]bool), + } r.global = newEnv(nil) r.installBuiltins(r.global) return r