rucc-target 0.18.10

//! The register file: what registers a target has, and what classes they fall into.
//!
//! Design: `spec/10-backend.md` section 10.8.
//!
//! A register file is data rather than code, which is the same claim the rest of this crate
//! makes and the one `M10` puts a number on. A class is a set of registers that an operand of
//! that class may be assigned to, and a physical register is its number inside its class, so
//! the allocator works in dense small integers and only the printer and the parser ever deal in
//! names.
//!
//! The file lives here rather than in `rucc-mir` because more than one thing reads it. The
//! machine IR needs it to print, the allocator needs the set it may assign from, and the ABI
//! description needs to name the registers arguments arrive in. All three are above this crate,
//! and the alternative is the register file living in whichever of them happens to be lowest,
//! which is how a layering ends up describing itself as historical.
//!
//! Names are unique across the whole file, not merely inside a class. That is what lets a
//! register be written `$rax` in a dump rather than `$gpr.0`, and it is a real constraint on a
//! target that gives one register two classes: it has to say which class it is in, or use two
//! names. [`RegFile::duplicate`] is what a target's own test asks to find out.

use std::fmt;

use rucc_abi::{AbiDescription, Convention, StackArgs};

/// One class of registers, and the registers in it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ClassInfo {
    /// What the class is called in a dump, such as `gpr`.
    pub name: &'static str,
    /// How wide one of its registers is, in bits.
    pub bits: u32,
    /// The registers, in the order their numbers run, without the sigil a dump writes.
    pub regs: &'static [&'static str],
    /// Whether the allocator may put a value in one of these.
    ///
    /// True for every class a target means the allocator to use, which is nearly all of them.
    /// False says the registers exist and are named and are not somewhere a value may be told to
    /// live, so a virtual register of this class is a mistake at the point it was made rather than
    /// a value the allocator has nowhere to put.
    ///
    /// The x87 stack is the case this exists for, and it is worth the sentence because it is not
    /// the usual reason a register is unavailable. `rsp` is unavailable because it has a job;
    /// `st0` is unavailable because the machine addresses it as a stack, so which register a name
    /// means depends on how many values are on the stack at the time, and an allocator that hands
    /// out a name has no way to say that. So nothing allocates from it, an eighty bit value lives
    /// in a stack slot between one operation and the next, and the stack is empty on both sides of
    /// every group of instructions that uses it. See `spec/10-backend.md` section 10.8, which says
    /// what a group is and why nothing the allocator inserts can get into the middle of one, and
    /// tamnd/rucc#540.
    ///
    /// A register in such a class can still be named, which is the whole reason the class is
    /// described at all: a `long double` comes back from a call in `st0` and the convention has to
    /// be able to say so.
    pub allocatable: bool,
}

/// Which class a register or an operand belongs to.
///
/// A number into the file's classes rather than a name, because it is on every operand of every
/// instruction and it is compared far more often than it is printed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RegClass(u8);

impl RegClass {
    /// The class with that number.
    #[must_use]
    pub const fn new(number: u8) -> Self {
        Self(number)
    }

    /// Its number, which is what indexes the file.
    #[must_use]
    pub const fn number(self) -> u8 {
        self.0
    }
}

/// One physical register, as its number inside its class.
///
/// The class is not in here. An operand carries its class already, and a fixed-register
/// constraint is a constraint on an operand, so repeating the class would be a second copy of
/// something that can disagree with the first.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PhysReg(u8);

impl PhysReg {
    /// The register with that number in its class.
    #[must_use]
    pub const fn new(number: u8) -> Self {
        Self(number)
    }

    /// Its number inside its class.
    #[must_use]
    pub const fn number(self) -> u8 {
        self.0
    }
}

/// Every register a target has.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegFile {
    classes: &'static [ClassInfo],
}

impl RegFile {
    /// The file of a target whose registers nothing has described yet.
    ///
    /// A target reaches 1.0 with a real one. Until it has one, the honest answer to what
    /// registers it has is that nobody has written them down, and that is a file with no
    /// classes in it rather than a panic or a plausible guess.
    pub const EMPTY: Self = Self::new(&[]);

    /// A file made of those classes, numbered in the order they are given.
    #[must_use]
    pub const fn new(classes: &'static [ClassInfo]) -> Self {
        Self { classes }
    }

    /// Its classes, each with the number it is known by.
    pub fn classes(&self) -> impl Iterator<Item = (RegClass, &'static ClassInfo)> + use<> {
        self.classes.iter().enumerate().map(|(number, info)| (RegClass::new(number as u8), info))
    }

    /// What is in one class.
    #[must_use]
    pub fn class(&self, class: RegClass) -> Option<&'static ClassInfo> {
        self.classes.get(usize::from(class.number()))
    }

    /// The class of that name, such as `gpr`.
    #[must_use]
    pub fn class_named(&self, name: &str) -> Option<RegClass> {
        self.classes().find(|(_, info)| info.name == name).map(|(class, _)| class)
    }

    /// Whether the allocator may put a value in that class, which is [`ClassInfo::allocatable`].
    ///
    /// A class the file does not have is not one either, which is the same answer as a class
    /// nothing allocates from and is the one that keeps a caller from having to say what it means
    /// by a class number the target never gave out.
    #[must_use]
    pub fn allocatable(&self, class: RegClass) -> bool {
        self.class(class).is_some_and(|info| info.allocatable)
    }

    /// How many registers are in a class, which is one past the largest number in it.
    #[must_use]
    pub fn len(&self, class: RegClass) -> usize {
        self.class(class).map_or(0, |info| info.regs.len())
    }

    /// Whether the file has no classes at all, which is a target that has not described one.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.classes.is_empty()
    }

    /// What one register is called.
    #[must_use]
    pub fn name(&self, class: RegClass, reg: PhysReg) -> Option<&'static str> {
        self.class(class)?.regs.get(usize::from(reg.number())).copied()
    }

    /// The register of that name, and the class it is in.
    ///
    /// The name is written without the sigil, so `rax` rather than `$rax`.
    #[must_use]
    pub fn reg_named(&self, name: &str) -> Option<(RegClass, PhysReg)> {
        for (class, info) in self.classes() {
            if let Some(number) = info.regs.iter().position(|&reg| reg == name) {
                return Some((class, PhysReg::new(number as u8)));
            }
        }
        None
    }

    /// A name this file gives to two registers, if it gives one to two.
    ///
    /// Reading a dump back needs every name to say which register it means, and a target that
    /// breaks that produces text that cannot be parsed rather than an error at the point of the
    /// mistake. So every target's own test asks this, which is why it is here and public.
    #[must_use]
    pub fn duplicate(&self) -> Option<&'static str> {
        let mut seen: Vec<&'static str> = Vec::new();
        for (_, info) in self.classes() {
            for &reg in info.regs {
                if seen.contains(&reg) {
                    return Some(reg);
                }
                seen.push(reg);
            }
        }
        None
    }
}

/// The storage an address is counted from, on a machine that has more than one.
///
/// x86 keeps a thread's own block of words at a fixed place reached through a segment register,
/// and that block is the only thing anything here uses one for. The stack protector's canary lives
/// in it, which is why `%fs:40` is an address a compiler writes and `%fs` is not a register any
/// program names. Every other address this compiler writes is in the flat segment and says nothing
/// at all, which is what `None` is.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Segment {
    /// `%fs`, which is where a thread's own block is on x86-64 under System V.
    Fs,
    /// `%gs`, which is where it is on x86-64 under Windows and inside a kernel.
    Gs,
    /// `%es`, which in long mode is the flat segment again and is only named by a file that asks
    /// for the override byte on purpose.
    Es,
    /// `%cs`, the code segment. A kernel reads a word through it to reach data kept beside its
    /// code.
    Cs,
    /// `%ss`, the stack segment.
    Ss,
    /// `%ds`, the data segment, whose override byte is also what a file writes in front of an
    /// instruction to make it longer without changing what it does.
    Ds,
}

impl Segment {
    /// The name of the register, without its sigil.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Segment::Fs => "fs",
            Segment::Gs => "gs",
            Segment::Es => "es",
            Segment::Cs => "cs",
            Segment::Ss => "ss",
            Segment::Ds => "ds",
        }
    }

    /// The segment register with that name, without its sigil.
    #[must_use]
    pub fn named(name: &str) -> Option<Segment> {
        [Segment::Es, Segment::Cs, Segment::Ss, Segment::Ds, Segment::Fs, Segment::Gs]
            .into_iter()
            .find(|segment| segment.name() == name)
    }

    /// The number an instruction that moves the register names it by, which is the order the
    /// manual lists the six in.
    #[must_use]
    pub const fn number(self) -> u8 {
        match self {
            Segment::Es => 0,
            Segment::Cs => 1,
            Segment::Ss => 2,
            Segment::Ds => 3,
            Segment::Fs => 4,
            Segment::Gs => 5,
        }
    }

    /// The byte in front of an instruction that says its address is counted from this segment.
    #[must_use]
    pub const fn prefix(self) -> u8 {
        match self {
            Segment::Es => 0x26,
            Segment::Cs => 0x2E,
            Segment::Ss => 0x36,
            Segment::Ds => 0x3E,
            Segment::Fs => 0x64,
            Segment::Gs => 0x65,
        }
    }
}

/// Where a target keeps the word a stack protector's canary is a copy of.
///
/// On the conventions here the word is in the block a thread has to itself, which is reached
/// through a segment register and no other way, so the only way to name it is a distance into that
/// block. That is why `%fs:40` appears in every protected function glibc has ever linked and why no
/// object file carries a relocation for it.
///
/// A kernel is the other kind of program, and it says where the word is on its command line. x86-64
/// Linux keeps it at `%gs:__ref_stack_chk_guard` from 6.13 on, which is a symbol read through the
/// segment, and at `%gs:40` before that. A kernel with no per CPU block keeps it in a plain global
/// named `__stack_chk_guard`, which is what `-mstack-protector-guard=global` asks for. All three
/// are this one struct with different fields set.
///
/// A convention that answers `None` is one this compiler has no protector for, and a command line
/// that asks for one on such a target is told so rather than quietly given an unprotected frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Guard {
    /// The segment the word is read through, or `None` for a word in the flat address space like
    /// any other global.
    pub segment: Option<Segment>,
    /// The symbol the word is at, or `None` for a word only a distance names.
    pub symbol: Option<&'static str>,
    /// Whether the symbol's address is read out of the global offset table first, which is what a
    /// global guard needs in code that may end up in a shared library.
    pub table: bool,
    /// How far past the symbol, or into the segment when there is no symbol, the word is.
    pub at: i32,
    /// The function called when the copy in the frame no longer matches it, which does not come
    /// back.
    pub fail: &'static str,
}

impl Guard {
    /// The word at a distance into a thread's block, which is where every C library keeps it.
    #[must_use]
    pub const fn in_segment(segment: Segment, at: i32) -> Self {
        Self { segment: Some(segment), symbol: None, table: false, at, fail: "__stack_chk_fail" }
    }
}

/// What a profiler's hook at the top of every function is called on this platform.
///
/// A profiler wants to know which function called which and how often, and the only place a
/// compiler can tell it that is the moment a function is entered. So `-pg` puts a call there, and
/// what it calls is a routine the runtime provides rather than anything the program wrote.
///
/// Two of them, because there are two conventions for the same job and they disagree about where
/// the call goes as well as what it is called. The older one runs once the frame is taken, so the
/// hook can walk back through the frame pointer, which is why it needs one. The newer one runs
/// before the prologue has done anything at all, which is what makes the return address the top
/// thing on the stack and the arguments still in the registers they arrived in, and that is what
/// lets a tracer replace the call with something else while the program runs. Linux's ftrace is
/// built on exactly that, and it is why every kernel is built with the newer one.
///
/// A convention that answers `None` is one this compiler has no hook for, and a command line that
/// asks for one on such a target is told so rather than quietly given an unprofiled program.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Trace {
    /// What is called in front of the prologue, which is what `-mfentry` asks for.
    pub early: &'static str,
    /// What is called once the frame is taken, which is what `-mno-fentry` asks for.
    pub late: &'static str,
    /// Which of the two a command line that named neither gets.
    pub fentry: bool,
}

/// What a platform calls the routine that reaches the pages of a frame before the frame is taken.
///
/// Windows is the platform this is about. A thread there is given a stack of which only a little is
/// committed, and one page below what is committed is a guard page whose whole job is to be touched:
/// the fault it raises is what tells the kernel to commit another page and move the guard down. So a
/// frame larger than a page has to be reached a page at a time or the guard is stepped over, and the
/// program gets an access violation on an address that was never going to be mapped. That is the
/// calling convention rather than a hardening flag, which is what makes this a field here and not
/// something `-fstack-clash-protection` turns on.
///
/// Every Windows toolchain calls a routine for it rather than writing the walk out, and the routine
/// is in the C runtime, so the name is the platform's. It reads the size in one register, touches
/// each page down to there, and comes back having moved nothing, which is why the caller still has
/// to take the frame afterwards.
///
/// A convention that answers `None` is one where reaching the pages is not the convention's
/// business. That is every System V target, where a stack grows by faulting anywhere below it and
/// the pages between are filled in by the kernel without being asked in order.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Chkstk {
    /// What the routine is called.
    pub name: &'static str,
    /// The register the size goes in, which is also the register it comes back in.
    pub size: PhysReg,
    /// How far right the size is shifted before it goes in, which is zero on x86-64 and four on
    /// ARM64, where the routine counts in units of sixteen bytes and the frame is taken with the
    /// register shifted back by [`crate::FrameInsts::scaled`].
    pub shift: u8,
    /// Whether the routine takes the frame itself, moving the stack pointer down by the size before
    /// it comes back. Only Microsoft's i386 one does, and a caller of that one subtracts nothing
    /// afterwards. Every other routine leaves the stack pointer where it found it.
    pub moves: bool,
}

/// Which registers a calling convention gives which job.
///
/// This is the second half of a target description and it is separate from [`RegFile`] because
/// the two do not vary together. x86-64 has one register file and two conventions over it, and
/// they disagree about nearly everything below: `rdi` is where the first argument arrives on
/// SysV and a register a callee has to preserve on Windows, and a Windows caller reserves
/// thirty two bytes below the call that a SysV caller does not.
///
/// The allocation order is here rather than on a class because it is a consequence of what a
/// call clobbers. A value that does not live across a call belongs in a register the callee is
/// free to destroy, because putting it in a preserved one costs a push and a pop in the
/// prologue of whichever function ends up owning it.
///
/// Every register named here is a register of the file the same target describes, and each list
/// is in the order the convention uses them, so the fourth integer argument is `int_args[3]` and
/// nothing has to count.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CallRegs {
    /// The ABI these registers are the register half of.
    ///
    /// The two halves of one convention: this structure says which register a value goes in and
    /// the description says what form it travels in on the way there, and a target that has one
    /// has the other. It is a link rather than a copy of the fact anybody wants, because a back end
    /// pass that writes a call to a runtime routine has to ask the same classification question a
    /// call in the program is asked and there is one place that answers it. A target's registers and
    /// a target's ABI are still chosen by two separate matches, one in [`crate::TargetInfo`] and one
    /// in `rucc_abi::abis::for_target`, and the crate's test that walks every triple asking both is
    /// what holds them together.
    pub abi: &'static AbiDescription,
    /// The class the general purpose registers named here are in.
    ///
    /// A register is a number inside its class, so a list of them says nothing about which
    /// registers they are without this. Everything else could get the class from the operand it
    /// came off, and a frame cannot, because a saved register is not an operand of anything.
    pub int_class: RegClass,
    /// The class the vector registers named here are in.
    pub sse_class: RegClass,
    /// The general purpose registers integer arguments arrive in, in order.
    pub int_args: &'static [PhysReg],
    /// The vector registers floating point arguments arrive in, in order.
    ///
    /// Whether an argument's position counts against both lists or only against its own is
    /// [`CallRegs::shared_positions`].
    pub sse_args: &'static [PhysReg],
    /// Whether an argument's position counts against both argument lists or only against its own.
    ///
    /// False on SysV, which counts each separately, so a `double` after six integers is still in
    /// `xmm0`. True on Windows, which counts one position for both, so a `double` in the third
    /// position is in `xmm2` and `r8` is skipped.
    pub shared_positions: bool,
    /// The general purpose registers an integer return value comes back in.
    pub int_returns: &'static [PhysReg],
    /// The vector registers a floating point return value comes back in.
    pub sse_returns: &'static [PhysReg],
    /// The x87 registers a `long double` comes back in, which is empty on a target whose
    /// `long double` is a `double`.
    pub x87_returns: &'static [PhysReg],
    /// The general purpose registers a call leaves alone, so a value in one survives it.
    pub int_saved: &'static [PhysReg],
    /// The vector registers a call leaves alone, which is none of them on SysV.
    pub sse_saved: &'static [PhysReg],
    /// How many bytes of each of [`CallRegs::sse_saved`] a call leaves alone, counted from the
    /// bottom, when that is not the whole register.
    ///
    /// Eight on AArch64, where a callee gives back `d8` to `d15` and not the top half of `v8` to
    /// `v15`, so a value wider than a `double` is not kept by a call in any vector register. Nothing
    /// on Windows, which gives back the whole of `xmm6` to `xmm15`, and on SysV, which gives back
    /// none of them.
    pub sse_kept: Option<u8>,
    /// The general purpose registers the allocator may hand out, in the order it prefers them.
    ///
    /// The stack pointer is never in this list, and neither is the frame pointer, which a
    /// target could allocate when nothing needs a frame and which nothing here does yet.
    pub int_order: &'static [PhysReg],
    /// The vector registers the allocator may hand out, in the order it prefers them.
    pub sse_order: &'static [PhysReg],
    /// The stack pointer.
    pub stack_pointer: PhysReg,
    /// The frame pointer, which is the register a prologue puts the old stack pointer in.
    pub frame_pointer: PhysReg,
    /// Whether the prologue points the frame pointer at the frame after taking it rather than
    /// before taking it.
    ///
    /// False everywhere but Windows, and there it is the unwind table asking rather than a
    /// preference. The record a function carries on that platform counts every slot in it from
    /// where the stack pointer ends the prologue, and it finds that place by taking a constant off
    /// the frame pointer, so a register pushed after the pointer was established is below the place
    /// the record counts from and has no row the format can write. The order that does work is the
    /// pushes, then the frame, and only then the pointer, which is what Microsoft's compiler emits
    /// and what gcc emits for this target in every function that saves anything besides the pointer
    /// itself.
    ///
    /// What it costs is the chain: the frame pointer holds a copy of the body's stack pointer
    /// rather than the address of the caller's copy of itself, so the words that used to lead from
    /// one frame to the next no longer do. Nothing on this platform walks that chain. Unwinding
    /// reads the table, there is no profiler's hook that reads the pointer, and gcc gives the chain
    /// up on the same functions for the same reason.
    pub late_frame_pointer: bool,
    /// Whether every prologue has to be one the ARM64 Windows unwind codes can describe.
    ///
    /// Those codes are one to an instruction and restore registers from wherever the stack pointer
    /// is, so two things the frame code does elsewhere have to change. A pair stored with one `stp`
    /// has to be two registers in a row, since that is the only pair a code can name, so a frame
    /// saving `x19` and `x21` saves `x20` as well. And a prologue that goes on to push registers
    /// after pointing the frame pointer at the frame record says where the frame pointer is again,
    /// with an `add x29, sp, #n` that changes nothing, when the stack pointer is about to move by
    /// an amount the codes cannot say: before the stack is aligned, and at the end of a prologue
    /// whose body grows the frame. Unwinding then starts from the frame pointer, as it has to.
    pub unwind_codes: bool,
    /// Where a variadic call says how many vector registers it passed arguments in, when the
    /// convention makes it say.
    ///
    /// SysV puts the count in `al` and a variadic callee reads it to decide whether to save the
    /// vector argument registers at all, which is what makes a call to `printf` with no
    /// floating point argument cheap.
    pub vector_count: Option<PhysReg>,
    /// How many bytes below the stack pointer a leaf function may use without moving it.
    ///
    /// A hundred and twenty eight on SysV and nothing on Windows. It is nothing in kernel code
    /// on either, because an interrupt handler runs on the interrupted stack and writes over
    /// exactly this, which is what `-mno-red-zone` is for.
    pub red_zone: u32,
    /// How many bytes a caller reserves below the call for the callee to spill its register
    /// arguments into, which is thirty two on Windows and nothing on SysV.
    pub shadow: u32,
    /// How many bytes a variadic callee takes at the very top of its own frame, directly below the
    /// arguments the caller left in memory, to home its argument registers in.
    ///
    /// Sixty four on Windows on AArch64 and nothing anywhere else. It is [`CallRegs::shadow`] with
    /// the other party paying for it: the caller reserves nothing, and the callee's prologue takes
    /// the bytes before it pushes anything, so that the x registers it writes there and the
    /// arguments above them are one run of words a `char *` walks. Microsoft's compiler and clang
    /// both lay a variadic function out this way, and the unwind record has a code for it.
    pub home: u32,
    /// What the stack pointer has to be a multiple of at the instruction that makes a call.
    ///
    /// Sixteen on every convention here, and it is a real obligation rather than a preference,
    /// because a callee is entitled to use an aligned vector store on its own frame and gets a
    /// fault rather than a wrong answer when a caller got this wrong. A command line can ask for
    /// another with `-mpreferred-stack-boundary=`, which is [`CallRegs::aligned_to`].
    pub stack_align: u32,
    /// The most alignment a function counts on finding the stack pointer at when it starts, without
    /// forcing it in its prologue. A frame that needs more than this is realigned.
    ///
    /// [`CallRegs::stack_align`] everywhere a caller is held to that, so the two say the same thing
    /// and nothing changes. i686 Windows is the exception: Windows only promises four bytes there,
    /// and a callback from a DLL Microsoft's compiler built arrives on four. It is eight rather than
    /// four because nothing on x86 faults on an eight byte value off its alignment, which costs
    /// only speed, while an aligned sixteen byte vector move off its alignment faults. So a frame
    /// with a sixteen byte spill or local is realigned with `and $-16, %esp`, which is what gcc
    /// does for mingw-w64 with SSE, and one with a `double` is not.
    pub trusted_align: u32,
    /// How many bytes the call instruction itself pushes before the callee starts running.
    ///
    /// Eight on x86-64, where the return address is on the stack, and nothing on a machine that
    /// leaves it in a register. It is what makes the stack pointer misaligned on entry by
    /// exactly one word, which every frame layout has to undo.
    pub return_address: u32,
    /// How many bytes one general purpose register takes when it is saved on the stack.
    pub word: u32,
    /// Whether every plain load already orders like an acquire and every plain store like a
    /// release, which is what total store order means.
    ///
    /// True on x86-64, where an ordered access below sequential consistency is the same `mov` as
    /// an unordered one. False on AArch64, where a plain `ldr` and `str` may be reordered with the
    /// accesses around them and an acquire or a release has an instruction of its own. Here beside
    /// the word because the same pass asks both questions about the same access.
    pub total_store_order: bool,
    /// Whether a plain load or store of a word may be at any address, as fast and as correct as
    /// an aligned one, so a copy of bytes may move them a word at a time whatever the alignment.
    ///
    /// True on x86 and on AArch64, where it holds for normal memory, which is all a copy of bytes
    /// ever touches. `-mstrict-align`, which would make it false there, is refused.
    pub unaligned: bool,
    /// The widths in bits a byte reversal is one instruction at, which the selector has a rule for.
    ///
    /// Sixteen, thirty two and sixty four on x86-64, where the two wider ones are `bswap` and the
    /// narrow one is a rotate by eight. Sixteen and thirty two on i386, where a sixty four bit value
    /// is two registers. None yet on AArch64, where `rev` and `rev16` are waiting on their rules. A
    /// reversal at any other width is built out of shifts and masks before selection.
    pub byte_swaps: &'static [u32],
    /// How far one push moves the stack pointer.
    ///
    /// The word on x86-64. Sixteen on AArch64, where the stack pointer has to stay a multiple of
    /// sixteen whenever memory is reached through it, so a push of one register leaves eight bytes
    /// of its slot unused and a push of two fills it.
    pub push: u32,
    /// The register a call leaves the return address in, or `None` on a machine whose call pushes
    /// it.
    ///
    /// A function that calls anything has to put this register away first, since the call writes
    /// over it. It goes with the frame pointer as one push, which is the pair AAPCS64 calls a frame
    /// record, and so a function that calls keeps a frame pointer on such a machine whatever the
    /// flags say. gcc does the same there.
    pub link: Option<PhysReg>,
    /// The register the address of a result returned through memory is passed in, or `None` on a
    /// convention that passes it as the first integer argument.
    ///
    /// AAPCS64 gives it `x8`, which is not an argument register, so the arguments after it still
    /// start at `x0`. SysV and Windows x64 pass it where the first argument would have gone and
    /// move the rest along by one.
    pub sret: Option<PhysReg>,
    /// The register the static chain of a GNU nested function travels in, or `None` on a
    /// convention rucc has no nested functions on.
    ///
    /// gcc passes the chain in `r10` on x86-64, and rucc keeps `r10` and `r11` back from the
    /// allocator as the scratch registers everything after allocation writes through. So the
    /// chain travels in `rax` between two functions rucc compiled, which is free at a call on
    /// SysV unless the callee is variadic, and a nested function never is. What reaches a
    /// nested function through a pointer arrives the way gcc's trampolines deliver it, in `r10`,
    /// and a two instruction stub in front of the function moves it to `rax` before anything
    /// can use `r10`.
    pub chain: Option<PhysReg>,
    /// What a `va_list` is on this convention, which is what a variadic callee builds and walks.
    ///
    /// The same answer [`crate::TargetInfo::va_list`] gives the front end, kept here as well since
    /// the walk is written after the front end is gone. It is not the same question as
    /// [`CallRegs::shared_positions`]: Apple's AArch64 counts the files apart and still has a list
    /// that is a pointer, because every argument a signature does not name goes on the stack.
    pub list: crate::VaList,
    /// What DWARF calls each register, one list per class in the order the file numbers the
    /// classes, and inside a list in the order the class numbers its registers.
    ///
    /// The two numberings are a real difference and not a formality. On x86-64 the machine puts
    /// `rcx` at one and DWARF puts `rdx` there, so a table written with the machine's numbers is
    /// well formed and describes the wrong registers, which is a backtrace with plausible
    /// nonsense in it rather than an error. Shorter than the file when the classes at the end are
    /// ones DWARF has no column for, and empty on a target nobody has written this down for yet.
    pub dwarf: &'static [&'static [u16]],
    /// The column an unwind table files the return address under.
    ///
    /// Not a register on x86-64, where it is sixteen and `rip` is not a register anything can
    /// name, and a real one on a machine that returns through a link register.
    pub dwarf_return_address: u16,
    /// Where the word a stack protector's canary is copied from lives, on a convention that has
    /// somewhere to put one.
    ///
    /// Here rather than beside the frame instructions because it is a fact about the runtime the
    /// code is linked against rather than about the machine. The two x86-64 conventions share
    /// every instruction the check is made of and disagree about this.
    pub guard: Option<Guard>,
    /// What a profiler's hook is called on this platform, on one that has one.
    ///
    /// Here for the same reason [`CallRegs::guard`] is: the names are the runtime's rather than the
    /// machine's, and the two x86-64 conventions write the same call instruction and disagree about
    /// what goes in it.
    pub trace: Option<Trace>,
    /// What this platform calls the routine a prologue reaches the pages of a large frame with, on
    /// one where reaching them is the convention.
    ///
    /// Here for the same reason the two above are, and it is the clearest case of the three: the
    /// walk itself is written out of the machine's own instructions and both x86-64 conventions
    /// have them, and what the two disagree about is whether a frame may be taken in one step at
    /// all. A prologue that leaves this out on Windows writes a function that faults on its own
    /// locals.
    pub chkstk: Option<Chkstk>,
    /// Every convention a function on this platform may be compiled for, each with its registers,
    /// and empty on a platform that has only the one.
    ///
    /// x86-64 is where this is not empty. A function written `__attribute__((ms_abi))` on Linux
    /// takes its arguments where Windows puts them and preserves what Windows preserves, and
    /// everything about it that is the platform's rather than the convention's stays Linux's: the
    /// canary is still at `%fs:40`, nothing probes a large frame and the frame pointer still goes
    /// up first. So a convention on a platform is its own set of registers and not the other
    /// platform's set, and this list is where [`CallRegs::under`] finds it. Every set on one
    /// platform carries the same list, which is what lets a function of one convention find the
    /// registers of a function of the other that it calls.
    pub conventions: Conventions,
}

/// The conventions one platform has and the registers each of them uses, which is
/// [`CallRegs::conventions`].
///
/// A list of references between statics that name each other, so the two traits a derive would
/// write are written by hand: a derived [`fmt::Debug`] would print a set of registers that holds
/// this list that holds the same set again, and never stop, and so would a derived comparison.
/// Two lists are the same when they name the same conventions and the same sets of registers,
/// which is a question about where the sets are and not about what is in them.
#[derive(Clone, Copy)]
pub struct Conventions(pub &'static [(Convention, &'static CallRegs)]);

impl Conventions {
    /// The list of a platform with one convention, which every convention but x86-64's is.
    pub const ONLY: Conventions = Conventions(&[]);
}

impl fmt::Debug for Conventions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.0.iter().map(|(convention, _)| convention)).finish()
    }
}

impl PartialEq for Conventions {
    fn eq(&self, other: &Self) -> bool {
        self.0.len() == other.0.len()
            && self.0.iter().zip(other.0).all(|((a, x), (b, y))| a == b && std::ptr::eq(*x, *y))
    }
}

impl Eq for Conventions {}

impl CallRegs {
    /// The bytes a function that returns through a hidden address takes off the stack as it
    /// returns. That is the address's slot where the ABI says the callee pops it, which is i386
    /// System V, and nothing where the caller does, which is every other ABI including i386
    /// Windows.
    pub fn return_pointer_popped(&self) -> u32 {
        match self.abi.return_pointer {
            rucc_abi::ReturnPointer::FirstArgumentPopped => self.word,
            _ => 0,
        }
    }

    /// The registers a function of that convention uses on this platform, and [`None`] for a
    /// convention the platform does not have.
    ///
    /// [`Convention::Target`] is always an answer, and it is the platform's own set rather than
    /// this one: asked of the set an `ms_abi` function on Linux uses, it gives back SysV, which is
    /// what a call from that function to an ordinary one wants. A platform with one convention
    /// has no list, and there this set is the answer.
    #[must_use]
    pub fn under(&self, convention: Convention) -> Option<&CallRegs> {
        match self.conventions.0.iter().find(|(named, _)| *named == convention) {
            Some(&(_, regs)) => Some(regs),
            None if convention == Convention::Target => Some(self),
            None => None,
        }
    }

    /// The registers as a variadic function that homes its argument registers sees them, which is
    /// the same set on every convention but Windows on AArch64.
    ///
    /// There every argument of such a function, named or not, arrived in an x register or in the
    /// caller's memory, and the function homes the x registers in the [`CallRegs::home`] bytes it
    /// takes directly below that memory. Seen from inside, that is Windows x64 with the callee paying
    /// for the shadow space: one run of positions, no vector file, and the arguments the caller left
    /// in memory starting that many bytes up from the bottom of the homed words.
    #[must_use]
    pub fn homed(&self) -> CallRegs {
        if self.home == 0 {
            return *self;
        }
        CallRegs { shadow: self.home, shared_positions: true, sse_args: &[], ..*self }
    }

    /// The same convention with the stack pointer kept on a multiple of `bytes` at every call
    /// rather than on [`CallRegs::stack_align`], which is what `-mpreferred-stack-boundary=` asks
    /// for.
    ///
    /// The answer is made once for each convention and boundary and kept, see `made`.
    ///
    /// # Panics
    ///
    /// Panics when `bytes` is not a power of two.
    #[must_use]
    pub fn aligned_to(&'static self, bytes: u32) -> &'static CallRegs {
        assert!(bytes.is_power_of_two(), "a stack boundary that is not a power of 2");
        if bytes == self.stack_align {
            return self;
        }
        // Where a function counts on what a call promises, it goes on doing so at the new boundary.
        // i686 Windows counts on less, and goes on counting on that.
        let trusted_align = if self.trusted_align == self.stack_align {
            bytes
        } else {
            self.trusted_align.min(bytes)
        };
        made(CallRegs { stack_align: bytes, trusted_align, ..*self })
    }

    /// The same convention as an x86 interrupt handler sees it, which is what a function with
    /// gcc's `interrupt` attribute is compiled against.
    ///
    /// The processor rather than a call is what arrives at one of these, and what it pushes is an
    /// interrupt frame rather than a return address. Two things about that matter to the frame
    /// laid out under it. For the exceptions that come with an error code there is one word more
    /// below the frame, which the handler takes off again before its `iretq`, so with `code` the
    /// word is counted as part of what the return address takes and every offset into the frame
    /// comes out sixteen bytes above the entry stack pointer rather than eight. And the code that
    /// was interrupted may have been using the bytes below its stack pointer when it was stopped,
    /// since nothing told it a push was coming, so there is no red zone to keep locals in.
    ///
    /// Kept the way [`CallRegs::aligned_to`] keeps its answers, see `made`.
    #[must_use]
    pub fn interrupted(&'static self, code: bool) -> &'static CallRegs {
        let return_address = self.return_address + if code { self.word } else { 0 };
        made(CallRegs { return_address, red_zone: 0, ..*self })
    }

    /// The same convention with no vector register carrying an argument, which is what a
    /// function compiled under `-mno-sse` or `-mgeneral-regs-only` sees.
    ///
    /// Nothing that would travel in one gets this far, since a function with a value of that kind
    /// in it is refused before selection. What is left for the convention to say is the register
    /// save area of a variadic function, which then holds the general purpose registers and none
    /// of the vector ones, and that is the area gcc lays out for the same flags. A variadic call
    /// says no vector register carries anything, which is true.
    ///
    /// Kept the way [`CallRegs::aligned_to`] keeps its answers, see `made`.
    #[must_use]
    pub fn without_vectors(&'static self) -> &'static CallRegs {
        if self.sse_args.is_empty() {
            return self;
        }
        made(CallRegs { sse_args: &[], ..*self })
    }

    /// The same convention with the stack protector's word somewhere else, which is what the
    /// `-mstack-protector-guard` flags ask for.
    ///
    /// Kept the way [`CallRegs::aligned_to`] keeps its answers, see `made`.
    #[must_use]
    pub fn guarded_by(&'static self, guard: Guard) -> &'static CallRegs {
        if self.guard == Some(guard) {
            return self;
        }
        made(CallRegs { guard: Some(guard), ..*self })
    }

    /// The number DWARF gives that register, or `None` for one it has no column for.
    ///
    /// The x87 stack is the case that answers `None` on x86-64, and it is not an omission: a
    /// register whose name means whichever one is on top of the stack is not one a table can have
    /// a column for. Nothing saves one across a call either, so nothing ever asks.
    #[must_use]
    pub fn dwarf(&self, class: RegClass, reg: PhysReg) -> Option<u16> {
        self.dwarf.get(usize::from(class.number()))?.get(usize::from(reg.number())).copied()
    }

    /// Which register of that class DWARF gave that number to, which is [`Self::dwarf`] the other
    /// way round, and `None` for a number no register of the class holds.
    ///
    /// What asks is a table written in the machine's own numbering rather than DWARF's, which is
    /// what Windows unwinds from. A row a prologue produces carries DWARF's number, because that is
    /// what the format two of the three platforms want is written in, and the machine's number is
    /// this register's place in its class. The two disagree over the first eight general purpose
    /// registers on x86-64 and nowhere else, which is the worst shape a disagreement can have: every
    /// number is a register either way, so the table comes out well formed and about the wrong
    /// registers.
    #[must_use]
    pub fn machine(&self, class: RegClass, dwarf: u16) -> Option<PhysReg> {
        let numbers = self.dwarf.get(usize::from(class.number()))?;
        let at = numbers.iter().position(|&number| number == dwarf)?;
        Some(PhysReg::new(u8::try_from(at).ok()?))
    }

    /// Whether a call preserves that general purpose register.
    #[must_use]
    pub fn preserves_int(&self, reg: PhysReg) -> bool {
        self.int_saved.contains(&reg)
    }

    /// Whether a call preserves that vector register.
    #[must_use]
    pub fn preserves_sse(&self, reg: PhysReg) -> bool {
        self.sse_saved.contains(&reg)
    }
}

/// Where one of the values a call passes is.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Where {
    /// In that register.
    Reg(PhysReg),
    /// That many bytes up the argument area, which is where the stack pointer points at the
    /// instruction that makes the call and is one word above the return address in the callee.
    Stack(u32),
}

/// Where the values a call passes are, worked out one after another.
///
/// [`crate::abi::Call`] answers a different question: whether a value travels in registers at all
/// and in how many, which is what decides the shape of a signature and is settled before the IR
/// for a function exists. This answers the question after it. Given values in the order the
/// signature holds them, it says which register each one is in and how far up the argument area
/// the ones that got no register are. Both count registers, and they agree about how many fit
/// because they read the same lists, but they run at opposite ends of the compiler and neither
/// can be the other.
///
/// Ask about each value in the order the signature holds them. Asking out of order answers about
/// a different signature, because where a value is depends on every value before it.
#[derive(Debug, Clone)]
pub struct Places<'a> {
    regs: &'a CallRegs,
    int: usize,
    sse: usize,
    stack: u32,
}

impl<'a> Places<'a> {
    /// Where the first value is, for a call under that convention.
    #[must_use]
    pub fn new(regs: &'a CallRegs) -> Self {
        Self { regs, int: 0, sse: 0, stack: regs.shadow }
    }

    /// Where the next value is, when it travels in a general purpose register.
    ///
    /// `bytes` is how wide the value is, which only matters once the registers have run out and
    /// only on a convention that packs the argument area, for the reason `Places::scalar` gives.
    pub fn integer(&mut self, bytes: u32) -> Where {
        match self.regs.int_args.get(self.position(false)) {
            Some(&reg) => {
                self.int += 1;
                Where::Reg(reg)
            }
            None => self.scalar(bytes),
        }
    }

    /// Where the next value is, when it travels in a vector register.
    ///
    /// `bytes` is how wide the value is, and it is asked for because of what happens once the
    /// vector registers have run out. A register holds whatever is put in it, so up to that point
    /// the width changes nothing, and the argument area is a run of words, so a `float` or a
    /// `double` that got no register takes one word wherever it starts. A `_Float128` is neither:
    /// it is sixteen bytes aligned to sixteen, so its slot is two words and begins on an even one.
    /// A slot of one word would leave the argument behind it sitting on the top half of the value,
    /// and the load that reads it back is a `movaps`, which faults on an address that is not a
    /// multiple of sixteen rather than being slow.
    pub fn float(&mut self, bytes: u32) -> Where {
        match self.regs.sse_args.get(self.position(true)) {
            Some(&reg) => {
                self.sse += 1;
                Where::Reg(reg)
            }
            None => self.scalar(bytes),
        }
    }

    /// Where a scalar that got no register is, which is its natural size and alignment on a
    /// convention that packs the argument area and a whole number of words everywhere else.
    ///
    /// Apple's AArch64 is the one that packs, so a `char` in the ninth place there takes one byte
    /// and the `short` after it starts at the second. That covers only the arguments a signature
    /// names. One it does not is a word or more wherever it goes, and the caller asks for that
    /// with [`Places::on_stack`] rather than here.
    ///
    /// It is also where an integer two registers wide goes when the pair did not fit, which is an
    /// `__int128` at sixteen bytes on a sixty four bit machine and a `long long` at a word on i386.
    pub fn scalar(&mut self, bytes: u32) -> Where {
        if self.regs.abi.stack_args == StackArgs::Packed {
            let bytes = bytes.max(1);
            let at = self.stack.next_multiple_of(bytes);
            self.stack = at.saturating_add(bytes);
            return Where::Stack(at);
        }
        // The alignment is the width, which [`Places::on_stack`] raises to a word for anything
        // narrower, so this is the natural alignment of the value and not a rule of its own. The
        // one exception is a scalar of two words, which is a `double` or a `long long` on i386,
        // and the i386 psABI puts those at the next word and not the next eight bytes. A scalar of
        // sixteen bytes keeps its own alignment everywhere, since a `movaps` reads it back.
        let align = if bytes <= 8 { bytes.min(self.regs.word) } else { bytes };
        self.on_stack(bytes, align)
    }

    /// Where the next value is, when it travels in memory whatever is left.
    ///
    /// Every argument area is a run of whole words, so a value narrower than one still takes one
    /// and a value that is not a whole number of them is rounded up. An alignment wider than a
    /// word is respected, which is what a sixteen byte aligned structure passed by value needs.
    pub fn on_stack(&mut self, size: u32, align: u32) -> Where {
        let word = self.regs.word;
        let at = self.stack.next_multiple_of(align.max(word));
        self.stack = at.saturating_add(size.max(word).next_multiple_of(word));
        Where::Stack(at)
    }

    /// Where an object a signature names and passes by value is.
    ///
    /// The same as [`Places::on_stack`] on every convention but one that packs the argument area.
    /// There the alignment is the one the ABI gave the object, which is a word for most of them,
    /// and the object takes its size rounded up to that, so a record of three `char`s is still a
    /// word and three `float`s are twelve bytes.
    pub fn object(&mut self, size: u32, align: u32) -> Where {
        if self.regs.abi.stack_args != StackArgs::Packed {
            return self.on_stack(size, align);
        }
        let align = align.max(1);
        let at = self.stack.next_multiple_of(align);
        self.stack = at.saturating_add(size.next_multiple_of(align));
        Where::Stack(at)
    }

    /// Leaves no general purpose register for the values after this one.
    ///
    /// AAPCS64 asks for it after a record of sixteen bytes or less that found too few of them
    /// left and went to memory, so an `int` after it goes to memory too rather than into the one
    /// register the record could not use.
    pub fn drain_integers(&mut self) {
        self.int = self.regs.int_args.len();
    }

    /// Leaves no vector register for the values after this one, which AAPCS64 asks for after a
    /// homogeneous floating point aggregate that found too few of them left.
    pub fn drain_floats(&mut self) {
        self.sse = self.regs.sse_args.len();
    }

    /// How many bytes of argument area the values so far need, shadow space included.
    #[must_use]
    pub fn size(&self) -> u32 {
        self.stack
    }

    /// How many general purpose argument registers the values so far took.
    ///
    /// What a variadic callee needs and nothing else does. `va_start` has to record how far into
    /// each of the two register sequences the arguments the signature names got, because the first
    /// argument it does not name is the one after them, and asking here is the only way to know
    /// that is the same count the caller worked from.
    #[must_use]
    pub fn integers(&self) -> usize {
        self.int
    }

    /// How many vector argument registers the values so far took.
    #[must_use]
    pub fn floats(&self) -> usize {
        self.sse
    }

    /// The position the next value of a kind is at.
    fn position(&self, sse: bool) -> usize {
        if self.regs.shared_positions {
            self.int + self.sse
        } else if sse {
            self.sse
        } else {
            self.int
        }
    }
}

impl fmt::Display for RegFile {
    /// The file as a dump reads it, one class to a line.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for (_, info) in self.classes() {
            writeln!(f, "class {} : i{} = {}", info.name, info.bits, info.regs.join(", "))?;
        }
        Ok(())
    }
}

/// The one copy of a convention one of the flags made, made the first time it is asked for.
///
/// Everything that reads a convention holds it for as long as the compilation, so each is made
/// once and kept. There are a handful of conventions and a handful of flags, which bounds what is
/// kept to a few dozen of these however many units are compiled.
fn made(wanted: CallRegs) -> &'static CallRegs {
    use std::sync::Mutex;

    static MADE: Mutex<Vec<&'static CallRegs>> = Mutex::new(Vec::new());

    let mut made = MADE.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
    if let Some(&regs) = made.iter().find(|&&regs| *regs == wanted) {
        return regs;
    }
    let regs: &'static CallRegs = Box::leak(Box::new(wanted));
    made.push(regs);
    regs
}

#[cfg(test)]
mod tests {
    use super::*;

    static GPR: [&str; 3] = ["rax", "rcx", "rdx"];
    static XMM: [&str; 2] = ["xmm0", "xmm1"];
    static CLASSES: [ClassInfo; 2] = [
        ClassInfo { name: "gpr", bits: 64, regs: &GPR, allocatable: true },
        ClassInfo { name: "xmm", bits: 128, regs: &XMM, allocatable: true },
    ];
    static FILE: RegFile = RegFile::new(&CLASSES);

    #[test]
    fn a_class_is_found_by_its_name() {
        let gpr = FILE.class_named("gpr").expect("the file has a gpr class");
        assert_eq!(FILE.len(gpr), 3);
        assert_eq!(FILE.class(gpr).map(|info| info.bits), Some(64));
        assert_eq!(FILE.class_named("vec"), None);
    }

    #[test]
    fn a_register_is_found_by_its_name_and_names_itself_back() {
        let (class, reg) = FILE.reg_named("xmm1").expect("the file has xmm1");
        assert_eq!(FILE.class(class).map(|info| info.name), Some("xmm"));
        assert_eq!(reg.number(), 1);
        assert_eq!(FILE.name(class, reg), Some("xmm1"));
        assert_eq!(FILE.reg_named("r15"), None);
    }

    #[test]
    fn a_number_past_the_end_of_a_class_has_no_name() {
        let gpr = FILE.class_named("gpr").expect("the file has a gpr class");
        assert_eq!(FILE.name(gpr, PhysReg::new(3)), None);
        assert_eq!(FILE.name(RegClass::new(7), PhysReg::new(0)), None);
    }

    #[test]
    fn a_file_that_names_two_registers_alike_says_so() {
        assert_eq!(FILE.duplicate(), None);
        static BOTH: [ClassInfo; 2] = [
            ClassInfo { name: "gpr", bits: 64, regs: &GPR, allocatable: true },
            ClassInfo { name: "shadow", bits: 64, regs: &GPR, allocatable: true },
        ];
        assert_eq!(RegFile::new(&BOTH).duplicate(), Some("rax"));
    }

    #[test]
    fn a_class_nothing_allocates_from_is_still_a_class_in_every_other_way() {
        static WITH_STACK: [ClassInfo; 2] = [
            ClassInfo { name: "gpr", bits: 64, regs: &GPR, allocatable: true },
            ClassInfo { name: "x87", bits: 80, regs: &XMM, allocatable: false },
        ];
        let file = RegFile::new(&WITH_STACK);
        let stack = file.class_named("x87").expect("the file has an x87 class");

        assert!(!file.allocatable(stack));
        assert!(file.allocatable(file.class_named("gpr").expect("the file has a gpr class")));

        // Everything else about it works, which is the point of describing a class the allocator
        // will not touch: the registers are counted, are named, and name themselves back.
        assert_eq!(file.len(stack), 2);
        assert_eq!(file.name(stack, PhysReg::new(1)), Some("xmm1"));
        assert_eq!(file.reg_named("xmm1"), Some((stack, PhysReg::new(1))));
    }

    #[test]
    fn a_class_the_file_does_not_have_is_not_one_to_allocate_from_either() {
        assert!(!FILE.allocatable(RegClass::new(7)));
    }

    #[test]
    fn the_file_prints_one_class_to_a_line() {
        assert_eq!(
            FILE.to_string(),
            "class gpr : i64 = rax, rcx, rdx\nclass xmm : i128 = xmm0, xmm1\n"
        );
    }

    /// Two integer registers, two vector registers and nothing else, so running out of them takes
    /// three arguments rather than seven and the interesting case is the one being tested.
    fn convention(shared: bool, shadow: u32) -> CallRegs {
        static INT: [PhysReg; 2] = [PhysReg::new(0), PhysReg::new(1)];
        static SSE: [PhysReg; 2] = [PhysReg::new(10), PhysReg::new(11)];
        static NONE: [PhysReg; 0] = [];
        // The registers are invented and the description is not, so it is picked by the one flag
        // the two real conventions disagree about, which is the flag these tests vary.
        let abi: &'static AbiDescription =
            if shared { &rucc_abi::abis::WIN64 } else { &rucc_abi::abis::SYSV_AMD64 };
        CallRegs {
            abi,
            int_class: RegClass::new(0),
            sse_class: RegClass::new(1),
            int_args: &INT,
            sse_args: &SSE,
            shared_positions: shared,
            int_returns: &INT,
            sse_returns: &SSE,
            x87_returns: &NONE,
            int_saved: &NONE,
            sse_saved: &NONE,
            sse_kept: None,
            int_order: &INT,
            sse_order: &SSE,
            stack_pointer: PhysReg::new(4),
            frame_pointer: PhysReg::new(5),
            late_frame_pointer: false,
            unwind_codes: false,
            vector_count: None,
            red_zone: 0,
            shadow,
            home: 0,
            stack_align: 16,
            trusted_align: 16,
            return_address: 8,
            word: 8,
            total_store_order: true,
            unaligned: true,
            byte_swaps: &[16, 32, 64],
            push: 8,
            link: None,
            sret: None,
            chain: None,
            list: if shared { crate::VaList::CharPointer } else { crate::VaList::SysV },
            // Empty, which is all a convention made up for a test of argument placement needs to
            // say about a question it never asks.
            dwarf: &[],
            dwarf_return_address: 16,
            guard: None,
            trace: None,
            chkstk: None,
            conventions: Conventions::ONLY,
        }
    }

    #[test]
    fn counting_each_kind_separately_leaves_the_first_vector_register_to_the_first_float() {
        let regs = convention(false, 0);
        let mut places = Places::new(&regs);
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(0)));
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(1)));
        // Two integers went past, and a convention that counts separately has not spent a vector
        // register on either of them.
        assert_eq!(places.float(8), Where::Reg(PhysReg::new(10)));
        assert_eq!(places.size(), 0);
    }

    #[test]
    fn counting_one_position_for_both_skips_the_register_the_other_kind_would_have_used() {
        let regs = convention(true, 0);
        let mut places = Places::new(&regs);
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(0)));
        // The second position, so the second vector register, and the second integer register is
        // spent whether anything is in it or not.
        assert_eq!(places.float(8), Where::Reg(PhysReg::new(11)));
        assert_eq!(places.integer(8), Where::Stack(0));
    }

    #[test]
    fn running_out_of_one_kind_of_register_does_not_touch_the_other() {
        let regs = convention(false, 0);
        let mut places = Places::new(&regs);
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(0)));
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(1)));
        assert_eq!(places.integer(8), Where::Stack(0));
        assert_eq!(places.float(8), Where::Reg(PhysReg::new(10)));
        assert_eq!(places.size(), 8);
    }

    #[test]
    fn the_argument_area_starts_above_the_shadow_space_and_keeps_every_value_aligned() {
        let regs = convention(false, 32);
        let mut places = Places::new(&regs);
        // A Windows caller reserves this whether it passes anything on the stack or not, which is
        // why an empty area is thirty two bytes rather than none.
        assert_eq!(places.size(), 32);
        assert_eq!(places.on_stack(4, 4), Where::Stack(32));
        // Sixteen byte alignment skips the word at 40, which is what a vector or an over-aligned
        // structure passed by value asks for. The four byte value before it still took a whole
        // word, which is why the skipped word is there to skip.
        assert_eq!(places.on_stack(16, 16), Where::Stack(48));
        assert_eq!(places.on_stack(8, 8), Where::Stack(64));
        assert_eq!(places.size(), 72);
    }

    #[test]
    fn a_float_wider_than_a_word_takes_two_of_them_once_the_registers_are_gone() {
        let regs = convention(false, 0);
        let mut places = Places::new(&regs);
        assert_eq!(places.float(16), Where::Reg(PhysReg::new(10)));
        assert_eq!(places.float(16), Where::Reg(PhysReg::new(11)));
        // The vector registers are gone, and so are the two general purpose ones, so the rest of
        // this is in the area. The word the integer took is not where the first quad starts,
        // because sixteen bytes aligned to sixteen skips the odd word above it, and the second
        // quad is sixteen bytes above the first rather than eight.
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(0)));
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(1)));
        assert_eq!(places.integer(8), Where::Stack(0));
        assert_eq!(places.float(16), Where::Stack(16));
        assert_eq!(places.float(16), Where::Stack(32));
        assert_eq!(places.size(), 48);
        // A float narrower than a word still takes one, which is what it took before any of this.
        assert_eq!(places.float(4), Where::Stack(48));
        assert_eq!(places.size(), 56);
    }

    #[test]
    fn apple_packs_the_arguments_that_got_no_register_at_their_own_size() {
        let mut regs = convention(false, 0);
        regs.abi = &rucc_abi::abis::DARWIN_ARM64;
        let mut places = Places::new(&regs);
        assert_eq!(places.integer(4), Where::Reg(PhysReg::new(0)));
        assert_eq!(places.integer(4), Where::Reg(PhysReg::new(1)));
        // A byte, a short and an int, each on its own alignment and nothing more, so the short
        // skips the one byte after the char.
        assert_eq!(places.integer(1), Where::Stack(0));
        assert_eq!(places.integer(2), Where::Stack(2));
        assert_eq!(places.integer(4), Where::Stack(4));
        assert_eq!(places.float(8), Where::Reg(PhysReg::new(10)));
        assert_eq!(places.float(4), Where::Reg(PhysReg::new(11)));
        // The float goes straight after the int, and the long after it skips four bytes to get to
        // its own alignment.
        assert_eq!(places.float(4), Where::Stack(8));
        assert_eq!(places.integer(8), Where::Stack(16));
        assert_eq!(places.size(), 24);
        // An object keeps the alignment it was given and takes its size up to it.
        assert_eq!(places.object(12, 4), Where::Stack(24));
        assert_eq!(places.object(3, 8), Where::Stack(40));
        assert_eq!(places.size(), 48);
        // Anything asked for as bytes is still a word or more, which is what an unnamed argument
        // is there.
        assert_eq!(places.on_stack(1, 1), Where::Stack(48));
        assert_eq!(places.size(), 56);
    }

    #[test]
    fn draining_one_kind_of_register_sends_the_rest_of_that_kind_to_memory_and_no_other() {
        let regs = convention(false, 0);
        let mut places = Places::new(&regs);
        assert_eq!(places.float(4), Where::Reg(PhysReg::new(10)));
        places.drain_floats();
        // The second vector register is still free and nothing may have it.
        assert_eq!(places.float(4), Where::Stack(0));
        assert_eq!(places.integer(8), Where::Reg(PhysReg::new(0)));
        places.drain_integers();
        assert_eq!(places.integer(8), Where::Stack(8));
        assert_eq!((places.integers(), places.floats()), (2, 2));
    }
}