The compiler is designed to be used either directly as a static library, or indirectly through a loader library.

The compiler::Info struct (include/compiler/info.h) describes a particular compiler implementation that can be used to compile programs for a particular mux_device_info_t. Info contains information about the compiler capabilities and metadata, and additionally acts as an interface for creating a compiler::Target object.

The compiler::Context interface (include/compiler/context.h) serves as an opaque wrapper over the LLVM context object. This object can also contain other shared state used by compiler modules, and contains a mutex that is locked when interacting with a specific instance of LLVM.

The compiler::Target interface (include/compiler/target.h) represents a particular target device to generate machine code for. This object is also responsible for creating instances of compiler::Module (described below) and listing snapshot stages.

The compiler::Module interface (include/compiler/module.h) is responsible for driving the compilation process from source code all the way to machine code. It acts as a container for LLVM IR by wrapping the LLVM Module object, and executes the required passes.

The compiler::Kernel interface (include/compiler/kernel.h) represents a single function entry point in a finalized compiler::Module. It’s main purpose is to provide an opportunity for the backend to perform optimizations and code generation as late as possible. Most of the work is driven by the compiler::Module::createSpecializedKernel method that creates a Mux runtime kernel potentially optimized for a set of execution options that will be passed to it during muxCommandNDRange.

The OpenCL standard defines an optional -cl-fast-relaxed-math flag that can be set when building programs, allowing optimizations on floating point arithmetic that could violate the IEEE-754 standard. When this flag is used we run the LLVM module level pass FastMathPass to perform these optimizations straight after frontend parsing from clang.

First the pass looks for any llvm::FPMathOperator instructions and for those found sets the llvm::FastMathFlags attribute to enable all of:

• Unsafe algebra - Operation can be algebraically transformed.

• No NaNs - Arguments and results can be treated as non-NaN.

• No Infs - Arguments and results can be treated as non-Infinity.

• No Signed Zeros - Sign of zero can be treated as insignificant.

• Allow Reciprocal - Reciprocal can be used instead of division.

As well as the above compiler::FastMathPass replaces maths and geometric builtin functions with fast variants. Any math builtin functions which have a native equivalent are replaced with the native function, specified as having an implementation defined maximum error. For example exp2(float4) is replaced with native_exp2(float4).

Geometric builtins distance, length, and normalize are all defined in OpenCL as having fast variants fast_distance, fast_length, and fast_normalize which use reduced precision maths. If any of these functions are present we also replace them with the relaxed alternative.

These builtin replacements are done by searching the LLVM module for call instructions which invoke the mangled name of a builtin function we want to replace. If the fast version of the builtin isn’t already in the module, i.e. it wasn’t called explicitly somewhere else, then we also need to add a function declaration for the mangled name of the fast builtin. Finally a new call instruction is created invoking the fast function declaration and the old call it replaces is deleted.

LLVM IR does not define the results of oversized shift amounts, however SPIR does. As a result shift instructions need to be updated to perform a ‘modulo N’ by the shift amount prior to the shift operation itself, where N is the bit width of the value to shift.

BitShiftFixupPass implements this as a LLVM function pass iterating over all the function instructions looking for shifts. For each shift found the pass uses the first operand to work out ‘N’ for the modulo based on the bit width of the operand type. If the shift amount from the second operand is less than N however, then we can skip the shift without inserting a modulo operation since the shift is not oversized. We can also skip shift instructions that already have the modulo applied, which can happen if the SPIR module was created by clang. Otherwise the pass creates a modulo by generating a ‘logical and’ instruction with operands N-1 and the original shift amount, this masked value is then used to replace the second operand of the shift.

The compiler pass SoftwareDivisionPass is a function level pass designed to prevent undefined behaviour in division operations. To do this the pass adds runtime checks using llvm::CmpInst instructions for two specific cases, divide by zero and INT_MIN / -1. Due to the specification of undefined behaviour if one of these cases is detected we are free to update the behaviour of the divide operation. In both cases we set the divisor operand of the divide instruction to be +1 using a llvm::SelectInst with the original operand based on the result of our checks.

Since IEEE-754 defines these error cases for floating point types our runtime checks only need to be applied to integer divides. This is ensured in the pass by checking if the instruction opcode is one of SDiv, SRem, UDiv, URem. Whereas floating point divide instructions will have opcode FDiv or FRem.

OpenCL image calls with opaque types are replaced to use those coming from the image library.

A manual implementation of LLVM’s MemToReg pass, which promotes allocas which have only loads and stores as uses to register references. This is needed because after LLVM 5.0 llvm:MemToReg has regressed and is not removing all the allocas it should be.

BuiltinSimplificationPass is a module level pass for simplifying builtin function calls. The pass performs two kinds of optimization on builtins:

• Converts builtins to more efficient variants where possible (for example, a call to the math function pow(x, y), where y is a constant that is representable by an integer, will be converted to pown(x, y)).

• Replace builtins whose arguments are all constant (for example, a call to the math function cos(x), where x is a constant, will be replaced by a new constant value that is the calculation of the cosine of x).

Of the myriad of architectures that have ComputeMux back ends, most do not have access to an implementation of printf whereby they can route a call to printf within a kernel to stdout of the process running on the host CPU processor.

To enable our ComputeMux back ends to call printf, we provide an optimized software implementation. An additional kernel argument buffer is implicitly added to any kernel that uses printf, and our implementation of printf that is run on the ComputeMux backend will write the results of the printf into this buffer instead. Then, when the kernel has completed its execution, the data that was written to this buffer is streamed out on the host CPU processor via stdout.

CombineFPExtFPTruncPass is a function level pass, rather than a module pass, for removing FPExt and FPTrunc instructions that cancel each out. This is used after the printf replacement pass because var-args printf arguments will be expanded to double by clang even if the device doesn’t support doubles. So if the device doesn’t support doubles, the printf pass will fptrunc the parameters back to float. CombineFPExtFPTruncPass will find and remove the matching fpext (added by clang) and fptrunc (added by the printf pass) to get rid of the doubles.

The pass is implemented by iterating over all the instructions looking for any llvm::FPExtInst instructions. If one is found then we check its uses, if the fpext is unused, remove it. Otherwise if the instruction only has one use and it’s a llvm::FPTruncInst then we can replace all uses of the fptrunc with the first operand of fpext and delete both the fptrunc and fpext.

In clang the convergent attribute can be set on a function to indicate to the optimizer that the function relies on cross work item semantics. For OpenCL we need this attribute to be set on the barrier function, for example, since it’s used to control the scheduling of threads. Recent versions of clang will proactively set such functions in OpenCL-C kernels as convergent, but we also set the attribute implicitly in the builtins header out of an abundance of caution.

This pass iterates over all the functions in the module, including declarations requiring the pass to be a module pass instead of a function pass. If the function inspected may be convergent, identified by the compiler’s BuiltinInfo analysis, then we assign the llvm::Attribute::Convergent attribute to it. When the pass encounters a convergent function, all functions calling that function are transitively marked convergent.