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.

ehuss · 2024-07-26T19:45:37Z

src/abi.md

-linking external libraries.
+## ABI Compatibility
+
+r[abi.compatibility]


Can you add a few sentences explaining what abi compatibility is? Such as the consequence of what it means for types to be abi compatible? In general, I felt a little uncertain what I was reading, since it immediately jumps into a list of rules without giving context or explaining what this section is about.

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

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

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

…e new claims about `link_section`.

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

cc @rust-lang/opsem

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 error when calling/declaring functions with vectors that require missing target feature rust-lang/rust#127731

Open

ehuss mentioned this pull request Sep 20, 2024

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

Open

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 added 6 commits September 21, 2024 22:15

Start abi chapter.

d44e741

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

9689126

Cleanup styling of abi chapter

8cdee55

Link to section that lists abi chapters

7c5623a

Add links to clauses in abi chapter

bb40f83

Add tests to abi chapter

8ab15ce

chorman0773 and others added 8 commits September 21, 2024 22:18

Fix style issues from CI

a63c4af

Fix "File Must End with a newline" error

a06fe1b

Fix broken links to abi chapter

ad2ded8

Apply suggestions from code review

83a3b71

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

Make suggested changes from PR comments

0c95719

Apply suggestions from code review

51fc74a

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

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

2477068

…e new claims about `link_section`.

Add introductory clauses and reformat to use existing grammar style

bcbfdf7

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

chorman0773 added 3 commits September 21, 2024 22:43

Add additional explanations to the abi compatibility section

a4081da

Fix style issues

bda9a06

Fix broken links

3092f3c

chorman0773 mentioned this pull request Sep 23, 2024

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

Open

90 tasks

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 Jul 26, 2024

ehuss Jul 26, 2024

ehuss Jul 26, 2024

ehuss Jul 26, 2024

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



		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.

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

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

pnkfelix Jul 25, 2024 •

edited

Loading

pnkfelix Jul 25, 2024 •

edited

Loading