[−][src]Crate stlog

Ultra lightweight logging framework for resource constrained devices

stlog running on a Cortex-M microcontroller

See stlog in action!

Features

O(1) execution time. Logging a message of arbitrary size is done in a constant number of instructions.
O(0) memory usage. The messages are NOT stored in the target device memory.
Supports different logging levels: error, warning, info, debug and trace, in decreasing level of severity. By default, the dev profile logs debug, and more severe, messages and the release profile logs info, and more severe, messages, but this can changed using the Cargo features of this crate.
Provides a global logging mode

Non-features

printf style or any other kind of formatting

Known limitations

The current implementation only supports 256 different log strings. This restriction may be lifted in the future.
The exact same string can't be used in two or more macro invocations. This restriction will be lifted when procedural macros that expand into expressions are allowed on stable.

use stlog::{error, info};

fn foo() {
    info!("Hello!");
}

fn good() {
    foo();
    foo();
}

fn bad() {
    info!("Hey!");
    info!("Hey!"); //~ ERROR symbol `Hey!` is already defined
}

fn also_bad() {
    info!("Bye!");
    error!("Bye!"); //~ ERROR symbol `Bye!` is already defined
}

Requirements

The target application must be linked using the stlog.x linker script provided by this crate. The easiest way to do this is to append the -C link-arg to the other rustc flags using a Cargo configuration file (.cargo/config).

[target.thumbv7m-none-eabi]
rustflags = [
    "-C", "link-arg=-Tstlog.x",
    # ..
]

To decode the logs on the host you'll need version v0.2.x of the stcat tool.

Example

Local logger

Device side

extern crate stlog;

use stlog::{info, warn, Log};

struct Logger {
    // ..
}

impl Log for Logger {
    // ..
}

fn main() {
    let mut logger = Logger {
        // ..
    };

    info!(logger, "Hello, world!");
    warn!(logger, "The quick brown fox jumps over the lazy dog");
}

Host side

Assuming that the device is logging through the /dev/ttyUSB0 interface.

$ flash-and-run /path/to/device/binary

$ cat /dev/ttyUSB0 | stcat -e /path/to/device/binary
Sept 22 13:00:00.000 INFO Hello, world!
Sept 22 13:00:00.001 WARN The quick brown fox jumps over the lazy dog

Global logger

If the first argument is omitted from the logging macros then logging will be done through the global logger. The global logger must be selected using the global_logger attribute in the top crate.

use stlog::{info, GlobalLog};

struct Logger;

impl GlobalLog for Logger { .. }

#[global_logger]
static LOGGER: Logger = Logger;

fn main() {
    info!("Hello");
}

#[interrupt]
fn SomeInterrupt() {
    info!("World");
}

Troubleshooting

Didn't pass `-Tstlog.x` to the linker

Symptom: you'll get an error when linking the target application or when calling stcat.

$ cargo build
error: linking with `rust-lld` failed: exit code: 1
  |
  = note: "rust-lld" (..)
  = note: rust-lld: error: no memory region specified for section '.stlog.info'
          rust-lld: error: no memory region specified for section '.stlog.error'

$ stcat -e /path/to/binary logfile
error: symbol `__stlog_error_start__` not found

Pass -Tstlog.x to the linker as explained in the requirements section.

Didn't set a `global_logger`

Symptom: you'll get an error when linking the program

$ cargo build
error: linking with `rust-lld` failed: exit code: 1
  |
  = note: "rust-lld" (..)
  = note: rust-lld: error: undefined symbol: stlog::GLOBAL_LOGGER

Re-exports

pub use stlog_macros::global_logger;

Macros

debug	Logs the given string literal at the DEBUG log level
error	Logs the given string literal at the ERROR log level
info	Logs the given string literal at the INFO log level
trace	Logs the given string literal at the TRACE log level
warn	Logs the given string literal at the WARNING log level

Traits

GlobalLog	A global version of the `Log` trait
Log	A logger that encodes messages using a symbol table