This file has incorrect statements such as

    /// The `abi` defines how this data is passed between functions.
    pub abi: ValueAbi,

See #132246 for more on why this is wrong.

I would honestly rather you not "enhance" anything here and set almost this entire file on fire here because it's just going to make me actually rewriting this harder. We could make more accurate information available in the future, but it's unclear why anyone would benefit from the current information because they lack the full context to interpret it.

View changes since the review

I appreciate the context. Having to reverse engineer the compiler is not an easy task, so please do point out any inaccuracies. Most of the comments here I wrote based on the comments from rustc_target and from analyzing the generated FnAbi for different function signatures.

I dearly sympathize because my task of figuring out what the hell is going on involves reverse-engineering LLVM. 🙃

At some point I just sort of started assuming everything I am reading is probably wrong, unfortunately.

My question here is mostly: What question is someone trying to answer that they think this information would be of use to them? If they're trying to do a basic ABI equality check then smuggling the data around opaquely with mostly no transformation and exposing a PartialEq impl that interrogates the innards seems more useful.

To elaborate: The rustc_target and rustc_abi crates were mostly written ages ago by people who are not easy to ask questions of anymore, in a single-backend context, where x86-64 was our only tier 1 target. It was then incrementally edited, including by people such as myself, in ways that were "good enough", and our unclear understandings documented as truth because no one was around anymore who completely knew exactly what was going on and we could usefully discuss things with. "cg_ssa" (rustc_codegen_ssa) was introduced as an incomplete abstraction layer over LLVMIR, and to the extent it has abstracted anything, it has made everything in rustc_abi and rustc_target wronger.

That is why asking questions about things below FnAbi is probably not a good idea, unless it's about a fundamental like Size or Align. Obviously those have to be correct. And we've... tried to make LayoutData... vaguely intelligible.

The use case is tools that build their own backends or analyzers on top of MIR and need to generate compatible call sequences or how the code interacts via FFI without depending on LLVM. They need to know: how many arguments there are (including implicit ones), whether a value is passed by copy or by pointer, and what type transformations the ABI requires. FnAbi/PassMode captures those decisions.

I've pushed a commit fixing the inaccuracies you pointed out — renamed ValueAbi to ValueRepr and LayoutShape::abi to LayoutShape::value_repr to align with the BackendRepr rename from #132246, and corrected the doc comments that were claiming layout fields define calling behavior. Happy to address any other inaccuracies you spot.

Let me know if there are changes to how we expose the data that would make it easier to evolve the internals.

So, if anyone wants to build a codegen backend, they should be focusing on using cg_ssa. That doesn't allow multi-version stability, but there is a reason I am saying it. If it is insufficient or problematic, it should be improved until it serves the need.

Analysis alone, however, is indeed the intended use-case of things here.

In either case, if they want a precise answer that doesn't depend on LLVM that can reason about things like "generating correct call sequences", they're Kinda Screwed Right Now. They would need to also implement the exact logic, essentially, that LLVM does, in order to get a consistently correct answer, because of how we kinda only model "ABI modulo LLVM".

Hmm. It might be sufficient if they want only a purely abstract matching of Rust's function ABI to a C signature? That might be wrong but it should be correct-enough.

In the Rust ABI there are things that can't be represented as a valid C signature. For example there are cases where we use more return registers than the platform C ABI allows, but LLVM supports representing it anyway.

Thanks for the context. To summarize where I think we are: this PR adds information that is currently missing from rustc_public — the structure of PassMode::Cast, argument attributes, and corrected documentation. The data itself is not incorrect; it accurately reflects the compiler's calling convention decisions.

Users may still need to do further processing depending on their use case (as cg_ssa does today), and the Rust ABI can produce things that don't map cleanly to a C signature. The data shouldn't be taken at face value as "this is exactly what happens on the wire" — but it is the correct input for tools that need to reason about argument layout and pass modes.