Running LLVM on GraalVM

GraalVM provides an implementation of the lli tool to directly executeprograms in LLVM bitcode form.

In contrast to static compilation that is normally used for LLVM basedlanguages, LLI first interprets the bitcode and then dynamically compiles thehot parts of the program using the GraalVM compiler. This allows seamlessinteroperability with the dynamic languages supported by GraalVM.

Run programs in LLVM bitcode format:

lli [LLI Options] [GraalVM Options] [Polyglot Options] filename [program args]

Where filename is a single executable that contains LLVM bitcode.

Note: LLVM bitcode is platform dependent. The program must be compiled tobitcode for the appropriate platform.

Compiling to LLVM Bitcode

GraalVM can execute C/C++, Rust, and other languages that can be compiled toLLVM bitcode. As a first step, you have to compile the program to LLVM bitcodeusing an LLVM frontend such as clang. C/C++ code can be compiled to LLVMbitcode using the clang shipped with GraalVM.

To download a pre-built LLVM toolchain for GraalVM, execute the followingcommands:

$ gu install llvm-toolchain
$ export LLVM_TOOLCHAIN=$(lli --print-toolchain-path)

Here is some example C code named hello.c:

#include <stdio.h>
int main() {
    printf("Hello from GraalVM!\n");
    return 0;
}

You can compile hello.c to an executable with embedded LLVM bitcode as follows:

$ $LLVM_TOOLCHAIN/clang hello.c -o hello

You can then run hello on GraalVM like this:

$ lli hello
Hello from GraalVM!

External library dependencies

If the bitcode file depends on external libraries, GraalVM will automaticallypick up the dependencies from the binary headers.

For example:

#include <unistd.h>
#include <ncurses.h>
int main() {
    initscr();
    printw("Hello, Curses!");
    refresh();
    sleep(1);
    endwin();
    return 0;
}

This can be run with:

$ $LLVM_TOOLCHAIN/clang hello-curses.c -lncurses -o hello-curses
$ lli hello-curses

Running C++

For running C++ code, the GraalVM LLVM runtime requires thelibc++ standard library from the LLVM project. TheLLVM toolchain shipped with GraalVM automatically links against libc++.

#include <iostream>
int main() {
    std::cout << "Hello, C++ World!" << std::endl;
}

Compile the code with clang++:

$ $LLVM_TOOLCHAIN/clang++ hello-c++.cpp -o hello-c++
$ lli hello-c++
Hello, C++ World!

Running Rust

The LLVM toolchain that is bundled with GraalVM does not come with the Rustcompiler. To install Rust, run the following in your terminal, then follow theonscreen instructions:

curl https://sh.rustup.rs -sSf | sh

Here is an example Rust program:

fn main() {
    println!("Hello Rust!");
}

This can be compiled to bitcode with the —emit=llvm-bc flag:

$ rustc --emit=llvm-bc hello-rust.rs

To run the Rust program, we have to tell GraalVM where to find the Ruststandard libraries.

$ lli --lib $(rustc --print sysroot)/lib/libstd-* hello-rust.bc
Hello Rust!

Interoperability

GraalVM supports several other programming languages, including JavaScript,Python, Ruby, and R. While LLI is designed to run LLVM bitcode, it also providesan API for programming language interoperability that lets you execute code fromany other language that GraalVM supports.

Dynamic languages like JavaScript usually access object members by name. Sincenormally names are not preserved in LLVM bitcode, it must be compiled with debuginfo enabled (the LLVM toolchain shipped with GraalVM will automatically enabledebug info).

The following example demonstrates how you can use the API for interoperabilitywith other programming languages.

Let us define a C struct for points and implement allocation functions:

// cpart.c
#include <polyglot.h>
#include <stdlib.h>
#include <stdio.h>
struct Point {
    double x;
    double y;
};
POLYGLOT_DECLARE_STRUCT(Point)
void *allocNativePoint() {
    struct Point *ret = malloc(sizeof(*ret));
    return polyglot_from_Point(ret);
}
void *allocNativePointArray(int length) {
    struct Point *ret = calloc(length, sizeof(*ret));
    return polyglot_from_Point_array(ret, length);
}
void freeNativePoint(struct Point *p) {
    free(p);
}
void printPoint(struct Point *p) {
    printf("Point<%f,%f>\n", p->x, p->y);
}

Make sure LLVMTOOLCHAIN resolves to the GraalVM LLVM toolchain (lli —print-toolchain-path),then compile _cpart.c with (the polyglot-mock library defines the polyglotAPI functions used in the example):

$ $LLVM_TOOLCHAIN/clang -shared cpart.c -lpolyglot-mock -o cpart.so

You can access your C/C++ code from other languages like JavaScript:

// jspart.js
// Load and parse the LLVM bitcode into GraalVM
var cpart = Polyglot.evalFile("llvm" ,"cpart.so");
// Allocate a light-weight C struct
var point = cpart.allocNativePoint();
// Access it as if it were a JS object
point.x = 5;
point.y = 7;
// Pass it back to a native function
cpart.printPoint(point);
// We can also allocate an array of structs
var pointArray = cpart.allocNativePointArray(15);
// We can access this array like it was a JS array
for (var i = 0; i < pointArray.length; i++) {
    var p = pointArray[i];
    p.x = i;
    p.y = 2*i;
}
cpart.printPoint(pointArray[3]);
// We can also pass a JS object to a native function
cpart.printPoint({x: 17, y: 42});
// Don't forget to free the unmanaged data objects
cpart.freeNativePoint(point);
cpart.freeNativePoint(pointArray);

Run this JavaScript file with:

$ js --polyglot jspart.js
Point<5.000000,7.000000>
Point<3.000000,6.000000>
Point<17.000000,42.000000>

Polyglot C API

There are also lower level API functions for directly accessing polyglot valuesfrom C. See the Polyglot Referenceand the documentation comments in polyglot.h for more details.

For example, this program allocates and accesses a Java array from C:

#include <stdio.h>
#include <polyglot.h>
int main() {
    void *arrayType = polyglot_java_type("int[]");
    void *array = polyglot_new_instance(arrayType, 4);
    polyglot_set_array_element(array, 2, 24);
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}

Compile it to LLVM bitcode:

$ $LLVM_TOOLCHAIN/clang polyglot.c -lpolyglot-mock -o polyglot

And run it, using the —jvm argument to run GraalVM in the JVM mode, since we areusing a Java type:

$ lli --jvm polyglot
24

Embedding in Java

GraalVM can also be used to embed LLVM bitcode in Java host programs.

For example, let us write a Java class Polyglot.java that embeds GraalVM torun the previous example:

import java.io.*;
import org.graalvm.polyglot.*;
class Polyglot {
    public static void main(String[] args) throws IOException {
        Context polyglot = Context.newBuilder().
                               allowAllAccess(true).build();
        File file = new File("polyglot");
        Source source = Source.newBuilder("llvm", file).build();
        Value cpart = polyglot.eval(source);
        cpart.execute();
    }
}

Compiling and running it:

$ javac Polyglot.java
$ java Polyglot
24

See the Embedding documentationfor more information.

Source-Level Debugging

You can use GraalVM’s Debugger to debug the programyou compiled to LLVM bitcode.To use this feature, please make sure to compile your program with debug information by specifying the -gargument when compiling with clang (the LLVM toolchain shipped with GraalVM will automatically enabledebug info). This gives you the ability to step through the program’s source code and set breakpoints in it.To also be able to inspect the local and global variables of your program you may pass—llvm.enableLVI=true as argument to lli.This option is not enabled per default as it can significantly decrease your program’s run-time performance.

LLVM Compatibility

GraalVM works with LLVM bitcode versions 3.8 to 9.0. We recommend using theversion of LLVM that is shipped with GraalVM.

Optimization Flags

In contrast to the static compilation model of LLVM languages, in GraalVM themachine code is not directly produced from the LLVM bitcode, but there is anadditional dynamic compilation step by the GraalVM compiler.

In this scenario, first the LLVM frontend (e.g. clang) does optimizations onthe bitcode level, and then the GraalVM compiler does its own optimizations on top of thatduring dynamic compilation. Some optimizations are better when doneahead-of-time on the bitcode, while other optimizations are better left for thedynamic compilation of the GraalVM compiler, when profiling information is available.

The LLVM toolchain that is shipped with GraalVM automatically selects therecommended flags by default.

In principle, all optimization levels should work, but for best results wesuggest compiling the bitcode with optimization level -O1.

Cross-language interoperability will only work when the bitcode is compiledwith debug information enabled (-g), and the -mem2reg optimization isperformed on the bitcode (compiled with at least -O1, or explicitly using theopt tool).

LLI Command Options

—print-toolchain-path: print the path of the LLVM toolchain bundled withGraalVM. This directory contains compilers and tools that can be used tocompile C/C++ programs to LLVM bitcode for execution with GraalVM.

-L <path>/—llvm.libraryPath=<path>: a list of paths where GraalVM willsearch for library dependencies. Paths are delimited by :.

—lib <libs>/—llvm.libraries=<libs>: a list of libraries to load. The listcan contain precompiled native libraries (.so/.dylib) and bitcodelibraries (*.bc). Files with a relative path are looked up relative tollvm.libraryPath. Entries are delimited by :.

—llvm.enableLVI=<true/false>: enable source-level symbol inspection in thedebugger. This defaults to false as it can decrease run-time performance.

—llvm.managed enable a managed execution mode for LLVM IR code, which means memory allocations from LLVM bitcode are done on the managed heap. This article explains the managed execution in every detail.

—version prints the version and exit.

—version:graalvm prints GraalVM version information and exit.

Expert and Diagnostic Options

Use —help and —help:<topic> to get a full list of options.

Limitations and Differences to Native Execution

LLVM code interpreted or compiled with the default configuration of GraalVMCommunity or Enterprise editions will not have the same characteristics as thesame code interpreted or compiled in a managed environment, enabledwith the —llvm.managed option on top of GraalVM Enterprise. Thebehavior of the lli interpreter tool used to directly execute programsin LLVM bitcode format differs between native and managed modes. Thedifference lies in safety guarantees and cross-language interoperability.

In the default configuration, cross-language interoperability requires bitcodeto be compiled with the debug information enabled (-g), and the -mem2regoptimization is performed on the bitcode (compiled with at least -O1, orexplicitly using the opt tool). These requirements can be overcome in amanaged environment of GraalVM EE that allows native code to participate in thepolyglot programs, passing and receiving the data from any other supportedlanguage. In terms of security, the execution of native code in a managedenvironment passes with additional safety features: catching illegal pointeraccesses, accessing arrays outside of the bounds, etc..

There are certain limitations and differences to the native execution depending on the GraalVM edition.Consider them respectively.

Limitations and Differences to Native Execution on Top of GraalVM CE

The LLVM interpreter in GraalVM Community Edition environment allows executing LLVM bitcode within amultilingual context. Even though it aspires to be a generic LLVM runtime, thereare certain fundamental and/or implementational limitations that users need tobe aware of.

The following restrictions and differences to native execution (i.e., bitcode compiled down to native code) exist when LLVM bitcode is executed with the LLVM interpreter on top of GraalVM CE:

• The GraalVM LLVM interpreter assumes that bitcode was generated to target the x86_64 architecture.
• Bitcode should be the result of compiling C/C++ code using clang version 7, other compilers/languages, e.g., Rust, might have specific requirements that are not supported.
• Unsupported functionality – it is not possible to call any of the following functions:
  • clone()
  • fork()
  • vfork()
  • setjmp(), sigsetjmp(), longjmp(), siglongjmp()
  • Functions of the exec() function family
  • Pthread functions
  • Code running in the LLVM interpreter needs to be aware that a JVM is running in the same process, so many syscalls such as fork, brk, sbrk, futex, mmap, rt_sigaction, rt_sigprocmask, etc. might not work as expected or cause the JVM to crash.
  • Calling unsupported syscalls or unsupported functionality (listed above) via native code libraries can cause unexpected side effects and crashes.
• Thread local variables
  • Thread local variables from bitcode are not compatible with thread local variables from native code.
• Cannot rely on memory layout
  • Pointers to thread local variables are not stored in specific locations, e.g., the FS segment.
  • The order of globals in memory might be different, consequently no assumptions about their relative locations can be made.
  • Stack frames cannot be inspected or modified using pointer arithmetic (overwrite return address, etc.).
  • Walking the stack is only possible using the Truffle APIs.
  • There is a strict separation between code and data, so that reads, writes and pointer arithmetic on function pointers or pointers to code will lead to undefined behavior.
• Signal handlers
  • Installing signal handlers is not supported.
• The stack
  • The default stack size is not set by the operating system but by the option —llvm.stackSize.
• Dynamic linking
  • Interacting with the LLVM bitcode dynamic linker is not supported, e.g., dlsym/dlopen can only be used for native libraries.
  • The dynamic linking order is undefined if native libraries and LLVM bitcode libraries are mixed.
  • Native libraries cannot import symbols from bitcode libraries.
• x86_64 inline assembly is not supported.
• Undefined behavior according to C spec
  • While most C compilers map undefined behavior to CPU semantics, the GraalVM LLVM interpreter might map some of this undefined behavior to Java or other semantics. Examples include: signed integer overflow (mapped to the Java semantics of an arithmetic overflow), integer division by zero (will throw an ArithmeticException), oversized shift amounts (mapped to the Java behavior).
• Floating point arithmetics
  • Some floating point operations and math functions will use more precise operations and cast the result to a lower precision (instead of performing the operation at a lower precision).
  • Only the rounding mode FE_TONEAREST is supported.
  • Floating point exceptions are not supported.
• NFI limitations (calling real native functions)
  • Structs, complex numbers, or fp80 values are not supported as by-value arguments or by-value return values.
  • The same limitation applies to calls back from native code into interpreted LLVM bitcode.
• Limitations of polyglot interoperability (working with values from other GraalVM languages)
  • Foreign objects cannot be stored in native memory locations. Native memory locations include:
    • globals (except the specific case of a global holding exactly one pointer value);
    • malloc’ed memory (including c++ new, etc.);
    • stack (e.g. escaping automatic variables).
• LLVM instruction set support (based on LLVM 7.0.1)
  • A set of rarely-used bitcode instructions are not available (va_arg, catchpad, cleanuppad, catchswitch, catchret, cleanupret, fneg, callbr).
  • The instructions with limited support:
    • atomicrmw (only supports sub, add, and, nand, or, xor, xchg);
    • extract value and insert value (only supports a single indexing operand);
    • cast (missing support for certain rarely-used kinds);
    • atomic ordering and address space attributes of load and store instructions are ignored.
  • Values – assembly constants are not supported (module-level assembly and any assembly strings).
  • Types:
    • There is no support for 128-bit floating point types (fp128 and ppc_fp128), x86_mmx, half-precision floats (fp16) and any vectors of unsupported primitive types.
    • The support for fp80 is limited (not all intrinsics are supported for fp80, some intrinsics or instructions might silently fall back to fp64).
• A number of rarely-used or experimental intrinsics based on LLVM 7.0.1 are not supported because of implementational limitations or because they are out of scope:
  • experimental intrinsics: llvm.experimental.*, llvm.launder.invariant.group, llvm.strip.invariant.group;
  • trampoline intrinsics: llvm.init.trampoline, llvm.adjust.trampoline;
  • general intrinsics: llvm.var.annotation, llvm.ptr.annotation, llvm.annotation, llvm.codeview.annotation, llvm.trap, llvm.debugtrap, llvm.stackprotector, llvm.stackguard, llvm.ssa_copy, llvm.type.test, llvm.type.checked.load, llvm.load.relative, llvm.sideeffect;
  • specialised arithmetic intrinsics: llvm.canonicalize, llvm.fmuladd;
  • standard c library intrinsics: llvm.fma, llvm.trunc, llvm.nearbyint, llvm.round;
  • code generator intrinsics: llvm.returnaddress, llvm.addressofreturnaddress, llvm.frameaddress, llvm.localescape, llvm.localrecover, llvm.read_register, llvm.write_register, llvm.stacksave, llvm.stackrestore, llvm.get.dynamic.area.offset, llvm.prefetch, llvm.pcmarker, llvm.readcyclecounter, llvm.clear_cache, llvm.instrprof*, llvm.thread.pointer;
  • exact gc intrinsics: llvm.gcroot, llvm.gcread, llvm.gcwrite;
  • element wise atomic memory intrinsics: llvm.*.element.unordered.atomic;
  • masked vector intrinsics: llvm.masked.*;
  • bit manipulation intrinsics: llvm.bitreverse, llvm.fshl, llvm.fshr.

Limitations and Differences to Managed Execution on Top of GraalVM EE

A managed execution for LLVM intermediate representation code is GraalVMEnterprise Edition feature and can be enabled with —llvm.managed commandline option. In the managed mode, GraalVM LLVM prevents access to unmanagedmemory and uncontrolled calls to native code and operating system functionality.The allocations are performed in the managed Java heap, and accesses to thesurrounding system are routed through proper Truffle API and Java API calls.

All the restrictions from the default native LLVM execution on GraalVM apply to the managed execution, but with the following differences/changes:

• Platform independent
  • Bitcode must be compiled for the a generic linux_x86_64 target, using the provided musl libc library, on all platforms, regardless of the actual underlying operating system.
• C++
  • C++ is currently not supported in a managed mode.
• Native memory and code
  • Calls to native functions are not possible, thus only the functionality provided in the supplied musl libc and by the GraalVM LLVM interface is available.
  • Loading native libraries is not possible.
  • Native memory access is not possible.
• System calls
  • System calls with only limited support are read, readv, write, writev, open, close, dup, dup2, lseek, stat, fstat, lstat, chmod, fchmod, ioctl, fcntl, unlink, rmdir, utimensat, uname, set_tid_address, gettid, getppid, getpid, getcwd, exit, exit_group, clock_gettime, arch_prctl.
  • The functionality is limited to common terminal IO, process control and file system operations.
  • Some syscalls are implemented as a noop and/or return errors warning that they are not available, e.g. chown, lchown, fchown, brk, rt_sigaction, sigprocmask, futex.
• Musl libc
  • The musl libc library behaves differently than the more common glibc in some cases.
• The stack
  • Accessing the stack pointer directly is not possible.
  • The stack is not contiguous, and accessing memory that is out of the bounds of a stack allocation (e.g., accessing neighboring stack value using pointer arithmetics) is not possible.
• Pointers into the managed heap
  • Reading parts of a managed pointer is not possible.
  • Overwriting parts of a managed pointer (e.g., using bits for pointer tagging) and subsequently dereferencing the destroyed managed pointer is not possible.
  • Undefined behavior in C pointer arithmetics applies.
  • Complex pointer arithmetics (e.g., multiplying pointers) can convert a managed pointer to an i64 value – the i64 value can be used in pointer comparisons but cannot be dereferenced.
• Floating point arithmetics
  • 80-bit floating points only use 64-bit floating point precision.
• Dynamic linking
  • The interaction with the LLVM bitcode dynamic linker is not supported, e.g., dlsym/dlopen cannot be used. This does not allow to load native code.