Burst User Guide

Overview

Burst is a compiler from IL/.NET bytecode to highly optimized native code using LLVM. It is released as a unity package and integrated into Unity using the Unity Package Manager.

Quick Start

Compile a Job with the burst compiler

Burst is primarily designed to work efficiently with the Job system.

You can start using the burst compiler in your code by simply decorating a Job struct with the attribute [BurstCompile]

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using UnityEngine;

public class MyBurst2Behavior : MonoBehaviour
{
    void Start()
    {
        var input = new NativeArray<float>(10, Allocator.Persistent);
        var output = new NativeArray<float>(1, Allocator.Persistent);
        for (int i = 0; i < input.Length; i++)
            input[i] = 1.0f * i;

        var job = new MyJob
        {
            Input = input,
            Output = output
        };
        job.Schedule().Complete();

        Debug.Log("The result of the sum is: " + output[0]);
        input.Dispose();
        output.Dispose();
    }

    // Using BurstCompile to compile a Job with burst
    // Set CompileSynchronously to true to make sure that the method will not be compiled asynchronously
    // but on the first schedule
    [BurstCompile(CompileSynchronously = true)]
    private struct MyJob : IJob
    {
        [ReadOnly]
        public NativeArray<float> Input;

        [WriteOnly]
        public NativeArray<float> Output;

        public void Execute()
        {
            float result = 0.0f;
            for (int i = 0; i < Input.Length; i++)
            {
                result += Input[i];
            }
            Output[0] = result;
        }
    }
}

By default within the Editor, burst JIT compile jobs asynchronously, but in the example above, we are using the option CompileSynchronously = true to make sure that the method will be compiled on the first schedule. In general, you should use asynchronous compilation. See [BurstCompile] options

Jobs/Burst Menu

Burst is adding a few menu entries to the Jobs menu:

• Use Burst Jobs: When this is checked, Jobs with the attribute [BurstCompile] will be compiled by burst. Default is checked
• Burst Inspector: Opens the Burst Inspector Window
• Enable Burst Safety Checks: When this is checked, code that will use collection containers (e.g NativeArray<T>) will check safety usages most notably the job data dependency checking system and containers index out of bounds. Note that this option is disabling by default noaliasing performance optimizations. Default is checked
• Enable Burst Compilation: When this is checked, burst will compile jobs and burst custom delegates that are tagged with the attribute [BurstCompile]. Default is checked
• Show Burst Timings: When this is checked, everytime burst will have to JIT compile a job in the Editor, the timing taken to compile this method will be displayed in the log. Default is unchecked

Burst Inspector

From the Jobs menu, you can open the burst inspector that allows to view all the jobs that can be compiled and you can then check the generated native code.

On the left pane, we have Compile Targets that provide a list of Jobs that burst can compile. Jobs that are white highlighted can be compiled by burst while the ones that are disabled don't have the [BurstCompile] attribute.

1. Select an active compile target from the left pane.
2. On the right pane, press the button Refresh Disassembly
3. Switch between the different tabs to display the details:
   • The tab Assembly provides the final optimized native code generated by burst
   • The tab .NET IL provides a view on the original .NET IL extracted from the Job method
   • The tab LLVM (Unoptimized) provides a view on the internal LLVM IR before optimizations.
   • The tab LLVM (Optimized) provides a view on the internal LLVM IR after optimizations.
   • The tab LLVM IR Optimization Diagnostics provides detailed LLVM diagnostics of the optimizations (i.e if they succeeded or failed).
4. You can also switch different options:
   • The Safety Checks if enabled will generate code that include containers accesses safety checks (e.g check if a job is writing to a native container that is readonly)
   • The Optimizations option if enabled allows the compiler to optimize code
   • The Fast Math option if enabled allows the compiler to collapse mathematical operations in a more efficient at the expense of not respecting an exact mathematical correctness

C#/.NET Language Support

Burst is working on a subset of .NET that doesn't allow managed objects/reference types (class in C#).

The following sections gives more details about the constructs actually supported by burst.

Supported .NET types

Primitive types

Burst supports the following primitive types:

• char
• sbyte/byte
• short/ushort
• int/uint
• long/ulong
• float
• double

Burst does not support the following type:

• string as this is a managed type
• decimal

Vector types

Burst is able to translate vector types from Unity.Mathematics to native SIMD vector types with first class support for optimizations:

• bool2/bool3/bool4
• uint2/uint3/uint4
• int2/int3/int4
• float2/float3/float4

Enum types

Burst supports all enums including enums with a specific storage type (e.g public enum MyEnum : short)

Burst currently doesn't currently support Enum methods (e.g Enum.HasFlag)

Struct types

Burst supports regular structs with any of supported types.

Burst supports fixed array fields.

Regarding the layout, LayoutKind.Sequential and LayoutKind.Explicit are supported

The StructLayout.Pack packing size is not supported

The System.IntPtr and UIntPtr are supported natively as an intrinsic structs directly representing pointers.

Pointer types

Burst supports any pointer types to any burst supported types

Generic types

Burst supports generic types used with structs. Specifically, it supports full instantiation of generic calls for generic types with interface constraints (e.g when a struct with a generic parameter requiring to implement an interface)

Array types

Managed arrays are not supported by burst. You should use instead a native container like NativeArray<T>

Language Support

Burst supports the following code flows and syntaxes:

• Regular C# control flows:
  • if/else/switch/case/for/while/break/continue
• Extension methods
• Unsafe code, pointers manipulation...etc.
• Instance methods of structs
• By ref/out parameters
• Calling an icall/internal function
• Limited support for throw expressions, assuming simple throw patterns (e.g throw new ArgumentException("Invalid argument")). In that case, we will try to extract the static string exception message to include it in the generated code.
• Some special IL opcodes like cpblk, initblk, sizeof
• Loading from static readonly fields

Burst does not support:

• DllImport or calli (This should be supported in a future version)
• catch
• try/finally (which will come at some point)
• foreach as it is requiring try/finally (This should be supported in a future version)
• Loading from non readonly static fields or storing to static fields
• Any methods related to managed objects (e.g array access...etc.)

Intrinsics

System.Math

Burst provides an intrinsic for all methods declared by System.Math except for the following methods that are not supported:

• double IEEERemainder(double x, double y)
• Round(double value, int digits)

System.IntPtr

Burst supports all methods of System.IntPtr/System.UIntPtr, including the static fields IntPtr.Zero and IntPtr.Size

System.Threading.Interlocked

Burst supports atomic memory intrinsics for all methods provided by System.Threading.Interlocked (e.g Interlocked.Increment...etc.)

NativeArray<T>

Burst supports intrinsics with noalias only for the following NativeArray<T> methods:

• int Length { get; }
• T this[int index] { get; set; }

Optimization Guidelines

Memory Aliasing and noalias

Memory aliasing is an important concept that can lead to significant optimizations for a compiler that is aware about how the data are being used by the code.

The problem

Let's take a simple example of a job copying data from an input array to an output array:

[BurstCompile]
private struct CopyJob : IJob
{
    [ReadOnly]
    public NativeArray<float> Input;

    [WriteOnly]
    public NativeArray<float> Output;

    public void Execute()
    {
        for (int i = 0; i < Input.Length; i++)
        {
            Output[i] = Input[i];
        }
    }
}

No memory aliasing:

If the two arrays Input and Output are not slightly overlapping, meaning that their respective memory location are not aliasing, we will get the following result after running this job on a sample input/output:

No memory aliasing with the auto-vectorizer:

Now, if the compiler is noalias aware, it will be able to optimize the previous scalar loop (working at a scalar level) by what is called vectorizing: The compiler will rewrite the loop on your behalf to process elements by a small batch (working at a vector level, 4 by 4 elements for example) like this:

Memory aliasing:

Next, if for some reasons (that is not directly easy to introduce with the JobSystem today), the Output array is actually overlapping the Input array by one element off (e.g Output[0] points actually to Input[1]) meaning that memory are aliasing, we will get the following result when running the CopyJob (assuming that the auto-vectorizer is not running):

Memory aliasing with invalid vectorized code:

Worse, if the compiler was not aware of this memory aliasing, it would still try to auto-vectorize the loop, and we would get the following result, which is different from the previous scalar version:

The result of this code would be invalid and could lead to very serious bugs if they are not identified by the compiler.

The solution with burst and the JobSystem

To ensure that a Job can be safely vectorized (when there is a loop), burst relies on:

• The assumption brought by the safety of the JobSystem regarding the data in input/output that you can specify in the Job: It means that by default, all data accessed safety through a job are not aliasing
• A further analysis of burst on the code to make sure that the code is also safe

The alias analysis in burst is currently relying on a few constraints that your code needs to follow in order to let the auto-vectorizer to work correctly:

• Only NativeArray<T> is used and only the property Length and or the indexer this[index] are used
• Native containers (e.g NativeArray<T>) or a struct containing indirectly a container should not be copied to a local variable
• Native containers can be passed by value to a method argument, at the condition that all arguments are coming from identified source, either from fields or other arguments from static methods, but not both and that the method is static
• Native Containers or a struct containing indirectly a container are not stored to a field of a struct
• Assuming that the option Enable Burst Safety Checks is unchecked in the Jobs menu

We are expecting to improve the alias analysis with a finer grained model that will allow to relax a few of these constraints.

Example of generated code with noalias analysis

Let's take the example of the CopyJob, with the compiled to native code with the noalias analysis disabled.

The following loop is the result of the compilation x64 using AVX2 instructions with noalias analysis enabled: (Note that we are only copying the core loop, not the full prolog, epilog of the whole method)

The instruction vmovups is moving 8 floats here, so a single auto-vectorized loop is now moving 4 x 8 = 32 floats copied per loop iteration instead of one! (So there will be /32th of loop step iterations compare to the original loop)

.LBB0_4:
    vmovups ymm0, ymmword ptr [rcx - 96]
    vmovups ymm1, ymmword ptr [rcx - 64]
    vmovups ymm2, ymmword ptr [rcx - 32]
    vmovups ymm3, ymmword ptr [rcx]
    vmovups ymmword ptr [rdx - 96], ymm0
    vmovups ymmword ptr [rdx - 64], ymm1
    vmovups ymmword ptr [rdx - 32], ymm2
    vmovups ymmword ptr [rdx], ymm3
    sub     rdx, -128
    sub     rcx, -128
    add     rsi, -32
    jne     .LBB0_4
    test    r10d, r10d
    je      .LBB0_8

The same loop with the noalias analysis disabled will be copying only a single float per loop iteration:

.LBB0_2:
    mov     r8, qword ptr [rcx]
    mov     rdx, qword ptr [rcx + 16]
    cdqe
    mov     edx, dword ptr [rdx + 4*rax]
    mov     dword ptr [r8 + 4*rax], edx
    inc     eax
    cmp     eax, dword ptr [rcx + 8]
    jl      .LBB0_2

As we can see, the performance difference can be significant here. That's why noalias aware native code generation is fundamental, and that's that burst is trying to bring.

Unity.Mathematics

TODO: Add more details about the support for the SIMD types and SIMD math instructions.

Known issues