rucc_codegen/

abi.rs

//! Where a function's arguments already are when it starts running, and where a call puts its own.
//!
//! Design: `spec/12-abi-and-runtime.md`.
//!
//! This is the one part of the calling convention that is not a lowering rule, and it is worth
//! saying why, because everything else in this crate is. A rule matches a term and rewrites it,
//! and which register the third argument arrives in is not a fact about any term: it depends on
//! the argument's position and on the classification of every argument before it. A pattern has
//! nowhere to put that. So the arguments are built here, by hand, out of what the convention
//! says, the same way [`crate::finish`] builds a prologue.
//!
//! The classification itself is not here either. `rucc-lower` has already run it by the time a
//! function reaches this crate, which is why the parameters read here are nearly all plain
//! scalars: an aggregate has been split into the pieces it travels in, and a return through memory
//! is an ordinary pointer parameter in front of the rest. What is left for this is the step after
//! classification, from how a value travels to which register it is actually in, which is
//! [`rucc_target::Places`].
//!
//! The one parameter that is not a scalar is an aggregate the classification put in the argument
//! area whole, which is [`rucc_ir::Abi::ByVal`]. The IR calls it a pointer, because a pointer is
//! what an instruction reading it has to have, and the convention says the bytes travel and the
//! pointer does not. So this is the one place that reads what the classification said rather than
//! only the type, on both sides of the call, and the two sides are the two halves of one copy.
//!
//! # What it writes
//!
//! One `x64.arg_val_*` per parameter that arrived in a register, at the top of the entry block,
//! each defining a fresh register constrained to the one the argument arrived in. They encode to
//! nothing. The point of them is that a parameter has to be defined somewhere for the allocator to
//! have anything to move, and the entry block cannot define it as a block parameter: there is no
//! edge into the entry block for the move to go on, which is what `rucc_regalloc::rewrite` asserts.
//!
//! What the allocator does with them is the whole of the argument sequence. A parameter that is
//! read where it arrived costs nothing, and one that is not gets a copy, which is the same
//! bargain the return already makes and is decided by the same code.
//!
//! A parameter whose bytes travelled is the exception to all of that. Its bytes are already in
//! this function, at a place in the caller's argument area the same walk gives, so nothing is
//! brought in at all: what the parameter is is where they are, and that is one `lea`. It waits on
//! the frame the way the loads below it do, and for the same reason.
//!
//! A parameter past the last register arrived in the caller's memory rather than in a register, so
//! it is a load and not a pseudo, and it is a real instruction that encodes to real bytes. How far
//! up the caller's argument area it is is a number [`rucc_target::Places`] answers here, but where
//! that area is from inside this function is a distance into a frame, and no frame exists until
//! after allocation. So the load is written with nothing in its displacement, which of the two
//! registers it reads through is left to be settled too, and both are filled in by [`crate::finish`]
//! out of [`crate::frame::Frame::incoming`]. That is the same bargain an `alloca` already makes,
//! for the same reason and in the same two places.
//!
//! # A call
//!
//! The same reasoning the other way round, and one instruction rather than several. `x64.call`
//! and `x64.call_reg` are the only opcodes in the description whose operand vector is empty
//! there, because nothing about a call's operands is the same from one call to the next, so they
//! are built here: one read per argument constrained to the register the convention passes it in,
//! one definition for the value that comes back constrained to the register it comes back in, and
//! one definition per register the convention does not preserve.
//!
//! A call through an address has one operand more, which is the address, and it is the one
//! operand of a call that is a fact about the instruction rather than about the signature. It
//! goes in front of the arguments, because the assembler has to find it and an index into a
//! vector whose length depends on the convention is not a way of finding anything.
//!
//! Those last ones are the clobbers, and they are the whole of what the allocator has to know
//! about a call besides where the values go. Each is a definition of the physical register itself
//! rather than of a value, since there is no value: it says the register is written here, which
//! is exactly what stops the allocator from leaving something in one across the call. A register
//! an argument or the result already names is not repeated, because naming it once already blocks
//! it for the length of the instruction, which is all a clobber does.
//!
//! An argument past the last register the convention has for it is a store into the outgoing area
//! rather than an operand of the call, written in front of the call in the same block. Where that
//! area is does not have to wait for the frame the way the incoming one does, because the outgoing
//! area is at the bottom of the frame and the bottom of the frame is where the stack pointer is:
//! that is the whole reason the frame puts it there, since it is where the callee will look. So the
//! offset [`rucc_target::Places`] gives back is the offset the store is written with.
//!
//! An object passed by value in memory is the same thing again and a copy rather than a store. The
//! caller owes the callee a copy it is free to write to, which is what makes a C call by value
//! different from passing a pointer the callee must not keep, and the argument area is where the
//! convention says that copy goes. So the bytes are read out of the object and written into the
//! area a word at a time, in front of the call, with the words chosen by the same function that
//! chooses them for a `memcpy`. An object with more words than that unrolls to is copied by a call
//! to the runtime's `memcpy` instead, written in front of the outer call in the same block.
//!
//! That is one call built in the middle of building another, which sounds worse than it is.
//! Nothing of the outer call is in a physical register when the copy is written: every argument
//! that travels in one is still a virtual register, and the register it has to end up in is a
//! constraint on an operand of the call instruction, which is not built until every copy in front
//! of it has been. So what the inner call destroys is what any call destroys, and the allocator
//! keeps the outer call's values out of those registers the same way it does across a call the
//! program wrote. The arguments already stored into the outgoing area are safe for a plainer
//! reason: the inner call's own frame is below the stack pointer and that area is above it.
//!
//! The call still reports how many bytes it needed, because the frame reserves as many as the
//! widest call in the function asked for and cannot know that until every call has been seen.

use rucc_base::{Interner, Symbol};
use rucc_diag::Span;
use rucc_ir::{Abi, Drains, Param, Type};
use rucc_mir as mir;
use rucc_target::{CallRegs, Constraint, PhysReg, Places, RegClass, Variadic, Where};

use crate::capability;
use crate::varargs::Area;

pub mod aarch64;

/// Why a parameter could not be brought in.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Missing {
    /// It travels on the x87 stack, which is a `long double` and nothing else. That stack is a
    /// third register file, it is not one the allocator has, and no instruction in the
    /// description touches it.
    OnX87,
    /// It is a width no pseudo covers, which is anything a machine register does not hold.
    Width,
    /// It is a value that comes back in more registers than the convention returns in. A structure
    /// of at most sixteen bytes comes back in up to two, which is as many as SysV has, and a
    /// convention with fewer of them returns such a structure through a hidden pointer instead. So
    /// this is what a signature the classification did not produce would get.
    NoRoom,
    /// It is an object whose bytes travel in the argument area and there are more of them than
    /// any count of them can be written down as. A copy too long to unroll is a call to the
    /// runtime and not a refusal, so what is left here is an object of two gigabytes or more,
    /// which is a size the immediate holding the byte count has nowhere to put and a structure no
    /// program passes.
    TooBig,
}

impl Missing {
    /// What it says when a function could not be compiled because of it.
    ///
    /// Worded so that it reads the same about a value arriving and a value being passed, since
    /// the two are the same fact seen from the two ends of one call.
    #[must_use]
    pub fn why(self) -> &'static str {
        match self {
            Missing::OnX87 => "is on the x87 stack",
            Missing::Width => "is a width no argument register holds",
            Missing::NoRoom => "takes more registers than this convention has for it",
            Missing::TooBig => "is more bytes than a count of them can be written down as",
        }
    }
}

/// Which register file a value of that type travels in.
///
/// The whole of what the two files mean to this module. A float is in the vector one and
/// everything else is in the general purpose one, which is what both of this machine's conventions
/// say. A `long double` is in neither and what its register holds is an address, which is a general
/// purpose value like every other address, so it answers with the other file rather than with the
/// one its type would suggest.
fn class_of(ty: Type, conv: &CallRegs) -> RegClass {
    if ty.is_float() && !on_the_stack(ty) { conv.sse_class } else { conv.int_class }
}

/// How many bytes of the argument area a value in the vector file takes.
///
/// Its own width, lanes included, which is what [`Places::float`] wants and is a number that only
/// matters to a value the registers ran out before. Everything the machine computes in is a word
/// or narrower and takes a word either way. The `_Float128` is the one that is not: two words, and
/// aligned to two words, which is the difference between the argument behind it being placed after
/// it and being placed on top of half of it.
pub(crate) fn float_bytes(ty: Type) -> u32 {
    ty.bits().div_ceil(8).saturating_mul(ty.lanes())
}

/// Spends the registers an object in the argument area said nothing after it may have.
pub(crate) fn drain(places: &mut Places<'_>, drains: Drains) {
    match drains {
        Drains::Nothing => {}
        Drains::Integers => places.drain_integers(),
        Drains::Floats => places.drain_floats(),
    }
}

/// How many bytes of the argument area a value in the general purpose file takes.
///
/// Its own width, which only a convention that packs the argument area reads, since everywhere
/// else anything this narrow takes a word. A pointer has no width of its own in the IR, so it is
/// the word.
pub(crate) fn int_bytes(ty: Type, conv: &CallRegs) -> u32 {
    if ty.is_ptr() { conv.word } else { ty.bits().saturating_mul(ty.lanes()).div_ceil(8).max(1) }
}

/// Whether a value of that type travels as bytes in the argument area because of what it is.
///
/// One type does, and it is the `long double`. SysV classifies it X87 and X87UP, which is the
/// classification that means memory, so it goes where a structure the classification put in memory
/// goes and what the two ends pass is the address of the bytes. That is not a decision about
/// registers running out: a `long double` travels in the argument area when it is the only argument
/// there is.
///
/// Sixteen bytes aligned to sixteen, which is what the psABI says the type takes and is the same
/// number [`crate::lower`] gives one in the frame, so a value being passed and a value being worked
/// on are the same shape of object in two places.
#[must_use]
pub fn on_the_stack(ty: Type) -> bool {
    ty.is_float() && ty.is_scalar() && ty.bits() == 80
}

/// Whether what a function gives back is left on the x87 stack, which is one `long double` in
/// `st(0)` or a `_Complex long double` with its real half there and its imaginary half in `st(1)`.
///
/// Those two are the whole of what SysV returns on that stack, and a structure holding a `long
/// double` is not one of them, since the lowering sends that back through memory.
#[must_use]
pub fn back_on_x87(returns: &[Type]) -> bool {
    matches!(returns.len(), 1 | 2) && returns.iter().all(|&ty| on_the_stack(ty))
}

/// How much room one takes in the argument area, as a size and an alignment.
pub(crate) const X87_AREA: (u32, u32) = (16, 16);

/// Why a value of that type cannot travel at all, or nothing if it can.
///
/// The width question and the file question in one place, so that the two ends of a call give the
/// same answer about the same type, and so that a `return` this cannot make says the same thing
/// about a type as the call that would have received it.
///
/// A `long double` is not one of them any more when it is an argument, since an argument of that
/// type travels as bytes and [`on_the_stack`] is what says so before this is asked. What is left
/// here is the value that comes back, because coming back is the one direction where it is not
/// bytes: it arrives in `st(0)`, which is a register file this cannot name.
#[must_use]
pub fn refuses(ty: Type, insts: &Insts) -> Option<Missing> {
    if (insts.arg)(ty).is_some() {
        return None;
    }
    // A `long double` is the one type here that is in neither of the two files. Saying so is worth
    // more than calling it a width, because eighty bits is a width this machine computes in and
    // the file it computes in is what actually stands in the way.
    if on_the_stack(ty) {
        return Some(Missing::OnX87);
    }
    Some(Missing::Width)
}

/// What a function's parameters came to.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct Arrived {
    /// The register each parameter is in, in the order the parameters were given, so the caller can
    /// bind each IR parameter to the one at its position.
    pub regs: Vec<mir::Reg>,
    /// The loads that read a parameter out of the caller's argument area, and how far up that area
    /// each of them reads.
    ///
    /// Empty for almost every function, because almost every function has few enough parameters to
    /// have been handed all of them in registers. The distance is from the bottom of the caller's
    /// argument area, which is somewhere [`crate::finish`] works out and this cannot.
    pub stack: Vec<(mir::Inst, u32)>,
    /// How many general purpose argument registers the parameters took, and how many vector ones.
    ///
    /// Nothing about an ordinary function needs this. A variadic one does: the first argument its
    /// signature does not name is the one after the last it does, so where each of the two walks
    /// stopped is where `va_start` has to say the next argument begins.
    pub took: (usize, usize),
    /// How far up the caller's argument area the first argument the signature does not name is.
    ///
    /// However much of that area the named parameters took, on a convention that counts the two
    /// register files apart, because there the area holds only the arguments no register was left
    /// for. On one that counts them as one run it is not the same number: that area begins with the
    /// shadow space the caller reserved, every argument owns one word of it whether it also arrived
    /// in a register or not, and the named ones own the first few of those words. So it is where
    /// the walk over the registers stopped, which is a position rather than a size, until the named
    /// parameters have used every register and the two agree again.
    pub beyond: u32,
    /// The argument registers left over for the arguments the signature does not name, as the
    /// register each was bound into and how far up the save area its slot is.
    ///
    /// Empty unless a save area was asked for. The ones a named parameter took are not here,
    /// because their slots are behind where `va_start` sets the two offsets and nothing ever reads
    /// them, so writing them would be fourteen stores where six are wanted.
    pub spare: Vec<(mir::Reg, RegClass, u32)>,
}

/// Binds a function's parameters to where the convention says they arrive.
///
/// # Errors
///
/// The first parameter this cannot bring in, and why. A function with one is reported rather
/// than compiled, because the alternative is a function that reads an argument from wherever the
/// last one happened to leave a register.
pub fn entry(
    out: &mut mir::Func,
    block: mir::Block,
    params: &[Param],
    conv: &CallRegs,
    insts: &Insts,
    names: &mut Interner,
    save: Option<Area>,
) -> Result<Arrived, (usize, Missing)> {
    // Where everything is, worked out before anything is written, both so that a parameter this
    // cannot bring in stops the function before half of one is built and so that the two loops
    // below can be two loops. Asking for the place of a parameter that cannot be brought in is
    // still done, because every place after it depends on it and a reader stepping through this
    // should see the same numbers a working version would.
    let mut places = Places::new(conv);
    let mut where_from = Vec::with_capacity(params.len());
    for (index, &Param { ty, abi }) in params.iter().enumerate() {
        // A structure the classification put in the argument area arrived as bytes, and the
        // parameter the IR sees is a pointer to them. So there is nothing to bring in: the bytes
        // are already in this function's frame, and what the pointer holds is where they are.
        if let Abi::ByVal { size, align, drains } = abi {
            let size = u32::try_from(size).map_err(|_| (index, Missing::TooBig))?;
            where_from.push((ty, places.object(size, align), abi));
            drain(&mut places, drains);
            continue;
        }
        // And an eighty bit float, which arrives the same way for the same reason and is told
        // apart only by the classification having said nothing about it: the front end passes it
        // as a value of its own type, and it is this that knows the type is one that travels as
        // bytes. What arrives is the address of those bytes, which is what an object in the
        // argument area always hands over.
        if on_the_stack(ty) {
            let (size, align) = X87_AREA;
            where_from.push((
                ty,
                places.on_stack(size, align),
                Abi::ByVal { size: size.into(), align, drains: Drains::Nothing },
            ));
            continue;
        }
        let at = match (abi, conv.sret) {
            // The address a result goes back through, on a convention with a register of its own
            // for it, which takes no position from the arguments after it.
            (Abi::Sret { .. }, Some(sret)) => Where::Reg(sret),
            _ if ty.is_float() => places.float(float_bytes(ty)),
            _ => places.integer(int_bytes(ty, conv)),
        };
        if let Some(missing) = refuses(ty, insts) {
            return Err((index, missing));
        }
        where_from.push((ty, at, abi));
    }
    let took = (places.integers(), places.floats());
    // Where the first argument the signature does not name is, which is the two sentences on
    // [`Arrived::beyond`] written out. The run of words is contiguous from the bottom of the area on
    // a convention that homes its register arguments, so a position multiplied by a word is the
    // answer there until the positions run out and the named parameters start taking room of their
    // own, at which point what they took is the answer again.
    let reached = took.0 + took.1;
    let beyond = match conv.shared_positions && reached < conv.int_args.len() {
        true => conv.word * u32::try_from(reached).unwrap_or(0),
        false => places.size(),
    };
    let mut arrived =
        Arrived { regs: Vec::with_capacity(params.len()), took, beyond, ..Arrived::default() };

    // Every pseudo first and everything else after, which is not a preference. A pseudo says a
    // register holds an argument and defines nothing before it, so as far as the allocator can see
    // the register was dead until then and is free to be used as a scratch. That is true of a
    // register no pseudo has named yet, and it stops being true the moment one does. Anything that
    // needs a scratch has to come after all of them, and a load out of the caller's stack needs one
    // for the value it loads.
    for (index, &(ty, at, _)) in where_from.iter().enumerate() {
        let class = class_of(ty, conv);
        let reg = out.new_vreg(class);
        arrived.regs.push(reg);
        let Where::Reg(arrived_in) = at else { continue };
        let head = (insts.arg)(ty).ok_or((index, Missing::Width))?;
        let opcode = mir::Opcode::new(names.intern(head));
        let operand = mir::Operand::write(reg, class).with(Constraint::Fixed(arrived_in));
        out.build(block, opcode).operand(operand).finish();
    }
    if let Some(area) = save {
        arrived.spare = spare(out, block, conv, insts, names, area, arrived.took);
    }

    // The stack pointer is written down as the register to read through because it is the one that
    // reaches the caller's stack in almost every function, and a realigned frame is the exception
    // that [`crate::finish`] rewrites. Putting something here rather than nothing keeps the
    // instruction printable and verifiable in between.
    for (index, &(ty, at, abi)) in where_from.iter().enumerate() {
        let Where::Stack(up) = at else { continue };
        let class = class_of(ty, conv);
        // The bytes of an object that travelled as bytes are read by whatever reads the parameter,
        // and what the parameter is is their address, so this takes the address rather than a
        // value out of it. Everything else about it is the load's, including the two fields
        // [`crate::finish`] fills in, because where the caller's argument area is is the same
        // question for both.
        let name = match abi {
            Abi::ByVal { .. } => insts.lea,
            _ => (insts.load)(ty).ok_or((index, Missing::Width))?,
        };
        let opcode = mir::Opcode::new(names.intern(name));
        let sp = mir::Operand::read(mir::Reg::physical(conv.stack_pointer), conv.int_class);
        let made =
            out.build(block, opcode).def(arrived.regs[index], class).mem(mir::Mem::at(sp)).finish();
        arrived.stack.push((made, up));
    }
    Ok(arrived)
}

/// Binds the argument registers no parameter the signature names took, which are the ones the
/// arguments it does not name arrived in.
///
/// One pseudo each and nothing else, for the reason the loop above them gives: what these do is say
/// the register holds something, and the stores that put it in the save area are written by
/// [`crate::lower`] once it has an address to store to, which is after every pseudo in the block.
///
/// Where each file's walk stopped is the file's own count on a convention that keeps two, and the
/// sum of both on one that counts the files as a single run of positions, since there an argument
/// of either kind steps the one counter. A file the area holds no slots of is skipped entirely,
/// which is the vector file on the second kind: a variadic float travels in the general purpose
/// register at its position as well, so the copy the walk reads is already the one being spilled.
fn spare(
    out: &mut mir::Func,
    block: mir::Block,
    conv: &CallRegs,
    insts: &Insts,
    names: &mut Interner,
    area: Area,
    took: (usize, usize),
) -> Vec<(mir::Reg, RegClass, u32)> {
    let word = Type::int(64);
    let double = Type::float(rucc_ir::Float::F64);
    let reached = |own: usize| if conv.shared_positions { took.0 + took.1 } else { own };
    let files = [
        (conv.int_args, reached(took.0), word, false),
        (conv.sse_args, reached(took.1), double, true),
    ];
    let mut spare = Vec::new();
    for (regs, taken, ty, float) in files {
        let held = usize::try_from(area.holds(float)).unwrap_or(0);
        let Some(head) = (insts.arg)(ty) else { continue };
        let class = class_of(ty, conv);
        for (index, &arrived_in) in regs.iter().enumerate().take(held).skip(taken) {
            let reg = out.new_vreg(class);
            let opcode = mir::Opcode::new(names.intern(head));
            let operand = mir::Operand::write(reg, class).with(Constraint::Fixed(arrived_in));
            out.build(block, opcode).operand(operand).finish();
            let at = area.starts_at(float) + area.stride(float) * u32::try_from(index).unwrap_or(0);
            spare.push((reg, class, at));
        }
    }
    spare
}

/// The instructions this file writes, for one machine.
///
/// Every one of them is written here by hand rather than by a rule, for the reasons the module
/// comment gives, so this file is where a machine's names for them have to come from. Each answer
/// is the whole name, prefix and all, because each is interned as it is.
///
/// The four functions answer for the same set of types, and a type one of them has no name for is
/// a type none of them should have: an argument that can arrive in a register but not be read off
/// the stack is a function turned away for where its sixth argument happened to land.
#[derive(Debug)]
pub struct Insts {
    /// The pseudo a parameter of that type arrives in a register as. See [`head_of`].
    pub arg: fn(Type) -> Option<&'static str>,
    /// The load that reads one of that type out of the argument area. See [`load_of`].
    pub load: fn(Type) -> Option<&'static str>,
    /// The store that writes one of that type into the argument area. See [`store_of`].
    pub store: fn(Type) -> Option<&'static str>,
    /// The pseudo a value of that type leaves in the register at that place. See [`ret_of`].
    pub ret: fn(Type, usize) -> Option<&'static str>,
    /// The call of a name. See [`CALL`].
    pub call: &'static str,
    /// The call of an address in a register. See [`CALL_REG`].
    pub call_reg: &'static str,
    /// The instruction that puts an address in a register without reading what is at it.
    pub lea: &'static str,
    /// The instruction that writes a small constant into a general purpose register, which is
    /// what a byte count and a SysV vector count are.
    pub small: &'static str,
}

/// The x86-64 ones.
pub static X86_64: Insts = Insts {
    arg: head_of,
    load: load_of,
    store: store_of,
    ret: ret_of,
    call: CALL,
    call_reg: CALL_REG,
    lea: "x64.lea_64",
    small: "x64.mov_ri_32",
};

/// What the instruction that calls a name is called.
///
/// Here rather than in a rule for the same reason the arguments are: a rule pattern sees one term
/// and a call's operands are whatever the signature made them, so no pattern could name them.
pub const CALL: &str = "x64.call";

/// What the instruction that calls an address in a register is called.
///
/// A different instruction rather than the same one with a different operand, which is what the
/// machine says too: one carries the distance to somewhere in the program and takes a relocation,
/// and the other carries the register the address is in and takes none. Sharing an opcode would
/// mean an instruction whose bytes depend on whether a field beside it happens to be set.
pub const CALL_REG: &str = "x64.call_reg";

/// One value a call passes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Passing {
    /// The type it travels as, which for an object travelling as bytes is the pointer's rather
    /// than the object's, because the pointer is what the machine IR has.
    pub ty: Type,
    /// The register holding it, or holding its address when the bytes are what travel.
    pub reg: mir::Reg,
    /// What the classification asked of it. The one thing read here is whether the object behind
    /// the pointer is the argument, since everything else it can say is about a value that is
    /// already in a register in the form it travels in.
    pub abi: Abi,
}

/// What one call came to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Made {
    /// The registers the value came back in, in the order the signature returns them, which is
    /// empty for a call that gives nothing back and holds two for a structure that comes back in a
    /// pair. Which register each of them is is the classification's answer and is worked out here
    /// rather than in a table, for the reason the second half of [`Calling::returns`] gives.
    pub results: Vec<mir::Reg>,
    /// How many bytes below the stack pointer this call needs for the arguments it passes there.
    ///
    /// Not always zero for a call that passes everything in registers: a Windows caller reserves
    /// thirty two bytes for the callee to spill its register arguments into whether it uses them
    /// or not, and that reservation is this.
    pub outgoing: u32,
}

/// Which of a call's values could not be passed, and why.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Refused {
    /// Its position among the arguments, or `None` for the value that comes back.
    pub argument: Option<usize>,
    /// What is wrong with where it travels.
    pub missing: Missing,
}

/// What a call goes to.
///
/// The whole of the difference between the two calls. Everything else about them, which is what
/// they pass and what comes back and which registers they destroy, is the signature's answer and
/// is the same answer either way.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Callee {
    /// A name, which the linker resolves.
    Named(Symbol),
    /// An address in a register, which nothing resolves because there is nothing to resolve: the
    /// value is not known until the program runs.
    ///
    /// The register is unconstrained, and it has to be, because every register the convention
    /// does not preserve is one this instruction writes and every register an argument travels in
    /// is spoken for. What is left is the registers the callee has to put back, which is where
    /// the allocator will put the address, and it is the right answer for the same reason it is
    /// the only one.
    Through(mir::Reg),
}

/// One call, as everything about it that is not the function it is being built into.
#[derive(Debug, Clone, Copy)]
pub struct Calling<'a> {
    /// What it calls.
    pub callee: Callee,
    /// What it passes, in the order the signature holds them, which is the order the convention
    /// places them in.
    pub args: &'a [Passing],
    /// What comes back, which is empty for a call that gives nothing back, one type for a value,
    /// and two for a structure small enough to come back in a pair of registers.
    ///
    /// A pair is placed here rather than named by a rule for the reason the arguments are: which
    /// register each half goes in depends on the halves before it, since the two files are walked
    /// separately, and a pattern over a term cannot see them.
    pub returns: &'a [Type],
    /// Whether the callee takes arguments beyond the ones its signature names, which is what says
    /// whether it reads the count of vector registers the call passed arguments in.
    pub variadic: bool,
    /// How many of the arguments the signature does name, so that the ones past it can be told
    /// apart from the ones before it.
    ///
    /// A convention that passes a variadic float in both register files needs that, because which
    /// arguments get the second copy is exactly the ones the callee has no prototype for. Every
    /// other convention treats the two the same and never asks.
    pub named: usize,
    /// Where the call was written, which every instruction built for it is filed under.
    ///
    /// A call is one of the few places in the machine IR where a run of instructions comes from no
    /// term in the IR at all: the stores into the outgoing area, the copies a structure passed by
    /// value is made of and the call itself are the convention's answer rather than anything a rule
    /// matched. So there is nothing for them to inherit a span from, and without this the bytes of
    /// an entire call statement are covered by whichever row came before them, which is usually the
    /// line above. gcc names the line the call is written on over all of it.
    ///
    /// [`Span::DUMMY`] in a call this crate builds for itself, which is the copy into the argument
    /// area that the runtime does, since that one is under whatever the call it belongs to is under.
    pub at: Span,
}

/// Builds one call: what it passes, what comes back, and what it destroys.
///
/// # Errors
///
/// The first value this cannot pass, and why, before anything is written. A call with one is
/// reported rather than compiled, because the alternative is a call that leaves an argument
/// wherever the last one happened to put a register.
///
/// # Panics
///
/// If a call passes two gigabytes of arguments on the stack, which is a distance no offset in a
/// frame can hold and a call no program makes.
pub fn call(
    out: &mut mir::Func,
    block: mir::Block,
    made: &Calling<'_>,
    conv: &CallRegs,
    insts: &Insts,
    names: &mut Interner,
) -> Result<Made, Refused> {
    let &Calling { callee, args, returns, variadic, named, at: span } = made;
    // Where everything goes, worked out before anything is built, so that a call this cannot make
    // leaves no half of one behind.
    let mut places = Places::new(conv);
    let mut passed = Vec::with_capacity(args.len());
    // The ones with no register left for them, as the store each of them becomes and how far up
    // the outgoing area it writes. Almost always empty.
    let mut on_stack = Vec::new();
    // How many of them went in vector registers, which is what a SysV variadic callee is told.
    let mut vectors = 0u32;
    // The ones whose bytes travel rather than their address, as the register that address is in,
    // how far up the outgoing area they go and which words the copy is made of. Almost always
    // empty too, and never at the same time as a register: an object in the argument area is in
    // the argument area whatever is left of the register files.
    let mut as_bytes = Vec::new();
    // The arguments beyond the ones the signature names that travel in a vector register and have
    // to travel in a general purpose one at the same time, as the register each is in and the
    // general purpose register its copy belongs in. Empty on every convention but the one that says
    // so, and on that one this is what makes `printf("%f", x)` read the right register.
    let mut in_both = Vec::new();
    // Which argument position the next one that gets a register is at, which is only the same as
    // the index when nothing ahead of it went to memory. A convention that counts the two register
    // files as one run is what needs it: the general purpose register a variadic float's second
    // copy goes in is the one at that position.
    let mut position = 0usize;
    for (index, &Passing { ty, reg, abi }) in args.iter().enumerate() {
        let refused = |missing| Refused { argument: Some(index), missing };
        // An eighty bit float is bytes in the argument area whatever the classification said, for
        // the reason [`on_the_stack`] gives, and the register holding it holds their address. So it
        // joins the objects below rather than being a case of its own, and the copy it becomes is
        // the copy any other sixteen byte object gets.
        let abi = match abi {
            _ if on_the_stack(ty) => {
                let (size, align) = X87_AREA;
                Abi::ByVal { size: size.into(), align, drains: Drains::Nothing }
            }
            abi => abi,
        };
        if let Abi::ByVal { size, align, drains } = abi {
            let size = u32::try_from(size).map_err(|_| refused(Missing::TooBig))?;
            // One past the `...` is never packed, so it is words wherever it is.
            let at = if variadic && index >= named {
                places.on_stack(size, align)
            } else {
                places.object(size, align)
            };
            drain(&mut places, drains);
            let Where::Stack(up) = at else {
                unreachable!("an object in the argument area is in the argument area")
            };
            // Nothing here refuses a plan it did not get, because a copy the words give up on is
            // a call to the runtime below. What the byte count has to fit in is the immediate the
            // call passes it as, and an object that large is what is left of the old refusal.
            let plan = crate::expand::plan(u64::from(size), align, conv.word);
            let count = i32::try_from(size).map_err(|_| refused(Missing::TooBig))?;
            as_bytes.push((reg, up, count, plan));
            continue;
        }
        // The address a result comes back through goes in its own register where the convention
        // has one, and is not an argument position, the same as on the other side in [`entry`].
        if let (Abi::Sret { .. }, Some(sret)) = (abi, conv.sret) {
            passed.push((reg, sret, class_of(ty, conv)));
            continue;
        }
        // Apple's AArch64 puts every argument past the named ones in memory, a word or more each,
        // whatever registers are left.
        let unnamed = variadic && index >= named && conv.abi.variadic == Variadic::AlwaysMemory;
        let at = if unnamed {
            let bytes = int_bytes(ty, conv);
            places.on_stack(bytes, bytes)
        } else if ty.is_float() {
            places.float(float_bytes(ty))
        } else {
            places.integer(int_bytes(ty, conv))
        };
        if let Some(missing) = refuses(ty, insts) {
            return Err(refused(missing));
        }
        let class = class_of(ty, conv);
        match at {
            Where::Reg(at) => {
                // Only a register counts, because the count is of registers. An argument that went
                // to memory is one the callee reads from memory whatever this says.
                if class == conv.sse_class {
                    vectors += 1;
                    // Windows passes a float the callee has no prototype for in the vector register
                    // and in the general purpose register at the same position, both at once,
                    // because the callee has no way to know which file to look in and its walk over
                    // the arguments reads the second one. An argument the signature does name needs
                    // no second copy, since the callee's parameter says where it is.
                    let both = conv.shared_positions && variadic && index >= named;
                    if let Some(&also) = conv.int_args.get(position).filter(|_| both) {
                        in_both.push((reg, also));
                    }
                }
                passed.push((reg, at, class));
                position += 1;
            }
            Where::Stack(up) => {
                let store = (insts.store)(ty).ok_or(refused(Missing::Width))?;
                on_stack.push((reg, class, names.intern(store), up));
            }
        }
    }
    // A `long double` comes back in `st(0)`, which is not a register in either file and not one
    // this call can be said to write. So nothing is placed for it and nothing is constrained, and
    // the call gives back no register at all: what takes the value off that stack is the `fstp`
    // [`crate::lower`] writes straight after the call, which is the same shape every other use of
    // the x87 stack is written in. A complex one is the same with its imaginary half in `st(1)`,
    // and a second `fstp` takes that one off.
    let comes_back =
        if back_on_x87(returns) { Vec::new() } else { places_back(returns, conv, insts)? };

    // A variadic callee on SysV reads how many vector registers the call passed arguments in and
    // skips saving them when the answer is none, which is what makes `printf` with no floating
    // point argument cheap. It is an obligation rather than an optimization: leaving whatever was
    // in the register there makes the callee save a register file it was not given, and a count
    // that is too low makes it read an argument out of a register nothing put one in.
    let counted = if variadic { conv.vector_count } else { None };

    // The arguments that go to memory go there now, in front of the call and after everything this
    // could have refused, so that a call it cannot make leaves no store behind either. The offset
    // is written straight in rather than left for [`crate::finish`]: the outgoing area is at the
    // bottom of the frame because that is where the callee looks for it, and the bottom of the
    // frame is where the stack pointer already is.
    for (reg, class, store, up) in on_stack {
        let sp = mir::Operand::read(mir::Reg::physical(conv.stack_pointer), conv.int_class);
        let up = i32::try_from(up).expect("an argument area under two gigabytes");
        let build = out.build(block, mir::Opcode::new(store)).at(span);
        build.uses(reg, class).mem(mir::Mem::at(sp).plus(up)).finish();
    }

    // How many bytes the copies below needed for calls of their own, which is nothing on a
    // convention that passes three pointers in registers and thirty two bytes on the one that
    // reserves a place for them anyway. The frame has to hear about it, since a call built here is
    // still a call this function makes.
    let mut nested = 0u32;

    // And the objects whose bytes go there, as a load and a store for each word of each of them.
    // This is the copy the caller owes a callee that takes a structure by value: the callee is
    // free to write to what it was handed, so what it was handed cannot be the caller's own copy,
    // and the argument area is where the convention says the caller's copy goes. The words are the
    // same words `crate::expand` would have chosen for a `memcpy` of the same block, because they
    // are chosen by the same function.
    for (from, up, count, plan) in as_bytes {
        let up = i32::try_from(up).expect("an argument area under two gigabytes");
        let Some(plan) = plan else {
            let what = Copying { from, up, count, span };
            nested = nested.max(by_runtime(out, block, conv, insts, names, what));
            continue;
        };
        for (at, width) in plan {
            let ty = Type::int(width * 8);
            let at = i32::try_from(at).expect("an object under two gigabytes");
            let word = out.new_vreg(conv.int_class);
            let load = names.intern(
                (insts.load)(ty).ok_or(Refused { argument: None, missing: Missing::Width })?,
            );
            let there = mir::Operand::read(from, conv.int_class);
            let build = out.build(block, mir::Opcode::new(load)).at(span);
            build.def(word, conv.int_class).mem(mir::Mem::at(there).plus(at)).finish();
            let store = names.intern(
                (insts.store)(ty).ok_or(Refused { argument: None, missing: Missing::Width })?,
            );
            let sp = mir::Operand::read(mir::Reg::physical(conv.stack_pointer), conv.int_class);
            let build = out.build(block, mir::Opcode::new(store)).at(span);
            build.uses(word, conv.int_class).mem(mir::Mem::at(sp).plus(up + at)).finish();
        }
    }

    // And the second copy of each float the callee has no prototype for, which is one `movq` out of
    // the vector register it is already in. What the callee reads out of the general purpose
    // register is the sixty four bits and not a value of any type, so the bits are what move, and
    // the copy joins the arguments rather than being a thing of its own: it is passed in a register
    // the convention names, which is what every other argument here is.
    for (from, into) in in_both {
        let word = out.new_vreg(conv.int_class);
        let movq = mir::Opcode::new(names.intern("x64.movq_from_xmm"));
        out.build(block, movq)
            .at(span)
            .def(word, conv.int_class)
            .uses(from, conv.sse_class)
            .finish();
        passed.push((word, into, conv.int_class));
    }

    // The definitions first and the reads after, which is the order every operand vector in the
    // machine IR is in and the order `rucc_mir::defs` counts.
    let mut operands = Vec::with_capacity(args.len() + conv.int_order.len() + 2);
    let results: Vec<mir::Reg> = comes_back
        .iter()
        .map(|&(at, class)| {
            let reg = out.new_vreg(class);
            operands.push(mir::Operand::write(reg, class).with(Constraint::Fixed(at)));
            reg
        })
        .collect();
    // One list per file, because a physical register is a number and the class is what says which
    // file it is a number in. One list would have `xmm0` blocking `rax`.
    let spoken_for = |class: RegClass| -> Vec<PhysReg> {
        comes_back
            .iter()
            .filter(|&&(_, at)| at == class)
            .map(|&(reg, _)| reg)
            .chain(counted.filter(|_| class == conv.int_class))
            .chain(passed.iter().filter(|&&(_, _, at)| at == class).map(|&(_, reg, _)| reg))
            .collect()
    };
    let named = spoken_for(conv.int_class);
    for &reg in conv.int_order {
        if !conv.preserves_int(reg) && !named.contains(&reg) {
            operands.push(mir::Operand::write(mir::Reg::physical(reg), conv.int_class));
        }
    }
    let named = spoken_for(conv.sse_class);
    for &reg in conv.sse_order {
        if !conv.preserves_sse(reg) && !named.contains(&reg) {
            operands.push(mir::Operand::write(mir::Reg::physical(reg), conv.sse_class));
        }
    }
    // The address in front of the arguments, because a call through one is written with the
    // register it goes through and nothing in the operand vector is at a place a table could name.
    // First read is a place that does not depend on the signature, which is what
    // [`rucc_target::x86_64::Arg::Through`] is written against.
    if let Callee::Through(reg) = callee {
        operands.push(mir::Operand::read(reg, conv.int_class));
    }
    for (reg, at, class) in passed {
        operands.push(mir::Operand::read(reg, class).with(Constraint::Fixed(at)));
    }
    if let Some(at) = counted {
        let count = out.new_vreg(conv.int_class);
        let zero = mir::Opcode::new(names.intern(insts.small));
        out.build(block, zero).at(span).def(count, conv.int_class).imm(i64::from(vectors)).finish();
        operands.push(mir::Operand::read(count, conv.int_class).with(Constraint::Fixed(at)));
    }

    let opcode = mir::Opcode::new(names.intern(match callee {
        Callee::Named(_) => insts.call,
        Callee::Through(_) => insts.call_reg,
    }));
    let mut build = out.build(block, opcode).at(span);
    if let Callee::Named(symbol) = callee {
        build = build.symbol(symbol);
    }
    for operand in operands {
        build = build.operand(operand);
    }
    build.finish();
    Ok(Made { results, outgoing: places.size().max(nested) })
}

/// One object whose bytes go into the argument area by a call to the runtime.
#[derive(Debug, Clone, Copy)]
struct Copying {
    /// The register its address is in.
    from: mir::Reg,
    /// How far up the outgoing area its copy goes.
    up: i32,
    /// How many bytes it is.
    count: i32,
    /// Where the call it is an argument of was written.
    span: Span,
}

/// One object with more words than a copy into the argument area unrolls to, copied there by a
/// call to the runtime, and how many bytes that call itself needed below the stack pointer.
///
/// Which routine it is is [`crate::capability`]'s answer and not a name written here, because a
/// call standing in for an operation the machine has no instruction for is what that table is a
/// list of, and a copy too large to unroll is already on it: this is the same row `crate::expand`
/// reads for a `memcpy` in the IR of the same size.
fn by_runtime(
    out: &mut mir::Func,
    block: mir::Block,
    conv: &CallRegs,
    insts: &Insts,
    names: &mut Interner,
    what: Copying,
) -> u32 {
    let Copying { from, up, count, span } = what;
    let routine = capability::libcall(rucc_ir::Opcode::Memcpy, "big")
        .expect("the runtime copies a block too large to unroll");

    // Where the copy goes, which is a distance up the outgoing area and so is the stack pointer
    // plus that distance. A `lea` rather than an add, because the stack pointer is not this
    // function's to move and what the call wants is the address in a register of the allocator's
    // choosing.
    let sp = mir::Operand::read(mir::Reg::physical(conv.stack_pointer), conv.int_class);
    let into = out.new_vreg(conv.int_class);
    let lea = mir::Opcode::new(names.intern(insts.lea));
    out.build(block, lea)
        .at(span)
        .def(into, conv.int_class)
        .mem(mir::Mem::at(sp).plus(up))
        .finish();

    // And how many bytes, which C takes as a `size_t` and this has as a number. A thirty two bit
    // move carries it, because writing the low half of a general purpose register clears the high
    // half, so the sixty four bit count it becomes is the count as long as the count fits in the
    // immediate, which is what the caller checked before anything was built.
    let bytes = out.new_vreg(conv.int_class);
    let mov = mir::Opcode::new(names.intern(insts.small));
    out.build(block, mov).at(span).def(bytes, conv.int_class).imm(i64::from(count)).finish();

    let args = [
        Passing { ty: Type::PTR, reg: into, abi: Abi::Plain },
        Passing { ty: Type::PTR, reg: from, abi: Abi::Plain },
        Passing { ty: Type::int(conv.word * 8), reg: bytes, abi: Abi::Plain },
    ];
    let made = Calling {
        callee: Callee::Named(names.intern(routine)),
        args: &args,
        returns: &[],
        variadic: false,
        named: args.len(),
        at: span,
    };
    // Three pointer sized arguments and nothing coming back is a call every convention here has
    // registers for, so the only way this could refuse is a convention with fewer than three
    // argument registers, and there is no such convention.
    call(out, block, &made, conv, insts, names)
        .expect("the runtime's copy passes three words and takes nothing back")
        .outgoing
}

/// Which register each value comes back in, walked the way the arguments are.
///
/// The two files are counted separately, because a structure of a `double` and a `long` comes back
/// with the `double` in the first vector register and the `long` in the first integer one, and a
/// single count would put the second half one place further along a list it is not on.
///
/// # Errors
///
/// The first value that cannot come back at all, and why, so that a call this cannot make leaves
/// nothing behind. Nothing here reports which value it was, because the caller has one answer for
/// all of them: the value that comes back is not an argument and has no position among them.
fn places_back(
    returns: &[Type],
    conv: &CallRegs,
    insts: &Insts,
) -> Result<Vec<(PhysReg, RegClass)>, Refused> {
    let refused = |missing| Refused { argument: None, missing };
    let mut back = Vec::with_capacity(returns.len());
    let (mut ints, mut sses) = (0usize, 0usize);
    for &ty in returns {
        if let Some(missing) = refuses(ty, insts) {
            return Err(refused(missing));
        }
        let class = class_of(ty, conv);
        let (file, at) = if class == conv.sse_class {
            (conv.sse_returns, &mut sses)
        } else {
            (conv.int_returns, &mut ints)
        };
        let reg = *file.get(*at).ok_or_else(|| refused(Missing::NoRoom))?;
        *at += 1;
        back.push((reg, class));
    }
    Ok(back)
}

/// Which of the four widths a value travels at, where a truth value travels as the byte it lives
/// in.
///
/// [`crate::term::slot`] is the question the rule set asks and it answers nothing for one bit,
/// because there is no register of that width and so no instruction written at it. A convention
/// asks a different question. It has nothing narrower than a byte to put an argument in either,
/// and what it says about the one type that is a bit is that the byte holding it is the argument,
/// with the seven bits above unspecified. So the two lists differ by exactly this entry.
///
/// It is written here and not in [`crate::term::slot`] because moving it there would tell the rule
/// set that one bit is a byte, and then every byte rule in the file would match a term that is not
/// one. What the convention needs is narrower: a name for the register an argument arrives in, and
/// that name says a width because a listing is easier to read when it does.
fn place(ty: Type) -> Option<usize> {
    if crate::term::is_bit(ty) { Some(0) } else { crate::term::slot(ty) }
}

/// What the pseudo for an argument of that type is called.
///
/// The width is in the name for the same reason it is in every other opcode here: it is what the
/// instruction is about. Nothing encodes it, so nothing depends on it being right, but a listing
/// that says an argument arrived and does not say how much of it did is a listing worth less.
///
/// Which widths there are is `place` above, and not a list of its own, because it has to be the
/// same list the three below use. An argument brought in at a width nothing downstream has a name
/// for is a register nothing could then read, and a width the others cover that this refuses is a
/// function turned away for no reason. Asking one question in one place is what keeps the four
/// answers from drifting, and an address is what they used to disagree about.
#[must_use]
pub fn head_of(ty: Type) -> Option<&'static str> {
    // The format that fills a whole vector register, which travels in one of them: the psABI
    // classifies it SSE and SSEUP, and those two eightbytes are the one register the pair names
    // rather than two registers.
    if crate::term::is_quad(ty) {
        return Some("x64.arg_val_f128");
    }
    // The half, which arrives in the low sixteen bits of a vector register the same way a `float`
    // arrives in the low thirty two. It is a name of its own rather than the `f32` one for the
    // reason every other width here has a name of its own: what arrived is two bytes, and a
    // listing that said four would be saying something the convention does not.
    if crate::term::is_half(ty) {
        return Some("x64.arg_val_f16");
    }
    if let Some(at) = crate::term::float_slot(ty) {
        return Some(["x64.arg_val_f32", "x64.arg_val_f64"][at]);
    }
    let names = ["x64.arg_val_8", "x64.arg_val_16", "x64.arg_val_32", "x64.arg_val_64"];
    Some(names[place(ty)?])
}

/// What the instruction that reads an argument of that type out of memory is called.
///
/// Keyed off the same two questions [`head_of`] asks and answering for the same set of types, so
/// that a parameter this compiler can bring in from a register is one it can bring in from the
/// caller's stack as well. A width one of them covered and the other did not would be a function
/// turned away for where its sixth argument happened to land.
///
/// Reading a narrow argument at its own width and not at a word is deliberate. The caller wrote a
/// whole word, but what it put in the part above the value is not something the convention says, so
/// the bits this reads are exactly the bits that mean anything. That is the same thing an argument
/// arriving in a register gets: `x64.arg_val_8` says the low byte of that register is the argument
/// and says nothing at all about the rest of it.
#[must_use]
pub fn load_of(ty: Type) -> Option<&'static str> {
    // Sixteen bytes, which is the whole register and is also the whole value, so the instruction
    // a spill uses and the instruction an argument uses are the same one here. They are two
    // different instructions at the two narrower formats because there the value is part of the
    // register, and at this format there is no part of it to leave behind.
    if crate::term::is_quad(ty) {
        return Some("x64.movaps_rm");
    }
    // Two bytes out of the argument area and into the low lane of a vector register, which is one
    // instruction and is the same one a rule writes for a program's own read of a `_Float16`.
    if crate::term::is_half(ty) {
        return Some("x64.pinsrw_rm");
    }
    if let Some(at) = crate::term::float_slot(ty) {
        return Some(["x64.movss_rm", "x64.movsd_rm"][at]);
    }
    let names = ["x64.mov_rm_8", "x64.mov_rm_16", "x64.mov_rm_32", "x64.mov_rm_64"];
    Some(names[place(ty)?])
}

/// What the instruction that writes an argument of that type into memory is called.
///
/// The mirror of [`load_of`], keyed off the same two questions and answering for the same set of
/// types, so that the two ends of one call agree about what travels. A type a callee can read out
/// of the argument area and a caller cannot write into it would be a call turned away for a reason
/// the function it calls does not have.
///
/// Writing a narrow argument at its own width leaves whatever was already in the rest of the word.
/// That is allowed, and it is what [`load_of`] is written against: the convention does not say what
/// is above the value, so the callee reads only the bits that mean anything and neither end has to
/// agree about the rest.
#[must_use]
pub fn store_of(ty: Type) -> Option<&'static str> {
    if crate::term::is_quad(ty) {
        return Some("x64.movaps_mr");
    }
    // The half goes out four bytes wide, which is the one place here where the instruction is not
    // the width of the value. SSE2 has no store of sixteen bits out of a vector register: the form
    // of `pextrw` that writes memory arrived with SSE4.1 and is above this target's baseline, so
    // the choices are a four byte store or a pair of instructions through a general purpose
    // register, and a pair is not something one name can be.
    //
    // Four bytes is safe here and would not be everywhere. An argument on the stack sits in an
    // eightbyte of its own, the paragraph above says the convention promises nothing about the
    // part of it above the value, and [`load_of`] reads back exactly the two bytes that mean
    // anything. What lands in the two bytes beside them is whatever was in the register, which is
    // no more than any other narrow argument leaves behind.
    if crate::term::is_half(ty) {
        return Some("x64.movss_mr");
    }
    if let Some(at) = crate::term::float_slot(ty) {
        return Some(["x64.movss_mr", "x64.movsd_mr"][at]);
    }
    let names = ["x64.mov_mr_8", "x64.mov_mr_16", "x64.mov_mr_32", "x64.mov_mr_64"];
    Some(names[place(ty)?])
}

/// What the instruction that leaves a returned value in its register is called, for the value at
/// that place in its own register file.
///
/// Keyed off the same two questions [`head_of`] asks, so a type this can give back is a type it can
/// take in. The place is the one a call counted to when it laid the return out, which is per file
/// rather than over the whole list: a structure of a `double` and a `long` gives both of them back
/// at place zero.
///
/// The register itself is not here. It is in the operand table in `rucc_target::x86_64`, which is
/// where the first one has always been, and the two names below are how a value says which of the
/// two it is. A convention with more than two registers to come back in would need more names, and
/// there is none, which is what the `None` at the end is about.
#[must_use]
pub fn ret_of(ty: Type, at: usize) -> Option<&'static str> {
    if crate::term::is_quad(ty) {
        return Some(*["x64.ret_val_f128", "x64.ret_val2_f128"].get(at)?);
    }
    if crate::term::is_half(ty) {
        return Some(*["x64.ret_val_f16", "x64.ret_val2_f16"].get(at)?);
    }
    if let Some(width) = crate::term::float_slot(ty) {
        let names =
            [["x64.ret_val_f32", "x64.ret_val_f64"], ["x64.ret_val2_f32", "x64.ret_val2_f64"]];
        return Some(names.get(at)?[width]);
    }
    let names = [
        ["x64.ret_val_8", "x64.ret_val_16", "x64.ret_val_32", "x64.ret_val_64"],
        ["x64.ret_val2_8", "x64.ret_val2_16", "x64.ret_val2_32", "x64.ret_val2_64"],
    ];
    Some(names.get(at)?[place(ty)?])
}

#[cfg(test)]
mod tests {
    use rucc_target::x86_64::{REGS, SYSV, WIN64};

    use super::*;

    /// Those types as parameters that travel as the values they are, which is every one of them
    /// that is not a structure the classification put in the argument area.
    fn plain(params: &[Type]) -> Vec<Param> {
        params.iter().copied().map(Param::new).collect()
    }

    /// The parameters of a function under a convention, as machine IR text.
    fn bind(params: &[Type], conv: &CallRegs) -> String {
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        entry(&mut out, block, &plain(params), conv, &X86_64, &mut names, None)
            .expect("every parameter arrives");
        mir::print_func(&out, &names, &REGS)
    }

    #[test]
    fn the_first_arguments_arrive_where_the_convention_puts_them() {
        let i32 = Type::int(32);
        assert_eq!(
            bind(&[i32, i32, Type::int(64)], &SYSV),
            "mfunc @f {\nblock0:\n    %0:gpr($rdi) = x64.arg_val_32\n    \
             %1:gpr($rsi) = x64.arg_val_32\n    %2:gpr($rdx) = x64.arg_val_64\n}\n"
        );
    }

    #[test]
    fn the_other_convention_puts_the_same_arguments_somewhere_else() {
        // The first argument is in `rcx` here and in `rdi` above, which is the difference that
        // makes a SysV binary calling a Windows one read the wrong value rather than fail.
        let i64 = Type::int(64);
        assert_eq!(
            bind(&[i64, i64], &WIN64),
            "mfunc @f {\nblock0:\n    %0:gpr($rcx) = x64.arg_val_64\n    \
             %1:gpr($rdx) = x64.arg_val_64\n}\n"
        );
    }

    /// The parameters of a function under a convention, and what each of the ones that arrived in
    /// memory is waiting on.
    fn arrive(params: &[Type], conv: &CallRegs) -> (String, Vec<u32>) {
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        let arrived = entry(&mut out, block, &plain(params), conv, &X86_64, &mut names, None)
            .expect("every parameter");
        let up = arrived.stack.iter().map(|&(_, up)| up).collect();
        (mir::print_func(&out, &names, &REGS), up)
    }

    #[test]
    fn an_argument_past_the_last_register_is_read_out_of_the_caller_s_stack() {
        let (text, up) = arrive(&[Type::int(64); 7], &SYSV);

        // Six of them got registers and the seventh did not, so the seventh is a load rather than
        // a pseudo. It reads through the stack pointer with nothing in its displacement, because
        // where the caller's argument area is from in here is a distance into a frame that does
        // not exist yet, and it is at the bottom of that area because it is the first one in it.
        assert_eq!(up, [0]);
        assert!(text.contains("%6:gpr = x64.mov_rm_64 [$rsp]"), "{text}");
        assert_eq!(text.matches("x64.arg_val_64").count(), 6, "{text}");
    }

    #[test]
    fn the_other_convention_runs_out_of_registers_three_arguments_earlier() {
        let (text, up) = arrive(&[Type::int(64); 7], &WIN64);

        // Windows passes four integers in registers and reserves thirty two bytes below the call
        // whether they are used or not, so the fifth argument is not at the bottom of the argument
        // area but above the shadow space, and the three after it follow it a word at a time.
        assert_eq!(up, [32, 40, 48]);
        assert_eq!(text.matches("x64.arg_val_64").count(), 4, "{text}");
        assert!(text.contains("%4:gpr = x64.mov_rm_64 [$rsp]"), "{text}");
    }

    /// The parameters of a function under a convention, with one of them a structure whose bytes
    /// travel, and what each of the ones that arrived in memory is waiting on.
    fn arrive_with(params: &[Param], conv: &CallRegs) -> (String, Vec<u32>) {
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        let arrived = entry(&mut out, block, params, conv, &X86_64, &mut names, None)
            .expect("every parameter");
        let up = arrived.stack.iter().map(|&(_, up)| up).collect();
        (mir::print_func(&out, &names, &REGS), up)
    }

    #[test]
    fn a_structure_that_arrived_as_bytes_is_an_address_and_not_a_load() {
        let byval =
            Param::with_abi(Type::PTR, Abi::ByVal { size: 32, align: 8, drains: Drains::Nothing });
        let (text, up) =
            arrive_with(&[Param::new(Type::int(32)), byval, Param::new(Type::int(32))], &SYSV);

        // `int f(int a, struct Big b, int c)`. The bytes of `b` are already in this function, at
        // the bottom of the caller's argument area, so nothing is read out of them here: what the
        // parameter is is where they are, which is one address. The two integers still travel in
        // registers, because an object in the argument area takes no register and the arguments
        // behind it do not shift along.
        assert_eq!(up, [0]);
        assert_eq!(text.matches("x64.arg_val_32").count(), 2, "{text}");
        assert!(text.contains("%2:gpr = x64.lea_64 [$rsp]"), "{text}");
        assert!(!text.contains("mov_rm"), "nothing is read out of the bytes: {text}");
    }

    #[test]
    fn the_argument_behind_a_structure_that_travelled_as_bytes_is_above_all_of_them() {
        let byval =
            Param::with_abi(Type::PTR, Abi::ByVal { size: 24, align: 16, drains: Drains::Nothing });
        let params: Vec<Param> = (0..7).map(|_| Param::new(Type::int(64))).collect();
        let (_, up) = arrive_with(&[&params[..], &[byval], &params[..1]].concat(), &SYSV);

        // Six integers take the six registers, the seventh is at the bottom of the argument area,
        // and the structure is above it at the alignment its type asks for rather than at a word.
        // The one behind the structure is above all twenty four of its bytes, rounded up to a
        // whole number of words, because the area is a run of words.
        assert_eq!(up, [0, 16, 40]);
    }

    /// A parameter narrower than a word is read at its own width rather than at a word, and one in
    /// the other register file is read with the other file's instruction. Both are the same list
    /// [`head_of`] answers from, which is what stops a function being turned away for the width of
    /// its seventh argument alone.
    #[test]
    fn what_a_stack_argument_is_read_with_is_its_own_width_and_its_own_file() {
        let f32 = Type::float(rucc_ir::Float::F32);
        let params = [Type::int(64), Type::int(64), Type::int(64), Type::int(64), Type::int(8)];
        let (text, up) = arrive(&params, &WIN64);
        assert_eq!(up, [32]);
        assert!(text.contains("x64.mov_rm_8 [$rsp]"), "{text}");

        let floats = [f32; 5];
        let (text, up) = arrive(&floats, &WIN64);
        assert_eq!(up, [32]);
        assert!(text.contains("%4:xmm = x64.movss_rm [$rsp]"), "{text}");
    }

    /// Every type a parameter can arrive in a register at is one it can be read from memory at.
    /// The two lists are keyed off the same two questions so that they cannot drift, and this is
    /// what says so: a width one covered and the other did not would be a function turned away for
    /// where its arguments happened to land rather than for anything about it.
    #[test]
    fn the_two_lists_of_widths_answer_for_the_same_types() {
        let types = [
            Type::int(1),
            Type::int(8),
            Type::int(16),
            Type::int(32),
            Type::int(64),
            Type::int(128),
            Type::PTR,
            Type::float(rucc_ir::Float::F32),
            Type::float(rucc_ir::Float::F64),
            Type::float(rucc_ir::Float::F80),
            Type::float(rucc_ir::Float::F128),
        ];
        for ty in types {
            assert_eq!(head_of(ty).is_some(), load_of(ty).is_some(), "{ty:?}");
            assert_eq!(head_of(ty).is_some(), store_of(ty).is_some(), "{ty:?}");
            assert_eq!(head_of(ty).is_some(), ret_of(ty, 0).is_some(), "{ty:?}");
        }
    }

    /// A hundred and twenty eight bit float arrives in a vector register like the two narrower
    /// formats, and it takes one of them rather than two: the psABI classifies it SSE and SSEUP,
    /// and what that pair names is the one register both eightbytes are in.
    ///
    /// The second float here is what says so. If the quad had taken two vector registers the
    /// `double` after it would be in `xmm2`.
    #[test]
    fn a_quad_float_arrives_in_one_vector_register_and_not_in_two() {
        let quad = Type::float(rucc_ir::Float::F128);
        let f64 = Type::float(rucc_ir::Float::F64);
        assert_eq!(
            bind(&[quad, f64], &SYSV),
            "mfunc @f {\nblock0:\n    %0:xmm($xmm0) = x64.arg_val_f128\n    \
             %1:xmm($xmm1) = x64.arg_val_f64\n}\n"
        );
    }

    /// And it is not the width that was refused before there was an instruction to move it with,
    /// which is the one thing about this type that used to turn a whole function away.
    #[test]
    fn a_quad_float_is_no_longer_a_width_nothing_can_carry() {
        assert_eq!(refuses(Type::float(rucc_ir::Float::F128), &X86_64), None);
        assert_eq!(refuses(Type::float(rucc_ir::Float::F80), &X86_64), Some(Missing::OnX87));
        assert_eq!(refuses(Type::int(128), &X86_64), Some(Missing::Width));
    }

    /// A float arrives in the other file, and the two files are counted apart on SysV: the
    /// integer here is the first integer argument and the float is the first float one, so they
    /// are in `rdi` and `xmm0` rather than in the first and second of anything.
    #[test]
    fn a_float_arrives_in_a_vector_register_and_is_counted_apart_from_the_integers() {
        let f32 = Type::float(rucc_ir::Float::F32);
        let f64 = Type::float(rucc_ir::Float::F64);
        assert_eq!(
            bind(&[Type::int(32), f64, f32], &SYSV),
            "mfunc @f {\nblock0:\n    %0:gpr($rdi) = x64.arg_val_32\n    \
             %1:xmm($xmm0) = x64.arg_val_f64\n    %2:xmm($xmm1) = x64.arg_val_f32\n}\n"
        );
    }

    /// Windows counts the two files together, so the same three arguments land in different
    /// registers: the float is the second argument and takes the second vector register rather
    /// than the first, which is the difference that makes a mismatched call read the wrong value.
    #[test]
    fn the_other_convention_counts_the_two_files_as_one_run_of_positions() {
        let f64 = Type::float(rucc_ir::Float::F64);
        assert_eq!(
            bind(&[Type::int(32), f64, Type::int(64)], &WIN64),
            "mfunc @f {\nblock0:\n    %0:gpr($rcx) = x64.arg_val_32\n    \
             %1:xmm($xmm1) = x64.arg_val_f64\n    %2:gpr($r8) = x64.arg_val_64\n}\n"
        );
    }

    /// A `long double` is in neither file and travels in the argument area, which is what SysV's
    /// X87 classification comes to. So it arrives the way a structure the classification put in
    /// memory arrives, as the address of its bytes in a general purpose register, and it does that
    /// while the vector file is untouched: this one is in the argument area because of what it is
    /// rather than because the registers ran out.
    #[test]
    fn a_long_double_arrives_as_the_address_of_its_bytes_in_the_argument_area() {
        let params = [Type::int(32), Type::float(rucc_ir::Float::F80)];
        assert_eq!(
            bind(&params, &SYSV),
            "mfunc @f {\nblock0:\n    %0:gpr($rdi) = x64.arg_val_32\n    \
             %1:gpr = x64.lea_64 [$rsp]\n}\n"
        );
    }

    /// It still cannot come back beside another value, and what it is turned away for says which
    /// file is in the way rather than calling eighty bits a width no register holds. A pair comes
    /// back in a pair of registers and there is no pair with the x87 stack in it.
    #[test]
    fn a_long_double_in_a_pair_is_reported_as_the_x87_stack_it_travels_on() {
        let returns = [Type::float(rucc_ir::Float::F80), Type::int(64)];
        assert_eq!(
            make(&[], &returns, false, &SYSV).2,
            Err(Refused { argument: None, missing: Missing::OnX87 })
        );
    }

    /// One call to `g`, with a register for each argument arriving in the block that makes it.
    ///
    /// A variadic call here names none of its arguments, which is the shape that asks the most of a
    /// convention. [`made_naming`] is for the tests that care where the line between the named ones
    /// and the rest actually falls.
    fn make(
        args: &[Type],
        returns: &[Type],
        variadic: bool,
        conv: &CallRegs,
    ) -> (Interner, mir::Func, Result<Made, Refused>) {
        let named = if variadic { 0 } else { args.len() };
        made_naming(args, returns, named, variadic, conv)
    }

    /// The same, for a callee whose signature names that many of the arguments.
    fn made_naming(
        args: &[Type],
        returns: &[Type],
        named: usize,
        variadic: bool,
        conv: &CallRegs,
    ) -> (Interner, mir::Func, Result<Made, Refused>) {
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        let passed: Vec<Passing> = args
            .iter()
            .map(|&ty| Passing {
                ty,
                reg: out.append_param(block, class_of(ty, conv)),
                abi: Abi::Plain,
            })
            .collect();
        let callee = Callee::Named(names.intern("g"));
        let what = Calling { callee, args: &passed, returns, variadic, named, at: Span::DUMMY };
        let made = call(&mut out, block, &what, conv, &X86_64, &mut names);
        (names, out, made)
    }

    /// What the call in that function reads and writes, by register name, in the order the
    /// operands are in.
    fn operands(func: &mir::Func) -> (Vec<String>, Vec<String>) {
        let block = func.entry().expect("a function with a block in it");
        let call = func.terminator(block).expect("the call is the last thing in the block");
        let name = |operand: &mir::Operand| match (operand.reg.phys(), operand.constraint) {
            (Some(reg), _) | (None, Constraint::Fixed(reg)) => {
                REGS.name(operand.class, reg).expect("a register the file describes").to_string()
            }
            _ => format!("{:?}", operand.reg),
        };
        let mut written = Vec::new();
        let mut read = Vec::new();
        for operand in &func[func[call].operands] {
            let into = if operand.role == mir::Role::Use { &mut read } else { &mut written };
            into.push(name(operand));
        }
        (written, read)
    }

    #[test]
    fn a_call_passes_its_arguments_where_the_convention_puts_them() {
        let i32 = Type::int(32);
        let (_, func, made) = make(&[i32, i32, i32], &[], false, &SYSV);
        assert_eq!(made.expect("three integers all fit in registers").results, []);
        assert_eq!(operands(&func).1, ["rdi", "rsi", "rdx"]);
    }

    #[test]
    fn the_other_convention_passes_the_same_arguments_somewhere_else() {
        let i64 = Type::int(64);
        let (_, func, made) = make(&[i64, i64], &[], false, &WIN64);
        // Thirty two bytes of stack for a call that passes nothing on the stack, which is what
        // Windows asks a caller to leave the callee whether the callee uses it or not.
        assert_eq!(made.expect("two integers fit in registers").outgoing, 32);
        assert_eq!(operands(&func).1, ["rcx", "rdx"]);
    }

    #[test]
    fn what_a_call_gives_back_comes_out_of_the_register_the_convention_returns_in() {
        let (names, func, made) = make(&[], &[Type::int(32)], false, &SYSV);
        let made = made.expect("an integer comes back");
        let [result] = made.results[..] else { panic!("one register") };
        // The first thing written is the result, and it is the only thing written that is a value
        // rather than a register the callee destroyed.
        assert_eq!(operands(&func).0.first().map(String::as_str), Some("rax"));
        assert_eq!(func.class_of(result), Some(SYSV.int_class));
        assert!(mir::print_func(&func, &names, &REGS).contains("x64.call"));
    }

    #[test]
    fn every_register_the_callee_may_destroy_is_written_by_the_call() {
        let (_, func, _) = make(&[Type::int(64)], &[Type::int(64)], false, &SYSV);
        let (written, read) = operands(&func);
        // The callee saved registers are not here, because a value in one of those survives a
        // call and that is the whole difference between the two halves of the convention.
        for saved in ["rbx", "rbp", "r12", "r13", "r14", "r15"] {
            assert!(!written.contains(&saved.to_string()), "{saved} survives a call");
        }
        // Every other integer register is, once. The two named ones are named by the result and
        // by the argument instead, and naming one twice would be blocking it twice.
        for destroyed in ["rcx", "rdx", "rsi", "r8", "r9", "r10", "r11"] {
            let count = written.iter().filter(|name| *name == destroyed).count();
            assert_eq!(count, 1, "{destroyed} is destroyed by a call and is written {count} times");
        }
        assert_eq!(written.iter().filter(|name| *name == "rax").count(), 1);
        assert_eq!(read, ["rdi"]);
        // The vector registers are all destroyed on SysV, and they are in the other class.
        assert!(written.contains(&"xmm0".to_string()));
    }

    #[test]
    fn a_variadic_call_says_how_many_vector_registers_it_passed_arguments_in() {
        let (names, func, made) = make(&[Type::int(64)], &[], true, &SYSV);
        made.expect("an integer argument to a variadic callee");
        let (_, read) = operands(&func);
        // Zero of them here, and `al` is where a SysV callee looks for it. Leaving whatever was in
        // the register there would make a callee that saves its vector registers save ones it was
        // never given.
        assert_eq!(read, ["rdi", "rax"]);
        assert_eq!(
            mir::print_func(&func, &names, &REGS).lines().nth(2),
            Some("    %1:gpr = x64.mov_ri_32 0")
        );

        // Two of them here, which is the number that decides how much of the register save area a
        // callee like `printf` fills in. A count of zero with a float in `xmm0` would be a callee
        // reading its first `%f` out of a register nothing wrote.
        let f64 = Type::float(rucc_ir::Float::F64);
        let (names, func, made) = make(&[Type::int(64), f64, f64], &[], true, &SYSV);
        made.expect("one integer and two floats all fit in registers");
        assert_eq!(operands(&func).1, ["rdi", "xmm0", "xmm1", "rax"]);
        assert!(mir::print_func(&func, &names, &REGS).contains("x64.mov_ri_32 2"));
    }

    /// Windows passes a float the callee has no prototype for in both files at once, because the
    /// callee has no way to know which file to look in and its walk over the arguments reads the
    /// general purpose one. This is the whole of what `printf("%f", x)` needs from the caller.
    #[test]
    fn a_float_a_variadic_callee_has_no_prototype_for_travels_in_both_files_on_windows() {
        let f64 = Type::float(rucc_ir::Float::F64);
        let (names, func, made) = made_naming(&[Type::int(32), f64], &[], 1, true, &WIN64);
        made.expect("an integer and a float both fit in registers");

        // The float is the second argument, so its position is one and both of its registers are
        // the second of their file. `rdx` holds the bits and nothing converts them, which is what
        // the `movq` is: the callee reads bits out of it and not a value of any type.
        assert_eq!(operands(&func).1, ["rcx", "xmm1", "rdx"]);
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.movq_from_xmm %1"), "{text}");
    }

    /// An argument the signature does name needs no second copy, since the callee's parameter says
    /// where it is, and neither does one on a convention that keeps the two files apart.
    #[test]
    fn an_argument_the_signature_names_travels_in_one_file() {
        let f64 = Type::float(rucc_ir::Float::F64);
        let (names, func, made) = made_naming(&[Type::int(32), f64], &[], 2, true, &WIN64);
        made.expect("both are named");
        assert_eq!(operands(&func).1, ["rcx", "xmm1"]);
        assert!(!mir::print_func(&func, &names, &REGS).contains("movq_from_xmm"));

        let (names, func, made) = made_naming(&[Type::int(32), f64], &[], 1, true, &SYSV);
        made.expect("an integer and a float");
        assert!(!mir::print_func(&func, &names, &REGS).contains("movq_from_xmm"));
    }

    /// A float past the position the registers run out at is in the argument area and nowhere else,
    /// which is where the second copy stops being a thing there is room for. The callee reads it
    /// out of memory whichever file it would have been in.
    #[test]
    fn a_float_the_registers_ran_out_before_gets_no_second_copy() {
        let f64 = Type::float(rucc_ir::Float::F64);
        let (names, func, made) = made_naming(&[f64; 6], &[], 0, true, &WIN64);
        made.expect("four in registers and two in memory");
        let text = mir::print_func(&func, &names, &REGS);
        assert_eq!(text.matches("movq_from_xmm").count(), 4, "{text}");
        assert!(text.contains("x64.movsd_mr %4, [$rsp + 32]"), "{text}");
    }

    #[test]
    fn a_call_through_an_address_reads_it_in_front_of_the_arguments() {
        let i32 = Type::int(32);
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        let address = out.append_param(block, SYSV.int_class);
        let reg = out.append_param(block, SYSV.int_class);
        let passed = vec![Passing { ty: i32, reg, abi: Abi::Plain }];
        let what = Calling {
            callee: Callee::Through(address),
            args: &passed,
            returns: &[i32],
            variadic: false,
            named: passed.len(),
            at: Span::DUMMY,
        };
        call(&mut out, block, &what, &SYSV, &X86_64, &mut names)
            .expect("one integer fits in a register");

        // The address is the first thing read and the arguments follow it, which is the order the
        // assembler counts on, and it is in no particular register because every register a call
        // could insist on is one the call has already spoken for.
        let text = mir::print_func(&out, &names, &REGS);
        assert!(text.contains("= x64.call_reg %0, %1($rdi)\n"), "{text}");
        assert!(!text.contains("@g"), "a call through an address names nobody: {text}");
    }

    #[test]
    fn a_call_with_no_register_left_writes_the_argument_into_the_outgoing_area() {
        let i64 = Type::int(64);
        let (names, func, made) = make(&[i64; 7], &[], false, &SYSV);
        let made = made.expect("the seventh goes to memory");

        // At the stack pointer, because the outgoing area is at the bottom of the frame, and in
        // front of the call rather than as an operand of it.
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_mr_64 %6, [$rsp]\n"), "{text}");
        let store = text.find("x64.mov_mr_64").expect("the store");
        assert!(store < text.find("x64.call").expect("the call"), "{text}");
        // One word of it, which is what the frame has to reserve for this call.
        assert_eq!(made.outgoing, 8);
    }

    /// One call to `g`, passing that many words, then an object of that size and alignment by
    /// value, then one more integer, which is `int g(long.., struct Big, int)` after the
    /// classification.
    fn pass_bytes(
        before: usize,
        size: u64,
        align: u32,
        conv: &CallRegs,
    ) -> (Interner, mir::Func, Result<Made, Refused>) {
        let mut names = Interner::new();
        let mut out = mir::Func::new(names.intern("f"));
        let block = out.create_block();
        let mut args: Vec<Passing> = (0..before)
            .map(|_| Passing {
                ty: Type::int(64),
                reg: out.append_param(block, conv.int_class),
                abi: Abi::Plain,
            })
            .collect();
        args.push(Passing {
            ty: Type::PTR,
            reg: out.append_param(block, conv.int_class),
            abi: Abi::ByVal { size, align, drains: Drains::Nothing },
        });
        args.push(Passing {
            ty: Type::int(32),
            reg: out.append_param(block, conv.int_class),
            abi: Abi::Plain,
        });
        let callee = Callee::Named(names.intern("g"));
        let what = Calling {
            callee,
            args: &args,
            returns: &[],
            variadic: false,
            named: args.len(),
            at: Span::DUMMY,
        };
        let made = call(&mut out, block, &what, conv, &X86_64, &mut names);
        (names, out, made)
    }

    #[test]
    fn a_structure_passed_by_value_in_memory_is_copied_into_the_outgoing_area() {
        let (names, func, made) = pass_bytes(1, 24, 8, &SYSV);
        let made = made.expect("an object of three words is copied a word at a time");

        // The bytes travel and the address does not, so the copy is a load and a store for each
        // word of it, in front of the call, and the callee's copy is at the bottom of the outgoing
        // area. The caller owes it this copy: the callee is free to write to what it was handed,
        // so what it was handed cannot be the object itself.
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_mr_64 %3, [$rsp]\n"), "{text}");
        assert!(text.contains("x64.mov_mr_64 %4, [$rsp + 8]\n"), "{text}");
        assert!(text.contains("x64.mov_mr_64 %5, [$rsp + 16]\n"), "{text}");
        assert_eq!(text.matches("x64.mov_rm_64").count(), 3, "{text}");
        assert!(text.find("x64.mov_mr_64") < text.find("x64.call"), "{text}");
        assert_eq!(made.outgoing, 24);
    }

    #[test]
    fn the_integers_beside_it_still_travel_in_registers() {
        let (_, func, _) = pass_bytes(1, 24, 8, &SYSV);

        // An object in the argument area takes no argument register, so the integer behind it is
        // in the second one and not the third. Counting it as a register is the mistake that would
        // shift every argument after it along by one.
        let (clobbered, read) = operands(&func);
        assert_eq!(read, ["rdi", "rsi"]);
        assert!(clobbered.contains(&"rdx".to_owned()), "the third is free: {clobbered:?}");
    }

    #[test]
    fn an_object_wanting_more_alignment_than_a_word_gets_it() {
        let (names, func, made) = pass_bytes(7, 24, 16, &SYSV);
        let made = made.expect("an object of three words");

        // Six of the integers took the registers and the seventh is at the bottom of the area, so
        // the object cannot start where it left off: sixteen byte alignment moves it up to the
        // next multiple of sixteen and leaves a word of nothing behind it. The integer after it is
        // above all three of its words.
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_mr_64 %9, [$rsp + 16]\n"), "{text}");
        assert!(text.contains("x64.mov_mr_32 %8, [$rsp + 40]\n"), "{text}");
        assert_eq!(made.outgoing, 48);
    }

    #[test]
    fn an_object_too_large_to_copy_a_word_at_a_time_is_copied_by_the_runtime() {
        let (names, func, made) = pass_bytes(1, 4096, 8, &SYSV);
        let made = made.expect("an object the runtime copies");

        // Five hundred and twelve words is past what unrolling is worth, so the copy is the call
        // the same size of `memcpy` in the IR becomes: the address in the outgoing area, the
        // address of the object, and the count, and then the call the object was an argument of.
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.lea_64 [$rsp]"), "{text}");
        assert!(text.contains("x64.mov_ri_32 4096"), "{text}");
        assert_eq!(text.matches("x64.call").count(), 2, "the copy and the call: {text}");
        assert!(text.find("@memcpy") < text.find("@g"), "the copy comes first: {text}");

        // And the argument area is the object, because a call passing three words in registers
        // needs none of its own.
        assert_eq!(made.outgoing, 4096);
    }

    #[test]
    fn an_object_too_large_to_count_the_bytes_of_is_reported_rather_than_passed() {
        let (_, _, made) = pass_bytes(1, 1 << 31, 8, &SYSV);

        // Two gigabytes is more than the immediate the byte count travels in holds, and a count
        // that does not fit is the whole of what is left to refuse. No program passes a structure
        // that size by value, and one that tried would rather hear about it than be handed a copy
        // of the low part of it.
        assert_eq!(made, Err(Refused { argument: Some(1), missing: Missing::TooBig }));
        assert_eq!(
            Missing::TooBig.why(),
            "is more bytes than a count of them can be written down as"
        );
    }

    /// The other convention runs out three arguments earlier and starts its argument area above the
    /// shadow space it also has to reserve, and both of those are what `Places` already said.
    #[test]
    fn where_the_outgoing_area_starts_is_the_convention_s_answer() {
        let i64 = Type::int(64);
        let (names, func, made) = make(&[i64; 7], &[], false, &WIN64);
        assert_eq!(made.expect("the last three go to memory").outgoing, 56);

        // Thirty two bytes of shadow space first, which the caller writes nothing into and the
        // callee owns, and the fifth argument above it.
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_mr_64 %4, [$rsp + 32]\n"), "{text}");
        assert!(text.contains("x64.mov_mr_64 %5, [$rsp + 40]\n"), "{text}");
        assert!(text.contains("x64.mov_mr_64 %6, [$rsp + 48]\n"), "{text}");
    }

    /// What a stack argument is written with is its own width and its own register file, matching
    /// what the callee reads it back with.
    #[test]
    fn a_narrow_or_floating_argument_keeps_its_own_store() {
        let i64 = Type::int(64);
        let narrow = [i64, i64, i64, i64, i64, i64, Type::int(8)];
        let (names, func, made) = make(&narrow, &[], false, &SYSV);
        made.expect("the seventh goes to memory");
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_mr_8 %6, [$rsp]\n"), "{text}");

        let f32 = Type::float(rucc_ir::Float::F32);
        let (names, func, made) = make(&[f32; 9], &[], false, &SYSV);
        made.expect("the ninth goes to memory");
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.movss_mr %8, [$rsp]\n"), "{text}");
    }

    /// The count a SysV variadic callee reads is a count of registers, so an argument that went to
    /// memory instead is not in it.
    #[test]
    fn an_argument_in_memory_is_not_counted_as_a_vector_register() {
        let f64 = Type::float(rucc_ir::Float::F64);
        let (names, func, made) = make(&[f64; 9], &[], true, &SYSV);
        made.expect("the ninth goes to memory");
        let text = mir::print_func(&func, &names, &REGS);
        assert!(text.contains("x64.mov_ri_32 8\n"), "eight registers, not nine: {text}");
    }

    /// The two lists of widths answer for the same set of types, so that a value the callee can
    /// read out of the argument area is one the caller can write into it.
    #[test]
    fn what_can_be_read_can_be_written() {
        let types = [
            Type::int(1),
            Type::int(8),
            Type::int(16),
            Type::int(32),
            Type::int(64),
            Type::int(128),
            Type::PTR,
            Type::float(rucc_ir::Float::F32),
            Type::float(rucc_ir::Float::F64),
            Type::float(rucc_ir::Float::F80),
        ];
        for ty in types {
            assert_eq!(load_of(ty).is_some(), store_of(ty).is_some(), "{ty:?}");
        }
    }

    /// A float travels in the other file at both ends of a call, and the register it comes back in
    /// is the first of that file rather than the first of the other one.
    #[test]
    fn a_call_passes_and_returns_a_float_in_a_vector_register() {
        let f64 = Type::float(rucc_ir::Float::F64);
        let (_, func, made) = make(&[Type::int(32), f64], &[f64], false, &SYSV);
        let result = made.expect("an integer and a float both fit in registers");
        let (written, read) = operands(&func);
        assert_eq!(read, ["rdi", "xmm0"]);
        assert_eq!(written.first().map(String::as_str), Some("xmm0"));
        assert_eq!(func.class_of(result.results[0]), Some(SYSV.sse_class));
        // Written once, because the register the result comes back in is already blocked by being
        // named and a clobber that repeated it would be blocking it twice. `rax` is a clobber here
        // rather than the result, which is the same register number in the other file and is the
        // whole reason the two lists are counted apart.
        assert_eq!(written.iter().filter(|name| *name == "xmm0").count(), 1);
        assert!(written.contains(&"rax".to_string()));
    }

    #[test]
    fn a_call_at_a_width_no_register_holds_is_reported_on_either_side() {
        let i128 = Type::int(128);
        assert_eq!(
            make(&[i128], &[], false, &SYSV).2,
            Err(Refused { argument: Some(0), missing: Missing::Width })
        );
        assert_eq!(
            make(&[], &[i128], false, &SYSV).2,
            Err(Refused { argument: None, missing: Missing::Width })
        );
    }

    #[test]
    fn an_argument_wider_than_a_register_has_no_name() {
        assert_eq!(head_of(Type::int(128)), None);
        assert_eq!(head_of(Type::int(8)), Some("x64.arg_val_8"));
        assert_eq!(head_of(Type::int(64)), Some("x64.arg_val_64"));
    }

    /// An address arrives in a general purpose register like any other integer of its width, and
    /// used to be turned away here as a width no register holds, which is what issue 274 is.
    /// `int g(char *s)` is the smallest program that was.
    #[test]
    fn an_address_arrives_in_a_register_like_the_integer_it_is() {
        assert_eq!(head_of(Type::PTR), Some("x64.arg_val_64"));
        assert_eq!(
            bind(&[Type::PTR], &SYSV),
            "mfunc @f {\nblock0:\n    %0:gpr($rdi) = x64.arg_val_64\n}\n"
        );
        // And it travels the same way at a call, on both sides of one.
        assert!(make(&[Type::PTR], &[Type::PTR], false, &SYSV).2.is_ok());
    }
}