stabilize extern "custom"

[folkertdev]

tracking issue: #140829
reference PR: rust-lang/reference#2300
closes #140829

Summary

An extern "custom" fn is a function with a custom ABI that is unknown to rust. Often these are low-level functions that pass arguments in different registers than any standard calling convention.

#[unsafe(naked)]
pub unsafe extern "custom" fn __aeabi_uidivmod() {
    core::arch::naked_asm!(
        "push {{lr}}",
        "sub sp, sp, #4",
        "mov r2, sp",
        "bl {trampoline}",
        "ldr r1, [sp]",
        "add sp, sp, #4",
        "pop {{pc}}",
        trampoline = sym crate::arm::__udivmodsi4
    );
}

unsafe extern "custom" {
	fn __fentry__();
}

Design

Because rust doesn't know what calling convention to use, an extern "custom" function can only be called via inline assembly or FFI.

error: functions with the "custom" ABI cannot be called
 --> <source>:5:5
  |
5 |     bar();
  |     ^^^^^
  |
note: an `extern "custom"` function can only be called using inline assembly

An extern "custom" function definition must be a naked function:

error: items with the "custom" ABI can only be declared externally or defined via naked functions
  --> <source>:10:1
   |
10 | unsafe extern "custom" fn bar() {
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
help: convert this to an `#[unsafe(naked)]` function
   |
10 + #[unsafe(naked)]
11 | unsafe extern "custom" fn bar() {
   |

An extern "custom" function definition must be unsafe. The intent here is that a safety comment is written on how this function may be called.

error: functions with the "custom" ABI must be unsafe
  --> <source>:10:1
   |
10 | extern "custom" fn bar() {
   | ^^^^^^^^^^^^^^^^^^^^^^^^
   |
help: add the `unsafe` keyword to this definition
   |
10 | unsafe extern "custom" fn bar() {
   | ++++++

In an extern "custom" block, functions cannot be marked as safe:

error: foreign functions with the "custom" ABI cannot be safe
  --> <source>:16:5
   |
16 |     safe fn foobar();
   |     ^^^^^^^^^^^^^^^^^
   |
help: remove the `safe` keyword from this definition
   |
16 -     safe fn foobar();
16 +     fn foobar();

Tests

• tests/ui/abi/custom.rs tests that the feature works as expected, e.g. that functions can be defined, symbols are defined, and extern blocks can be used.
• tests/ui/abi/bad-custom.rs checks the restrictions: definitions must be unsafe and naked, attempting to call an extern "custom" function gives an error, etc.

History

• Lang proposal: extern "unspecified" for naked functions with arbitrary ABI #140566
• Tracking Issue for abi_custom #140829
• add extern "custom" functions #140770

unresolved questions

None

[folkertdev]

r? tgross35

[rustbot]

tgross35 is currently at their maximum review capacity.
They may take a while to respond.

[rustbot]

compiler-builtins is developed in its own repository. If possible, consider making this change to rust-lang/compiler-builtins instead.

cc @tgross35

[rust-bors]

☔ The latest upstream changes (presumably #158524) made this pull request unmergeable. Please resolve the merge conflicts by rebasing.

[bjorn3]

Do we deny this on wasm? Wasm requires the function signature to be known when defining or importing it.

[folkertdev]

In that case, does the whole concept of a naked function even make sense there? That is, can it do something that a normal function whose body is an asm! block cannot do?

Practically inline assembly is unstable (and extremely incomplete) for wasm, so I'm not sure if/how it'll eventually fit in.

But we can deny extern "custom" on wasm if that seems best right now.

[bjorn3]

Naked asm can avoid touching the stack, maybe there are cases that is useful? Naked asm doesn't help for defining functions that use ref types or GC types as there isn't a way to express those using rust syntax, so those still need global_asm!().