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

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

workingjubilee · 2026-07-07T19:09:11Z

+}
+
+const PID_OFFSET: usize = core::mem::offset_of!(task_struct, pid);
+// error: cannot use `offset_of!` with a `#[repr(Btf)]` type


Suggested change

// error: cannot use `offset_of!` with a `#[repr(Btf)]` type

// error: cannot use `offset_of!` with a `#[btf_relocatable]` type

workingjubilee · 2026-07-07T19:09:29Z

+
+fn pid(task: &task_struct) -> i32 {
+    task.pid
+    // error: cannot access fields of a `#[repr(Btf)]` type directly


Suggested change

// error: cannot access fields of a `#[repr(Btf)]` type directly

// error: cannot access fields of a `#[btf_relocatable]` type directly

workingjubilee · 2026-07-07T19:11:11Z

+Direct field projection from a `#[btf_relocatable]` ADT is rejected. This
+includes projections reached through autoderef:
+
+```rust
+task.pid
+```


I actually feel slightly unclear why this code example is here because it doesn't seem to illustrate the paragraph before it.

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

	// error: cannot use `offset_of!` with a `#[repr(Btf)]` type
	// error: cannot use `offset_of!` with a `#[btf_relocatable]` type

	// error: cannot access fields of a `#[repr(Btf)]` type directly
	// error: cannot access fields of a `#[btf_relocatable]` type directly

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

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

workingjubilee left a comment •

edited by rustbot

Loading