Expand description
ABI handling for rustc
§What is an “ABI”?
Literally, “application binary interface”, which means it is everything about how code interacts, at the machine level, with other code. This means it technically covers all of the following:
- object binary format for e.g. relocations or offset tables
- in-memory layout of types
- procedure calling conventions
When we discuss “ABI” in the context of rustc, we are probably discussing calling conventions.
To describe those rustc_abi also covers type layout, as it must for values passed on the stack.
Despite rustc_abi being about calling conventions, it is good to remember these usages exist.
You will encounter all of them and more if you study target-specific codegen enough!
Even in general conversation, when someone says “the Rust ABI is unstable”, it may allude to
either or both of
repr(Rust)types have a mostly-unspecified layoutextern "Rust" fn(A) -> Rhas an unspecified calling convention
§Crate Goal
ABI is a foundational concept, so the rustc_abi crate serves as an equally foundational crate.
It cannot carry all details relevant to an ABI: those permeate code generation and linkage.
Instead, rustc_abi is intended to provide the interface for reasoning about the binary interface.
It should contain traits and types that other crates then use in their implementation.
For example, a platform’s extern "C" fn calling convention will be implemented in rustc_target
but rustc_abi contains the types for calculating layout and describing register-passing.
This makes it easier to describe things in the same way across targets, codegen backends, and
even other Rust compilers, such as rust-analyzer!
Structs§
- AbiAnd
Pref Align - A pair of alignments, ABI-mandated and preferred.
- Address
Space - An identifier that specifies the address space that some operation should operate on. Special address spaces have an effect on code generation, depending on the target and the address spaces it implements.
- Align
- Alignment of a type in bytes (always a power of two).
- Heterogeneous
- Error from the
homogeneous_aggregatetest function, indicating there are distinct leaf fields passed in different ways, or this is uninhabited. - Layout
Calculator - Layout
Data - Niche
- Pointee
Info - Encodes extra information we have about a pointer. Note that this information is advisory only, and backends are free to ignore it: if the information is wrong, that can cause UB, but if the information is absent, that must always be okay.
- Reg
- Repr
Flags - Repr
Options - Represents the repr options provided by the user.
- Size
- Size of a type in bytes.
- Target
Data Layout - Parsed Data layout for a target, which contains everything needed to compute layouts.
- Wrapping
Range - Inclusive wrap-around range of valid values, that is, if
start > end, it represents
start..=MAX, followed by0..=end.
Enums§
- Align
From Bytes Error - Backend
Repr - The way we represent values to the backend
- Endian
- Endianness of the target, which must match cfg(target-endian).
- Fields
Shape - Describes how the fields of a type are located in memory.
- Float
- Floating-point types.
- Homogeneous
Aggregate - Return value from the
homogeneous_aggregatetest function. - Integer
- Integers, also used for enum discriminants.
- Integer
Type - Layout
Calculator Error - Pointer
Kind - Primitive
- Fundamental unit of memory access and layout.
- RegKind
- Scalar
- Information about one scalar component of a Rust type.
- Struct
Kind - TagEncoding
- Target
Data Layout Errors - Variants