[llvm] [LFI][Doc] Update documentation for planned features (PR #192128)
Zachary Yedidia via llvm-commits
llvm-commits at lists.llvm.org
Thu Apr 16 17:04:41 PDT 2026
https://github.com/zyedidia updated https://github.com/llvm/llvm-project/pull/192128
>From 8b4f12a8afd921b7923c49e954edd0a1fe09b766 Mon Sep 17 00:00:00 2001
From: Zachary Yedidia <zyedidia at gmail.com>
Date: Tue, 14 Apr 2026 16:27:12 -0400
Subject: [PATCH 1/2] [LFI] Update documentation
---
llvm/docs/LFI.rst | 172 +++++++++++++++++++++++-----------------------
1 file changed, 87 insertions(+), 85 deletions(-)
diff --git a/llvm/docs/LFI.rst b/llvm/docs/LFI.rst
index cf99cc5faae38..73947e868e9d3 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 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
+
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``.
+
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
+~~~~~~~~~~~~~~
-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
++++++++++
>From a7e1b7b6400539bfcf8b92455c18e09329b9524b Mon Sep 17 00:00:00 2001
From: Zachary Yedidia <zyedidia at gmail.com>
Date: Thu, 16 Apr 2026 20:04:29 -0400
Subject: [PATCH 2/2] Update based on comments
---
llvm/docs/LFI.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/llvm/docs/LFI.rst b/llvm/docs/LFI.rst
index 73947e868e9d3..e63096ca18458 100644
--- a/llvm/docs/LFI.rst
+++ b/llvm/docs/LFI.rst
@@ -89,8 +89,7 @@ order to conform to the LFI architecture subset.
Assembler Directives
++++++++++++++++++++
-The LFI assembler supports the following directives for controlling the
-rewriter.
+The following directives are supported for controlling the rewriter.
``.lfi_rewrite_disable``
========================
@@ -134,7 +133,8 @@ combination with some other form of memory sandboxing, such as Intel MPK.
AArch64
+++++++
-The AArch64 LFI target is ``aarch64_lfi``.
+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
==================
@@ -348,7 +348,7 @@ used for branching into the runtime.
| | |
+-----------------+------------------------------+
-Thread pointer
+Thread pointer (TP)
~~~~~~~~~~~~~~
TP accesses are rewritten into loads/stores from the context register
More information about the llvm-commits
mailing list