Add BTF relocation builtins by vadorovsky · Pull Request #161107 · rust-lang/rust

vadorovsky · 2026-08-14T16:57:35Z

Add experimental Rust support for Compile Once, Run Everywhere (CO-RE) relocations based on the BPF Type Format (BTF). The entire feature is specific to the BPF architecture and cannot be used elsewhere. The feature introduces a #[btf_relocatable] attribute for structs and unions whose field layout must be queried through BTF-aware operations, and adds BTF-aware bultins:

btf_field_exists
btf_field_byte_offset
btf_field_byte_size

This PR does not yet expose these builtins to the users, the core_arch API will be added as a follow-up change.

The user-facing feature is gated by #![feature(btf_relocations)].

See individual commits for details.

Created with the help of an LLM, initially used to analyze the existing MIR, codegen SSA and LLVM backend code, to help identifying which parts of code need modification. Afterwards, the code and commit messages were written by hand, then reviewed by an LLM.

Tracking issue: #160616
RFC: rust-lang/rfcs#3966

r? @traviscross @nagisa

rustbot · 2026-08-14T16:57:38Z

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

This PR changes MIR

cc @oli-obk, @RalfJung, @JakobDegen, @vakaras

Some changes occurred to constck

cc @fee1-dead

stdarch is developed in its own repository. If possible, consider making this change to rust-lang/stdarch instead.

cc @Amanieu, @folkertdev, @sayantn

This PR changes rustc_public

cc @oli-obk, @celinval, @ouz-a, @makai410

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

Some changes occurred in compiler/rustc_passes/src/check_attr.rs

cc @jdonszelmann, @JonathanBrouwer

rustc_codegen_cranelift is developed in its own repository. If possible, consider making this change to rust-lang/rustc_codegen_cranelift instead.

cc @bjorn3

Some changes occurred in match checking

cc @Nadrieril

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann, @JonathanBrouwer

Some changes occurred in compiler/rustc_attr_ir

cc @jdonszelmann, @JonathanBrouwer

Some changes occurred in rustc_ty_utils::consts.rs

cc @BoxyUwU

The parser was modified, potentially altering the grammar of (stable) Rust
which would be a breaking change.

cc @fmease

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri

vadorovsky · 2026-08-14T20:01:12Z

stdarch is developed in its own repository. If possible, consider making this change to rust-lang/stdarch instead.

cc @Amanieu, @folkertdev, @sayantn

[...]

rustc_codegen_cranelift is developed in its own repository. If possible, consider making this change to rust-lang/rustc_codegen_cranelift instead.

cc @bjorn3

Sorry, I will trim this PR only to the builtins. They can be still tested with minicore and a macro embedded in test. And I'm going to leave the core_arch change for later.

vadorovsky · 2026-08-15T07:11:20Z

Now CI fails on rustc_codegen_cranelift. https://github.com/rust-lang/rust/actions/runs/31870909600/job/94979319914 How do we usually fix such chicken-and-egg problems?

RalfJung · 2026-08-16T16:07:49Z

    Reborrow(Ty<'tcx>, Mutability, Place<'tcx>),
+
+    /// Queries BTF metadata for a statically resolved field path.
+    BtfFieldInfo { base_ty: Ty<'tcx>, path: Box<[BtfFieldStep<'tcx>]>, kind: BtfFieldInfoKind },


This is a very unusual MIR construct, to put it quite mildly. Please add a bit more detail. What is this "metadata" that is being queried and how is it returned? What are the validity conditions? When is this operation UB (if ever)?

We usually work very hard to keep target-specific things away from this core part of the compiler, so seeing BTF-specific things here is somewhat alarming.

View changes since the review

Also, please write comments in this part in the compiler assuming that the reader never heard of BTF or BPF before. So, always include a link for such acronyms.

We usually work very hard to keep target-specific things away from this core part of the compiler, so seeing BTF-specific things here is somewhat alarming.

I hear you. Given that the other field relocation mechanisms (like Swift ABI reslence, Objective-C ivars etc.) could potentially reuse this construct, I will try to come up with some neutral name. Would that be satisfactory for you?

That's not where I was going. :) I am not asking for overeager generalization, we can always rename stuff later if it becomes more generally useful.

What I was going for with the second paragraph in my comment is: does this have to be a primitive MIR statement? Why is there no less invasive way to do this?

Can this for example be an intrinsic (core::intrinsics::btf_field_info(...))?

RalfJung · 2026-08-16T16:09:56Z

+            Self::ByteOffset => 0,
+            Self::ByteSize => 1,
+            Self::Exists => 2,


Where do these constants come from? Can rustc just do whatever it wants here or are these magic constants defined by some outside protocol?

View changes since the review

They are defined by LLVM in https://github.com/llvm/llvm-project/blob/llvmorg-23.1.1/llvm/include/llvm/DebugInfo/BTF/BTF.h#L280-L296

I added only these 3 variants, because they are sufficient for basic field relocations to work. I was thinking about following up with the rest of relocation types later.

We should definitely not have any values defined by LLVM in rustc_middle. This is backend-agonstic code. LLVM-specific consts can only be used in the LLVM backend.

Sorry, I wasn't exactly right in my last comment - these values are not limited to LLVM, they're honored in Linux kernel headers as well:

https://elixir.bootlin.com/linux/v7.2.5/source/include/uapi/linux/bpf.h#L7616

And they are used in the binary relocation records that are present in BPF object files. So I think these variant IDs can be treated as universal for BPF, not LLVM-specific.

That said, I can try avoiding to use them in MIR.

RalfJung · 2026-08-16T16:11:24Z

            }
+
+            BtfFieldInfo { .. } => {
+                throw_unsup_format!("BTF field relocation queries cannot be interpreted");


FWIW Miri will probably eventually want to support these, so for stabilization we need to consider what to do. But for now this is fine.

View changes since the review

RalfJung · 2026-08-16T16:11:47Z

    (unstable, bpf_target_feature, "1.54.0", Some(150247)),
+    // no-tracking-issue-start
+    /// Allows BTF CO-RE field relocation queries.
+    (unstable, btf_relocations, "CURRENT_RUSTC_VERSION", None),


You do have a tracking issue though...?

View changes since the review

rustbot · 2026-09-15T12:41:28Z

⚠️ Warning ⚠️

This PR is based on an upstream commit that is older than 28 days.

It's recommended to update your branch according to the rustc-dev-guide.

Register the unstable `btf_relocations` feature and add the `#[btf_relocatable]` built-in attribute for structs and unions, that can be used only on BPF architecture. Preserve the attribute in crate metadata, add UI coverage for feature gating and attribute target validation.

Reject field projection and `offset_off!` usage on `#[btf_relocatable]` types.

Add builtin macros for requesting BTF field information from the Rust compiler's frontend perspective: * `btf_field_byte_offset` * `btf_field_byte_size` * `btf_field_exists` Parse them as `BtfFieldInfo` expressions that carry the kind of requested information (offset, size, exists), base type and the field path. This mechanism supports nested field accesses in one query. Add internal compiler intrinsics corresponding to LLVM's and GCC's BTF preservation intrinsics: * `btf_preserve_access_index` * `btf_preserve_field_info` Lower the builtin macros to calls to these intrinsics. Add corresponding methods to the `BuilderMethods` trait in codegen SSA and use them for lowering the intrinsic calls. Backends without BTF relocation support report an error. Support in backends will be added in follow-up changes. This change does not expose the functionality to the users. A user-facing API will also be added in a follow-up change.

Expose wrappers for the `llvm.preserve.struct.access.index` and `llvm.preserve.union.access.index` intrinsics. Lower backend-neutral BTF field paths by mapping Rust field indices to LLVM aggregate indices and emitting the corresponding intrinsic calls (`llvm.preserve.{struct,union}.access.index`). Pass the resulting field pointer to `llvm.bpf.preserve.field.info`.

Test the `btf_field_exists`, `btf_field_byte_offset` and `btf_field_byte_size` builtins and make sure they emit correct LLVM intrinsic calls.

rustbot added the A-attributes Area: Attributes (`#[…]`, `#![…]`) label Aug 14, 2026

rustbot assigned traviscross Aug 14, 2026

This comment has been minimized.

Sign in to view

vadorovsky force-pushed the vad/btf-relocations branch from 7de4ec2 to 869a54b Compare August 15, 2026 07:01

This comment has been minimized.

Sign in to view

vadorovsky force-pushed the vad/btf-relocations branch from 869a54b to b42b869 Compare August 15, 2026 07:23

vadorovsky changed the title ~~BTF relocations~~ Add BTF relocation builtins Aug 15, 2026

This comment has been minimized.

Sign in to view

RalfJung reviewed Aug 16, 2026

View reviewed changes

vadorovsky force-pushed the vad/btf-relocations branch from b42b869 to 3dea160 Compare September 15, 2026 12:41

vadorovsky added 5 commits September 15, 2026 14:42

Reject direct field access on BTF-relocatable types

27cacbf

Reject field projection and `offset_off!` usage on `#[btf_relocatable]` types.

Add codegen test for BTF relocations

2a1be29

Test the `btf_field_exists`, `btf_field_byte_offset` and `btf_field_byte_size` builtins and make sure they emit correct LLVM intrinsic calls.

vadorovsky force-pushed the vad/btf-relocations branch from 3dea160 to 2a1be29 Compare September 15, 2026 12:45

Uh oh!

Uh oh!

Conversation

vadorovsky commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Aug 14, 2026

Uh oh!

This comment has been minimized.

vadorovsky commented Aug 14, 2026

Uh oh!

This comment has been minimized.

vadorovsky commented Aug 15, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

RalfJung Aug 16, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

vadorovsky Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

bjorn3 Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung Aug 16, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vadorovsky Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

vadorovsky Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Aug 16, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Aug 16, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Sep 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vadorovsky commented Aug 14, 2026 •

edited

Loading

RalfJung Aug 16, 2026 •

edited by rustbot

Loading

RalfJung Aug 16, 2026 •

edited by rustbot

Loading

vadorovsky Sep 14, 2026 •

edited

Loading

RalfJung Aug 16, 2026 •

edited by rustbot

Loading

RalfJung Aug 16, 2026 •

edited by rustbot

Loading