Spec abi chapter #1545

chorman0773 · 2024-07-24T16:25:25Z

This rewrites the abi chapter, and adds call compatibility to the chapter.

src/abi.md

pnkfelix · 2024-07-25T14:33:54Z

src/abi.md

+* There exists a type `V`, such that `T` is *abi compatible* with `V` an `V` is *abi compatuble* with `U`,
+
+> [!NOTE]
+> These properties ensure that *abi compatibility* is an equivalence relation.


Consider adding the terms "reflexivity", "symmetry", and "transitivity" to the three bullets above, especially since you use at least the term "transitivity' in the text that follows.

Probably a good idea. I wouldn't want to put it on the bullets though, maybe add it to the note.

These properties are respectively called "reflexivity", "symmetry", and "transitivity". They ensure that abi compatibility is an equivalence relation.

src/abi.md

pnkfelix · 2024-07-25T14:42:12Z

src/abi.md

+
+fn main(){
+    let f: unsafe fn(*mut ()) = unsafe{core::mem::transmute(foo as unsafe fn(_))}; // Type Erase the function
+    let mut val = 0;


this example is relying on i32 being the fallback integer type when there is no other alternative being imposed, right?

(E.g., if one had written 5_i8 down below, then that ends up affecting the type inferred for val, and yields UB overall since now the write will be out-of-bounds, at least according to miri.)

I am wondering whether it would be better, for purposes of this example, to explicitly assign the i32 type via let val: i32 = 0; and then you avoid discussion of how integer type fallback is handled in this part of the spec.

Probably, yeah. I guess my brain was just on autopilot writing that test.

src/abi.md

pnkfelix · 2024-07-25T14:46:44Z

src/abi.md

+
+
+r[abi.compatibility.fn-ptr]
+An [`fn`-ptr type] `T` is compatible with an [`fn`-ptr type] `U` if `T` and `U` have *abi compatible* tags.


is this supposed to say *abi compatible* or just compatible ?

That one is supposed to say abi compatible, yes.

chorman0773 · 2024-07-26T19:23:23Z

We need to make mdbook-spec linkify Result<T,S>

ehuss

Thanks @chorman0773! I really appreciate this!

src/abi.md

ehuss · 2024-07-26T20:21:25Z

We need to make mdbook-spec linkify Result<T,S>

For now, you'll need to use a fully qualified path like [`Result<T, S>`](std::result::Result). It's not really possible to support prelude items, since it needs some kind of token (like std::) to know if it is a standard library link.

chorman0773 · 2024-07-26T20:23:26Z

That's current what I'm using - the issue is on the <T,S>. It seems to handle 1 generic parameter fine, but not 2.

ehuss · 2024-07-26T20:41:45Z

Ah, I see! Posted #1549 with a fix.

ehuss · 2024-07-30T21:41:56Z

A concern that I think we should consider is that this seems to duplicate content from the core documentation. I think this is an important question about how we want to handle that. There are a few options:

Move everything to the reference, and remove from the core docs and link to the reference.
Keep everything in the core docs, and don't add it to the reference.
Duplicate in both places.

I think if it is duplicated, it will get out of sync, which I think will contribute to confusion, and cause more work.

I lean towards moving it to the reference, but there are some considerations of it being very useful to be in the core docs.

traviscross · 2024-09-20T09:05:25Z

cc @RalfJung

workingjubilee · 2024-09-20T20:09:48Z

I lean towards moving it to the reference, but there are some considerations of it being very useful to be in the core docs.

I think that where it is relevant, some things should be documented in the standard library even at the cost of duplication and even at the cost of desync.

Tersely, and then immediately (ahem) reference the Reference.

workingjubilee · 2024-09-20T20:16:10Z

This probably could afford splitting the attributes and argument/return type equivalence into different files?

ehuss · 2024-09-21T13:22:22Z

cc rust-lang/rust#130653

traviscross · 2024-09-22T09:13:02Z

cc @rust-lang/opsem

ehuss · 2024-10-21T13:59:53Z

Can you update to also include rust-lang/rust#128784 (assuming that isn't already covered, and should go here and not elsewhere)?

ehuss · 2024-10-21T14:52:06Z

Does this also need to be updated for rust-lang/rust#110503?

chorman0773 · 2024-10-21T16:14:10Z

rust-lang/rust#128784 seems more like something for the items/extern-block.md, as the list of supported ABI strings are documented in that chapter.

Does this also need to be updated for rust-lang/rust#110503?

Hmm... I can't tell whether the FCP in rust-lang/rust#130628 provides a just the Layout guarantee for all types or an ABI guarantee, so I'd like for T-lang to clarify that.

@rustbot label: +I-lang-nominated

Question for T-lang: In rust#130628, T-lang FCP-stabilized a layout guarantee for any enum type that matches the specific form documented there in rust-lang/rust#130628 (comment). The layout guarantee will be documented in #1654. Does this layout guarantee also carry an ABI compatibility guarantee that should be documented here?

Co-authored-by: bjorn3 <17426603+bjorn3@users.noreply.github.com>

Co-authored-by: Eric Huss <eric@huss.org>

…e new claims about `link_section`.

… abi compatible with their *elision candidate field*s

chorman0773 · 2024-10-21T17:05:59Z

The new section points to Ralf's UCG chapter temporarily, but the link can be removed and pointed to the id defined by #1654.

RalfJung · 2024-10-29T07:04:49Z

src/abi.md

 linking external libraries.

+## ABI compatibility
+
+r[abi.compatibility]


There's no paragraph after this marker... is this the normal syntax?

Yes, it's an identifier for the whole section.

src/abi.md

RalfJung · 2024-10-29T07:07:39Z

src/abi.md

+> [!NOTE]
+> This can include calls to functions defined outside of rust, or built using a different Rust compiler version.
+> Additional guarantees will apply in this case for "FFI Safe" types, which match up with the platform C ABI in well-defined ways.
+> These are not fully documented here currently.


Shouldn't this say that additional requirements apply? The document right now only describes the rules for Rust-to-Rust calls, as far as I can see.

No, because the note is talking about the fact that "FFI Safe" types have a defined mapping to the platform C abi.
You can technically pass a non-"FFI Safe" type to an FFI call, there's just no guarantee you can match it on the other side.

src/abi.md

RalfJung · 2024-10-29T07:17:31Z

src/abi.md

+```
+
+r[abi.compatibility.core]
+The types [`core::mem::MaybeUninit<T>`], [`core::cell::UnsafeCell<T>`], and [`core::num::NonZero<T>`], are *abi compatible* with `T`.


This is odd... why do we list these types and not others?

These types are magic lang items. MaybeUninit<T> is a transparent union (which isn't otherwise a thing that can exist), UnsafeCell<T> doesn't fully qualify as normal repr(transparent) due to excluding niches (including guaranteed ones that would normally be inherited by repr(transparent), and NonZero<T> has GDE.

src/abi.md

RalfJung · 2024-10-29T07:22:34Z

src/abi.md

+Two types, `T` and `U`, are *abi compatible* if both have size 0 and alignment 1.
+
+r[abi.compatibility.discriminant]
+If `T` is an a type listed in [layout.repr.rust.option.elision], and `U` is the type of the *elision candidate field*, then `T` is layout compatible with `U`.


The referenced section here doesn't exist yet, does it?

Oh this is just a normal markdown link for now, I see.

Getting rid of the hard dependency on #1654.
If #1654 lands first, then I'll remove the link. If this lands before #1654 I'll make #1645 remove the link.

…rn type is noted as being part of signature compatibility

Co-authored-by: Ralf Jung <post@ralfj.de>

…il after other clauses

chorman0773 added A-abi Area: ABI S-waiting-on-review Status: The marked PR is awaiting review from a maintainer T-spec Team: spec and removed T-spec Team: spec labels Jul 24, 2024

pnkfelix reviewed Jul 25, 2024

View reviewed changes

src/abi.md Outdated Show resolved Hide resolved

pnkfelix reviewed Jul 25, 2024

View reviewed changes

bjorn3 reviewed Jul 25, 2024

View reviewed changes

src/abi.md Outdated Show resolved Hide resolved

pnkfelix reviewed Jul 25, 2024

View reviewed changes

bjorn3 reviewed Jul 25, 2024

View reviewed changes

src/abi.md Outdated Show resolved Hide resolved

pnkfelix reviewed Jul 25, 2024

View reviewed changes

chorman0773 mentioned this pull request Jul 26, 2024

Should we / can we make MaybeUninit<T> always preserve all bytes of T? rust-lang/unsafe-code-guidelines#518

Open

ehuss reviewed Jul 26, 2024

View reviewed changes

traviscross mentioned this pull request Sep 3, 2024

Emit future-incompatibility lint when calling/declaring functions with vectors that require missing target feature rust-lang/rust#127731

Merged

ehuss mentioned this pull request Sep 20, 2024

Tracking Issue for result_ffi_guarantees (RFC 3391) rust-lang/rust#110503

Closed

7 tasks

chorman0773 mentioned this pull request Sep 20, 2024

Explain what the fn is an "ABI" and what equivalencies we guarantee #1623

Open

12 tasks

chorman0773 force-pushed the spec-abi-chapter branch from 8c634cb to bcbfdf7 Compare September 22, 2024 02:20

chorman0773 mentioned this pull request Sep 23, 2024

Tracking Issue: Adding mdbook-spec identifiers to reference chapters #1561

Open

90 tasks

chorman0773 and others added 17 commits October 21, 2024 12:55

Start abi chapter.

8116b5e

Clarify that extern "Rust" is safe, even when simd types are used

48be95a

Cleanup styling of abi chapter

fee9c23

Link to section that lists abi chapters

b5c0528

Add links to clauses in abi chapter

15e1563

Add tests to abi chapter

d10ef05

Fix style issues from CI

e10129a

Fix "File Must End with a newline" error

8b7d4df

Fix broken links to abi chapter

6d695cd

Apply suggestions from code review

92c0c94

Co-authored-by: bjorn3 <17426603+bjorn3@users.noreply.github.com>

Make suggested changes from PR comments

5c441ea

Apply suggestions from code review

3f5ca53

Co-authored-by: Eric Huss <eric@huss.org>

Elaborate more on *abi compatible* and *simd abi requirements*. Remov…

b99883a

…e new claims about `link_section`.

Add introductory clauses and reformat to use existing grammar style

0d0635b

Add additional explanations to the abi compatibility section

073ca42

Fix style issues

7dd5425

Fix broken links

97cd91f

chorman0773 force-pushed the spec-abi-chapter branch from 3092f3c to 97cd91f Compare October 21, 2024 16:55

Indicate that all types subject to mandatory discriminant elision are…

e4c62ac

… abi compatible with their *elision candidate field*s

chorman0773 added 2 commits October 21, 2024 13:07

Fix link reference to be the correct identifier

cbc8349

Fix "Lines must not end with spaces" error

36f80c3

RalfJung reviewed Oct 29, 2024

View reviewed changes

Remove simd abi requirements from definition and ensure that the retu…

79a248d

…rn type is noted as being part of signature compatibility

This comment has been minimized.

Sign in to view

chorman0773 and others added 5 commits December 11, 2024 18:56

Merge branch 'master' into spec-abi-chapter

4c219fc

Apply suggestions from code review

1582d3f

Co-authored-by: Ralf Jung <post@ralfj.de>

Fix abi chapter tests to comply with edition 2024

2afe85e

Fix parenthesis on unsafe(no_mangle)

5be0423

Move clause about abi-compatibility being an equivalence relation unt…

ce0915c

…il after other clauses

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Spec abi chapter #1545

Spec abi chapter #1545

chorman0773 commented Jul 24, 2024

pnkfelix Jul 25, 2024 •

edited

Loading

chorman0773 Jul 25, 2024

pnkfelix Jul 25, 2024

chorman0773 Jul 25, 2024

pnkfelix Jul 25, 2024 •

edited

Loading

chorman0773 Jul 25, 2024

chorman0773 commented Jul 26, 2024

ehuss left a comment

ehuss commented Jul 26, 2024

chorman0773 commented Jul 26, 2024

ehuss commented Jul 26, 2024

ehuss commented Jul 30, 2024

traviscross commented Sep 20, 2024

workingjubilee commented Sep 20, 2024

workingjubilee commented Sep 20, 2024

ehuss commented Sep 21, 2024

traviscross commented Sep 22, 2024

ehuss commented Oct 21, 2024

ehuss commented Oct 21, 2024

chorman0773 commented Oct 21, 2024 •

edited

Loading

chorman0773 commented Oct 21, 2024

RalfJung Oct 29, 2024

chorman0773 Dec 11, 2024

RalfJung Oct 29, 2024

chorman0773 Dec 12, 2024

RalfJung Oct 29, 2024

chorman0773 Dec 12, 2024

RalfJung Oct 29, 2024

RalfJung Oct 29, 2024

chorman0773 Dec 12, 2024

This comment has been minimized.



		r[abi.compatibility.fn-ptr]
		An [`fn`-ptr type] `T` is compatible with an [`fn`-ptr type] `U` if `T` and `U` have abi compatible tags.

Spec abi chapter #1545

Are you sure you want to change the base?

Spec abi chapter #1545

Conversation

chorman0773 commented Jul 24, 2024

pnkfelix Jul 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pnkfelix Jul 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chorman0773 commented Jul 26, 2024

ehuss left a comment

Choose a reason for hiding this comment

ehuss commented Jul 26, 2024

chorman0773 commented Jul 26, 2024

ehuss commented Jul 26, 2024

ehuss commented Jul 30, 2024

traviscross commented Sep 20, 2024

workingjubilee commented Sep 20, 2024

workingjubilee commented Sep 20, 2024

ehuss commented Sep 21, 2024

traviscross commented Sep 22, 2024

ehuss commented Oct 21, 2024

ehuss commented Oct 21, 2024

chorman0773 commented Oct 21, 2024 • edited Loading

chorman0773 commented Oct 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment has been minimized.

pnkfelix Jul 25, 2024 •

edited

Loading

pnkfelix Jul 25, 2024 •

edited

Loading

chorman0773 commented Oct 21, 2024 •

edited

Loading