Auto merge of #51946 - japaric:emit-stack-sizes, r=nikomatsakis

[eRFC] add -Z emit-stack-sizes

# What

This PR exposes LLVM's ability to report the stack usage of each function through the unstable /
experimental `-Z emit-stack-sizes` flag.

# Motivation

The end goal is to enable whole program analysis of stack usage to prove absence of stack overflows
at compile time. Such property is important in systems that lack a MMU / MPU and where stack
overflows can corrupt memory. And in systems that have protection against stack overflows such proof
can be used to opt out of runtime checks (e.g. stack probes or the MPU).

Such analysis requires the call graph of the program, which can be obtained from MIR, and the stack
usage of each function in the program. Precise information about the later later can only be
obtained from LLVM as it depends on the optimization level and optimization options like LTO.

This PR does **not** attempt to add the ability to perform such whole program analysis to rustc;
it simply does the minimal amount of work to enable such analysis to be implemented out of tree.

# Implementation

This PR exposes a way to set LLVM's `EmitStackSizeSection` option from the command line. The option
is documented [here]; the documentation is copied below for convenience and posteriority:

[here]: https://llvm.org/docs/CodeGenerator.html#emitting-function-stack-size-information

> A section containing metadata on function stack sizes will be emitted when
> TargetLoweringObjectFile::StackSizesSection is not null, and TargetOptions::EmitStackSizeSection
> is set (-stack-size-section). The section will contain an array of pairs of function symbol values
> (pointer size) and stack sizes (unsigned LEB128). The stack size values only include the space
> allocated in the function prologue. Functions with dynamic stack allocations are not included.

Where the LLVM feature is not available (e.g. LLVM version < 6.0) or can't be applied (e.g. the
output format doesn't support sections e.g. .wasm files) the flag does nothing -- i.e. no error or
warning is emitted.

# Example usage

``` console
$ cargo new --bin hello && cd $_

$ cat >src/main.rs <<'EOF'
use std::{mem, ptr};

fn main() {
    registers();
    stack();
}

#[inline(never)]
fn registers() {
    unsafe {
        // values loaded into registers
        ptr::read_volatile(&(0u64, 1u64));
    }
}

#[inline(never)]
fn stack() {
    unsafe {
        // array allocated on the stack
        let array: [i32; 4] = mem::uninitialized();
        for elem in &array {
            ptr::read_volatile(&elem);
        }
    }
}
EOF

$ # we need a custom linking step to preserve the .stack_sizes section
$ # (see unresolved questions for a solution that doesn't require custom linking)
$ cat > keep-stack-sizes.x <<'EOF'
SECTIONS
{
  .stack_sizes :
  {
    KEEP(*(.stack_sizes));
  }
}
EOF

$ cargo rustc --release -- \
    -Z emit-stack-sizes \
    -C link-arg=-Wl,-Tkeep-stack-sizes.x \
    -C link-arg=-N

$ size -A target/release/hello | grep stack_sizes
.stack_sizes    117   185136
```

Then a tool like [`stack-sizes`] can be used to print the information in human readable format

[`stack-sizes`]: https://github.com/japaric/stack-sizes/#stack-sizes

``` console
$ stack-sizes target/release/hello
address                 size    name
0x000000000004b0        0       core::array::<impl core::iter::traits::IntoIterator for &'a [T; _]>::into_iter::ha50e6661c0ec84aa
0x000000000004c0        8       std::rt::lang_start::ha02aea783e0e1b3e
0x000000000004f0        8       std::rt::lang_start::{{closure}}::h5115b527d5244952
0x00000000000500        8       core::ops::function::FnOnce::call_once::h6bfa1076da82b0fb
0x00000000000510        0       core::ptr::drop_in_place::hb4de82e57787bc70
0x00000000000520        8       hello::main::h08bb6cec0556bd66
0x00000000000530        0       hello::registers::h9d058a5d765ec1d2
0x00000000000540        24      hello::stack::h88c8cb66adfdc6f3
0x00000000000580        8       main
0x000000000005b0        0       __rust_alloc
0x000000000005c0        0       __rust_dealloc
0x000000000005d0        0       __rust_realloc
0x000000000005e0        0       __rust_alloc_zeroed
```

# Stability

Like `-Z sanitize` this is a re-export of an LLVM feature. To me knowledge, we don't have a policy
about stabilization of such features as they are incompatible with, or demand extra implementation
effort from, alternative backends (e.g. cranelift). As such this feature will remain experimental /
unstable for the foreseeable future.

# Unresolved questions

## Section name

Should we rename the `.stack_sizes` section to `.debug_stacksizes`?

With the former name linkers will strip the section unless told otherwise using a linker script,
which means getting this information requires both knowledge about linker scripts and a custom
linker invocation (see example above).

If we use the `.debug_stacksizes` name (I believe) linkers will always keep the section, which means
`-Z emit-stack-sizes` is the only thing required to get the stack usage information.

# ~TODOs~

~Investigate why this doesn't work with the `thumb` targets. I get the LLVM error shown below:~

``` console
$ cargo new --lib foo && cd $_

$ echo '#![no_std] pub fn foo() {}' > src/lib.rs

$ cargo rustc --target thumbv7m-none-eabi -- -Z emit-stack-sizes
LLVM ERROR: unsupported relocation on symbol
```

~which sounds like it might be related to the `relocation-model` option. Maybe `relocation-model =
static` is not supported for some reason?~

This fixed itself after the LLVM upgrade.

---

r? @nikomatsakis
cc @rust-lang/compiler @perlindgren @whitequark

Author: bors

src/doc/unstable-book/src/compiler-flags/emit-stack-sizes.md

@@ -0,0 +1,167 @@
+# `emit-stack-sizes`
+
+The tracking issue for this feature is: [#54192]
+
+[#54192]: https://github.com/rust-lang/rust/issues/54192
+
+------------------------
+
+The rustc flag `-Z emit-stack-sizes` makes LLVM emit stack size metadata.
+
+> **NOTE**: This LLVM feature only supports the ELF object format as of LLVM
+> 8.0. Using this flag with targets that use other object formats (e.g. macOS
+> and Windows) will result in it being ignored.
+
+Consider this crate:
+
+```
+#![crate_type = "lib"]
+
+use std::ptr;
+
+pub fn foo() {
+    // this function doesn't use the stack
+}
+
+pub fn bar() {
+    let xs = [0u32; 2];
+
+    // force LLVM to allocate `xs` on the stack
+    unsafe { ptr::read_volatile(&xs.as_ptr()); }
+}
+```
+
+Using the `-Z emit-stack-sizes` flag produces extra linker sections in the
+output *object file*.
+
+``` console
+$ rustc -C opt-level=3 --emit=obj foo.rs
+
+$ size -A foo.o
+foo.o  :
+section                                 size   addr
+.text                                      0      0
+.text._ZN3foo3foo17he211d7b4a3a0c16eE      1      0
+.text._ZN3foo3bar17h1acb594305f70c2eE     22      0
+.note.GNU-stack                            0      0
+.eh_frame                                 72      0
+Total                                     95
+
+$ rustc -C opt-level=3 --emit=obj -Z emit-stack-sizes foo.rs
+
+$ size -A foo.o
+foo.o  :
+section                                 size   addr
+.text                                      0      0
+.text._ZN3foo3foo17he211d7b4a3a0c16eE      1      0
+.stack_sizes                               9      0
+.text._ZN3foo3bar17h1acb594305f70c2eE     22      0
+.stack_sizes                               9      0
+.note.GNU-stack                            0      0
+.eh_frame                                 72      0
+Total                                    113
+```
+
+As of LLVM 7.0 the data will be written into a section named `.stack_sizes` and
+the format is "an array of pairs of function symbol values (pointer size) and
+stack sizes (unsigned LEB128)".
+
+``` console
+$ objdump -d foo.o
+
+foo.o:     file format elf64-x86-64
+
+Disassembly of section .text._ZN3foo3foo17he211d7b4a3a0c16eE:
+
+0000000000000000 <_ZN3foo3foo17he211d7b4a3a0c16eE>:
+   0:   c3                      retq
+
+Disassembly of section .text._ZN3foo3bar17h1acb594305f70c2eE:
+
+0000000000000000 <_ZN3foo3bar17h1acb594305f70c2eE>:
+   0:   48 83 ec 10             sub    $0x10,%rsp
+   4:   48 8d 44 24 08          lea    0x8(%rsp),%rax
+   9:   48 89 04 24             mov    %rax,(%rsp)
+   d:   48 8b 04 24             mov    (%rsp),%rax
+  11:   48 83 c4 10             add    $0x10,%rsp
+  15:   c3                      retq
+
+$ objdump -s -j .stack_sizes foo.o
+
+foo.o:     file format elf64-x86-64
+
+Contents of section .stack_sizes:
+ 0000 00000000 00000000 00                 .........
+Contents of section .stack_sizes:
+ 0000 00000000 00000000 10                 .........
+```
+
+It's important to note that linkers will discard this linker section by default.
+To preserve the section you can use a linker script like the one shown below.
+
+``` text
+/* file: keep-stack-sizes.x */
+SECTIONS
+{
+  /* `INFO` makes the section not allocatable so it won't be loaded into memory */
+  .stack_sizes (INFO) :
+  {
+    KEEP(*(.stack_sizes));
+  }
+}
+```
+
+The linker script must be passed to the linker using a rustc flag like `-C
+link-arg`.
+
+```
+// file: src/main.rs
+use std::ptr;
+
+#[inline(never)]
+fn main() {
+    let xs = [0u32; 2];
+
+    // force LLVM to allocate `xs` on the stack
+    unsafe { ptr::read_volatile(&xs.as_ptr()); }
+}
+```
+
+``` console
+$ RUSTFLAGS="-Z emit-stack-sizes" cargo build --release
+
+$ size -A target/release/hello | grep stack_sizes || echo section was not found
+section was not found
+
+$ RUSTFLAGS="-Z emit-stack-sizes" cargo rustc --release -- \
+    -C link-arg=-Wl,-Tkeep-stack-sizes.x \
+    -C link-arg=-N
+
+$ size -A target/release/hello | grep stack_sizes
+.stack_sizes                               90   176272
+
+$ # non-allocatable section (flags don't contain the "A" (alloc) flag)
+$ readelf -S target/release/hello
+Section Headers:
+  [Nr]   Name              Type             Address           Offset
+       Size              EntSize            Flags  Link  Info  Align
+(..)
+  [1031] .stack_sizes      PROGBITS         000000000002b090  0002b0f0
+       000000000000005a  0000000000000000   L       5     0     1
+
+$ objdump -s -j .stack_sizes target/release/hello
+
+target/release/hello:     file format elf64-x86-64
+
+Contents of section .stack_sizes:
+ 2b090 c0040000 00000000 08f00400 00000000  ................
+ 2b0a0 00080005 00000000 00000810 05000000  ................
+ 2b0b0 00000000 20050000 00000000 10400500  .... ........@..
+ 2b0c0 00000000 00087005 00000000 00000080  ......p.........
+ 2b0d0 05000000 00000000 90050000 00000000  ................
+ 2b0e0 00a00500 00000000 0000               ..........
+```
+
+> Author note: I'm not entirely sure why, in *this* case, `-N` is required in
+> addition to `-Tkeep-stack-sizes.x`. For example, it's not required when
+> producing statically linked files for the ARM Cortex-M architecture.

src/librustc/session/config.rs

@@ -1385,6 +1385,8 @@ options! {DebuggingOptions, DebuggingSetter, basic_debugging_options,
           "run the self profiler"),
     profile_json: bool = (false, parse_bool, [UNTRACKED],
           "output a json file with profiler results"),
+    emit_stack_sizes: bool = (false, parse_bool, [UNTRACKED],
+          "emits a section containing stack size metadata"),
 }
 
 pub fn default_lib_output() -> CrateType {

src/librustc_codegen_llvm/back/write.rs

@@ -196,6 +196,7 @@ pub fn target_machine_factory(sess: &Session, find_features: bool)
     let features = CString::new(features).unwrap();
     let is_pie_binary = !find_features && is_pie_binary(sess);
     let trap_unreachable = sess.target.target.options.trap_unreachable;
+    let emit_stack_size_section = sess.opts.debugging_opts.emit_stack_sizes;
 
     let asm_comments = sess.asm_comments();
 
@@ -213,6 +214,7 @@ pub fn target_machine_factory(sess: &Session, find_features: bool)
                 trap_unreachable,
                 singlethread,
                 asm_comments,
+                emit_stack_size_section,
             )
         };
 

src/librustc_codegen_llvm/llvm/ffi.rs

@@ -1460,7 +1460,8 @@ extern "C" {
                                        DataSections: bool,
                                        TrapUnreachable: bool,
                                        Singlethread: bool,
-                                       AsmComments: bool)
+                                       AsmComments: bool,
+                                       EmitStackSizeSection: bool)
                                        -> Option<&'static mut TargetMachine>;
     pub fn LLVMRustDisposeTargetMachine(T: &'static mut TargetMachine);
     pub fn LLVMRustAddAnalysisPasses(T: &'a TargetMachine, PM: &PassManager<'a>, M: &'a Module);

src/rustllvm/PassWrapper.cpp

@@ -373,7 +373,8 @@ extern "C" LLVMTargetMachineRef LLVMRustCreateTargetMachine(
     bool DataSections,
     bool TrapUnreachable,
     bool Singlethread,
-    bool AsmComments) {
+    bool AsmComments,
+    bool EmitStackSizeSection) {
 
   auto OptLevel = fromRust(RustOptLevel);
   auto RM = fromRust(RustReloc);
@@ -411,6 +412,8 @@ extern "C" LLVMTargetMachineRef LLVMRustCreateTargetMachine(
   }
 
 #if LLVM_VERSION_GE(6, 0)
+  Options.EmitStackSizeSection = EmitStackSizeSection;
+
   Optional<CodeModel::Model> CM;
 #else
   CodeModel::Model CM = CodeModel::Model::Default;

src/test/run-make-fulldeps/emit-stack-sizes/Makefile

@@ -0,0 +1,31 @@
+-include ../tools.mk
+
+# This feature only works when the output object format is ELF so we ignore
+# macOS and Windows
+ifdef IS_WINDOWS
+# Do nothing on Windows.
+all:
+	exit 0
+else ifneq (,$(filter $(TARGET),i686-apple-darwin x86_64-apple-darwin))
+# Do nothing on macOS.
+all:
+	exit 0
+else
+# check that the .stack_sizes section is generated
+# this test requires LLVM >= 6.0.0
+vers = $(shell $(RUSTC) -Vv)
+ifneq (,$(findstring LLVM version: 3,$(vers)))
+all:
+	exit 0
+else ifneq (,$(findstring LLVM version: 4,$(vers)))
+all:
+	exit 0
+else ifneq (,$(findstring LLVM version: 5,$(vers)))
+all:
+	exit 0
+else
+all:
+	$(RUSTC) -C opt-level=3 -Z emit-stack-sizes --emit=obj foo.rs
+	size -A $(TMPDIR)/foo.o | $(CGREP) .stack_sizes
+endif
+endif

src/test/run-make-fulldeps/emit-stack-sizes/foo.rs

@@ -0,0 +1,13 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+#![crate_type = "lib"]
+
+pub fn foo() {}