1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! A library and tool (`itmdump`) to parse and dump ARM ITM packets.
//!
//! ## Usage
//!
//! ``` text
//! itmdump  (de13e34 2017-12-19)
//!
//! Reads data from an ARM CPU ITM and decodes it.
//!
//! Input is from an existing file (or named pipe) at a supplied path, or else from standard input.
//!
//! USAGE:
//!     itmdump [FLAGS] [OPTIONS]
//!
//! FLAGS:
//!     -F, --follow     Keep the file open after reading through it and append new output as it is written. Like `tail -f'.
//!     -h, --help       Prints help information
//!     -V, --version    Prints version information
//!
//! OPTIONS:
//!     -f, --file <file>        Path to file (or named pipe) to read from
//!     -s, --stimulus <port>    Stimulus port to extract ITM data for. [default: 0]
//! ```
//!
//! ### Example: reading from saved ITM data in a file
//!
//! ``` text
//! $ itmdump -f /tmp/itm.dump
//! PANIC at 'Hello, world!', examples/panic.rs:13
//! ```
//!
//! ### Example: reading from OpenOCD via a named pipe
//!
//! [OpenOCD][openocd home] is an open-source tool to debug and flash microcontrollers.
//!
//! Reading via a named pipe works well on POSIX machines; e.g. Linux or macOS, but not Windows.
//!
//! ``` text
//! $ mkfifo /tmp/itm.fifo
//! $ itmdump -f /tmp/itm.fifo
//! ```
//!
//! This will create a named pipe: `/tmp/itm.fifo`. Another application, e.g.  OpenOCD, will have to
//! connect to this pipe and write to it. Here's an example command for OpenOCD + GDB that does
//! that. ([OpenOCD documentation on ITM and TPIU][openocd v7m]).
//!
//! [openocd home]: http://openocd.org/
//! [openocd v7m]: http://openocd.org/doc/html/Architecture-and-Core-Commands.html#ARMv7_002dM-specific-commands
//!
//! ``` text
//! (gdb) monitor tpiu config internal /tmp/itm.fifo uart off 8000000
//! ```
//!
//! `itmdump` will read from the pipe, parse the packets and write the payload to `stdout`:
//!
//! ``` text
//! PANIC at 'Hello, world!', examples/panic.rs:13
//! ```
//!
//! ### Example: monitoring a file
//!
//! `itmdump` can monitor a file and dump new ITM data written to it (similar to `tail -f`).
//!
//! This may be useful on Windows especially where POSIX named pipes are not available. Just let
//! OpenOCD capture to a file and monitor it with `itmdump`.
//!
//! ``` text
//! $ itmdump -f /tmp/itm.live -F
//! PANIC at 'Hello, world!', examples/panic.rs:13
//! ```
//!
//! # References
//!
//! - ARMv7-M Architecture Reference Manual - Appendix D4.2 Packet descriptions
//!
//! Available to download [as a PDF][ARMv7-m] after a free registration.
//!
//! [ARMv7-m]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0403e.b/index.html
//!
//! - [ARM CoreSight Technical Reference Manual section on ITM][CoreSight ITM]
//!
//! [CoreSight ITM]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0314h/CAAGGCDH.html

#![deny(missing_docs)]
#![deny(warnings)]

extern crate failure;
#[macro_use]
extern crate failure_derive;
#[allow(unused_imports)] // No logging yet.
#[macro_use]
extern crate log;

pub mod decoder;
pub use decoder::Decoder;

pub mod packet;

/// Error type
#[derive(Clone, Copy, Debug, Fail)]
pub enum Error {
    /// end of file before packet
    #[fail(display = "end of file before packet")]
    EofBeforePacket,

    /// end of file during packet
    #[fail(display = "end of file during packet")]
    EofDuringPacket,

    /// unknown header
    #[fail(display = "unknown header byte: {:x}", byte)]
    UnknownHeader {
        /// unknown header byte
        byte: u8,
    },
}