And yes, the estimated maximum stack usage is correct as shown in this debug session:

``` console (gdb) b app::foo

(gdb) b app::bar

(gdb) b app::baz

(gdb) c Continuing.

Breakpoint 3, main () at src/main.rs:16 16 foo();

(gdb) p $sp $1 = (void *) 0x20005000

(gdb) c Continuing. halted: PC: 0x08000400

Breakpoint 4, app::foo () at src/main.rs:31 31 if X.load(Ordering::Relaxed) {

(gdb) p $sp $2 = (void *) 0x20005000

(gdb) c Continuing. halted: PC: 0x0800040c

Breakpoint 5, app::bar () at src/main.rs:38 38 if X.load(Ordering::Relaxed) {

(gdb) p $sp $3 = (void *) 0x20005000

(gdb) c Continuing. halted: PC: 0x08000420

Breakpoint 6, app::baz () at src/main.rs:45 45 if X.load(Ordering::Relaxed) {

(gdb) p $sp $4 = (void *) 0x20005000

(gdb) c Continuing. halted: PC: 0x08000434

Breakpoint 4, app::foo () at src/main.rs:31 31 if X.load(Ordering::Relaxed) {

(gdb) p $sp $5 = (void *) 0x20005000 ```

Trait object dispatch

In some cases the tool can produce correct call graphs for programs that use trait objects -- more details about where and how it fails in the "Known limitations" section. Here's an example:

``` rust

![feature(llvm_asm)]

![no_main]

![no_std]

extern crate panic_halt;

use cortexmrt::{entry, exception}; use spin::Mutex; // spin = "0.5.0"

static TO: Mutex<&'static (dyn Foo + Sync)> = Mutex::new(&Bar);

[entry]

[inline(never)]

fn main() -> ! { // trait object dispatch (*TO.lock()).foo();

Quux.foo();

loop {}

}

trait Foo { // default implementation of this method fn foo(&self) -> bool { // spill variables onto the stack unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5)) }

    false
}

}

struct Bar;

// uses the default method implementation impl Foo for Bar {}

struct Baz;

impl Foo for Baz { // overrides the default method fn foo(&self) -> bool { unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5) "r"(6) "r"(7)) }

    true
}

}

struct Quux;

impl Quux { // not a trait method! #[inline(never)] fn foo(&self) -> bool { // NOTE(llvmasm!) side effect to preserve function calls to this method unsafe { llvmasm!("NOP" : : : : "volatile") }

    false
}

}

// this handler can change the trait object at any time

[exception]

fn SysTick() { *TO.lock() = &Baz; } ```

The tool produces the following call graph:

Here i1 ({}*) denotes dynamic dispatch of a method with (Rust) signature fn(&[mut] self) -> bool. The dynamic dispatch can invoke either Bar.foo, which boils down to the default method implementation (app::Foo::foo in the graph), or Baz.foo (<app::Baz as app::Foo>::foo in the graph). In this case the tool does not a draw an edge between i1 ({}*) and Quux::foo, whose signature is also fn(&self) -> bool, so the call graph is accurate.

If you are wondering why we use LLVM notation for the function signature of the trait method: that's because the tool operates on LLVM-IR where there's no bool primitive and most of Rust's type information has been erased.

Function pointers

In some cases the tool can produce correct call graphs for programs that invoke functions via pointers (e.g. fn()). Here's an example:

``` rust

![feature(llvm_asm)]

![no_main]

![no_std]

extern crate panic_halt;

use core::sync::atomic::{AtomicPtr, Ordering};

use cortexmrt::{entry, exception};

static F: AtomicPtr bool> = AtomicPtr::new(foo as *mut _);

[inline(never)]

[entry]

fn main() -> ! { if let Some(f) = unsafe { F.load(Ordering::Relaxed).as_ref() } { // call via function pointer f(); }

loop {}

}

fn foo() -> bool { // spill variables onto the stack unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5)) }

false

}

fn bar() -> bool { unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5) "r"(6) "r"(7)) }

true

}

// this handler can change the function pointer at any time

[exception]

fn SysTick() { F.store(bar as *mut _, Ordering::Relaxed); } ```

The tool produces the following call graph:

The node i1 ()* represents a call via function pointer -- the LLVM type i1 ()* is equivalent to Rust's fn() -> bool. This indirect call could invoke foo or bar, the only functions with signature fn() -> bool.

Known limitations

Lossy type information

To reason about indirect function calls the tool uses the type information available in the LLVM-IR of the program. This information does not exactly match Rust's type information and leads to mislabeling of functions. For example, consider this program:

``` rust

![feature(llvm_asm)]

![no_main]

![no_std]

extern crate panic_halt;

use core::{ ptr, sync::atomic::{AtomicPtr, Ordering}, };

use cortexmrt::{entry, exception};

static F: AtomicPtr u32> = AtomicPtr::new(foo as *mut _);

[inline(never)]

[entry]

fn main() -> ! { if let Some(f) = unsafe { F.load(Ordering::Relaxed).as_ref() } { // call via function pointer f(); }

let x = baz();
unsafe {
    // NOTE(volatile) used to preserve the return value of `baz`
    ptr::read_volatile(&x);
}

loop {}

}

// this handler can change the function pointer at any time

[exception]

fn SysTick() { F.store(bar as *mut _, Ordering::Relaxed); }

fn foo() -> u32 { // spill variables onto the stack unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5)) }

0

}

fn bar() -> u32 { 1 }

[inline(never)]

fn baz() -> i32 { unsafe { llvm_asm!("" : : "r"(0) "r"(1) "r"(2) "r"(3) "r"(4) "r"(5) "r"(6) "r"(7)) }

F.load(Ordering::Relaxed) as usize as i32

} ```

The tool produces the following call graph:

Note that the node that represents the indirect function call has type i32 ()* (fn() -> i32), not u32 ()*. The reason is that there's no u32 type in LLVM, there are only signed integers. This leads the tool to wrongly add an edge between i32 ()* and baz. If the tool had Rust's type information then this edge would have not been added.

Miscellaneous

Inline assembly breaks LLVM's stack usage analysis. LLVM does not consider inline assembly in its analysis and reports an incorrect number. In this case, cargo-call-stack will use its own stack usage analysis based on machine code, which only supports the ARM Cortex-M architecture.

Hardware exceptions, like SysTick on Cortex-M devices, appear as disconnected nodes in the call graph. At the moment, cargo-call-stack cannot compute the whole program maximum stack usage when exceptions are present.

The tool only supports ELF binaries because -Z emit-stack-sizes only supports the ELF format.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.