Commit 0d06cf63 authored by Per Lindgren's avatar Per Lindgren

readme

parent 3379b5dc
Pipeline #73 failed with stages
# 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
Cargo allows third party sub-commands to be installed, giving extended functionality to the build system. The crate name for a sub command should be pre-fixed with "cargo-X", X being the command name, in this case "cargo-call-stack". For further information see, ...
Cargo allows third party sub-commands to be installed, giving extended functionality to the build system. The crate name for a subcommand should be pre-fixed with "cargo-X", X being the command name, in this case "cargo-call-stack". For further information see, ...
### Paths
......@@ -37,4 +91,14 @@ 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).
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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment