Skip to content
Snippets Groups Projects
Commit 0d06cf63 authored by Per Lindgren's avatar Per Lindgren
Browse files

readme

parent 3379b5dc
No related branches found
No related tags found
No related merge requests found
Pipeline #73 failed
# Cargo call-stack
A cargo sub-commond for spanning the call stack for a `cortex-m` bare metal application.
A cargo subcommand for spanning the call stack for a `cortex-m` bare metal application.
## Requirements
- A recent (Edition 2018) Rust toolchain.
- LLVM `opt` tool, as distributed in the arch-linux LLVM package. As the tool uses `opt` to operate on the underlying `llvm-ir` we can give no compatibility guarantees if `opt` version differs to the `rustc` LLVM backend. The tool has been tested to work with LLVM `opt` 7.0, while the Rust toolchain has already moved to the LLVM 8.0 preview.
## Installing
> cargo install --path <PATH_TO cargo-call-stack> -f
> cargo install --path <PATH_TO cargo-call-stack>
If already installed, `-f` to force re-installation of the subcommand.
## Usage
Assume we have have an existing `cortex-m` bare metal application, e.g., ...
Assume we have have an existing `cortex-m` bare metal application:
> cargo call-stack --release
for analysing a crate, or
> cargo call-stack --release --example hello1
for analysing an example.
- The `stdout` output gives the call-graph in `dot` format.
- The `stderr` output gives additional information, mainly for debugging purposes.
## Errors
``` sh
cargo call-stack --example hello2 --release > callgraph.dot
...
Out { hash: None, crate_name: None, out_dir: None }
thread 'main' panicked at '--out-dir missing', libcore/option.rs:1008:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.
```
In this case, `rustc` did not recompile the crate (or example), and thus we cannot determine the output directory. This can be solved by forcing recompilation (e.g. by touching the respective source file.)
``` sh
cargo call-stack --examples --release > callgraph.dot
start sub command
"cargo" "rustc" "--examples" "--release" "-v" "--color=always" "--" "-C" "lto" "--emit=llvm-bc,llvm-ir" "-Z" "emit-stack-sizes"
error: extra arguments to `rustc` can only be passed to one target, consider filtering
the package by passing e.g. `--lib` or `--bin NAME` to specify a single target
thread 'main' panicked at 'assertion failed: status.success()', src/main.rs:228:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.
```
In this case `rustc` will abort, as extra arguments cannot be parsed to multiple targets. This problem is solved by giving a single target (see Usage above).
``` sh
cargo call-stack > callgraph.dot
...
error: can't perform LTO when compiling incrementally
```
In this case `rustc` fails, as we require LTO optimization in order to achieve a single (monolithic) LLVM-IR for the call-graph analysis. This problem is solved by adding the `--release` flag (see Usage above).
## Tech notes
### Cargo sub-commands
......@@ -38,3 +92,13 @@ the package by passing e.g. `--lib` or `--bin NAME` to specify a single target
```
This is fine Since we are interested in analysing a single application. This error is reported directly by `rustc` (not by the `call-stack` command).
## Todo
### Usabililty improvements
- forcing rebuild or find the current hash somehow (perhaps by date of generated files, if re-compilation is not done (can be checked))
### Functionality improvements
- handling of trait objects
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment