Stabilize -Zinstrument-mcount

[pmur]

Stabilization report

Summary

Stabilize the boolean -Zinstrument-mcount command line option into -Cinstrument-mcount.
This option is similar to the gcc or clang -pg option to support instrumented profiling. This option
inserts a special function call into each function's prologue in the crate being compiler. The name of
the function is target specific. A user would then link a library which implements this function to
collect profiling data.

A common use is to compile a binary for instrumented profiling using gprof.
ld supports a special option (also called -pg) to link the necessary runtime support for
instrumented profiling.

This option was introduced several years ago, and quietly broke for a period of time due to
refactoring within LLVM, but has since been fixed with an end-to-end test to verify (at least on
x86-64) functions are instrumented.

And all other contributors who have tested, reported, or fixed bugs since 2018.

cc @rust-lang/compiler

What is stabilized

The command line option -Cinstrument-mcount. More generally, the ability to instrument function entry points in way compatible with other widely adopted toolchains (gcc, clang) for instrumenting function calls.

What isn't stabilized

None.

Design

Reference

This feature annotates LLVM IR functions with instrument-function-entry-inlined=target_mcount_name where target_mcount_name is target specific.

RFC history

This option was likely considered too trivial for an RFC.

Answers to unresolved questions

None yet.

Post-RFC changes

None.

Key points

Nightly extensions

There is not part of this feature which will remain unstable.

Doors closed

This option has minimal impact on other options.

Feedback

Call for testing

No. This is a very narrowly scoped option. In the years since this was added there is now sufficient testing to verify the compiler feature
works end-to-end on major targets.

Nightly use

Do any known nightly users use this feature? Counting instances of #![feature(FEATURE_NAME)] on GitHub with grep might be informative.

No. It was suggested this might be useful for Rust For Linux, but it is not yet used.

Implementation

Major parts

• @quark-zju's PR#57220 add -Z instrument-mcount

Coverage

Various PR's over the years have added support for target specific mcount function names which verify the correct function attributes are applied, and several tier 1 targets verify the mcount function is called after LLVM code generation.

• @clubby789's PR#145884 test to verify LLVM actually instruments functions
• @JohnTitor's PR#59506 support for target specific mcount function name
• @ChoKyuWon's PR#113814 fix ARM32 mcount instrinsic

Outstanding bugs

There are no outstanding bugs.

Outstanding FIXMEs

None.

Tool changes

This requires no tooling changes. Though, the utility of this option could be increased by addition cargo support to build instrumented binaries. That would required a stabilized means to build and instrumented std and apply appropriate linker flags. That discussion is out of this scope.

Breaking changes

None.

History and Acknoledgments

The following contributors have implemented, tested, and stabilized this feature:

• @clubby789's PR#145884 test to verify LLVM actually instruments functions
• @JohnTitor's PR#59506 support for target specific mcount function name
• @ChoKyuWon's PR#113814 fix ARM32 mcount instrinsic
• @quark-zju's PR#57220 add -Z instrument-mcount

And any others I have failed to uncover in the long history of this option.

Open items

• The linux kernel also makes use of attributes to inhibit tracing on selected functions. Should a Rust attribute be added to support inhibiting instrumentation? e.g

#[instrument_mcount(no)]
fn foo() {
    // ...
}

• Is there any objection to the name of this option? mcount seems to be a historical artifact from BSD, nor is the instrumentation function named this.

[rustbot]

r? @petrochenkov

rustbot has assigned @petrochenkov.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

⚠️ Warning ⚠️

• This PR is based on an upstream commit that is older than 28 days.

  It's recommended to update your branch according to the rustc-dev-guide.