RFC: Interrupt calling conventions

[phil-opp]

Add compiler support for interrupt calling conventions that are specific to an architecture or target. This way, interrupt handler functions can be written directly in Rust without needing assembly shims.

While there are already some unstable implementations of interrupt calling conventions in rustc, they were only added for experimentation. As these calling conventions showed their worth over the years, the lang team requested an RFC for interrupt calling conventions general, to put them on a path towards stabilization. So this RFC tries to provide the necessary groundwork for such calling conventions.

Rendered

Pre-RFC discussion on internals

[nikomatsakis]

To be sure I understand, this RFC is not proposing any specific interrupt ABI, but simply talking about the idea of interrupt handler ABIs and what their requirements would be?

[phil-opp]

To be sure I understand, this RFC is not proposing any specific interrupt ABI, but simply talking about the idea of interrupt handler ABIs and what their requirements would be?

Yes, exactly. I added some more context to the PR description. The plan is to use this RFC as a foundation, so that we don't need separate RFCs for each individual interrupt ABI. See @joshtriplett's comment in rust-lang/rust#40180 (comment) for more details.

[bjorn3]

Maybe use usize as error code type instead?

[tbu-]

I think it makes sense being explicit here. usize isn't necessarily defined to be the width of a register.

[nikomatsakis]

I'm in favor of this. I guess this is a @rust-lang/lang decision, but I would want @rust-lang/compiler input too!

[fweimer]

This needs to say that interrupt routines are implicitly unsafe. Even if the interrupt routine only calls safe Rust functions, it can easily observe intermediate CPU states that are beyond the Rust safety model, or corrupt the state so that undefined behavior occurs after the interrupt routine returns.

[phil-opp]

Could you clarify what you mean by "implictly unsafe"? That they should be treated like an unsafe fn so that no unsafe {} blocks are required in it?

I agree this question is something that we should specify in the RFC in more detail. My opinion on this is that we should keep the function body safe, but make all dangerous operations unsafe:

• Functions with interrupt calling conventions cannot be called from Rust code directly, so there is no way to cause undefined behavior using only safe code.
• To register a interrupt handler function on the CPU, you typically need some unsafe code (e.g. inline asm) or place it at a specific address using a linker script (which allow all kinds of unsafe operations). In this "unsafe" code, you need to make sure that the referenced function fulfills all necessary safety invariants.
• We should try to make all operations that corrupt the CPU state unsafe, if possible. For example, the x86_64 crate requires an unsafe block to modify the passed InterruptStackFrame. Ideally, this unsafe block should be required directly by the compiler, for example by requiring raw pointer arguments instead of references for the x86-interrupt calling convention.

I'm happy to discuss this further!

[fweimer]

What I meant is that even if the function is not marked as unsafe, the usual rules about Rust memory safety do not apply at all to these functions. There are a lot of restrictions that have to be followed, depending on the rest of the system, and I'm not sure if Rust is actually up for that. (With C or C++, separate compilation with different compiler flags is sometimes used.)

[Lokathor]

That seems like a case by case basis as to how safe each ABI is going to be. The interrupt handler function ABI could (for example) have additional pre and post code inserted by rustc automatically so that the user's source code always runs in a safe environment.

Like we can literally make up these ABIs to do whatever, since normal code is never going to interface with the interrupt handler code.

[nikomatsakis]

@fweimer can you elaborate a bit more about what rules re: Rust memory safety are inapplicable? The function doesn't get access to anything but static data, right?

[Lokathor]

Ah, I see your point. Well then at least the situations I was talking about are fine enough if the compiler is handling it. Though, perhaps fweimer had something else in mind.

[fweimer]

@nikomatsakis Some mutex implementations have fast paths for single-threaded operation that do not do anything. I think this would enable an interrupt routine to access data behind a mutex while the interrupted program uses it. (We change pthread_mutex_lock to always perform the mutex update only in EDIT glibc 2.34—starting with that version, single-threaded processes should self-deadlock if the mutex is acquired twice.)

[bjorn3]

Once you introduce interrupts you are effectively no longer a single-threaded process as the easiest way to model interrupts in the rust abstract machine is as running on a separate thread which could synchronize with the non-interrupt thread using regular concurrency methods. It just so happens that while the interrupt runs, the non-interrupt thread doesn't make any progress and thus you may deadlock if you wait for it.

[chorman0773]

I don't think it can be treated the same as a separate thread precisely because it blocks the non-interrupt code while running and is identified as the same thread.

I've equated it to a signal handler before, which is far more limited in what it can do.

[fweimer]

@bjorn3 The single-thread optimization is an internal C runtime thing that gets disabled if you create another thread using a C runtime facility. The C runtime won't know about the interrupt code and therefore cannot treat the application as multi-threaded.

[mark-i-m]

I still think I would rather have custom calling conventions in general (i.e., allow me to define my own calling convention and use it). There are a few reasons I think a more general mechanism might be better:

• I think that could play nicely with naked functions.
• It would also allow defining architecture-specific conventions in libraries (e.g., as macros) rather than hardcoding them all into the compiler.
• It would allow people to use custom conventions for things that are not interrupts (e.g., trap and syscall handlers, userspace thread switchers, signal handlers, etc).

[bjorn3]

While that is a nice idea IMO, neither LLVM, nor GCC, nor Cranelift support that at the moment.

[mark-i-m]

I don't see why it needs to be. It seems buildable with naked functions and inline assembly. Custom calling conventions would just be sugar with some extra compiler support for checking arguments, generating function prologue/epilogue, etc...

[phil-opp]

It seems buildable with naked functions and inline assembly.

You only need to save the registers that are overwritten by called functions. The register selection happens in LLVM, so it's not possible to know this earlier. So using naked functions, you need to save and restore all registers, which is more expensive.

[mark-i-m]

@phil-opp I guess my expectation is that anything using a custom calling convention would not be callable from Rust. Moreover, the calling convention would specify who needs to save and restore what registers anyway.

[phil-opp]

Moreover, the calling convention would specify who needs to save and restore what registers anyway.

But how can we implement this without LLVM support?

[mark-i-m]

I imagine something like this (bikesheddable syntax):

// I haven't fully though through what this would look like...
#[calling_convention(
  name="mark-weird-exception-handler",
  arch="x86_64",
  // custom prologue and epilogue allow setting up the stack or any other state however you want...
  prologue = asm!(...),
  epilogue = asm!(...),
  args=["regs: Regs", "error_code: u64"], // function with this convention must have these arguments
)]

#[no_mangle]
fn extern "mark-weird-exception-handler" handler(regs: Regs, error_code: u64) {
  println!("{regs} {error_code:X}");
  // other code
}

would desugar to something like this:

#[naked]
#[no_mangle]
fn handler() {
  <prologue> // from the calling convention spec above

  asm!("call _handler_inner");

  <epilogue> // from the calling convention spec above
}

#[no_mangle]
fn extern "C" _handler_inner(regs: Regs, error_code: u64) {
   println!("{regs} {error_code:X}");
  // other code
}

The basic idea is that the custom calling convention is tasked with converting a weird calling convention into something the compiler can work with normally (e.g., the C or Rust calling conventions, though I prefer C, since it is specified and gives more control). I think this mostly means fixing up the stack, but it could also include other stateful things, such as enabling/disabling interrupts, fixing up page tables, etc.

The custom calling convention then becomes a simple trampoline mechanism into more normal Rust code.

[phil-opp]

The issue with this approach is that you have to write the assembly for the prologue and epilogue yourself. This includes saving and restoring all registers (on many platforms). To do that in an optimal way, you need to know which registers are actually overwritten by _handler_inner. However, this is not decided until LLVM performs register allocation. So without LLVM support you need to save all registers instead.

One way to work around that problem could be to use LLVM's preserve_all calling convention for your _handler_inner function. This way, LLVM would generate code that automatically restores all registers to their original values before returning, so we would not need to do it manually anymore. The RFC already describes this idea in the "rationale and alternatives" section at the end. I'm happy to explore and discuss this approach further!

[mark-i-m]

@phil-opp I see. But I'm wondering at the use case -- how important is it to use the minimal set of registers? AFAIK, most kernels save all (general-purpose) registers anyway (e.g., Linux, FreeBSD). If you are planning to do any substantial work during the interrupt/exception handler, you will need to save all of that state anyway -- either because you want to context switch to somewhere else or because you have enough code that the extra registers will be useful.

Are you thinking of an embedded systems use case or something?

[phil-opp]

I don't have any realistic use cases, but you can easily construct an example where the LLVM-generated code is much better:

static TICKS: AtomicUsize = AtomicUsize::new(0);
const THRESHOLD: usize = 10000;

#[no_mangle]
pub extern "x86-interrupt" fn timer_handler(_stack_frame: u8) {
    let prev = TICKS.fetch_add(1, Ordering::Acquire);
    if prev > THRESHOLD {
        // trigger a "context switch" interrupt 
        unsafe { asm!("int 0xf0"); }
    }
}

We want to count the timer ticks with minimal overhead. If a specified threshold value is passed, we trigger a secondary interrupt, which will save the registers and perform a context switch.

When you try this example on godbolt, you see that rustc generates the following assembly:

timer_handler:
        push    rax
        cld
        mov     eax, 1
        lock            xadd    qword ptr [rip + example::TICKS], rax
        cmp     rax, 10000
        jbe     .LBB0_1

        int     240

        pop     rax
        iretq
.LBB0_1:
        pop     rax
        iretq

example::TICKS:
        .zero   8

So we only save and restore the rax register, which leads to a much lower overhead, especially if the timer interrupt fires frequently.

[Lokathor]

We certainly should consider "some sort of embedded use case" to be the primary use case with this sort of thing. In which case all register savings are a big win.

[phil-opp]

We certainly should consider "some sort of embedded use case" to be the primary use case with this sort of thing. In which case all register savings are a big win.

Yes, I agree! Does someone have a similar example for some embedded device? Then I'd be happy to extend the motivation section of the RFC based on that.

[Lokathor]

On the GBA we're using an assembly interrupt handler which reads a nullable function pointer to an extern "C" fn(u16) (which is presumably written in Rust). If the assembly reads a non-null value then it has to mode switch, align the stack in system mode, save some registers, do the call, and then undo all that. If a custom handler ABI was allowed for use we could just skip over the register saving and stack alignment steps and have LLVM handle any necessary work in each particular extern "gba-irq" fn(u16) implementation.

[chorman0773]

I posted this on the tracking issue but it makes sense to cross-post to the RFC.

In 32-bit x86 mode, the StackFrame struct can vary dynamically - depending on the call cs.CPL (which may or may not end up in saveCS[1:0]). Specifically, ss:eSP are only pushed by the CPU when calling a lower privileged gate, and only popped when returning to higher privileged code (gate.selector.RPL<CPL, and CPL<cs.RPL respectively - note that it's impossible jump to a higher privileged gate, nor iret to lower privileged code). IDK how or if llvm (and thusly rustc) takes this into account, but that may be a blocker for x86. Note that this does not affect x86_64 - in long mode ss:RSP are always pushed and iret in 64-bit mode (which is almost always the case) always pops ss:RSP.

[nyabinary]

What's the status of this RFC?

[natevw]

Should the RISC-V interrupt (rust-lang/rust#111889) be added to the final paragraph of the Motivations section as well?