docs: install: Add linux 'man' file for trc_pkt_lister program.

Adds linux 'man' file for the trc_pkt_lister program that is installed
alongside the library.

Update makefile install / clean to add and remove this file.

Original Author: Wookey <wookey@wookware.org>
Signed-off-by: Mike Leach <mike.leach@linaro.org>

2 files changed, 127 insertions, 0 deletions

diff --git a/decoder/build/linux/makefile b/decoder/build/linux/makefile
index 5722e81..f63868c 100644
--- a/decoder/build/linux/makefile
+++ b/decoder/build/linux/makefile
@@ -68,6 +68,7 @@ LIB_PATH ?= lib
 INSTALL_LIB_DIR=$(DESTDIR)$(PREFIX)/$(LIB_PATH)
 INSTALL_BIN_DIR=$(DESTDIR)$(PREFIX)/bin
 export INSTALL_INCLUDE_DIR=$(DESTDIR)$(PREFIX)/include/
+INSTALL_MAN_DIR=$(DESTDIR)$(PREFIX)/share/man/man1
 
 # compile flags
 CFLAGS += $(CPPFLAGS) -c -Wall -DLINUX -Wno-switch -Wlogical-op -fPIC
@@ -131,6 +132,9 @@ endif
 	cd $(OCSD_ROOT)/build/linux/rctdl_c_api_lib && make install_inc
 	$(INSTALL) --mode=755 $(BIN_TEST_TARGET_DIR)/trc_pkt_lister $(INSTALL_BIN_DIR)/ 
 
+install_man:
+	$(INSTALL) --mode=644 $(OCSD_ROOT)/docs/man/trc_pkt_lister.1 $(INSTALL_MAN_DIR)/
+
 
 ################################
 # build  OpenCSD trace decode library
@@ -203,3 +207,4 @@ clean_install:
 	-rm    $(INSTALL_LIB_DIR)/lib$(LIB_CAPI_NAME).*
 	-rm -r $(INSTALL_INCLUDE_DIR)/$(LIB_UAPI_INC_DIR)
 	-rm    $(INSTALL_BIN_DIR)/trc_pkt_lister
+	-rm    $(INSTALL_MAN_DIR)/trc_pkt_lister.1
diff --git a/decoder/docs/man/trc_pkt_lister.1 b/decoder/docs/man/trc_pkt_lister.1
new file mode 100644
index 0000000..f16797c
--- /dev/null
+++ b/decoder/docs/man/trc_pkt_lister.1
@@ -0,0 +1,122 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.TH TRC_PKT_LISTER 1 "2018-03-28" 
+
+.SH NAME
+trc_pkt_lister \- decodes captured CoreSight\*R trace
+.SH SYNOPSIS
+.RI trc_pkt_lister
+[ \-ss_dir \fI<dir>\fP ]
+[ -ss_verbose ]
+[ \-id \fI<n>\fP ]
+[ \-src_name \fI<name>\fP ]
+[ \-decode ]
+[ \-decode_only ]
+[ \-o_raw_packed ]
+[ \-o_raw_unpacked ]
+[ \-logstdout ]
+[ \-logstderr ]
+[ \-logfile ]
+[ \-logfilename \fI<name>\fP ]
+.br
+.SH DESCRIPTION
+.B trc_pkt_lister
+is a tool that takes a snapshot directory as an input, and lists and/or
+decodes all the trace packets for a single source, for any currently
+supported protocol.
+.PP
+The output will be a list of discrete packets, generic output packets
+and any error messages to file and/or screen as selected by the input
+command line options.
+.PP
+By default the program will list packets only (no decode), for the
+first discovered trace sink (ETB, ETF, ETR) in the snapshot directory,
+with all streams output.
+.SH OPTIONS
+.SS Snapshot selection
+The program defaults to \./ if no \-ss_dir option is given
+.TP
+.B \-ss\_dir <dir>
+Set the directory path to a trace snapshot.
+.TP
+\fB\fC\-ss\_verbose\fR
+Verbose output when reading the snapshot.
+.SS Decode options
+.TP
+.B \-id <n>
+Set an ID to list (may be used multiple times) \- default if no id set is for all IDs to be printed.
+.TP
+.B \-src\_name <name>
+List packets from a given snapshot source name (defaults to first source found).
+.TP
+.B \-decode
+Full decode of the packets from the trace snapshot (default is to list undecoded packets only.
+.TP
+.B \-decode_only
+Does not list the undecoded packets, just the trace decode.
+.TP
+.B \-o\_raw\_packed
+Output raw packed trace frames.
+.TP
+.B \-o\_raw\_unpacked
+Output raw unpacked trace data per ID.
+.SS Output options
+Default is to output to file and stdout. Setting any option overrides and limits to only
+the options set.
+.TP
+.B \-logstdout
+output to stdout.
+.TP
+.B \-logstderr
+output to stderr.
+.TP
+.B \-logfile
+output to file using the default log file name.
+.TP
+.B \-logfilename <name>
+change the name of the output log file.
+.SH FILES
+.B Trace Snapshot directory.
+.PP
+The \fR./tests/snapshots\fP directory contains a number of trace
+snapshots used for testing the library.  Trace snapshots are dumps of
+captured binary trace data, CoreSight component configurations and
+memory dumps to allow trace decode.
+.PP
+Snapshots are generated on ARM targets and can then be analysed
+offline. The snapshot format is available in a separate document.
+.SH EXAMPLE
+Example command lines with short output excerpts.
+.PP
+.BI TC2 " ETMv3 packet processor output, raw packet output."
+.br
+Command line:
+.br
+.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/TC2 -o_raw_unpacked"
+.PP
+Output:
+.br
+Frame Data; Index  17958; ID_DATA[0x11]; 16 04 c0 86 42 97 e1 c4 
+.br
+Idx:17945; ID:11;	I_SYNC : Instruction Packet synchronisation.; (Periodic); Addr=0xc00
+416e2; S;  ISA=Thumb2; 
+.br
+Idx:17961; ID:11;	P_HDR : Atom P-header.; WEN; Cycles=1
+.br
+Frame Data; Index  17968; ID_DATA[0x11]; ce af 90 80 80 00 a4 84 a0 84 a4 88 
+.br
+Idx:17962; ID:11;	TIMESTAMP : Timestamp Value.; TS=0x82f9d13097 (562536984727) 
+.br
+Idx:17974; ID:11;	P_HDR : Atom P-header.; WW; Cycles=2
+.PP
+.BI Juno " ETB\_1 selected for STM packet output, raw packet output"
+.br
+Command line:
+.br
+.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/juno_r1_1 -o\_raw\_unpacked -src\_name ETB\_1"
+.PP
+.BI Juno " ETMv4 full trace decode + packet monitor, source trace ID 0x10 only."
+.br
+Command line:
+.br
+.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/juno\_r1\_1 -decode -id 0x10"
+