Proposal: Introduce `asm fn` to replace `callconv(.naked)`

[alexrp]

Background & Motivation

Some context:

• start: Avoid string concatenation in inline asm. #21056
• add error for stack allocation in naked functions #72
• Return value of inline functions called from .Naked functions cause stack allocations #21193
• Call functions in naked function #18183
• Proposal: A definition of naked functions based on comptime evaluation #21415

As can be seen from these issues, we're having to come up with a growing list of language rules to make naked functions work reliably, and I worry that we're going to keep running into edge cases in both the language and compiler implementation that will need special handling for naked functions. These rules add extra complexity throughout Sema, and they're really just trying to contend with a rather simple reality: All compilers that implement GCC-style inline assembly and naked functions, including LLVM, consider asm statements to be the only well-defined contents of naked functions. This is a reasonable stance for a compiler to take because, in the absence of an ABI-compliant prologue and epilogue, there are very few constructs that can be lowered correctly. It also makes a lot more sense if you think of naked functions as just being a convenient language feature for emitting a black box of machine instructions in function form, which is how GCC/Clang define them.

Rather than this growing list of language rules and the implementation complexity that come with them, I'd like to suggest what I think will be a simpler way of specifying and implementing naked functions. This proposal will make Zig's naked functions match the GCC/Clang definition and therefore also conform to LLVM's requirements.

(Note that some elements of this proposal are not unique to it; for example, the asm restrictions that I describe below will have to be adopted in some form even if this particular proposal is rejected.)

Proposal

An fn decl prefixed with asm is known as an assembly function (AKA naked function). Such a function cannot be annotated with inline, noinline, or extern, and must have a body. Its calling convention must be specified explicitly and cannot be auto, async, or inline.

The compiler treats an assembly function as a black box for the purposes of optimization and code generation; reachable calls to an assembly function cannot be inlined, reordered, or elided. The compiler will perform basic scaffolding for an assembly function, such as defining the symbol in the resulting object file, but it will not emit any machine instructions in the function body - not even the usual prologue and epilogue. The programmer is expected to provide the implementation by way of inline assembly.

The above definition has some notable consequences:

• The compiler cannot, in the general case, emit valid code to access argument values in an assembly function. Therefore, accessing arguments by name is simply not permitted; instead, the programmer must be aware of the calling convention and unique constraints within the function, and write inline assembly to access them. To go with this, the compiler will not issue its usual "unused parameter" errors in assembly functions.
• Some calling convention options that ordinarily affect a function's implementation, such as incoming_stack_alignment, will have no effect in an assembly function unless the programmer explicitly writes inline assembly code equivalent to what the compiler would normally have emitted.
• return and try expressions are not permitted in an assembly function regardless of what its return type is.

An assembly function has its body comptime-evaluated during semantic analysis; that is, its body is implicitly a comptime { ... } block. During this evaluation, asm expressions that are lexically contained within the assembly function are recorded rather than executed, and have some additional restrictions (see below). Besides this, all the usual comptime rules apply. After comptime evaluation finishes, the function's body is formed in full by concatenating and assembling the recorded asm expressions, in the order they were analyzed. No further compiler transformations are performed on the function body. (Note: The semantics here are very similar to container-level comptime blocks and the way global asm expressions are treated there, but note #24077.)

In an assembly function, there are some additional restrictions for asm expressions:

• They must be marked volatile.
• Inputs are allowed but with some restrictions.
  • The operand must be a comptime-known value, which includes addresses of fn decls and container-level var/const decls.
• Outputs are allowed but with some restrictions.
  • The operand must be a mutable comptime-known pointer - practically limiting it to pointers into container-level var decls.
  • Result outputs are not allowed as they're effectively meaningless in an assembly function.
• Clobbers are not allowed as assembly functions are already assumed to clobber all calling convention registers and memory.

Example

Just to illustrate, here's how an asm fn would actually look:

const builtin = @import("builtin");

fn includeDwarfCfiDirectives() bool {
    return builtin.unwind_tables != .none or !builtin.strip_debug_info;
}

pub asm fn clone(
    func: *const fn (arg: usize) callconv(.c) u8,
    stack: usize,
    flags: u32,
    arg: usize,
    ptid: ?*i32,
    tp: usize,
    ctid: ?*i32,
) callconv(.c) usize {
    asm volatile (
        \\ movl $56, %%eax // SYS_clone
        \\ movq %%rdi, %%r11
        \\ movq %%rdx, %%rdi
        \\ movq %%r8, %%rdx
        \\ movq %%r9, %%r8
        \\ movq 8(%%rsp), %%r10
        \\ movq %%r11, %%r9
        \\ andq $-16, %%rsi
        \\ subq $8, %%rsi
        \\ movq %%rcx, (%%rsi)
        \\ syscall
        \\ testq %%rax, %%rax
        \\ jz 1f
        \\ retq
        \\1:
    );
    // This if condition is implicitly comptime...
    if (includeDwarfCfiDirectives()) {
        // ... and this asm is only included in the function body if the condition evaluated to true.
        asm volatile (
            \\ .cfi_undefined %%rip
        );
    }
    asm volatile (
        \\ xorl %%ebp, %%ebp
        \\ popq %%rdi
        \\ callq *%%r9
        \\ movl %%eax, %%edi
        \\ movl $60, %%eax // SYS_exit
        \\ syscall
    );
}

See Also

• parse inline assembly syntax according to a set of dialects; integrate inline assembly more closely with the zig language #10761
• add an assembler to the toolchain #21169
• Proposal: Eliminate global assembly from the language #24077

[alexrp]

Updated the proposal to require that asms are marked volatile in asm fns since, as @mlugg pointed out, regular asm makes little sense here when the compiler is supposed to treat the function as a black box and emit assembly code exactly as instructed.

[rohlem]

I'm surprised by the restriction to disallow inline (as in inline asm fn),
but I guess status-quo asm in an inline fn without runtime arguments should already behave the same?
It would feel natural to me to have explicit inline asm fn syntax to opt into restrictions to similarly guard against stack allocations.
Or would that introduce some other unwanted complexity?

[mlugg]

Question: can the asm statements be in a function called from the asm fn (at comptime), or do they have to be directly in the asm fn? i.e.:

pub asm fn nop() callconv(.c) usize {
    emitRet(); // implicitly called at comptime
}
fn emitRet() void {
    asm volatile ("ret");
}

Arguments against:

• This is bad for readability; you now need to check all the functions you call to see if they secretly emit code (and hence perhaps e.g. clobber your registers)
  • The clobbering issue also makes this code harder to write
• If people forget to check the bodies of functions being called, they might miss some crucial asm in the function without ever realising
• Allowing this would force some validation to happen during semantic analysis rather than AST validation; for instance, if the above snippet wrote asm instead of asm volatile, we wouldn't be able to catch that error until semantic analysis resolved the comptime call to emitRet in nop

Arguments for:

• I guess this is analagous to calling an inline function in normal code, where it can add runtime code to the caller? But I don't think that's a very good argument; calling an inline fn isn't going to randomly clobber the caller's variables

In case it wasn't clear from those lists, I hold the "against" opinion right now.

---

EDIT: ah, I think you meant to imply it was disallowed here (emphasis my own):

asm expressions that are lexically contained within the assembly function are recorded

[alexrp]

EDIT: ah, I think you meant to imply it was disallowed here (emphasis my own):

That's right. I think recording asms inside comptime-called functions would be too confusing/complex. Such asms should just result in an error like they would today if evaluated at comptime.

[mlugg]

@rohlem there is no way in status quo Zig, or under this proposal, to prevent the compiler from adding stack allocations between different blocks of inline assembly in a non-naked function. But... why on earth would you want to? The reason asm fns need to avoid stack allocations is because the compiler doesn't know what the stack looks like, or even that there necessarily is a stack. This restriction clearly does not apply if the assembly is being included in a "normal" function, because such functions can only be called with a valid stack controlled by the compiler. The extension you are proposing is not obvious, and introduces language complexity which we'd clearly be better off without if there's no use case for it. If you can provide a clear use case, perhaps an extension could be considered.

[rohlem]

@mlugg inline asm fn follow-up

why on earth would you want to? [...] The extension you are proposing is not obvious [...] .

This proposal looks to me like a neat mechanism for generating a comptime-configured (stitched together) asm block.
Without inline, it holds the restriction that all users have to go through a function call via a calling convention to use it.
That means if there were a use case that wants to generate assembly without the function call, they're stuck generating and inlining it by hand.

If you can provide a clear use case, perhaps an extension could be considered.

I don't currently have one, but I thought it could be used for inlining any configurable, reusable asm block that does some work and cleans up after itself, and doesn't need a function call to do so.
E.g. it could save things to the stack (if the programmer knows one exists), do work, then restore everything local to the previous state.

Or would that introduce some other unwanted complexity?

The extension you are proposing [...] introduces language complexity which we'd clearly be better off without [...] .

I don't see that complexity yet, that's why I asked.
In my mind it could "just" be an inline fn without arguments, with similar restrictions to the proposed asm fn, that stitches asm blocks together like the proposed asm fn.
If you say "that's useless", I'll wait until I have a use case.
If you say "that's too complex", that makes me curious as to why/how! (sorry >.>)

[ikskuh]

I described some potential use cases in #24077 where "comptime dynamic" vector table generation might be solved by this instead of using assembly concatenation