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-26T19:35:12Z

src/abi.md

+```
+
+r[abi.symbol-name.names]
+The *`no_mangle` attribute* and the *`export_name` attribute* shall only be applied to a `static` or `fn` item. The *`export_name` attribute* shall not be applied to an item declared within an [`extern` block].


Can't no_mangle be applied to all other items?

src/abi.md

ehuss · 2024-07-26T19:42:21Z

src/abi.md

@@ -79,22 +344,46 @@ The *`link_section` attribute* specifies the section of the object file that a
 pub static VAR1: u32 = 1;
 ```

-## The `export_name` attribute
+r[abi.link_section.def]
+An item with the *`link_section` attribute* is placed in the specified section when linking. The section specified shall not violate the constraints on section names on the target, and shall not be invalid for the item type, no diagnostic is required.


Similar to our conversation before about ndr, I think it would be best to avoid this for now until we have a decision on it.

ehuss · 2024-07-26T19:42:46Z

src/abi.md

-exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax
-to specify the symbol name.
+> [!NOTE]
+> A section name may be invalid if it violates the requirements for the item type, for example, an `fn` item must be placed in an executable section, and a mutable static item (`static mut` or one containing an `UnsafeCell`) must be placed in a writable section.


Suggested change

> A section name may be invalid if it violates the requirements for the item type, for example, an `fn` item must be placed in an executable section, and a mutable static item (`static mut` or one containing an `UnsafeCell`) must be placed in a writable section.

> A section name may be invalid if it violates the requirements for the item type. For example, an `fn` item must be placed in an executable section, and a mutable static item (`static mut` or one containing an `UnsafeCell`) must be placed in a writable section.

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?

traviscross · 2024-10-21T16:35:35Z

@rustbot labels -I-lang-nominated

Good catch that we didn't do a great job of being clear about that in writing up the FCP. We did mean, though, for this to be an ABI guarantee (e.g., we were building on @RalfJung's comment here).

We're documenting this also in:

update ABI compatibility docs for new option-like rules rust#132003

Co-authored-by: bjorn3 <[email protected]>

Co-authored-by: Eric Huss <[email protected]>

…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?

RalfJung · 2024-10-29T07:06:48Z

src/abi.md

+r[abi.compatibility]
+
+r[abi.compatibility.intro]
+Function calls pass parameters and return values between the caller and the callee function. This requires the caller and callee to agree on an ABI for those parameters and return values. This is typically only guaranteed when the same type is used in both the call site and the definition site of the callee, but certain other types may be *abi compatible*. This can appear when transmuting a [function pointer] or using an [`extern` block] to call a function. When the parameters or return types differ between the call site and def site, assuming they are *abi compatible*, the parameters or return types are transmuted to the type at the def site or call site respectively.


Suggested change

Function calls pass parameters and return values between the caller and the callee function. This requires the caller and callee to agree on an ABI for those parameters and return values. This is typically only guaranteed when the same type is used in both the call site and the definition site of the callee, but certain other types may be *abi compatible*. This can appear when transmuting a [function pointer] or using an [`extern` block] to call a function. When the parameters or return types differ between the call site and def site, assuming they are *abi compatible*, the parameters or return types are transmuted to the type at the def site or call site respectively.

Function calls pass parameters and return values between the caller and the callee function. This requires the caller and callee to agree on an ABI for those parameters and return values. This is typically only guaranteed when the same type is used in both the call site and the definition site of the callee. However, differences between caller and callee types can appear when transmuting a [function pointer] or using an [`extern` block] to call a function. This is permitted if the caller and callee types are *abi compatible* (otherwise, it is undefined behavior). If the types are abi compatible, the parameters are transmuted to the callee type as part of the call and the return value is transmuted to the caller type upon return.

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

src/abi.md

+Function calls pass parameters and return values between the caller and the callee function. This requires the caller and callee to agree on an ABI for those parameters and return values. This is typically only guaranteed when the same type is used in both the call site and the definition site of the callee, but certain other types may be *abi compatible*. This can appear when transmuting a [function pointer] or using an [`extern` block] to call a function. When the parameters or return types differ between the call site and def site, assuming they are *abi compatible*, the parameters or return types are transmuted to the type at the def site or call site respectively.
+
+> [!NOTE]
+> This can include calls to functions defined outside of rust, or built using a different Rust compiler version.


Suggested change

> This can include calls to functions defined outside of rust, or built using a different Rust compiler version.

> This can include calls to functions defined outside of Rust, or built using a different Rust compiler version.

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.

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

src/abi.md

+r[abi.compatibility.equivalence]
+Two types `T` and `U` are *abi compatible* if:
+* They are the same type,
+* `U` is *abi compatible* with `T`, or
+* There exists a type `V`, such that `T` is *abi compatible* with `V` an `V` is *abi compatible* with `U`,


IMO this is better stated after all the other clauses, since really what we are doing is we are generating a relation by having some "seeds" and then we are upclosing it to become an equivalence relation. It is quite confusing to read this before we added any of the elements to the relation that make it interesting.

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?

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

src/abi.md

+> Due to transitivity, two such types are *abi compatible* with each other if their *elision candidate field*s are *abi comaptible*
+
+r[abi.compatibility.fn-ptr]
+An [function pointer] type `T` is *abi compatible* with an [function pointer] type `U` if `T` and `U` have *abi compatible* tags.


Suggested change

An [function pointer] type `T` is *abi compatible* with an [function pointer] type `U` if `T` and `U` have *abi compatible* tags.

A [function pointer] type `T` is *abi compatible* with an [function pointer] type `U` if `T` and `U` have *abi compatible* tags.

RalfJung · 2024-10-29T07:19:38Z

src/abi.md

+> [!NOTE]
+> A signature is compatible with itself.
+
+r[abi.compatibility.simd-abi]


Given that we consider this a bug and are very close to fixing the bug to at least emit warnings, I don't think we should list this here.

This clause no longer exists in the library docs, so it should be removed here as well.

Yep, was waiting for the documentation change or the lint to land. Will fix this tomorrow.

RalfJung · 2024-10-29T07:21:48Z

src/abi.md

+* The ABI tag of the signature is `extern "Rust"`, or
+* If any parameter type, the return type, or the type of any argument passed via C-varargs has *simd abi requirements*, each [*salient target features*][target_feature] of that type is either set at both the definition site of the function, and at the call site, or is set at neither site.
+
+The behavior of a call that is not valid is undefined.


Should this say that a valid call transmutes the arguments / return value?

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.

…rn type is noted as being part of signature compatibility

chorman0773 added A-abi Area: ABI S-waiting-on-review Status: The marked PR is awaiting review from the PR author. 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 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

rustbot added the I-lang-nominated label Oct 21, 2024

rustbot removed the I-lang-nominated label Oct 21, 2024

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 <[email protected]>

Make suggested changes from PR comments

5c441ea

Apply suggestions from code review

3f5ca53

Co-authored-by: Eric Huss <[email protected]>

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



		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.

	> A section name may be invalid if it violates the requirements for the item type, for example, an `fn` item must be placed in an executable section, and a mutable static item (`static mut` or one containing an `UnsafeCell`) must be placed in a writable section.
	> A section name may be invalid if it violates the requirements for the item type. For example, an `fn` item must be placed in an executable section, and a mutable static item (`static mut` or one containing an `UnsafeCell`) must be placed in a writable section.

	> This can include calls to functions defined outside of rust, or built using a different Rust compiler version.
	> This can include calls to functions defined outside of Rust, or built using a different Rust compiler version.

	An [function pointer] type `T` is abi compatible with an [function pointer] type `U` if `T` and `U` have abi compatible tags.
	A [function pointer] type `T` is abi compatible with an [function pointer] 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

Choose a reason for hiding this comment

Choose a reason for hiding this 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

traviscross commented Oct 21, 2024

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

chorman0773 Nov 10, 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

pnkfelix Jul 25, 2024 •

edited

Loading

chorman0773 commented Oct 21, 2024 •

edited

Loading

chorman0773 Nov 10, 2024 •

edited

Loading