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, }, }