llvm/docs/LFI.md - llvm-project - Git at Google


            
            # Lightweight Fault Isolation (LFI) in LLVM


            ## Introduction


            Lightweight Fault Isolation (LFI) is a compiler-based sandboxing technology for

            
            native code. Like WebAssembly and Native Client, LFI isolates sandboxed code in-process

            
            (i.e., in the same address space as a host application).


            LFI is designed from the ground up to sandbox existing code, such as C/C++

            
            libraries (including assembly code) and device drivers.


            LFI aims for the following goals:


            - Compatibility: LFI can be used to sandbox nearly all existing C/C++/assembly

            
              libraries unmodified (they just need to be recompiled). Sandboxed libraries

            
              work with existing system call interfaces, and are compatible with existing

            
              development tools such as profilers, debuggers, and sanitizers.

            
            - Performance: LFI aims for minimal overhead vs. unsandboxed code.

            
            - Security: The LFI runtime and compiler elements aim to be simple and

            
              verifiable when possible.

            
            - Usability: LFI aims to make it as easy as possible to retrofit sandboxing,

            
              i.e., to migrate from unsandboxed to sandboxed libraries with minimal effort.


            When building a program for the LFI target the compiler is designed to ensure

            
            that the program will only be able to access memory within a limited region of

            
            the virtual address space, starting from where the program is loaded (the

            
            current design sets this region to a size of 4GiB of virtual memory). Programs

            
            built for the LFI target are restricted to using a subset of the instruction

            
            set, designed so that the programs can be soundly confined to their sandbox

            
            region. LFI programs must run inside of an "emulator" (usually called the LFI

            
            runtime), responsible for initializing the sandbox region, loading the program,

            
            and servicing system call requests, or other forms of runtime calls.


            LFI uses an architecture-specific sandboxing scheme based on the general

            
            technique of Software-Based Fault Isolation (SFI). LLVM currently supports LFI

            
            for the AArch64 and X86-64 platforms. The AArch64 version is designed to

            
            support the Armv8.1 AArch64 architecture.


            See [https://github.com/lfi-project](https://github.com/lfi-project/) for

            
            details about the LFI project and additional software needed to run LFI

            
            programs.


            ## Compiler Requirements


            When building for an LFI target (`aarch64_lfi` or `x86_64_lfi`), the

            
            compiler must restrict use of the instruction set to a subset of instructions,

            
            which are known to be safe from a sandboxing perspective. To do this, we apply a

            
            set of simple rewrites at the assembly language level to transform standard

            
            native assembly into LFI-compatible assembly.


            These rewrites (also called "expansions") are applied at the very end of the

            
            LLVM compilation pipeline (during the assembler step). This allows the rewrites

            
            to be applied to hand-written assembly, including inline assembly.


            ## Context Register


            Both architectures designate a context register that points to a block of

            
            thread-local memory managed by the LFI runtime. The context register is `x25`

            
            on AArch64 and `r15` on X86-64. The layout is as follows:


            | Offset | Size | Description |

            
            | --- | --- | --- |

            
            | 0 | 8 | Reserved for future use. |

            
            | 8 | 8 | Reserved for use by the LFI runtime. |

            
            | 16 | 8 | Virtual thread pointer (used for TP access). |


            ## Linker Support


            In the initial version, LFI only supports static linking, and only supports

            
            creating `static-pie` binaries. There is nothing that fundamentally precludes

            
            support for dynamic linking on the LFI target, but such support would require

            
            that the code generated by the linker for PLT entries be slightly modified in

            
            order to conform to the LFI architecture subset.


            ## Assembler Directives


            The following directives are supported for controlling the rewriter.


            ### `.lfi_rewrite_disable`


            Disables LFI assembly rewrites for all subsequent instructions, until

            
            `.lfi_rewrite_enable` is used. This can be useful for hand-written assembly

            
            that is already safe and should not be modified by the rewriter.


            ### `.lfi_rewrite_enable`


            Re-enables LFI assembly rewrites after a previous `.lfi_rewrite_disable`.


            Example:


            ```gas

            
            .lfi_rewrite_disable

            
            // No rewrites applied here.

            
            ldr x0, [x27, w1, uxtw]

            
            .lfi_rewrite_enable

            
            ```


            ## Compiler Options


            The LFI target has several configuration options, specified via `-mattr=`:


            - `+no-lfi-loads`: Disable sandboxing for load instructions (stores-only mode).

            
            - `+no-lfi-stores`: Disable sandboxing for store instructions.


            Use `+no-lfi-loads` to create a "stores-only" sandbox that may read, but not

            
            write, outside the sandbox region.


            Use `+no-lfi-loads,+no-lfi-stores` to create a "jumps-only" sandbox that may

            
            read/write outside the sandbox region but may not transfer control outside

            
            (e.g., may not execute system calls directly). This is primarily useful in

            
            combination with some other form of memory sandboxing, such as Intel MPK.


            ## AArch64


            The AArch64 LFI target is `aarch64_lfi`. This is the first part of a target

            
            triple that can be used with `--triple=aarch64_lfi-<rest of triple>`.


            ### Reserved Registers


            The AArch64 LFI target uses a custom ABI that reserves additional registers for

            
            the platform. The registers are listed below, along with the security invariant

            
            that must be maintained.


            - `x27`: always holds the sandbox base address (must be aligned to the size

            
              of the sandbox).

            
            - `x28`: always holds an address within the sandbox.

            
            - `sp`: always holds an address within the sandbox.

            
            - `x30`: always holds an address within the sandbox.

            
            - `x26`: scratch register.

            
            - `x25`: context register (see [Context Register](#context-register)).


            The current design only supports 4GiB sandboxes, which requires the sandbox

            
            base address to be 4GiB-aligned. This is because LFI's ABI stores pointers as

            
            their full 64-bit values, rather than just 32-bit offsets from the base. This

            
            enables stores-only mode, where loads are not sandboxed but stores are, and

            
            allows the host to directly pass pointers to the sandbox.


            ### Assembly Rewrites


            #### Terminology


            In the following assembly rewrites, some shorthand is used.


            - `xN` or `wN`: refers to any general-purpose non-reserved register.

            
            - `{a,b,c}`: matches any of `a`, `b`, or `c`.

            
            - `LDSTr`: a load/store instruction that supports register-register addressing modes, with one source/destination register.

            
            - `LDSTx`: a load/store instruction not matched by `LDSTr`. This covers load/store pairs (`ldp`/`stp`), SIMD load/stores (`ld1`, `st1`, ...), atomics, exclusives, load/store-release, and unscaled (`ldur`/`stur`) forms. These instructions have a more limited set of addressing modes than `LDSTr`.


            #### Control flow


            Indirect branches get rewritten to branch through register `x28`, which must

            
            always contain an address within the sandbox. An `add` is used to safely

            
            update `x28` with the destination address. Since `ret` uses `x30` by

            
            default, which already must contain an address within the sandbox, it does not

            
            require any rewrite.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                {br,blr,ret} xN

            
                ```

            
              - ```gas

            
                add x28, x27, wN, uxtw

            
                {br,blr,ret} x28

            
                ```

            
            * - ```gas

            
                ret

            
                ```

            
              - ```gas

            
                ret

            
                ```

            
            :::


            #### Memory accesses


            Memory accesses are rewritten to use the `[x27, wM, uxtw]` addressing mode if

            
            it is available, which is automatically safe. Otherwise, rewrites fall back to

            
            using `x28` along with an instruction to safely load it with the target

            
            address.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                LDSTr xN, [xM]

            
                ```

            
              - ```gas

            
                LDSTr xN, [x27, wM, uxtw]

            
                ```

            
            * - ```gas

            
                LDSTr xN, [xM, #I]

            
                ```

            
              - ```gas

            
                add x28, x27, wM, uxtw

            
                LDSTr xN, [x28, #I]

            
                ```

            
            * - ```gas

            
                LDSTr xN, [xM, #I]!

            
                ```

            
              - ```gas

            
                add xM, xM, #I

            
                LDSTr xN, [x27, wM, uxtw]

            
                ```

            
            * - ```gas

            
                LDSTr xN, [xM], #I

            
                ```

            
              - ```gas

            
                LDSTr xN, [x27, wM, uxtw]

            
                add xM, xM, #I

            
                ```

            
            * - ```gas

            
                LDSTr xN, [xM1, xM2]

            
                ```

            
              - ```gas

            
                add x26, xM1, xM2

            
                LDSTr xN, [x27, w26, uxtw]

            
                ```

            
            * - ```gas

            
                LDSTr xN, [xM1, xM2, MOD #I]

            
                ```

            
              - ```gas

            
                add x26, xM1, xM2, MOD #I

            
                LDSTr xN, [x27, w26, uxtw]

            
                ```

            
            * - ```gas

            
                LDSTx ..., [xM]

            
                ```

            
              - ```gas

            
                add x28, x27, wM, uxtw

            
                LDSTx ..., [x28]

            
                ```

            
            * - ```gas

            
                LDSTx ..., [xM, #I]

            
                ```

            
              - ```gas

            
                add x28, x27, wM, uxtw

            
                LDSTx ..., [x28, #I]

            
                ```

            
            * - ```gas

            
                LDSTx ..., [xM, #I]!

            
                ```

            
              - ```gas

            
                add x28, x27, wM, uxtw

            
                LDSTx ..., [x28, #I]

            
                add xM, xM, #I

            
                ```

            
            * - ```gas

            
                LDSTx ..., [xM], #I

            
                ```

            
              - ```gas

            
                add x28, x27, wM, uxtw

            
                LDSTx ..., [x28]

            
                add xM, xM, #I

            
                ```

            
            * - ```gas

            
                LDSTx ..., [xM1], xM2

            
                ```

            
              - ```gas

            
                add x28, x27, wM1, uxtw

            
                LDSTx ..., [x28]

            
                add xM1, xM1, xM2

            
                ```

            
            :::


            #### Stack pointer modification


            When the stack pointer is modified, we write the modified value to a temporary,

            
            before moving it back into `sp` with a safe `add`.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                mov sp, xN

            
                ```

            
              - ```gas

            
                add sp, x27, wN, uxtw

            
                ```

            
            * - ```gas

            
                {add,sub} sp, sp, {#I,xN}

            
                ```

            
              - ```gas

            
                {add,sub} x26, sp, {#I,xN}

            
                add sp, x27, w26, uxtw

            
                ```

            
            :::


            #### Link register modification


            When the link register is modified, it is guarded back into the sandbox with a

            
            safe `add x30, x27, w30, uxtw`. This guard is deferred until the next

            
            control-flow instruction rather than emitted immediately after the

            
            modification. Deferral keeps a signed return address intact so that a following

            
            authentication instruction (such as `autiasp`) can run before the guard,

            
            which would otherwise destroy the pointer authentication signature. See

            
            [Pointer Authentication Code (PAC) support](#pointer-authentication-code-pac-support).


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                ldr x30, [...]

            
                ret

            
                ```

            
              - ```gas

            
                ldr x30, [...]

            
                add x30, x27, w30, uxtw

            
                ret

            
                ```

            
            * - ```gas

            
                ldp xN, x30, [...]

            
                ret

            
                ```

            
              - ```gas

            
                ldp xN, x30, [...]

            
                add x30, x27, w30, uxtw

            
                ret

            
                ```

            
            :::


            #### Pointer Authentication Code (PAC) support


            LFI is compatible with Arm Pointer Authentication Code (PAC) instructions,

            
            which are used to sign and authenticate `x30` to protect against control-flow

            
            hijacking.


            The typical use is `-mbranch-protection=pac-ret`, which signs only the return

            
            address in `x30` using the hint-space `paciasp` and `autiasp`

            
            instructions. The combined authenticate-and-branch and authenticate-and-return

            
            instructions covered below require Armv8.3-a and are not produced by

            
            `-mbranch-protection`. They can appear in hand-written assembly or from

            
            environments that sign all code pointers, so the rewriter still sandboxes them

            
            rather than passing them through unmodified.


            To gain the security benefit of PAC under LFI, the hardware must implement

            
            `FEAT_FPAC`, so that authentication failures fault immediately. Without

            
            `FEAT_FPAC`, a failed authentication produces a poisoned pointer, which LFI

            
            still keeps confined to the sandbox by masking it, but the mask overwrites the

            
            poison caused by the authentication failure.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                paciasp

            
                ```

            
              - ```gas

            
                paciasp

            
                ```

            
            * - ```gas

            
                autiasp

            
                ret

            
                ```

            
              - ```gas

            
                autiasp

            
                add x30, x27, w30, uxtw

            
                ret

            
                ```

            
            :::


            Authenticated returns (`retaa`/`retab`) combine authentication with return,

            
            and must be expanded during rewriting.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                retaa

            
                ```

            
              - ```gas

            
                autiasp

            
                add x30, x27, w30, uxtw

            
                ret

            
                ```

            
            * - ```gas

            
                retab

            
                ```

            
              - ```gas

            
                autibsp

            
                add x30, x27, w30, uxtw

            
                ret

            
                ```

            
            :::


            Authenticated branches (`braa`/`brab`/`braaz`/`brabz`) and calls

            
            (`blraa`/`blrab`/`blraaz`/`blrabz`) combine authentication with an

            
            indirect branch or call. They are expanded by first authenticating the target

            
            register in place, then performing a normal sandboxed branch or call.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                braa xN, xM

            
                ```

            
              - ```gas

            
                autia xN, xM

            
                add x28, x27, wN, uxtw

            
                br x28

            
                ```

            
            * - ```gas

            
                braaz xN

            
                ```

            
              - ```gas

            
                autiza xN

            
                add x28, x27, wN, uxtw

            
                br x28

            
                ```

            
            * - ```gas

            
                blraa xN, xM

            
                ```

            
              - ```gas

            
                autia xN, xM

            
                add x28, x27, wN, uxtw

            
                blr x28

            
                ```

            
            :::


            Authenticated exception returns (`eret`/`eretaa`/`eretab`) are privileged

            
            and are not supported: the rewriter reports an error for them.


            #### System instructions


            System calls are rewritten into a sequence that loads the address of the first

            
            runtime call entrypoint and jumps to it. The runtime call entrypoint table is

            
            stored at a negative offset from the sandbox base, so it can be referenced by

            
            `x27`. The rewrite also saves and restores the link register, since it is

            
            used for branching into the runtime.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                svc #0

            
                ```

            
              - ```gas

            
                mov x26, x30

            
                ldur x30, [x27, #-8]

            
                blr x30

            
                add x30, x27, w26, uxtw

            
                ```

            
            :::


            #### Thread pointer (TP)


            TP accesses are rewritten into loads/stores from the context register

            
            (`x25`), which holds the virtual thread pointer at offset 16 (see

            
            [Context Register](#context-register)).


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - `mrs xN, tpidr_el0`

            
              - `ldr xN, [x25, #16]`

            
            * - `msr tpidr_el0, xN`

            
              - `str xN, [x25, #16]`

            
            :::


            ### Optimizations


            #### Basic guard elimination


            If a register is guarded multiple times in the same basic block without any

            
            modifications to it during the intervening instructions, then subsequent guards

            
            can be removed.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                add x28, x27, wN, uxtw

            
                ldur xN, [x28]

            
                add x28, x27, wN, uxtw

            
                ldur xN, [x28, #8]

            
                add x28, x27, wN, uxtw

            
                ldur xN, [x28, #16]

            
                ```

            
              - ```gas

            
                add x28, x27, wN, uxtw

            
                ldur xN, [x28]

            
                ldur xN, [x28, #8]

            
                ldur xN, [x28, #16]

            
                ```

            
            :::


            #### Address generation


            **Note**: not yet implemented.


            Addresses to global symbols in position-independent executables are frequently

            
            generated via `adrp` followed by `ldr`. Since the address generated by

            
            `adrp` can be statically guaranteed to be within the sandbox, it is safe to

            
            directly target `x28` for these sequences. This allows the omission of a

            
            guard instruction before the `ldr`.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                adrp xN, target

            
                ldr xN, [xN, imm]

            
                ```

            
              - ```gas

            
                adrp x28, target

            
                ldr xN, [x28, imm]

            
                ```

            
            :::


            #### Stack guard elimination


            **Note**: not yet implemented.


            If the stack pointer is modified by adding/subtracting a small immediate, and

            
            then later used to perform a memory access without any intervening jumps, then

            
            the guard on the stack pointer modification can be removed. This is because the

            
            load/store is guaranteed to trap if the stack pointer has been moved outside of

            
            the sandbox region.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                add x26, sp, #8

            
                add sp, x27, w26, uxtw

            
                ... (same basic block)

            
                ldr xN, [sp]

            
                ```

            
              - ```gas

            
                add sp, sp, #8

            
                ... (same basic block)

            
                ldr xN, [sp]

            
                ```

            
            :::


            #### Guard hoisting


            **Note**: not yet implemented.


            In certain cases, guards may be hoisted outside of loops.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                    mov w8, #10

            
                    mov w9, #0

            
                .loop:

            
                    add w9, w9, #1

            
                    ldr xN, [xM]

            
                    cmp w9, w8

            
                    b.lt .loop

            
                .end:

            
                ```

            
              - ```gas

            
                    mov w8, #10

            
                    mov w9, #0

            
                    add x28, x27, wM, uxtw

            
                .loop:

            
                    add w9, w9, #1

            
                    ldr xN, [x28]

            
                    cmp w9, w8

            
                    b.lt .loop

            
                .end:

            
                ```

            
            :::


            ## X86-64


            The X86-64 LFI target is `x86_64_lfi`.


            ### Reserved Registers


            The X86-64 LFI target reserves the following registers:


            - `r14`: always holds the sandbox base address. Also used as the runtime call

            
              table pointer (the runtime call table is stored at the sandbox base).

            
            - `gs`: always holds the sandbox base address (used as a segment register for

            
              memory access sandboxing).

            
            - `rsp`: always holds an address within the sandbox.

            
            - `r15`: context register (see [Context Register](#context-register)).

            
            - `r11`: scratch register.


            ### Bundling


            The X86-64 LFI target confines control flow using 32-byte bundles. Indirect

            
            branch targets are masked to a 32-byte boundary, so control can only enter code

            
            at a bundle-aligned address. For this to constrain the instruction stream, no

            
            instruction may span a bundle boundary.


            LFI object files are therefore assembled with {doc}`aligned instruction

            
            bundling <AlignedBundling>` enabled, which inserts `nop` padding wherever an

            
            instruction would otherwise cross a boundary. Bundling is enabled implicitly

            
            for the `x86_64_lfi` target.


            A rewrite that expands one instruction into a sequence which must not be

            
            entered in the middle wraps that sequence in `.bundle_lock` / `.bundle_unlock`.

            
            This keeps the whole group within a single bundle, so no masked indirect branch

            
            can land between its instructions.


            **Note**: the masking of indirect branch targets is part of the control flow

            
            rewrites, which have not been implemented yet.


            Bundling is specific to X86-64. AArch64 instructions are fixed-width and

            
            naturally aligned, and the AArch64 LFI target confines indirect branches by

            
            guarding the target register instead.


            ### Assembly Rewrites


            #### Terminology


            In the following assembly rewrites, some shorthand is used.


            - `%rN` or `%eN`: refers to any general-purpose non-reserved register.

            
            - `{a,b,c}`: matches any of `a`, `b`, or `c`.


            #### Control flow


            **Note**: these rewrites have not been implemented.


            #### Memory accesses


            **Note**: these rewrites have not been implemented.


            #### String instructions


            **Note**: these rewrites have not been implemented.


            #### Stack modification


            **Note**: these rewrites have not been implemented.


            #### System instructions


            System calls are rewritten into a sequence that loads the return address into

            
            the scratch register and jumps to the runtime call handler. The runtime call

            
            handler table is stored at the address pointed to by `r14`. The `r11`

            
            register stores the return address (marked by the label `.Ltmp` in the

            
            block below).


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                syscall

            
                ```

            
              - ```gas

            
                leaq .Ltmp(%rip), %r11

            
                jmpq *-8(%r14)

            
                .Ltmp:

            
                ```

            
            :::


            #### Thread pointer


            Thread pointer accesses via the `%fs` segment (used for TLS) are rewritten to

            
            use the virtual thread pointer from the context register (`r15`) at offset 16

            
            (see [Context Register](#context-register)). The rewrite handles any load or

            
            store instruction with an `%fs`-segment memory operand. `Op` represents any

            
            such instruction.


            :::{list-table}

            
            :header-rows: 1


            * - Original

            
              - Rewritten

            
            * - ```gas

            
                Op %fs:0, %rD

            
                ```

            
              - ```gas

            
                Op 16(%r15), %rD

            
                ```

            
            * - ```gas

            
                Op %fs:(%rX), %rD

            
                ```

            
              - ```gas

            
                movq 16(%r15), %rD

            
                Op (%rD, %rX), %rD

            
                ```

            
            * - ```gas

            
                Op %rS, %fs:(%rX)

            
                ```

            
              - ```gas

            
                movq 16(%r15), %r11

            
                Op %rS, (%r11, %rX)

            
                ```

            
            * - ```gas

            
                Op %fs:N(%rX, %rY, S), %rD

            
                ```

            
              - ```gas

            
                movq 16(%r15), %r11

            
                leaq (%r11, %rX), %r11

            
                Op N(%r11, %rY, S), %rD

            
                ```

            
            * - ```gas

            
                Op %rS, %fs:N(%rX, %rY, S)

            
                ```

            
              - ```gas

            
                movq 16(%r15), %r11

            
                leaq (%r11, %rX), %r11

            
                Op %rS, N(%r11, %rY, S)

            
                ```

            
            :::


            ## References


            For more information, please see the following resources:


            - [LFI project page](https://github.com/lfi-project/)

            
            - [LFI RFC](https://discourse.llvm.org/t/rfc-lightweight-fault-isolation-lfi-efficient-native-code-sandboxing-upstream-lfi-target-and-compiler-changes/88380)

            
            - [LFI paper](https://zyedidia.github.io/papers/lfi_asplos24.pdf)


            Contact info:


            - Zachary Yedidia - [zyedidia@cs.stanford.edu](mailto:zyedidia@cs.stanford.edu)

            
            - Tal Garfinkel - [tgarfinkel@google.com](mailto:tgarfinkel@google.com)

            
            - Sharjeel Khan - [sharjeelkhan@google.com](mailto:sharjeelkhan@google.com)
	# Lightweight Fault Isolation (LFI) in LLVM

	## Introduction

	Lightweight Fault Isolation (LFI) is a compiler-based sandboxing technology for
	native code. Like WebAssembly and Native Client, LFI isolates sandboxed code in-process
	(i.e., in the same address space as a host application).

	LFI is designed from the ground up to sandbox existing code, such as C/C++
	libraries (including assembly code) and device drivers.

	LFI aims for the following goals:

	- Compatibility: LFI can be used to sandbox nearly all existing C/C++/assembly
	libraries unmodified (they just need to be recompiled). Sandboxed libraries
	work with existing system call interfaces, and are compatible with existing
	development tools such as profilers, debuggers, and sanitizers.
	- Performance: LFI aims for minimal overhead vs. unsandboxed code.
	- Security: The LFI runtime and compiler elements aim to be simple and
	verifiable when possible.
	- Usability: LFI aims to make it as easy as possible to retrofit sandboxing,
	i.e., to migrate from unsandboxed to sandboxed libraries with minimal effort.

	When building a program for the LFI target the compiler is designed to ensure
	that the program will only be able to access memory within a limited region of
	the virtual address space, starting from where the program is loaded (the
	current design sets this region to a size of 4GiB of virtual memory). Programs
	built for the LFI target are restricted to using a subset of the instruction
	set, designed so that the programs can be soundly confined to their sandbox
	region. LFI programs must run inside of an "emulator" (usually called the LFI
	runtime), responsible for initializing the sandbox region, loading the program,
	and servicing system call requests, or other forms of runtime calls.

	LFI uses an architecture-specific sandboxing scheme based on the general
	technique of Software-Based Fault Isolation (SFI). LLVM currently supports LFI
	for the AArch64 and X86-64 platforms. The AArch64 version is designed to
	support the Armv8.1 AArch64 architecture.

	See [https://github.com/lfi-project](https://github.com/lfi-project/) for
	details about the LFI project and additional software needed to run LFI
	programs.

	## Compiler Requirements

	When building for an LFI target (`aarch64_lfi` or `x86_64_lfi`), the
	compiler must restrict use of the instruction set to a subset of instructions,
	which are known to be safe from a sandboxing perspective. To do this, we apply a
	set of simple rewrites at the assembly language level to transform standard
	native assembly into LFI-compatible assembly.

	These rewrites (also called "expansions") are applied at the very end of the
	LLVM compilation pipeline (during the assembler step). This allows the rewrites
	to be applied to hand-written assembly, including inline assembly.

	## Context Register

	Both architectures designate a context register that points to a block of
	thread-local memory managed by the LFI runtime. The context register is `x25`
	on AArch64 and `r15` on X86-64. The layout is as follows:

	\| Offset \| Size \| Description \|
	\| --- \| --- \| --- \|
	\| 0 \| 8 \| Reserved for future use. \|
	\| 8 \| 8 \| Reserved for use by the LFI runtime. \|
	\| 16 \| 8 \| Virtual thread pointer (used for TP access). \|

	## Linker Support

	In the initial version, LFI only supports static linking, and only supports
	creating `static-pie` binaries. There is nothing that fundamentally precludes
	support for dynamic linking on the LFI target, but such support would require
	that the code generated by the linker for PLT entries be slightly modified in
	order to conform to the LFI architecture subset.

	## Assembler Directives

	The following directives are supported for controlling the rewriter.

	### `.lfi_rewrite_disable`

	Disables LFI assembly rewrites for all subsequent instructions, until
	`.lfi_rewrite_enable` is used. This can be useful for hand-written assembly
	that is already safe and should not be modified by the rewriter.

	### `.lfi_rewrite_enable`

	Re-enables LFI assembly rewrites after a previous `.lfi_rewrite_disable`.

	Example:

	```gas
	.lfi_rewrite_disable
	// No rewrites applied here.
	ldr x0, [x27, w1, uxtw]
	.lfi_rewrite_enable
	```

	## Compiler Options

	The LFI target has several configuration options, specified via `-mattr=`:

	- `+no-lfi-loads`: Disable sandboxing for load instructions (stores-only mode).
	- `+no-lfi-stores`: Disable sandboxing for store instructions.

	Use `+no-lfi-loads` to create a "stores-only" sandbox that may read, but not
	write, outside the sandbox region.

	Use `+no-lfi-loads,+no-lfi-stores` to create a "jumps-only" sandbox that may
	read/write outside the sandbox region but may not transfer control outside
	(e.g., may not execute system calls directly). This is primarily useful in
	combination with some other form of memory sandboxing, such as Intel MPK.

	## AArch64

	The AArch64 LFI target is `aarch64_lfi`. This is the first part of a target
	triple that can be used with `--triple=aarch64_lfi-<rest of triple>`.

	### Reserved Registers

	The AArch64 LFI target uses a custom ABI that reserves additional registers for
	the platform. The registers are listed below, along with the security invariant
	that must be maintained.

	- `x27`: always holds the sandbox base address (must be aligned to the size
	of the sandbox).
	- `x28`: always holds an address within the sandbox.
	- `sp`: always holds an address within the sandbox.
	- `x30`: always holds an address within the sandbox.
	- `x26`: scratch register.
	- `x25`: context register (see [Context Register](#context-register)).

	The current design only supports 4GiB sandboxes, which requires the sandbox
	base address to be 4GiB-aligned. This is because LFI's ABI stores pointers as
	their full 64-bit values, rather than just 32-bit offsets from the base. This
	enables stores-only mode, where loads are not sandboxed but stores are, and
	allows the host to directly pass pointers to the sandbox.

	### Assembly Rewrites

	#### Terminology

	In the following assembly rewrites, some shorthand is used.

	- `xN` or `wN`: refers to any general-purpose non-reserved register.
	- `{a,b,c}`: matches any of `a`, `b`, or `c`.
	- `LDSTr`: a load/store instruction that supports register-register addressing modes, with one source/destination register.
	- `LDSTx`: a load/store instruction not matched by `LDSTr`. This covers load/store pairs (`ldp`/`stp`), SIMD load/stores (`ld1`, `st1`, ...), atomics, exclusives, load/store-release, and unscaled (`ldur`/`stur`) forms. These instructions have a more limited set of addressing modes than `LDSTr`.

	#### Control flow

	Indirect branches get rewritten to branch through register `x28`, which must
	always contain an address within the sandbox. An `add` is used to safely
	update `x28` with the destination address. Since `ret` uses `x30` by
	default, which already must contain an address within the sandbox, it does not
	require any rewrite.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	{br,blr,ret} xN
	```
	- ```gas
	add x28, x27, wN, uxtw
	{br,blr,ret} x28
	```
	* - ```gas
	ret
	```
	- ```gas
	ret
	```
	:::

	#### Memory accesses

	Memory accesses are rewritten to use the `[x27, wM, uxtw]` addressing mode if
	it is available, which is automatically safe. Otherwise, rewrites fall back to
	using `x28` along with an instruction to safely load it with the target
	address.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	LDSTr xN, [xM]
	```
	- ```gas
	LDSTr xN, [x27, wM, uxtw]
	```
	* - ```gas
	LDSTr xN, [xM, #I]
	```
	- ```gas
	add x28, x27, wM, uxtw
	LDSTr xN, [x28, #I]
	```
	* - ```gas
	LDSTr xN, [xM, #I]!
	```
	- ```gas
	add xM, xM, #I
	LDSTr xN, [x27, wM, uxtw]
	```
	* - ```gas
	LDSTr xN, [xM], #I
	```
	- ```gas
	LDSTr xN, [x27, wM, uxtw]
	add xM, xM, #I
	```
	* - ```gas
	LDSTr xN, [xM1, xM2]
	```
	- ```gas
	add x26, xM1, xM2
	LDSTr xN, [x27, w26, uxtw]
	```
	* - ```gas
	LDSTr xN, [xM1, xM2, MOD #I]
	```
	- ```gas
	add x26, xM1, xM2, MOD #I
	LDSTr xN, [x27, w26, uxtw]
	```
	* - ```gas
	LDSTx ..., [xM]
	```
	- ```gas
	add x28, x27, wM, uxtw
	LDSTx ..., [x28]
	```
	* - ```gas
	LDSTx ..., [xM, #I]
	```
	- ```gas
	add x28, x27, wM, uxtw
	LDSTx ..., [x28, #I]
	```
	* - ```gas
	LDSTx ..., [xM, #I]!
	```
	- ```gas
	add x28, x27, wM, uxtw
	LDSTx ..., [x28, #I]
	add xM, xM, #I
	```
	* - ```gas
	LDSTx ..., [xM], #I
	```
	- ```gas
	add x28, x27, wM, uxtw
	LDSTx ..., [x28]
	add xM, xM, #I
	```
	* - ```gas
	LDSTx ..., [xM1], xM2
	```
	- ```gas
	add x28, x27, wM1, uxtw
	LDSTx ..., [x28]
	add xM1, xM1, xM2
	```
	:::

	#### Stack pointer modification

	When the stack pointer is modified, we write the modified value to a temporary,
	before moving it back into `sp` with a safe `add`.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	mov sp, xN
	```
	- ```gas
	add sp, x27, wN, uxtw
	```
	* - ```gas
	{add,sub} sp, sp, {#I,xN}
	```
	- ```gas
	{add,sub} x26, sp, {#I,xN}
	add sp, x27, w26, uxtw
	```
	:::

	#### Link register modification

	When the link register is modified, it is guarded back into the sandbox with a
	safe `add x30, x27, w30, uxtw`. This guard is deferred until the next
	control-flow instruction rather than emitted immediately after the
	modification. Deferral keeps a signed return address intact so that a following
	authentication instruction (such as `autiasp`) can run before the guard,
	which would otherwise destroy the pointer authentication signature. See
	[Pointer Authentication Code (PAC) support](#pointer-authentication-code-pac-support).

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	ldr x30, [...]
	ret
	```
	- ```gas
	ldr x30, [...]
	add x30, x27, w30, uxtw
	ret
	```
	* - ```gas
	ldp xN, x30, [...]
	ret
	```
	- ```gas
	ldp xN, x30, [...]
	add x30, x27, w30, uxtw
	ret
	```
	:::

	#### Pointer Authentication Code (PAC) support

	LFI is compatible with Arm Pointer Authentication Code (PAC) instructions,
	which are used to sign and authenticate `x30` to protect against control-flow
	hijacking.

	The typical use is `-mbranch-protection=pac-ret`, which signs only the return
	address in `x30` using the hint-space `paciasp` and `autiasp`
	instructions. The combined authenticate-and-branch and authenticate-and-return
	instructions covered below require Armv8.3-a and are not produced by
	`-mbranch-protection`. They can appear in hand-written assembly or from
	environments that sign all code pointers, so the rewriter still sandboxes them
	rather than passing them through unmodified.

	To gain the security benefit of PAC under LFI, the hardware must implement
	`FEAT_FPAC`, so that authentication failures fault immediately. Without
	`FEAT_FPAC`, a failed authentication produces a poisoned pointer, which LFI
	still keeps confined to the sandbox by masking it, but the mask overwrites the
	poison caused by the authentication failure.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	paciasp
	```
	- ```gas
	paciasp
	```
	* - ```gas
	autiasp
	ret
	```
	- ```gas
	autiasp
	add x30, x27, w30, uxtw
	ret
	```
	:::

	Authenticated returns (`retaa`/`retab`) combine authentication with return,
	and must be expanded during rewriting.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	retaa
	```
	- ```gas
	autiasp
	add x30, x27, w30, uxtw
	ret
	```
	* - ```gas
	retab
	```
	- ```gas
	autibsp
	add x30, x27, w30, uxtw
	ret
	```
	:::

	Authenticated branches (`braa`/`brab`/`braaz`/`brabz`) and calls
	(`blraa`/`blrab`/`blraaz`/`blrabz`) combine authentication with an
	indirect branch or call. They are expanded by first authenticating the target
	register in place, then performing a normal sandboxed branch or call.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	braa xN, xM
	```
	- ```gas
	autia xN, xM
	add x28, x27, wN, uxtw
	br x28
	```
	* - ```gas
	braaz xN
	```
	- ```gas
	autiza xN
	add x28, x27, wN, uxtw
	br x28
	```
	* - ```gas
	blraa xN, xM
	```
	- ```gas
	autia xN, xM
	add x28, x27, wN, uxtw
	blr x28
	```
	:::

	Authenticated exception returns (`eret`/`eretaa`/`eretab`) are privileged
	and are not supported: the rewriter reports an error for them.

	#### System instructions

	System calls are rewritten into a sequence that loads the address of the first
	runtime call entrypoint and jumps to it. The runtime call entrypoint table is
	stored at a negative offset from the sandbox base, so it can be referenced by
	`x27`. The rewrite also saves and restores the link register, since it is
	used for branching into the runtime.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	svc #0
	```
	- ```gas
	mov x26, x30
	ldur x30, [x27, #-8]
	blr x30
	add x30, x27, w26, uxtw
	```
	:::

	#### Thread pointer (TP)

	TP accesses are rewritten into loads/stores from the context register
	(`x25`), which holds the virtual thread pointer at offset 16 (see
	[Context Register](#context-register)).

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - `mrs xN, tpidr_el0`
	- `ldr xN, [x25, #16]`
	* - `msr tpidr_el0, xN`
	- `str xN, [x25, #16]`
	:::

	### Optimizations

	#### Basic guard elimination

	If a register is guarded multiple times in the same basic block without any
	modifications to it during the intervening instructions, then subsequent guards
	can be removed.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	add x28, x27, wN, uxtw
	ldur xN, [x28]
	add x28, x27, wN, uxtw
	ldur xN, [x28, #8]
	add x28, x27, wN, uxtw
	ldur xN, [x28, #16]
	```
	- ```gas
	add x28, x27, wN, uxtw
	ldur xN, [x28]
	ldur xN, [x28, #8]
	ldur xN, [x28, #16]
	```
	:::

	#### Address generation

	Note: not yet implemented.

	Addresses to global symbols in position-independent executables are frequently
	generated via `adrp` followed by `ldr`. Since the address generated by
	`adrp` can be statically guaranteed to be within the sandbox, it is safe to
	directly target `x28` for these sequences. This allows the omission of a
	guard instruction before the `ldr`.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	adrp xN, target
	ldr xN, [xN, imm]
	```
	- ```gas
	adrp x28, target
	ldr xN, [x28, imm]
	```
	:::

	#### Stack guard elimination

	Note: not yet implemented.

	If the stack pointer is modified by adding/subtracting a small immediate, and
	then later used to perform a memory access without any intervening jumps, then
	the guard on the stack pointer modification can be removed. This is because the
	load/store is guaranteed to trap if the stack pointer has been moved outside of
	the sandbox region.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	add x26, sp, #8
	add sp, x27, w26, uxtw
	... (same basic block)
	ldr xN, [sp]
	```
	- ```gas
	add sp, sp, #8
	... (same basic block)
	ldr xN, [sp]
	```
	:::

	#### Guard hoisting

	Note: not yet implemented.

	In certain cases, guards may be hoisted outside of loops.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	mov w8, #10
	mov w9, #0
	.loop:
	add w9, w9, #1
	ldr xN, [xM]
	cmp w9, w8
	b.lt .loop
	.end:
	```
	- ```gas
	mov w8, #10
	mov w9, #0
	add x28, x27, wM, uxtw
	.loop:
	add w9, w9, #1
	ldr xN, [x28]
	cmp w9, w8
	b.lt .loop
	.end:
	```
	:::

	## X86-64

	The X86-64 LFI target is `x86_64_lfi`.

	### Reserved Registers

	The X86-64 LFI target reserves the following registers:

	- `r14`: always holds the sandbox base address. Also used as the runtime call
	table pointer (the runtime call table is stored at the sandbox base).
	- `gs`: always holds the sandbox base address (used as a segment register for
	memory access sandboxing).
	- `rsp`: always holds an address within the sandbox.
	- `r15`: context register (see [Context Register](#context-register)).
	- `r11`: scratch register.

	### Bundling

	The X86-64 LFI target confines control flow using 32-byte bundles. Indirect
	branch targets are masked to a 32-byte boundary, so control can only enter code
	at a bundle-aligned address. For this to constrain the instruction stream, no
	instruction may span a bundle boundary.

	LFI object files are therefore assembled with {doc}`aligned instruction
	bundling <AlignedBundling>` enabled, which inserts `nop` padding wherever an
	instruction would otherwise cross a boundary. Bundling is enabled implicitly
	for the `x86_64_lfi` target.

	A rewrite that expands one instruction into a sequence which must not be
	entered in the middle wraps that sequence in `.bundle_lock` / `.bundle_unlock`.
	This keeps the whole group within a single bundle, so no masked indirect branch
	can land between its instructions.

	Note: the masking of indirect branch targets is part of the control flow
	rewrites, which have not been implemented yet.

	Bundling is specific to X86-64. AArch64 instructions are fixed-width and
	naturally aligned, and the AArch64 LFI target confines indirect branches by
	guarding the target register instead.

	### Assembly Rewrites

	#### Terminology

	In the following assembly rewrites, some shorthand is used.

	- `%rN` or `%eN`: refers to any general-purpose non-reserved register.
	- `{a,b,c}`: matches any of `a`, `b`, or `c`.

	#### Control flow

	Note: these rewrites have not been implemented.

	#### Memory accesses

	Note: these rewrites have not been implemented.

	#### String instructions

	Note: these rewrites have not been implemented.

	#### Stack modification

	Note: these rewrites have not been implemented.

	#### System instructions

	System calls are rewritten into a sequence that loads the return address into
	the scratch register and jumps to the runtime call handler. The runtime call
	handler table is stored at the address pointed to by `r14`. The `r11`
	register stores the return address (marked by the label `.Ltmp` in the
	block below).

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	syscall
	```
	- ```gas
	leaq .Ltmp(%rip), %r11
	jmpq *-8(%r14)
	.Ltmp:
	```
	:::

	#### Thread pointer

	Thread pointer accesses via the `%fs` segment (used for TLS) are rewritten to
	use the virtual thread pointer from the context register (`r15`) at offset 16
	(see [Context Register](#context-register)). The rewrite handles any load or
	store instruction with an `%fs`-segment memory operand. `Op` represents any
	such instruction.

	:::{list-table}
	:header-rows: 1

	* - Original
	- Rewritten
	* - ```gas
	Op %fs:0, %rD
	```
	- ```gas
	Op 16(%r15), %rD
	```
	* - ```gas
	Op %fs:(%rX), %rD
	```
	- ```gas
	movq 16(%r15), %rD
	Op (%rD, %rX), %rD
	```
	* - ```gas
	Op %rS, %fs:(%rX)
	```
	- ```gas
	movq 16(%r15), %r11
	Op %rS, (%r11, %rX)
	```
	* - ```gas
	Op %fs:N(%rX, %rY, S), %rD
	```
	- ```gas
	movq 16(%r15), %r11
	leaq (%r11, %rX), %r11
	Op N(%r11, %rY, S), %rD
	```
	* - ```gas
	Op %rS, %fs:N(%rX, %rY, S)
	```
	- ```gas
	movq 16(%r15), %r11
	leaq (%r11, %rX), %r11
	Op %rS, N(%r11, %rY, S)
	```
	:::

	## References

	For more information, please see the following resources:

	- [LFI project page](https://github.com/lfi-project/)
	- [LFI RFC](https://discourse.llvm.org/t/rfc-lightweight-fault-isolation-lfi-efficient-native-code-sandboxing-upstream-lfi-target-and-compiler-changes/88380)
	- [LFI paper](https://zyedidia.github.io/papers/lfi_asplos24.pdf)

	Contact info:

	- Zachary Yedidia - [zyedidia@cs.stanford.edu](mailto:zyedidia@cs.stanford.edu)
	- Tal Garfinkel - [tgarfinkel@google.com](mailto:tgarfinkel@google.com)
	- Sharjeel Khan - [sharjeelkhan@google.com](mailto:sharjeelkhan@google.com)