[llvm] 59a509a - [LFI][Doc] Update documentation for planned features (#192128)
via llvm-commits
llvm-commits at lists.llvm.org
Fri Apr 17 12:55:44 PDT 2026
Author: Zachary Yedidia
Date: 2026-04-17T12:55:39-07:00
New Revision: 59a509aa80e57c420d06f364b02f0159f7f70775
URL: https://github.com/llvm/llvm-project/commit/59a509aa80e57c420d06f364b02f0159f7f70775
DIFF: https://github.com/llvm/llvm-project/commit/59a509aa80e57c420d06f364b02f0159f7f70775.diff
LOG: [LFI][Doc] Update documentation for planned features (#192128)
This PR updates the LFI documentation to be a little less
AArch64-specific in anticipation of x86-64 support. I've also updated
the planned names for the `no-lfi-stores`/`no-lfi-loads` features, and
updated the planned rewrite sequence for `x30` modifications to make it
more PAC-compatible for when we include support for that.
Added:
Modified:
llvm/docs/LFI.rst
Removed:
################################################################################
diff --git a/llvm/docs/LFI.rst b/llvm/docs/LFI.rst
index cf99cc5faae38..12c68a54b8b8d 100644
--- a/llvm/docs/LFI.rst
+++ b/llvm/docs/LFI.rst
@@ -60,29 +60,87 @@ 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:
+
+.. code-block:: gas
+
+ .lfi_rewrite_disable
+ // No rewrites applied here.
+ ldr x0, [x27, w1, uxtw]
+ .lfi_rewrite_enable
+
Compiler Options
-================
+++++++++++++++++
**Note**: these options are not yet implemented.
-The LFI target has several configuration options.
+The LFI target has several configuration options, specified via ``-mattr=``:
-* ``+lfi-loads``: enable sandboxing for loads (default: true).
-* ``+lfi-stores``: enable sandboxing for stores (default: true).
+* ``+no-lfi-loads``: Disable sandboxing for load instructions (stores-only mode).
+* ``+no-lfi-stores``: Disable sandboxing for store instructions.
-Use ``+nolfi-loads`` to create a "stores-only" sandbox that may read, but not
+Use ``+no-lfi-loads`` to create a "stores-only" sandbox that may read, but not
write, outside the sandbox region.
-Use ``+nolfi-loads,+nolfi-stores`` to create a "jumps-only" sandbox that may
+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 LFI target uses a custom ABI that reserves additional registers for the
-platform. The registers are listed below, along with the security invariant
+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
@@ -91,7 +149,7 @@ that must be maintained.
* ``sp``: always holds an address within the sandbox.
* ``x30``: always holds an address within the sandbox.
* ``x26``: scratch register.
-* ``x25``: context register (see below).
+* ``x25``: context register (see `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
@@ -99,31 +157,6 @@ 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.
-Context Register
-~~~~~~~~~~~~~~~~
-
-The context register (``x25``) points to a block of thread-local memory managed
-by the LFI runtime. 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.
-
Assembly Rewrites
=================
@@ -276,27 +309,23 @@ Link register modification
When the link register is modified, we write the modified value to a
temporary, before loading it back into ``x30`` with a safe ``add``.
-+-----------------------+----------------------------+
-| Original | Rewritten |
-+-----------------------+----------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ldr x30, [...] | ldr x26, [...] |
-| | add x30, x27, w26, uxtw |
-| | |
-+-----------------------+----------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ldp xN, x30, [...] | ldp xN, x26, [...] |
-| | add x30, x27, w26, uxtw |
-| | |
-+-----------------------+----------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ldp x30, xN, [...] | ldp x26, xN, [...] |
-| | add x30, x27, w26, uxtw |
-| | |
-+-----------------------+----------------------------+
++---------------------------+-------------------------------+
+| Original | Rewritten |
++---------------------------+-------------------------------+
+| .. code-block:: | .. code-block:: |
+| | |
+| ldr x30, [...] | ldr x30, [...] |
+| ret | add x30, x27, w30, uxtw |
+| | ret |
+| | |
++---------------------------+-------------------------------+
+| .. code-block:: | .. code-block:: |
+| | |
+| ldp xN, x30, [...] | ldp xN, x30, [...] |
+| ret | add x30, x27, w30, uxtw |
+| | ret |
+| | |
++---------------------------+-------------------------------+
System instructions
~~~~~~~~~~~~~~~~~~~
@@ -319,10 +348,10 @@ used for branching into the runtime.
| | |
+-----------------+------------------------------+
-Thread-local storage
-~~~~~~~~~~~~~~~~~~~~
+Thread pointer (TP)
+~~~~~~~~~~~~~~~~~~~
-TLS accesses are rewritten into loads/stores from the context register
+TP accesses are rewritten into loads/stores from the context register
(``x25``), which holds the virtual thread pointer at offset 16 (see
`Context Register`_).
@@ -434,33 +463,6 @@ In certain cases, guards may be hoisted outside of loops.
| | |
+-----------------------+-------------------------------+
-Assembler Directives
-====================
-
-The LFI assembler supports the following directives 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:
-
-.. code-block:: gas
-
- .lfi_rewrite_disable
- // No rewrites applied here.
- ldr x0, [x27, w1, uxtw]
- .lfi_rewrite_enable
-
References
++++++++++
More information about the llvm-commits
mailing list