add `extern "custom"` functions by folkertdev · Pull Request #140770 · rust-lang/rust

folkertdev · 2025-05-07T20:26:31Z

tracking issue: #140829
previous discussion: #140566

In short, an extern "custom" function is a function with a custom ABI, that rust does not know about. Therefore, such functions can only be defined with #[unsafe(naked)] and naked_asm!, or via an extern "C" { /* ... */ } block. These functions cannot be called using normal rust syntax: calling them can only be done from inline assembly.

The motivation is low-level scenarios where a custom calling convention is used. Currently, we often pick extern "C", but that is a lie because the function does not actually respect the C calling convention.

At the moment "custom" seems to be the name with the most support. That name is not final, but we need to pick something to actually implement this.

r? @traviscross
cc @tgross35

try-job: x86_64-apple-2

rustbot · 2025-05-07T20:26:39Z

These commits modify compiler targets.
(See the Target Tier Policy.)

rustbot · 2025-05-07T20:53:08Z

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

Some changes occurred in compiler/rustc_codegen_gcc

cc @antoyo, @GuillaumeGomez

bjorn3 · 2025-05-08T18:39:10Z

Emit some extern "custom" errors in ast_validation:wq

Did you forget to press escape before quitting vim?

folkertdev · 2025-05-08T18:45:19Z

ah, yeah. Well it'll probably get squashed before this is ready

folkertdev · 2025-05-08T20:59:28Z

I've made a proper tracking issue at #140829

bors · 2025-05-17T07:02:22Z

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

bors · 2025-06-04T03:24:22Z

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

folkertdev · 2025-06-12T22:52:08Z

Looks like the job that failed with the npm stuff got re-run? In any case, it's green now, the try build worked, so

@bors r=@tgross35

bors · 2025-06-12T22:52:11Z

📌 Commit 5f73ce2 has been approved by tgross35

It is now in the queue for this repository.

Rollup of 9 pull requests Successful merges: - #128425 (Make `missing_fragment_specifier` an unconditional error) - #135927 (retpoline and retpoline-external-thunk flags (target modifiers) to enable retpoline-related target features) - #140770 (add `extern "custom"` functions) - #142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - #142248 (Add supported asm types for LoongArch32) - #142267 (assert more in release in `rustc_ast_lowering`) - #142274 (Update the stdarch submodule) - #142276 (Update dependencies in `library/Cargo.lock`) - #142308 (Upgrade `object`, `addr2line`, and `unwinding` in the standard library) Failed merges: - #140920 (Extract some shared code from codegen backend target feature handling) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various

Rollup merge of #140770 - folkertdev:custom-abi, r=tgross35 add `extern "custom"` functions tracking issue: #140829 previous discussion: #140566 In short, an `extern "custom"` function is a function with a custom ABI, that rust does not know about. Therefore, such functions can only be defined with `#[unsafe(naked)]` and `naked_asm!`, or via an `extern "C" { /* ... */ }` block. These functions cannot be called using normal rust syntax: calling them can only be done from inline assembly. The motivation is low-level scenarios where a custom calling convention is used. Currently, we often pick `extern "C"`, but that is a lie because the function does not actually respect the C calling convention. At the moment `"custom"` seems to be the name with the most support. That name is not final, but we need to pick something to actually implement this. r? `@traviscross` cc `@tgross35` try-job: x86_64-apple-2

Rollup of 9 pull requests Successful merges: - rust-lang/rust#128425 (Make `missing_fragment_specifier` an unconditional error) - rust-lang/rust#135927 (retpoline and retpoline-external-thunk flags (target modifiers) to enable retpoline-related target features) - rust-lang/rust#140770 (add `extern "custom"` functions) - rust-lang/rust#142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - rust-lang/rust#142248 (Add supported asm types for LoongArch32) - rust-lang/rust#142267 (assert more in release in `rustc_ast_lowering`) - rust-lang/rust#142274 (Update the stdarch submodule) - rust-lang/rust#142276 (Update dependencies in `library/Cargo.lock`) - rust-lang/rust#142308 (Upgrade `object`, `addr2line`, and `unwinding` in the standard library) Failed merges: - rust-lang/rust#140920 (Extract some shared code from codegen backend target feature handling) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various

Kobzol · 2025-06-17T06:28:12Z

@rust-timer build 2bf564a

(Testing #142443)

rust-timer · 2025-06-17T09:19:05Z

Finished benchmarking commit (2bf564a): comparison URL.

Overall result: no relevant changes - no action needed

Benchmarking this pull request means it may be perf-sensitive – we'll automatically label it not fit for rolling up. You can override this, but we strongly advise not to, due to possible changes in compiler perf.

@bors rollup=never
@rustbot label: -S-waiting-on-perf -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results (primary 2.0%, secondary -1.9%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	2.0%	[2.0%, 2.0%]	1
Regressions ❌ (secondary)	3.0%	[3.0%, 3.0%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-6.7%	[-6.7%, -6.7%]	1
All ❌✅ (primary)	2.0%	[2.0%, 2.0%]	1

Cycles

Results (secondary 2.9%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	5.3%	[4.5%, 6.1%]	2
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-1.8%	[-1.8%, -1.8%]	1
All ❌✅ (primary)	-	-	0

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 755.964s -> 690.275s (-8.69%)
Artifact size: 372.26 MiB -> 372.29 MiB (0.01%)

…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#128425 (Make `missing_fragment_specifier` an unconditional error) - rust-lang#135927 (retpoline and retpoline-external-thunk flags (target modifiers) to enable retpoline-related target features) - rust-lang#140770 (add `extern "custom"` functions) - rust-lang#142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - rust-lang#142248 (Add supported asm types for LoongArch32) - rust-lang#142267 (assert more in release in `rustc_ast_lowering`) - rust-lang#142274 (Update the stdarch submodule) - rust-lang#142276 (Update dependencies in `library/Cargo.lock`) - rust-lang#142308 (Upgrade `object`, `addr2line`, and `unwinding` in the standard library) Failed merges: - rust-lang#140920 (Extract some shared code from codegen backend target feature handling) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various

Rollup of 9 pull requests Successful merges: - rust-lang/rust#128425 (Make `missing_fragment_specifier` an unconditional error) - rust-lang/rust#135927 (retpoline and retpoline-external-thunk flags (target modifiers) to enable retpoline-related target features) - rust-lang/rust#140770 (add `extern "custom"` functions) - rust-lang/rust#142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - rust-lang/rust#142248 (Add supported asm types for LoongArch32) - rust-lang/rust#142267 (assert more in release in `rustc_ast_lowering`) - rust-lang/rust#142274 (Update the stdarch submodule) - rust-lang/rust#142276 (Update dependencies in `library/Cargo.lock`) - rust-lang/rust#142308 (Upgrade `object`, `addr2line`, and `unwinding` in the standard library) Failed merges: - rust-lang/rust#140920 (Extract some shared code from codegen backend target feature handling) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various

add `extern "custom"` functions tracking issue: rust-lang#140829 previous discussion: rust-lang#140566 In short, an `extern "custom"` function is a function with a custom ABI, that rust does not know about. Therefore, such functions can only be defined with `#[unsafe(naked)]` and `naked_asm!`, or via an `extern "C" { /* ... */ }` block. These functions cannot be called using normal rust syntax: calling them can only be done from inline assembly. The motivation is low-level scenarios where a custom calling convention is used. Currently, we often pick `extern "C"`, but that is a lie because the function does not actually respect the C calling convention. At the moment `"custom"` seems to be the name with the most support. That name is not final, but we need to pick something to actually implement this. r? `@traviscross` cc `@tgross35` try-job: x86_64-apple-2

Rollup of 9 pull requests Successful merges: - rust-lang/rust#128425 (Make `missing_fragment_specifier` an unconditional error) - rust-lang/rust#135927 (retpoline and retpoline-external-thunk flags (target modifiers) to enable retpoline-related target features) - rust-lang/rust#140770 (add `extern "custom"` functions) - rust-lang/rust#142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - rust-lang/rust#142248 (Add supported asm types for LoongArch32) - rust-lang/rust#142267 (assert more in release in `rustc_ast_lowering`) - rust-lang/rust#142274 (Update the stdarch submodule) - rust-lang/rust#142276 (Update dependencies in `library/Cargo.lock`) - rust-lang/rust#142308 (Upgrade `object`, `addr2line`, and `unwinding` in the standard library) Failed merges: - rust-lang/rust#140920 (Extract some shared code from codegen backend target feature handling) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various

…, r=tgross35 Stabilize `extern "custom"` tracking issue: rust-lang#140829 reference PR: rust-lang/reference#2300 closes rust-lang#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. ```rust #[unsafe(naked)] pub unsafe extern "custom" fn __aeabi_uidivmod() { core::arch::naked_asm!( "push {{lr}}", "sub sp, sp, rust-lang#4", "mov r2, sp", "bl {trampoline}", "ldr r1, [sp]", "add sp, sp, rust-lang#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(); ``` An `extern "custom"` function cannot have any arguments or a return type: ``` error: invalid signature for `extern "custom"` function --> <source>:6:31 | 6 | unsafe extern "custom" fn foo(a: i32) -> i32 { | ^^^^^^ ^^^ | = note: functions with the "custom" ABI cannot have any parameters or return type help: remove the parameters and return type | 6 - unsafe extern "custom" fn foo(a: i32) -> i32 { 6 + unsafe extern "custom" fn foo() { | ``` ## Tests - [tests/ui/abi/custom.rs](https://github.com/rust-lang/rust/blob/main/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](https://github.com/rust-lang/rust/blob/main/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 * rust-lang#140566 * rust-lang#140829 * rust-lang#140770 * rust-lang#159780 ## unresolved questions None

Rollup merge of #158504 - folkertdev:stabilize-extern-custom, r=tgross35 Stabilize `extern "custom"` 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. ```rust #[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(); ``` An `extern "custom"` function cannot have any arguments or a return type: ``` error: invalid signature for `extern "custom"` function --> <source>:6:31 | 6 | unsafe extern "custom" fn foo(a: i32) -> i32 { | ^^^^^^ ^^^ | = note: functions with the "custom" ABI cannot have any parameters or return type help: remove the parameters and return type | 6 - unsafe extern "custom" fn foo(a: i32) -> i32 { 6 + unsafe extern "custom" fn foo() { | ``` ## Tests - [tests/ui/abi/custom.rs](https://github.com/rust-lang/rust/blob/main/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](https://github.com/rust-lang/rust/blob/main/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 * #140566 * #140829 * #140770 * #159780 ## unresolved questions None

rustbot assigned traviscross May 7, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels May 7, 2025

This comment has been minimized.

Sign in to view

folkertdev force-pushed the custom-abi branch from f61cada to 847b357 Compare May 7, 2025 20:53

bjorn3 reviewed May 7, 2025

View reviewed changes

Comment thread compiler/rustc_smir/src/stable_mir/abi.rs

This comment has been minimized.

Sign in to view

folkertdev force-pushed the custom-abi branch from 847b357 to 93971b9 Compare May 7, 2025 22:17

tgross35 reviewed May 7, 2025

View reviewed changes

Comment thread compiler/rustc_passes/src/custom_abi.rs Outdated

This comment has been minimized.

Sign in to view

mejrs reviewed May 7, 2025

View reviewed changes

Comment thread compiler/rustc_passes/src/custom_abi.rs Outdated

Comment thread compiler/rustc_passes/messages.ftl Outdated

Comment thread compiler/rustc_smir/src/stable_mir/abi.rs

traviscross reviewed May 8, 2025

View reviewed changes

Comment thread tests/ui/abi/custom.rs

tgross35 reviewed May 8, 2025

View reviewed changes

Comment thread tests/ui/abi/bad-custom.rs Outdated

folkertdev force-pushed the custom-abi branch from 93971b9 to a72606d Compare May 8, 2025 15:44

This comment has been minimized.

Sign in to view

folkertdev force-pushed the custom-abi branch from a72606d to 64868d3 Compare May 8, 2025 17:02

This comment has been minimized.

Sign in to view

folkertdev force-pushed the custom-abi branch from 64868d3 to 7807720 Compare May 8, 2025 17:59

This comment has been minimized.

Sign in to view

folkertdev force-pushed the custom-abi branch from 7807720 to 9d529f8 Compare May 8, 2025 18:37

folkertdev mentioned this pull request May 8, 2025

Tracking Issue for abi_custom #140829

Closed

4 tasks

folkertdev force-pushed the custom-abi branch from 9d529f8 to 6ebe16c Compare May 8, 2025 20:58

folkertdev force-pushed the custom-abi branch from 6ebe16c to f9e1963 Compare May 17, 2025 19:22

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 12, 2025

matthiaskrgr mentioned this pull request Jun 13, 2025

Rollup of 9 pull requests #142443

Merged

bors merged commit 7c3b2e5 into rust-lang:master Jun 13, 2025

rustbot added this to the 1.89.0 milestone Jun 13, 2025

dtolnay mentioned this pull request Jun 13, 2025

Reduce precedence of expressions that have an outer attr #134661

Merged

This comment has been minimized.

Sign in to view

folkertdev added the F-abi_custom `#![feature(abi_custom)]` label Jun 27, 2026

This was referenced Jun 27, 2026

Stabilize extern "custom" #158504

Merged

Add extern "custom" rust-lang/rfcs#3980

Merged

Uh oh!

Uh oh!

Conversation

folkertdev commented May 7, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented May 7, 2025

Uh oh!

This comment has been minimized.

rustbot commented May 7, 2025

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

bjorn3 commented May 8, 2025

Uh oh!

folkertdev commented May 8, 2025

Uh oh!

folkertdev commented May 8, 2025

Uh oh!

bors commented May 17, 2025

Uh oh!

bors commented Jun 4, 2025

Uh oh!

folkertdev commented Jun 12, 2025

Uh oh!

bors commented Jun 12, 2025

Uh oh!

Kobzol commented Jun 17, 2025

Uh oh!

This comment has been minimized.

rust-timer commented Jun 17, 2025

Overall result: no relevant changes - no action needed

Instruction count

Max RSS (memory usage)

Cycles

Binary size

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

15 participants

folkertdev commented May 7, 2025 •

edited by rustbot

Loading