BTF relocations by vadorovsky · Pull Request #3966 · rust-lang/rfcs

vadorovsky · 2026-05-31T08:16:14Z

The RFC proposes the btf_relocatable_types feature gate, that provides a #[repr(Btf)] representation and low-level field-info intrinsics that emit BTF (BPF TypeFormat) CO-RE (Compile Once, Run Everywhere) relocations.

It also documents the relationship to offset_of!, ordinary field projection and LLVM BPF lowering.

This feature was originally proposed as pre-RFC.

Rendered

BTF, the BPF Type Format, encodes type information for both the running Linux kernel and compiled eBPF programs. An eBPF object can carry relocation records that describe field and aggregate accesses in terms of BTF types instead of fixed offsets; at load time, the loader compares the program's BTF with the kernel's BTF and rewrites those accesses to the correct offsets for the target kernel. This mechanism is often referred to as "CO-RE relocations" or "BTF relocations". `offset_of` always folds to a plain layout constant and does not preserve enough information for BTF CO-RE relocation emission. As a result, it is not suitable for relocatable field queries on BPF targets. Add three explicit intrinsics for BTF field metadata queries: * `btf_field_byte_offset` * `btf_field_byte_size` * `btf_field_exists` The user-facing BTF relocatable type support remains behind the `btf_relocations` feature gate, so use of this experimental CO-RE surface requires an explicit nightly opt-in. These intrinsics provide a frontend surface for CO-RE relocations. Unlike `offset_of`, they remain visible to backend codegen and can lower to relocatable field-info queries instead of immediate layout constants. For LLVM, lower these intrinsics through `@llvm.bpf.preserve.field.info` with the corresponding query kind. The necessary `@llvm.preserve.{struct,array,union}.access.index` chain is constructed internally during lowering, but it is not exposed as part of the user-facing API. On targets or backends without BTF relocation support, fall back to the ordinary layout-computed result: the field offset for `btf_field_byte_offset`, the field size for `btf_field_byte_size`, and `true` for `btf_field_exists`. The language-level design for this feature is proposed in rust-lang/rfcs#3966.

BTF, the BPF Type Format, encodes type information for both the running Linux kernel and compiled eBPF programs. An eBPF object can carry relocation records that describe field and aggregate accesses in terms of BTF types instead of fixed offsets; at load time, the loader compares the program's BTF with the kernel's BTF and rewrites those accesses to the correct offsets for the target kernel. This mechanism is often referred to as "CO-RE relocations" or "BTF relocations". `offset_of` always folds to a plain layout constant and does not preserve enough information for BTF CO-RE relocation emission. As a result, it is not suitable for relocatable field queries on BPF targets. Add three intrinsics for BTF field metadata queries: * `btf_field_byte_offset` * `btf_field_byte_size` * `btf_field_exists` Their availability is hidden behind the `btf_relocations` feature gate. Unlike `offset_of`, they remain visible to backend codegen and can lower to relocatable field-info queries instead of immediate layout constants. For LLVM, lower these intrinsics through `@llvm.bpf.preserve.field.info` with the corresponding query kind. The necessary `@llvm.preserve.{struct,array,union}.access.index` chain is constructed internally during lowering, but it is not exposed as part of the user-facing API. On targets or backends without BTF relocation support, fall back to: * The field offset for `btf_field_byte_offset`. * The field size for `btf_field_byte_size`. * `true` for `btf_field_exists`. The language-level design for this feature is proposed in rust-lang/rfcs#3966.

workingjubilee

Mostly minutiae that would benefit from being clarified.

View changes since this review

workingjubilee · 2026-06-27T22:45:00Z

+    #[inline]
+    pub fn pid(&self) -> Option<&i32> {
+        self.has_pid().then(|| {
+            let offset = core::btf::field_byte_offset!(task_struct, pid);
+            let ptr = self as *const task_struct as *const u8;
+
+            // SAFETY: the BTF relocation says that `se.vruntime` exists in the
+            // target layout, and the returned offset is relative to `task_struct`.
+            Some(unsafe { &*(ptr.add(offset) as *const i32) })
+        })


So a typo in a field name can result in simply turning this into a None and never taking the "active" code path, right? Since the relocation is functionally a set of runtime checks, and we would have to assume we take the field name for granted, and the entire reason to use these relocations is the struct definition per se is actually external to the program...?

Yes, that's right. Although instead of saying "is actually external", I would say that the struct definition is a reference point for the runtime checks.

To be fair, I proposed a field projection (like in clang) in my pre-RFC, but given the complexity, I'm not pursuing it for now.

workingjubilee · 2026-06-30T17:44:14Z

Syntax questions and my nits aside, this will want a sponsor from T-lang for proceeding as a nightly experiment (which will later come back to re-informing this RFC). I have nominated it so that if you do not find a sponsor in your own time they eventually see it appear on their agenda and one of them can either take up the gauntlet or they can decline it. And this comment as explanation for why I nominated it, of course. This may be a very eventual eventually, so I do suggest finding a sponsor in your own time.

traviscross · 2026-07-01T16:45:21Z

We talked about this in the lang call today. We were interested to hear what the people working on @rust-lang/rust-for-linux think about this, as well as what those working on reflection (@oli-obk, @scottmcm, rust-lang/rust-project-goals#406) and projection (@BennoLossin, @dingxiangfei2009, @tmandry, rust-lang/rust-project-goals#390) think.

If this generally makes sense to people, I'll be happy to champion a lang experiment here.

cc @lqd @Nadrieril

Darksonn · 2026-07-01T17:01:16Z

Also needs input from sized hierarchy side. cc @davidtwco

#t-lang > BTF relocations proposal @ 💬

Darksonn · 2026-07-01T17:36:47Z

+This overlaps with the accepted [Field Projections project goal][field-projections],
+which is exploring virtual places as a general mechanism for custom field
+projection. This RFC deliberately does not depend on that work: it provides the
+low-level BTF field metadata queries needed for CO-RE today, while leaving a
+future field-projection-based ergonomic surface open.
+
+Providing the field-info queries proposed in this RFC does not rule out
+exploring this alternative in the future. On the contrary, Clang provides both
+explicit field-info builtins and field projection. It makes sense to treat these
+as separate RFCs.


I think this RFC could be written to make it more clear that we expect field access and offset_of! to work in the future. For example, the offset_of! section is phrased as if we could never support offset_of! with btf relocations.

View changes since the review

Good point, I'm going to rephrase this (while still making it clear it's out of scope of this RFC).

Done 97478ed

oli-obk · 2026-07-01T18:41:34Z

+
+`offset_of!` is intentionally a constant layout query. It does not preserve the
+field identity needed to emit a BTF relocation. Reusing it would either silently
+produce non-relocatable code or require changing the meaning of an existing


How is the new macro with the same API change anything? Why isn't that also silently producing wrong things when e.g. a field doesn't exist at all in the relocation table?

View changes since the review

How is the new macro with the same API change anything?

When I submitted the pre-RFC, where I initially proposed emission of BTF relocations in regular field projections and offset_of! , the main feedback was that it goes against the principle that Sized types should have layout known at compile time, which is not the case with BTF-relocatable types.

Then the discussion went towards the hierarchy of Sized types RFC #3729 which would eliminate this problem. But then we also agreed treating BTF-relocatable types as !Sized and allowing access to them only with dedicated macros/intrinsics could be a good way to keep the feature rolling without hard dependency on #3729.

Why isn't that also silently producing wrong things when e.g. a field doesn't exist at all in the relocation table?

Not sure if I got this question right - are you asking about what field_byte_offset! and field_byte_size! macros produce when a field does not exist? That's a great question and actually made me realize that they should probably return an Option:

core::btf::field_byte_offset!(Carrier, field.path) -> Option<usize> core::btf::field_byte_size!(Carrier, field.path) -> Option<usize>

Jup, that makes sense now, thx

Done 6116056

Then the discussion went towards the hierarchy of Sized types RFC #3729 which would eliminate this problem

Just checking, as I'm not familiar with how BTF-relocatable types are used in practice: it seems like the property of having a size that is not known at compile time but known to be constant at runtime (depending on the hopefully future differentiation between const Sized vs Sized types from a follow-up to #3729) would be enough for you to model field offsets on BTF-relocatable types that are only known at runtime, and you won't need to model additional, separate, properties (e.g. with your own traits), right?

@lqd I'm so sorry for missing this question!

Just checking, as I'm not familiar with how BTF-relocatable types are used in practice: it seems like the property of having a size that is not known at compile time but known to be constant at runtime (depending on the hopefully future differentiation between const Sized vs Sized types from a follow-up to #3729) would be enough for you to model field offsets on BTF-relocatable types that are only known at runtime and you won't need to model additional, separate, properties (e.g. with your own traits), right?

That's right, under the Sized hierarchy RFC, BTF-relocatable types could implement SizeOfVal, I don't see any need for any additional trait.

One open question, which would remain even after the Sized hierarchy is accepted, is how do we handle direct field accesses to fields that don't exist during runtime. Do we panic? If so, are we going to generalize the macros (e.g. field_byte_offset! -> Option<usize>), that I'm proposing in this RFC, to become a fallible way of accessing potentially non-existing fields, that would apply to all of SizeOfVal but not Sized types?

vadorovsky · 2026-07-03T09:39:52Z

We talked about this in the lang call today. We were interested to hear what the people working on @rust-lang/rust-for-linux think about this, as well as what those working on reflection (@oli-obk, @scottmcm, rust-lang/rust-project-goals#406) and projection (@BennoLossin, @dingxiangfei2009, @tmandry, rust-lang/rust-project-goals#390) think.

If this generally makes sense to people, I'll be happy to champion a lang experiment here.

cc @lqd @Nadrieril

Thank you, @traviscross, for the discussion and for offering to champion this. I appreciate the lang team's interest. I'm going to modify the RFC according to the comments later today.

The RFC proposes the `btf_relocations` feature gate, which provides a `#[repr(Btf)]` representation and `core::btf` field-info macros that emit BTF (BPF Type Format)[0] CO-RE (Compile Once, Run Everywhere)[1] relocations. It also documents the relationship to `offset_of!`, ordinary field projection, and LLVM BPF lowering. This feature was originally proposed as a pre-RFC[2]. [0] https://docs.kernel.org/bpf/btf.html [1] https://nakryiko.com/posts/bpf-portability-and-co-re/ [2] https://internals.rust-lang.org/t/pre-rfc-btf-relocations/24161/25

It's better to emit a compile error.

rustbot · 2026-07-05T08:07:41Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

Move it under `#relocatable-field-access` section. Make it clear that we don't rule the `offset_of!` support out in the future.

Make the other macros sound by returning `None` when a field does not exist. That makes `field_exists!` redundant, so remove it.

workingjubilee

Cool. I resolved my concerns where they seemed no longer useful to think about or seemed to be adequately encompassed into the RFC. Noticed some typos, or at least incomplete substitutions.

View changes since this review

Keep code examples only in the guide-level explanation.

vadorovsky · 2026-08-04T19:21:53Z

I believe I’ve addressed all the review feedback.

I have an implementation ready on my branch (https://github.com/vadorovsky/rust/tree/vad/btf-relocations). @traviscross, would you be comfortable championing this as a lang experiment, or do we need more feedback and explicit approvals? In case we can proceed, should I create a tracking issue, or should rust-lang/rust#158412 be converted into one?

traviscross · 2026-08-05T11:09:51Z

I'll champion it. Go ahead and create a tracking issue if you would.

nagisa · 2026-08-05T11:49:42Z

Given that the long-term plan is to implement support for transparent operation with ordinary rust field projections, how terrible would it be to keep the core::bpf macros implemented but unstable until the field projections get implemented? Do these macros otherwise achieve anything that a plain field projection would not be able to provide functionality wise?

vadorovsky · 2026-08-06T08:31:39Z

@traviscross

I'll champion it. Go ahead and create a tracking issue if you would.

Thank you! I created the tracking issue and the libs-team ACP:

I'm going to send a PR later today.

@nagisa

Given that the long-term plan is to implement support for transparent operation with ordinary rust field projections, how terrible would it be to keep the core::bpf macros implemented but unstable until the field projections get implemented?

It probably depends on how long Sized hierarchy and the field projections take to implement. BPF targets are currently in Tier 3, but not because of lack of BTF relocations, but for another reasons:

They don't support >5 arguments (until LLVM 22, LLVM 23 fixes that).
They don't support aggregate returns (until LLVM 22, LLVM 23 fixes that).
They use a custom bitcode linker (bpf-linker). The two previous points are a blocker for using an ld-flavor of a linker (it's impossible to compile a full object file for libcore with the limitations above).

LLVM 23 support just got merged and it unblocks all of these points. The first two points should be fixed automatically, the last one will require some work on supporting linking with binutils (so far the only ld-type of linker supporting BPF). It would be also great to add BPF support to lld, mold, wild etc.

If the work on ld linking gets done faster than dynamic Sized and BTF field projection, I would be inclined to try moving the BPF targets at least to Tier 2. Tier 3 means nightly-only (with rustup), and it's a massive blocker in Aya's adoption. There are already some popular projects using it (e.g. mitmproxy) and some Linux distributions (e.g. Arch, Gentoo, NixOS) are enabling BPF targets in their Rust stable packages, even though Rust upstream considers BPF targets unstable.

I could imagine, that in situation when:

Ld flavor of linkers are supported.
core::btf macros are widely used.
Sized hierarchy and field projections are not done.

I would probably be in favor of trying to stabilize core::btf macros, together with moving the BPF target to Tier 2, to unblock Rust BPF projects that want to move to Rust stable, and have to use BTF relocations in some way (pretty much all of BPF that's not limited to networking). Just my opinion.

Of course it would be great to avoid such scenario by making all three done in similar time. I'll try to see how I can be helpful in Sized hierarchy, and I'm already experimenting on linkers support.

Do these macros otherwise achieve anything that a plain field projection would not be able to provide functionality wise?

Yes, there is one difference between macros and a plain field projection. Macros return an Option, and therefore return None if the requested field does not exist during runtime. Field projection would most likely panic in such case (up for decision in an another RFC, once Sized hierarchy is done).

It's not uncommon for Linux kernel code to remove, rename or add fields in important structs, and for BPF programs to want to handle layouts of such structs for different kernel versions. Even if the field projection is implemented, the macros will be useful for handling such cases. Also, some kernel structs have fields that depend on kernel configuration.

For example, there is a field called cg_dead_lnode in task_struct that depends on CONFIG_PREEMPT_RT being enabled:

https://elixir.bootlin.com/linux/v7.1.5/source/include/linux/sched.h#L1329-L1331

Writing a BPF program that would panic on absence of this field wouldn't be great, and it would be preferable to write code like:

// This would be generated by a proc-macro in Aya.
impl task_struct {
    pub fn maybe_cg_dead_lnode(&self) -> Option<&llist_node> {
        core::btf::field_byte_offset!(task_struct, cg_dead_lnode).map(|offset| {
            let ptr = self as *const task_struct as *const u8;
            Some(unsafe { &*(ptr.add(offset) as *const llist_node) })
        })
    }
}

// User's code that doesn't panic.
if let Some(cg_dead_lnode) = task_struct.maybe_cg_dead_lnode() {
    // handle `PREEMPT_RT`
} else {
    // no `PREEMPT_RT`
}

nagisa · 2026-08-06T11:17:13Z

A'ight. In that case the only other suggestion I have is that this module should be under core::arch::bpf, like all other arch-specific stuff, rather than at the top level in core.

Noratrieb added T-lang Relevant to the language team, which will review and decide on the RFC. T-opsem Relevant to the operational semantics team, which will review and decide on the RFC. labels May 31, 2026

vadorovsky force-pushed the btf-relocations branch 3 times, most recently from 0a822d7 to 2ec6577 Compare June 1, 2026 11:38

vadorovsky force-pushed the btf-relocations branch from 2ec6577 to 54a1461 Compare June 9, 2026 16:04

Jules-Bertholet mentioned this pull request Jun 25, 2026

BTF CO-RE relocations for the BPF target (preserve_access_index intrinsics) rust-lang/rust#158412

Open

workingjubilee reviewed Jun 29, 2026

View reviewed changes

workingjubilee added the I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. label Jun 30, 2026

traviscross added the P-lang-drag-1 Lang team prioritization drag level 1. label Jul 1, 2026

Mark-Simulacrum reviewed Jul 1, 2026

View reviewed changes

Comment thread text/0000-btf-relocations.md Outdated

traviscross added the I-lang-radar Items that are on lang's radar and will need eventual work or consideration. label Jul 1, 2026

traviscross added P-lang-drag-2 Lang team prioritization drag level 2. and removed P-lang-drag-1 Lang team prioritization drag level 1. labels Jul 1, 2026

Darksonn reviewed Jul 1, 2026

View reviewed changes

oli-obk reviewed Jul 1, 2026

View reviewed changes

Comment thread text/0000-btf-relocations.md

oli-obk reviewed Jul 1, 2026

View reviewed changes

gmreads mentioned this pull request Jul 4, 2026

Feature Request: Support logging bpf_get_current_comm() output as a human-readable string aya-rs/aya#1622

Open

vadorovsky added 3 commits July 5, 2026 09:51

Ditch the fallback mechanism

03549d3

It's better to emit a compile error.

Reword the "Pior art" section

6292c33

vadorovsky force-pushed the btf-relocations branch from 54a1461 to 6292c33 Compare July 5, 2026 08:07

workingjubilee reviewed Jul 5, 2026

View reviewed changes

Comment thread text/0000-btf-relocations.md Outdated

vadorovsky added 4 commits July 6, 2026 10:03

Move and rephrase the "Use offset_of!" section

97478ed

Move it under `#relocatable-field-access` section. Make it clear that we don't rule the `offset_of!` support out in the future.

Remove field_exists! macro, make the others return Option

6116056

Make the other macros sound by returning `None` when a field does not exist. That makes `field_exists!` redundant, so remove it.

Reword the statement about operational semantics

0a3bcf7

Change #[repr(Btf)] to #[btf_relocatable]

09663bd

vadorovsky requested review from Darksonn, Mark-Simulacrum, oli-obk and workingjubilee July 7, 2026 18:53

workingjubilee reviewed Jul 7, 2026

View reviewed changes

Comment thread text/0000-btf-relocations.md Outdated

Comment thread text/0000-btf-relocations.md Outdated

Comment thread text/0000-btf-relocations.md Outdated

vadorovsky added 2 commits July 8, 2026 10:42

Remove remaining mentions of #[repr(Btf)]

639bdc6

Remove the confusing code example from reference-level explanation

ad18f89

Keep code examples only in the guide-level explanation.

vadorovsky requested a review from workingjubilee July 8, 2026 08:56

vadorovsky mentioned this pull request Jul 9, 2026

aya for sched_ext: Add struct_ops program support and kfunc call resolution aya-rs/aya#1495

Open

3 tasks

This was referenced Aug 6, 2026

ACP: Add BTF relocation macros to core rust-lang/libs-team#846

Open

Tracking Issue for BTF relocations (btf_relocations) rust-lang/rust#160616

Open

Uh oh!

Conversation

vadorovsky commented May 31, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

workingjubilee left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

workingjubilee commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

traviscross commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Darksonn commented Jul 1, 2026

Uh oh!

Darksonn Jul 1, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

oli-obk Jul 1, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vadorovsky Jul 22, 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!

vadorovsky commented Jul 3, 2026

Uh oh!

rustbot commented Jul 5, 2026

Uh oh!

Uh oh!

workingjubilee left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

vadorovsky commented Aug 4, 2026

Uh oh!

traviscross commented Aug 5, 2026

Uh oh!

nagisa commented Aug 5, 2026

Uh oh!

vadorovsky commented Aug 6, 2026

Uh oh!

nagisa commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

vadorovsky commented May 31, 2026 •

edited by rustbot

Loading

workingjubilee left a comment •

edited by rustbot

Loading

workingjubilee commented Jun 30, 2026 •

edited

Loading

traviscross commented Jul 1, 2026 •

edited

Loading

Darksonn Jul 1, 2026 •

edited by rustbot

Loading

oli-obk Jul 1, 2026 •

edited by rustbot

Loading

vadorovsky Jul 22, 2026 •

edited

Loading

workingjubilee left a comment •

edited by rustbot

Loading