Add `extern "custom"` by folkertdev · Pull Request #3980 · rust-lang/rfcs

folkertdev · 2026-07-01T15:55:29Z

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__();
}

History

Important

Since RFCs involve many conversations at once that can be difficult to follow, please use review comment threads on the text changes instead of direct comments on the RFC.

If you don't have a particular section of the RFC to comment on, you can click on the "Comment on this file" button on the top-right corner of the diff, to the right of the "Viewed" checkbox. This will create a separate thread even if others have commented on the file too.

Rendered

traviscross · 2026-07-01T15:58:43Z

Thanks @folkertdev for putting this together.

@rfcbot fcp merge lang

rust-rfcbot · 2026-07-01T15:58:57Z

@traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

tmandry · 2026-07-01T15:59:22Z

@rfcbot reviewed

rust-rfcbot · 2026-07-01T16:01:56Z

🔔 This is now entering its final comment period, as per the review above. 🔔

nikomatsakis · 2026-07-01T16:17:46Z

@rfcbot reviewed

ChayimFriedman2 · 2026-07-01T17:33:51Z

Seeing a RFC entering a final comment period 1 hour after it was opened is extremely rare, and personally makes me worried. Even if it was discussed extensively in the past and all relevant team members are on-board, I believe we should let the community more time to discuss it.

Lokathor · 2026-07-01T17:35:42Z

+
+```rust
+#[unsafe(naked)]
+pub unsafe extern "custom" fn __aeabi_uidivmod() {


The motivation for why these must be unsafe is that it will remind people to write safety docs on how to call this correctly, but then you didn't write the docs. If there's going to be a multi-line example implementation there should be example docs too.

Separately, this particular function is one I recognize and it arguably doesn't really need to be a custom ABI, you can call it and return from it correctly using the C ABI if you define the return value to be a u64 value. But that's less important.

View changes since the review

Sure, I've added something but practically this function is not meant to be called (and a lack of safety comment means you can't satisfy the requirements).

I suspect you know as well as I do that a lack of safety comments doesn't stop people from calling it anyway ;)

programmerjake · 2026-07-01T17:36:54Z

imo it's fine since that's what the final comment period is for, announcing and giving people time to look at something before it's accepted, when the team already thinks it's good enough.

folkertdev · 2026-07-01T17:38:22Z

Right, this is the (final) ping for concerns to be raised. This was coordinated during the T-lang triage meeting.

This feature is based on the following lang proposal, it is basically unchanged from that thread.

Lang proposal: extern "unspecified" for naked functions with arbitrary ABI rust#140566

tgross35 · 2026-07-01T18:10:33Z

+* https://github.com/rust-lang/rust/issues/140566
+* https://github.com/rust-lang/rust/issues/140829
+* https://github.com/rust-lang/rust/pull/140770
+* https://github.com/rust-lang/rust/pull/158504


Suggested change

* https://github.com/rust-lang/rust/issues/140566

* https://github.com/rust-lang/rust/issues/140829

* https://github.com/rust-lang/rust/pull/140770

* https://github.com/rust-lang/rust/pull/158504

* Proposal: https://github.com/rust-lang/rust/issues/140566

* Tracking issue: https://github.com/rust-lang/rust/issues/140829

* Implementation: https://github.com/rust-lang/rust/pull/140770

* Stabilization PR: https://github.com/rust-lang/rust/pull/158504

Saving a click

View changes since the review

tgross35 · 2026-07-01T18:22:52Z

+https://github.com/rust-lang/rust/issues/140566
+
+The name has already been debated. The name `unknown` has been mentioned, but to write the implementation you really do need to know the ABI. It is custom in the sense that rustc does not know about it, but the author definitely does.
+


Would be good to address parameters since that was discussed at some point:

Suggested change

Arguments and return types are forbidden because they are not consumed in any way. The compiler has no way of validating them against the function body, similar to other naked functions, but the functions can never be invoked directly so they serve no purpose when calling. The intent is that correct parameter passing and returning will be covered in documentation.

View changes since the review

clarfonthey · 2026-07-01T23:53:07Z

I also felt a bit concerned by the sudden FCP, but the methodology here seems pretty canonical since it uses naked functions.

The only potential concern is bikeshedding the name "custom" which could potentially be worded as "none" (since this effectively is no ABI) but that's a pretty weak point and not worth blocking IMHO. Plus, it could be changed even post-acceptance but pre-stabilisation.

I see no reason to slow down on the FCP process.

steffahn · 2026-07-02T00:13:12Z

Plus, it could be changed even post-acceptance but pre-stabilisation.

I would expect this time frame to be fairly short in this case.

Lokathor · 2026-07-02T00:51:58Z

"none" is incorrect, as explained in the RFC, there is an ABI happening, it's just not an ABI the compiler knows how to use without assistance.

clarfonthey · 2026-07-02T01:57:32Z

"none" is incorrect, as explained in the RFC, there is an ABI happening, it's just not an ABI the compiler knows how to use without assistance.

Yes, this is another reason justifying the choice, although I do think that "none" that the compiler knows about is still appropriate: the compiler is not using any ABI for the function, even though yes, technically, ABI will always exist no matter what. Even just jumping to a label is still an ABI, after all.

My point is that this is technically a weak point of contention, but not one I think is worth discussing here, since the name is more than adequately justified.

kennytm · 2026-07-02T05:35:08Z

+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 {
+  |                               ^^^^^^     ^^^


in the current implementation in 1.98.0-nightly (2026-07-01 4c9d2bfe4ad7a6566909) returning ! seems to be accepted (but returning an actual never_type i.e. (!) or std::convert::Infallible is rejected). please clarify

#![feature(abi_custom, never_type)] use std::arch::naked_asm; #[unsafe(naked)] unsafe extern "custom" fn foo() -> ! { // no error. naked_asm!("ud2") } #[unsafe(naked)] unsafe extern "custom" fn bar() -> (!) { // error: invalid signature for `extern "custom"` function naked_asm!("ud2") }

View changes since the review

Darksonn · 2026-07-02T07:57:27Z

+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() {
+   | ++++++
+```


Since all ways of actually calling an extern "custom" function are unsafe, it doesn't seem required that we also make the functions themselves unsafe. Yes, you must call it with the right ABI for the call to be safe, but that's true for all functions. Defining such a function just seems analogous to creating a raw pointer to me.

View changes since the review

add extern "custom" RFC

bc0c28d

folkertdev mentioned this pull request Jul 1, 2026

Stabilize extern "custom" rust-lang/rust#158504

Open

folkertdev changed the title ~~add extern "custom" RFC~~ add extern "custom" Jul 1, 2026

folkertdev added the I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. label Jul 1, 2026

traviscross added the T-lang Relevant to the language team, which will review and decide on the RFC. label Jul 1, 2026

traviscross added the P-lang-drag-1 Lang team prioritization drag level 1. label Jul 1, 2026

rust-rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. labels Jul 1, 2026

rust-rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Jul 1, 2026

scottmcm reviewed Jul 1, 2026

View reviewed changes

Comment thread text/0000-extern-custom.md Outdated

traviscross changed the title ~~add extern "custom"~~ Add extern "custom" Jul 1, 2026

traviscross added I-lang-radar Items that are on lang's radar and will need eventual work or consideration. and removed I-lang-nominated Indicates that an issue has been nominated for prioritizing at the next lang team meeting. P-lang-drag-1 Lang team prioritization drag level 1. labels Jul 1, 2026

Lokathor reviewed Jul 1, 2026

View reviewed changes

changes after review

b38e056

tgross35 reviewed Jul 1, 2026

View reviewed changes

kennytm reviewed Jul 2, 2026

View reviewed changes

Darksonn reviewed Jul 2, 2026

View reviewed changes

		https://github.com/rust-lang/rust/issues/140566

		The name has already been debated. The name `unknown` has been mentioned, but to write the implementation you really do need to know the ABI. It is custom in the sense that rustc does not know about it, but the author definitely does.



	Arguments and return types are forbidden because they are not consumed in any way. The compiler has no way of validating them against the function body, similar to other naked functions, but the functions can never be invoked directly so they serve no purpose when calling. The intent is that correct parameter passing and returning will be covered in documentation.

Uh oh!

Conversation

folkertdev commented Jul 1, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

History

Uh oh!

traviscross commented Jul 1, 2026

Uh oh!

rust-rfcbot commented Jul 1, 2026 • edited by scottmcm Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tmandry commented Jul 1, 2026

Uh oh!

rust-rfcbot commented Jul 1, 2026

Uh oh!

Uh oh!

nikomatsakis commented Jul 1, 2026

Uh oh!

ChayimFriedman2 commented Jul 1, 2026

Uh oh!

Lokathor Jul 1, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

folkertdev Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Lokathor Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

programmerjake commented Jul 1, 2026

Uh oh!

folkertdev commented Jul 1, 2026

Uh oh!

tgross35 Jul 1, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tgross35 Jul 1, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clarfonthey commented Jul 1, 2026

Uh oh!

steffahn commented Jul 2, 2026

Uh oh!

Lokathor commented Jul 2, 2026

Uh oh!

clarfonthey commented Jul 2, 2026

Uh oh!

kennytm Jul 2, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Darksonn Jul 2, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

folkertdev commented Jul 1, 2026 •

edited by rustbot

Loading

rust-rfcbot commented Jul 1, 2026 •

edited by scottmcm

Loading

Lokathor Jul 1, 2026 •

edited by rustbot

Loading

tgross35 Jul 1, 2026 •

edited by rustbot

Loading

tgross35 Jul 1, 2026 •

edited by rustbot

Loading

kennytm Jul 2, 2026 •

edited by rustbot

Loading

Darksonn Jul 2, 2026 •

edited by rustbot

Loading