Auto merge of #13 - japaric:v2, r=japaric

update CHANGELOG, fix cargo doc warnings and add missing documentation bits

None

Author: homunkulus

CHANGELOG.md

@@ -7,13 +7,29 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.2.0] - 2018-01-11
+
+### Added
+
+- (library) A `Decoder` abstraction for parsing ITM packets out of `Read`-able sources.
+- (library) A `Packet` type that represent ITM packets.
+- (cli) The stimulus port to read ITM data from can be changed using the `-s` flag. If the flag is
+  omitted the port 0 is used by default.
+- (cli) A follow mode (`-F` flag) to keep reading the input file. Use this mode if your OS doesn't
+  support named pipes.
+- (cli) Support for reading from stdin when no `-f` flag is passed.
+
+### Changed
+
+- [breaking-change][] (cli) the file to read must now be passed as an argument of the `-f` flag
+
 ## [v0.1.1] - 2016-10-20
 
 ### Changed
 
 - `itmdump` no longer depends on the `mkfifo` command.
 - `itmdump`, which normally uses named pipes, now fallbacks to regular files to
-  be work on Windows. 
+  be work on Windows.
 - `itmdump` now is restrictive with about the arguments it receives. Before, a
   second argument would simply be ignored, but, now, that has become a hard
   error.
@@ -24,7 +40,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - `itmdump` tool that parses instrumentation packets from the stimulus port 0
-  and dumps the payload to `stdout`. 
+  and dumps the payload to `stdout`.
 
-[Unreleased]: https://github.com/japaric/itm/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/japaric/itm/compare/v0.2.0...HEAD
+[v0.2.0]: https://github.com/japaric/itm/compare/v0.1.1...v0.2.0
 [v0.1.1]: https://github.com/japaric/itm/compare/v0.1.0...v0.1.1

Cargo.lock

@@ -1,13 +1,13 @@
 [package]
-authors = ["Jorge Aparicio <[email protected]>"]
+authors = ["Jorge Aparicio <[email protected]>"]
 build = "build.rs"
 description = "Tool to parse and dump ITM packets"
 documentation = "https://docs.rs/itm"
 keywords = ["parse", "tool", "ARM", "ITM"]
 license = "MIT OR Apache-2.0"
 name = "itm"
 repository = "https://github.com/japaric/itm"
-version = "0.1.1"
+version = "0.2.0"
 
 [dependencies]
 chrono = "^0.4"

Cargo.toml

@@ -4,18 +4,21 @@ use std::io;
 
 error_chain! {
     foreign_links {
-        Io(io::Error);
+        Io(io::Error) #[doc = "I/O error"];
     }
 
     errors {
+        /// unknown header byte
         UnknownHeader(b: u8) {
             description("unknown header byte"),
             display("unknown header byte: {:x}", b),
         }
+        /// end of file during packet
         EofDuringPacket {
             description("end of file during packet"),
             display("end of file during packet"),
         }
+        /// end of file before packet
         EofBeforePacket {
             description("end of file before packet"),
             display("end of file before packet"),

src/error.rs

@@ -23,29 +23,26 @@
 //! ```
 //!
 //! ### 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.
+//! [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.
+//! 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]).
+//! 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
@@ -54,21 +51,18 @@
 //! (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`:
+//! `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`).
+//! `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`.
+//! 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
@@ -79,13 +73,15 @@
 //!
 //! - 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
+//! 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
+//!
+//! [CoreSight ITM]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0314h/CAAGGCDH.html
 
+#![deny(missing_docs)]
 #![deny(warnings)]
 
 #[macro_use]

src/lib.rs

@@ -1,6 +1,6 @@
 //! Defines ITM packets and their possible contents.
 
-pub const MAX_PAYLOAD_SIZE: usize = 4;
+pub(crate) const MAX_PAYLOAD_SIZE: usize = 4;
 
 /// Represents a complete received packet.
 #[derive(Debug)]