Terminology around layout, ABI, representation, and bit validity

[joshlf]

I'm writing the docs for the following type:

#[repr(packed)]
pub struct Unalign<T>(T);

I'd like to explain in the docs that the layout/ABI/representation/bit validity/whatever is the same as that of T with the exception of alignment, but I'm not sure what terminology to use. A few observations:

• Per the Rust reference, "layout" refers at least to size, alignment, and field offsets
• In some docs - such as those for MaybeUninit - the phrase "ABI" is also used
• The UCG WG has used the phrase "validity" to refer to the set of allowed bit patterns for a type
• The phrase "representation" seems to be fairly consistently used to refer to the repr attribute (whether or not the attribute is present and, if present, what values are given)

My questions are:

• Does "layout" also encompass a type's bit validity?
  • If not, what phrase refers to a type's bit validity? Do we just have to say "layout and bit validity" if we want to encompass everything?
• What does the phrase "ABI" mean?

As a meta point, it seems like the terminology has been somewhat standardized over time as folks have gravitated towards a common set of terms, but there's still some disagreement (e.g., I haven't seen "ABI" used in most places, but it does show up). It would be good to decide on a standard set of terms, and to standardize their usage across the docs.

[Lokathor]

I believe that ABI refers to, at least, how the data is passed between functions.

It might also mean other things, but it at least means that much.

[joshlf]

how the data is passed between data

Passed between functions?

[Lokathor]

Yes. When data is passed between functions both functions must agree where the caller will put the data for the callee's arguments, and also where the callee will leave the data for the caller's return value.

EDIT: oh i see, i made a typo at first. sorry, fixed

[RalfJung]

Yeah, sadly we never reached consensus for what exactly is part of "layout" and "ABI"... also see #122.

I honestly don't even really care which terms we end up using, as long as we have names for all the relevant things and we can all agree on using the same names. :)

[joshlf]

Assuming one were to come up with a standard set of terms, what would the process be like for getting that accepted as official? Is it just a matter of getting sign-off and merging a doc somewhere, or would deeper surgery be required in order to get all docs up to standard before such a doc was merged?

[RalfJung]

I would think it would start by updating the glossary and other documents in this repository. If we find something that works well for this, then one could start to figure out if there are conflicts with any of the official documentation, and start talking to the relevant teams to figure out how to update their terminology.

[scottmcm]

We have Layout::from_size_align on stable, so that nudges the definition in that direction, at least.

Then ABI + invariants are additional atop that, I guess.

[Lokathor]

Yeah but unfortunately that Layout type doesn't tell you field placement, which is the whole big thing people normally want to know about for their structs.