RFC: tail_chaincc - A Maximum-Efficiency Tail Call Convention

· LLVM Discussion Forums ·

15 min read Original article ↗

Summary

I propose to add a new calling convention (tentatively named tail_chaincc) to LLVM and Clang. This new convention is intended to be used with [[clang::musttail]] in C and C++ (and any other language that wants to use guaranteed tail calls with LLVM, e.g. become in Rust) and is designed to address several practical issues we have encountered when using tail calls.

This new convention combines the callee-cleanup mechanics of tailcc with the register optimizations of preserve_none, leading to an experience that is both ergonomic and high-performing. I expect that it should become the calling convention of choice for nearly all users of [[clang::musttail]].

I hope that this will help pave the way for language implementations and standards to support guaranteed tail calls more fully, resolving some of the caveats and headaches we encounter with tail calls today.

Note: if it is acceptable to break ABI compatibility of the existing tailcc convention, we could add the enhancements described here to the existing convention instead of adding a new one.

Background

Since 2021, Clang has supported the [[clang::musttail]] attribute for guaranteed tail calls. This Clang feature piggybacks on pre-existing musttail support that was added to LLVM IR in 2014.

I was previously motivated to add musttail support to Clang because a colleague and I discovered that parsing Protobufs using chains of tail calls performed better than any other technique that we tried, largely because it helped the compiler to generate more optimal register allocation sequences. I wrote up our results in my 2021 blog article Parsing Protobuf at 2+GB/s: How I Learned To Love Tail Calls in C, noting that the technique generalizes to programming language interpreters (and any code with a similar shape).

Since then, interest in tail calls has spread. Most notably, CPython released an experimental tail call interpreter in 3.14. This in turn led to more compiler support for musttail:

  • GCC added support in 2024 (docs, bug, announcement)
  • MSVC added support in 2025 (docs)
  • Rust added the become keyword to nightly in 2025 also (commit).

There has also been interest from standards bodies:

Motivation

While [[clang::musttail]] has been a powerful tool, it suffers from some significant problems when used with existing calling conventions.

The Matching Prototypes Rule

When LLVM added support for musttail to the IR in 2014, it came along with a constraint: the caller and callee have to have the same function signature. Reid Kleckner (@rnk), who added this feature, gives some history about why it was designed this way in his blog entry On Relaxing Musttail Prototype Requirements. Summarized, the intention was two-fold:

  1. Portability: by limiting musttail to cases where the stack frame (and crucially, the return address) should never need to shift, tail calls ideally become portable across architectures.
  2. Correctness: by giving the LLVM IR a strict rule about where musttail can appear, we ensure that compiler passes will not transform a valid program into an invalid one.

Both of these goals were at least partially accomplished. We can observe this by comparing Clang with GCC, which also added musttail support, but does not have this rule. Consider the following example:

int f(int a);

int g() {
    [[clang::musttail]] return f(1);
}

Clang rejects this in the frontend for failing the matching prototypes rule. GCC allows it in the frontend, and fully succeeds when compiling on architectures that pass a in a register. But on x86 (32-bit) compilation fails in the backend with:

<source>: In function 'int g()':
<source>:5:33: error: cannot tail-call: callee required more stack slots than the caller
    5 |     [[clang::musttail]] return f(1);

This is the kind of nonportability that Clang’s rule was intended to prevent.

GCC also has dealt with bugs like #118430 where optimization passes introduced breakage by rewriting the code in a way that breaks a tail call. Without a clear rule about when a tail call is allowed, breakage like this must be addressed on a case-by-case basis.

While the rule has clearly delivered some benefits, it has also led to many undesirable outcomes, while also not fully providing the intended reliability/portability.

Bad Developer UX

The first and most straightforward issue is the ergonomics. The matching prototype rule is conservative by nature: it imposes a blanket rule across all architectures in the name of portability.

In practice, the rule is more restrictive than necessary on many architectures. Consider a function like this:

int g();

int f(int x) {
  // Can easily be tail called on most architectures (since
  // x will be passed in registers).
  [[clang::musttail]] return g();
}

On any platform that passes arguments in registers, g() can be trivially tail call optimized, even using a caller-cleanup convention, because the arguments do not require any stack space.

Clang rejects the code above due to non-matching caller/callee prototypes, which has led to many complaints from developers, especially when one can plainly observe that a given tail call is possible to perform when musttail is omitted.

GCC allows the nonportable code above, and only raises an error if the tail call fails to lower on the current platform. This is more flexible but also less predictable. It also leads to inconsistent semantics between Clang and GCC.

Backend errors (failure to lower)

The matching prototype rule was designed to trade off flexibility in exchange for predictability and portability. In practice, it has not delivered the promised portability: since releasing [[clang::musttail]], we’ve had many reports of backend crashes even in well-behaved programs that follow the matching prototypes rule (e.g. #53271, #84090, #50758, #161193).

Unlike the other issues, this one probably could be worked through given enough time and attention. But the proposed convention can likely solve it more easily and systematically, while also improving the ergonomics and performance.

Performance Bottlenecks

The register assignments of standard calling conventions are not optimal for chains of tail calls. Many but not all of these issues have previously been addressed in the preserve_none calling convention. These issues are covered in detail in the proposal section below.

Prior Art

LLVM has an existing calling convention tailcc which uses a callee-cleanup design. As Eli Friedman (@efriedma-quic) pointed out in an earlier discussion, because tailcc is designed to allow tail calls in all cases, it is special-cased in LLVM IR to allow musttail even when the caller and callee function signatures do not match.

The downside of tailcc is that it lacks modern register optimizations (like preserve_none). Also, it is not exposed to Clang currently, so it is impossible to use from C or C++.

Note: as mentioned previously, if it is considered acceptable to modify the existing tailcc convention in place to have the behaviors described below, we could avoid introducing a new calling convention. The cost would be breaking the ABI compatibility of tailcc – I don’t know if this is considered a problem or not.

Proposal

I propose a new, dedicated calling convention:

  • LLVM: tail_chaincc
  • C/C++: __attribute__((tail_chain)), [[clang::tail_chain]]

The core idea is to marry the ergonomics of tailcc with the performance of preserve_none (plus a few novel performance tweaks) into a single calling convention that is optimal for chains of tail calls:

  • Like tailcc, it allows tail calls between functions in all cases, even if their signatures are different.
  • Like preserve_none, it adds many register optimizations that improve performance through chains of tail calls.

This will allow users to write code like this, and get maximum efficiency:

[[clang::tail_chain]] int g();

[[clang::tail_chain]] int f(int x) {
  // With tail_chain, this will work even though prototypes don't match!
  [[clang::musttail]] return g();
}

This new calling convention aspires to be the convention of choice for anyone using musttail. As a “best practice”, I hope that it would make standardization of musttail (or return goto) in C and C++ easier, and also be the convention of choice for Rust as it introduces guaranteed tail calls (become).

Features of the New Calling Convention

Rule 1: Callee-Cleanup Mechanics (currently in tailcc)

The callee is strictly responsible for popping its own stack arguments before returning. This mechanically enables [[clang::musttail]] to guarantee tail calls even when the caller and callee have differing argument signatures, allowing the compiler to dynamically adjust the stack frame prior to the jump.

On architectures that push the return address onto the stack (e.g. x86), a function may need to shift the return address before performing a tail call. Callee-cleanup makes this possible to do robustly since the old frame can be safely discarded and overwritten. There is a slight performance cost to shifting the return address, but this rarely occurs in practice, since arguments are usually passed in registers (especially with Rule 4).

Benefit: Enables tail calls in the backend even when caller and callee use different amounts of stack space.

Rule 2: Semantic Relaxation of musttail (currently in tailcc)

When caller and callee both use tail_chaincc, we no longer need the “matching prototypes” rule. The Clang frontend and the LLVM IR verifier can be relaxed to allow unlimited mixing and matching of caller and callee as long as both are using tail_chaincc.

However, the return types must still perfectly match. This is an existing limitation that universally applies to musttail, even with tailcc, but this limitation does not seem to be documented in the IR reference. We should document that return types must always match in the IR, and also enforce matching return types in the Clang frontend, even when tail_chaincc is in use.

Benefit: [[clang::musttail]] allows mismatched parameter lists (made possible by Rule 1).

Rule 3: Zero Callee-Save Registers (currently in preserve_none)

The convention treats all registers (general-purpose, floating point, and SIMD) as volatile/clobbered. This makes all registers available to the chain of functions without requiring them to be pushed/popped in the prologue and epilogue.

Callee-save registers make little sense with tail calls, because they impose limitations on the callee for the benefit of the caller. With chains of tail calls, we have N callees and only a single caller, so it’s more valuable to give callees as much flexibility as possible.

Benefit: More registers available for use without having to preserve them first.

Godbolt example: https://godbolt.org/z/8qnarn6qG (Notice that preserve_none avoids having to push/pop r14 and rbx)

Rule 4: Most registers are available for arguments (currently in preserve_none)

Since the tail call pattern requires storing all core state in arguments, we lift all restrictions on how many registers can be used for arguments. We allow the maximum number of arguments that is practically possible, rather than capping this number (e.g. at 6 registers on x86-64).

Benefit: Allows keeping a larger “working set” in registers across function calls.

Godbolt example: https://godbolt.org/z/TYqY8eETe

Rule 5: Optimized Register Allocation Order (partially in preserve_none)

To prevent unnecessary state spilling when a tail_chaincc function makes an intermediate non-tail call to a standard or preserve_most function, the argument register allocation priority is explicitly designed to minimize overlap by reversing the order used in normal functions.

x86-64 Argument Allocation Order: R12, R13, R14, R15, R11, R9, R8, RCX, RDX, RSI, RDI, RAX

Rationale: R12-R15 are traditional callee-saves, meaning standard functions will preserve them automatically. R11 is prioritized next as a scratch register never used for arguments in standard conventions. The argument registers are allocated in reverse order from normal calls, so that overlap only occurs if absolutely necessary (because the total number of arguments between the two functions exceeds the total number of available registers).

The same principle applies to other architectures also: this convention should allocate argument registers in the reverse order from what normal calling conventions (and preserve_most) would do.

Benefit: Reduces the need for register spills or shifts when calling other functions.

Godbolt example: https://godbolt.org/z/z9zcGne1h

Rule 6: Most registers are available for return values (not currently available in any convention)

Once the tail call chain returns, it is sometimes valuable to pass a significant amount of data back to the original caller. Most calling conventions cap the return value at two registers max. We lift this restriction and allow all of the argument registers to also be used as return values.

Benefit: Allows returning more data to the original caller efficiently. Also allows simulating callee-save registers by loading the caller’s state back into registers before returning.

Rule 7: Struct args/returns can use all available registers (not currently available in any convention)

Interpreter state is frequently bundled into a struct. Standard ABIs fall back to memory pointers (byval / sret) if a struct exceeds two registers (16 bytes), needlessly forcing data to the stack instead of passing it in registers.

This convention ignores those standard size constraints. Both arguments and returns can use the full set of available registers (the same set of registers mentioned in rules 4 and 6 above), with no artificial ceiling in the ABI.

The goal is to be able to write this:

struct State {
  long a, b, c, d, e, f, g, h;
};

[[clang::tail_chain]] int Func1(State state);

[[clang::tail_chain]] int Func2(State state) {
  // Do some stuff...
  [[clang::musttail]] return Func1(state);
}

Instead of this:

[[clang::tail_chain]] int Func1(
    long a, long b, long c, long d, long e, long f, long g, long h);

[[clang::tail_chain]] int Func2(
    long a, long b, long c, long d, long e, long f, long g, long h) {
  // Do some stuff...
  [[clang::musttail]] return Func1(a, b, c, d, e, f, g, h);
}

In addition to the efficiency benefits, passing structs in registers sidesteps tricky lifetime and ABI issues that arise when structs are passed indirectly via caller-allocated stack temporaries (such as #56435, or WebAssembly rejecting musttail on multi-field structs).

We preserve other characteristics of existing ABIs (for example, packing multiple struct members into a single register if they will fit). We simply lift the size ceiling.

Benefit: Allows grouping larger states into a single struct parameter rather than having to repeat a long parameter/argument list for every function and call.

Alternatives Considered

Relax the “Same Prototype” rule

Instead of introducing a new calling convention, we could relax the LLVM IR so that even calling conventions like preserve_none are allowed to use musttail with non-matching caller/callee. The compilation would then fail in the backend if the tail call cannot be performed on the current platform. This is the approach that GCC takes.

To indicate that this is not as “portable” as a standard [[clang::musttail]], it was proposed on #54964 to name this [[clang::nonportable_musttail]].

While this is attractive at first glance, there are significant practical barriers to making this work. Most notably, it makes it unpredictable from a language perspective whether a given program will compile or not. It would depend on intricate details of the calling convention that are difficult to describe.

Moreover, without a clear rule for the LLVM IR to follow, optimization passes could inadvertently change a valid program into an invalid one.

In contrast, tail_chaincc could provide both better predictability and better performance.

Open Questions

  • ABI Compatibility: Do custom calling conventions need to maintain ABI compatibility over time? Is it possible to opt out of a stable ABI (either temporarily or permanently) to allow for experimentation?

Future Possibilities

If LLVM and Clang adopt this calling convention, I anticipate that most existing users of musttail would benefit from adopting it. We would likely want to officially recommend it in the documentation for [[clang::musttail]].

In addition, it may help both the adoption and standardization of musttail across languages by addressing some of the most difficult blockers:

  • Rust: tail calls through the become keyword are an unstable feature. I hope that this proposal makes it easier to stabilize the feature:
  • C / C++: There is early interest in standardization (see “Background” section above); I hope that this proposal will help provide the predictability needed to define a standard behavior. While the default calling convention would still be unpredictable, users could opt into a convention that provides more predictable behavior.

One interesting possibility is to automatically opt local functions into the tail_chaincc calling convention if they are not exposed outside a single compilation unit (meaning they have no observable ABI) and are used with musttail. The C and C++ standards could also potentially carve out this behavior, guaranteeing that tail calls within a single file will always succeed, without needing to add calling convention annotations.

Addendum: Cross-DSO Linkage and Target-Specific Limitations

While tail_chaincc fully resolves stack memory and register allocation barriers to tail calls, it does not bypass fundamental architectural limitations imposed by the Operating System’s dynamic linker.

A known limitation of [[clang::musttail]] occurs when attempting to tail-call across Dynamic Shared Object (DSO) boundaries on architectures that rely on caller-restored global pointers (such as the TOC pointer on PowerPC or IA-64). This proposal does not address the DSO limitation.

There is a proposal to fix this for ELFv2. For ELFv1, it may also be fruitful to prohibit cross-DSO musttail, even when using tail_chaincc. However, these issues also exist with tailcc, so would not be unique to this proposal.

Thanks to Guozhi Wei, Charles Munger, and Chandler Carruth for discussions and feedback on earlier drafts of this proposal.

References