Tracking Issue for RFC #2972: Constrained Naked Functions

[nikomatsakis]

This is a tracking issue for the RFC "Constrained Naked Functions" (rust-lang/rfcs#2972).
The feature gate for the issue is #![feature(naked_functions)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement the RFC
• Confirm that all errors and warnings are emitted properly
• Final review of attributes that are incompatible with #[naked]
• Determine precise inlining gurantees
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)
  • Stabilize naked_functions #134213

Unresolved Questions

None.

Implementation history

[safinaskar]

"produce a clear warning if any of the above suggestions are not heeded" in RFC seems to contain typo

[bstrie]

This is implemented, checking the box.

Adding a new step: "Confirm that all errors and warnings are emitted properly".

[bstrie]

Request for Stabilization

A proposal that the naked_functions feature be stabilized for Rust 1.60, to be released 2022-04-07. A stabilization PR can be found at #93587.

Summary

Adds a new attribute, #[naked], which may be applied to functions. When applied to a function, the compiler will not emit a function prologue when generating code for this function. This attribute is analogous to __attribute__((naked)) in C. The use of this feature allows the programmer to have precise control over the assembly that is generated for a given function.

The body of a naked function must consist of a single asm! invocation. This asm! invocation is heavily restricted: the only legal operands are const and sym, and the only legal options are noreturn (which is mandatory) and att_syntax. In lieu of specifying operands, the asm! within a naked function relies on the specified extern calling convention in order to determine the validity of registers.

An example of a naked function:

const THREE: usize = 3;

#[naked]
/// Adds three to a number and returns the result.
pub extern "sysv64" fn add_n(number: usize) -> usize {
    // SAFETY: the validity of these registers is guaranteed according to the "sysv64" ABI
    unsafe {
        std::arch::asm!(
            "add rdi, {}",
            "mov rax, rdi",
            "ret",
            const THREE,
            options(noreturn)
        );
    }
}

Documentation

The Rust Reference: rust-lang/reference#1153

Tests

• codegen/naked-functions.rs: tests for the absence of a function prologue.
• codegen/naked-noinline.rs: tests for the presence of naked and noinline LLVM attributes.
• ui/asm/naked-functions.rs: tests that naked functions cannot accept patterns as function parameters, that referencing their function parameters is prohibited, that their body must consist of a single asm! block, that they must specify the noreturn option, that they must not specify any other option except att_syntax, that they only support const and sym operands, that they warn when used with extern "Rust", and that they are incompatible with the inline attribute.
• ui/asm/naked-functions-ffi.rs: tests that a warning occurs when the function signature contains types that are not FFI-safe.
• ui/asm/naked-functions-unused.rs: tests that the unused_variables lint is suppressed within naked functions.
• ui/asm/naked-invalid-attr.rs: tests that the naked attribute is only valid on function definitions.

History

This feature was originally proposed in RFC 1201, filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in #32410, landing on 2016-03-23. Development languished for several years as it was realized that the semantics given in RFC 1201 were insufficiently specific. To address this, a minimal subset of naked functions was specified by RFC 2972, filed on 2020-08-07 and accepted on 2021-11-16. Prior to the acceptance of RFC 2972, all of the stricter behavior specified by RFC 2972 was implemented as a series of warn-by-default lints that would trigger on existing uses of the naked attribute; these lints became hard errors in #93153 on 2022-01-22. As a result, today RFC 2972 has completely superseded RFC 1201 in describing the semantics of the naked attribute.

Unresolved Questions

• In C, __attribute__((naked)) prevents the compiler from generating both a function prologue and a function epilogue. However in Rust it was discovered that under some circumstances LLVM will choose to emit instructions following the body of a naked function, which is seemingly non-trivial to prevent. Since most of the utility of naked functions comes from preventing the prologue rather than the epilogue, for the time being this feature has restricted itself to only guaranteeing the absence of the prologue. Instead, the reference will specify that users must not rely on the presence of code following the body of a naked function, and that a future version of Rust reserves the right to guarantee the absence of such code.
• Prior to stabilization, concerns were raised that the current implementation might not be capable of guaranteeing that a naked function is never inlined in every circumstance. Obviously the correctness of naked functions relies on Rust setting up the callstack as if a function call were being performed, even in cases where the function is ultimately inlined. However, there may be observable differences in behavior based on whether or not a naked function is inlined, e.g. due to exported symbols or named labels. Thus the reference will specify that implementations are not currently required to prevent the inlining of naked functions, but that a future version of Rust reserves the right to guarantee that naked functions are not inlined, and that users must not rely on any observable differences that may arise due to the inlining of a naked function.

[bjorn3]

Since most of the utility of naked functions comes from preventing the prologue rather than the epilogue, for the time being this feature has restricted itself to only guaranteeing the absence of the prologue.

There is no observable difference between LLVM adding an epilogue and a following unnamed function starting with instructions identical to a regular epilogue.

[bstrie]

@bjorn3 I believe it can cause problems in circumstances such as #32408 (comment) . If someone were to work around that issue by assuming the existence of extra instructions and manually accounting for it, then their code would be broken if Rust ever stopped generating those instructions. It is this sort of edge case that this defensive wording is designed to address.

[roblabla]

Since most of the utility of naked functions comes from preventing the prologue rather than the epilogue, for the time being this feature has restricted itself to only guaranteeing the absence of the prologue.

There is no observable difference between LLVM adding an epilogue and a following unnamed function starting with instructions identical to a regular epilogue.

I believe it's possible to observe a difference when naked is coupled with #[link_section]. You could apply that attributed to a naked function to put it in a well-known section that you expect to only contain your function.

[joshtriplett]

👍 for stabilizing, though I'd like to make sure that there's consensus on #32408 (comment) .

[joshtriplett]

Shall we stabilize constrained naked functions?

@rfcbot merge

[rfcbot]

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

• @cramertj
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm

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!

See this document for info about what commands tagged team members can give me.

[Amanieu]

I'd like to have a whitelist of attributes that are allowed to be applies to a naked function. In the future we may want to lower naked functions directly to LLVM module-level assembly instead of using LLVM's native naked function support. For that to happen rustc needs to be able to manually translate any attributes (e.g. #[link_section]) to the corresponding asm directive.

[comex]

In the future we may want to lower naked functions directly to LLVM module-level assembly instead of using LLVM's native naked function support.

Why, because of the epilogue issue? Personally I would much rather see that fixed on LLVM’s end, rather than going to great lengths to work around it in rustc. Or is there another reason?

[bjorn3]

Lowering to global_asm! would allow all codegen backends to share the same naked function handling. Also codegen backends without native inline assembly support (like cg_clif) will have to lower to global_asm! even if no code is shared between codegen backends, so it will need this same restriction.

[bstrie]

@comex In addition to the epilogue issue, it seems the inlining issue could also be resolved by lowering to global_asm!.

@Amanieu I'd be interested in seeing such a list. Obviously part of the appeal of naked functions is that they can be treated just like a normal function in most cases, which includes the ability to be marked with attributes (e.g. #[doc]), so I'm curious how restrictive this list would be. It occurs to me that, in addition to forbidding #[inline], naked functions also already forbid #[track_caller]; I should probably mention this in the reference.

[roblabla]

Most attributes that work with arbitrary functions should work with naked functions IMO. Taking the list here, those make sense to use with naked fns:

• Conditional compilation: cfg, cfg_attr
• Diagnostics: allow and company, deprecated
• ABI...: link_section, export_name, no_mangle, used
• Documentation: doc

The only ones that I think make sense to disallow are those in the "Code Generation" category: inline, cold, track_caller.

target_feature is an interesting one. I'm not sure what it does, it may make sense to allow it in naked fns.

[folkertdev]

That's going down an analysis rabbit hole that isn't really feasible

yes, fair point.

I was going to make some argument about most naked_asm! blocks ending in ret anyway but a quick sampling of github shows that is really not the case. There is a bunch of fun/cursed stuff though https://github.com./search?q=naked_asm%21&type=code&p=1

Linting? what is valid?

My idea was that it is at least a signal to the programmer to check that their assembly satisfies the constraints: if they deem the lint fired incorrectly, they can just allow it, perhaps with some comment explaining the reasoning.

But I agree that it is hard/impossible to actually make it robust (enough) to work in practice.

[Amanieu]

Adding ud2 after every naked function is indistinguishable from a function which happens to compile to ud2 being placed right after the naked function, so you still get as much WYSIWYG. WYSIWYG only applies to the function itself, not the padding after it.

That's not entirely true: ELF symbols have a length and typically any padding bytes are not included in this length since they are inserted by the linker. If we append ud2 then this will observably be different when inspecting the symbol table.

[bjorn3]

Given that rustc generates inline assembly which defines the symbol, in the inline assembly rustc can specify the length of the symbol to exclude the ud2 instruction.

[dancrossnyc]

Please don't insert UD2's and things like that (or similar things for non-x86 targets) in naked functions. One of the problems with the earlier iterations of naked functions, mentioned above, was that they did this, which made it impossible to have precise control over layout and size.

Here's a motivating example: for example, consider two naked functions placed into a specific linker segment; both need to occupy exactly 4KiB (so, page sized on x86) and further they are both supposed to be aligned on 4K boundaries. One may not care what order they're put into the resulting binary, A before B or B before A, but the size and alignment requirements are absolute. They're not copied; instead, one relies on the linker to place them correctly. Adding extra UD2's at the end of these the NF's throws this off.

I appreciate the arguments for safety here, and in Rust generally, but naked functions are already incredibly niche: if one is reaching for them one's doing something so far out of the ordinary for most programmers that trying to add a ud2 to catch bugs here feels superfluous.

A response to this may be to use module-level assembly instead of naked functions for this sort of thing. While that's valid, there are some properties of naked functions that make them attractive versus global asm: symbol naming and visibility and so on.

[Qix-]

Might as well replace one nop with an ud2 for some extra safety.

On x86_64 there is padding after every function to align the next function to 16 bytes.

So in the cases when it's already aligned, there's no extra nop to replace, so no ud2 is emitted. So we're back in the territory of "ud2 sometimes, but not other times, and only in debug mode, and changing the preceding body can affect if a ud2 is there, or not".

So in such a case, it is functionally impossible to rely on it and therefore going to masquerade a ton of bugs and cause strange behavior in some cases and not others. Some developers will rely on it being there, erroneously of course. But then be surprised when it's not there. Instead of strictly specifying the safety constraints that must hold, which are there already. Also, nops are there to indicate padding. ud2/similar are not padding instructions. It has side effects, and we cannot know how different environments/tools/chips are going to react to them being there, even if they're not hit (e.g. in the case of pipelining).

There is a flimsy at best reason for emitting them, and a multitude of strong reasons not to emit them. Adding in such instructions is subverting expectation for some illusion of safety in a place that is very much opt-in and explicitly, objectively unsafe.

[Qix-]

Sorry for the double post, but just ran into a case where having a naked closure-like non-closure function would be extremely helpful.

static IDT: [fn(); 1] = [
    #[naked] // sadly not allowed
    || {}
];

Unless I'm missing something, this is the equivalent of

#[naked]
fn some_fn(){}

static IDT: [fn(); 1] = [
    some_fn
];

but is unfortunately not allowed. It would help to tidy up both the code and scope / symbol list when assembling certain types of embedded interrupt handler lists in macros.

[Skgland]

While still worse than a closure, it should at least tidy up the scope, what about defining the function in the static definition playground

Code

Not sure how long the playground link will stay valid, copy-pasting the code here to prevent dead link problems.

#![feature(naked_functions)]

use std::arch::naked_asm;

#[used]
static IDT: [extern "C" fn(); 2] = [
    {
        #[naked]
        extern "C" fn some_fn(){
            unsafe { naked_asm!("ret") }
        }
        some_fn
    },
    {
        #[naked]
        extern "C" fn some_fn(){
            unsafe { naked_asm!("ret") }
        }
        some_fn
    },
];

[folkertdev]

Unless I'm missing something

I think what you're missing is that naked functions cannot use the rust calling convention: they must always be an extern "something" fn.

Therefore, even if the attribute worked in this position #[naked] || {}, the function would still be rejected for using an unsupported calling convention. If we ever get closures that are also extern fn somehow, we can then allow the #[naked] attribute in that position. For now it is not useful.

[Qix-]

Ah yep, I figured I was missing something obvious. Thank you @Skgland and @folkertdev, the workaround works just fine :) Appreciate the info!

[tgross35]

With the stabilization at #134213, I believe this can be closed.