[PATCH 02/19] opencsd: Updated docs and help

1 Aug 2016

README: change to work done / work TBD for STM
Help program:    Updated output of help message to include the
     -log*** commands.
     Allowed help with input of any of -help --help -h.
HOWTO:    Updated the HOWTO document to reflect operation with the
          latest perf-opencsd branch, perf-opencsd-4.7-rc4, and the
          opencsd-0v003 library branch.
Added addtional example using the --dump option in perf report
    to see trace packet data.
Signed-off-by: Mike Leach mike.leach@linaro.org
---
 HOWTO.md                                | 90 +++++++++++++++++++++++++--------
 README.md                               |  7 ++-
 decoder/tests/source/trc_pkt_lister.cpp | 14 +++--
 3 files changed, 85 insertions(+), 26 deletions(-)

diff --git a/HOWTO.md b/HOWTO.md
index 93d6a9d..ad19e9e 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -7,9 +7,9 @@ This HOWTO explains how to use the perf cmd line tools and the openCSD
 library to collect and extract program flow traces generated by the 
 CoreSight IP blocks on a Linux system.  The examples have been generated using
 an aarch64 Juno-r0 platform.  All information is considered accurate and tested
-using library branch `opencsd-0v003` (decode library only) and the latest perf
-branch `perf-opencsd-4.7-rc1` (decode library + perf tools) on the
-[OpenCSD github repository][1].
+using library branches `opencsd-0v002` and `opencsd-0v003` (decode library only) 
+and the latest perf branch `perf-opencsd-4.7-rc4` (decode library + perf tools) 
+on the [OpenCSD github repository][1].
On Target Trace Acquisition - Perf Record
@@ -17,8 +17,8 @@ On Target Trace Acquisition - Perf Record
All the enhancement to the Perf tools that support the new `cs_etm` pmu have
 not been upstreamed yet.  To get the required functionality branch
-`perf-opencsd-4.7-rc1` needs to be downloaded to the target system where
-traces are to be collected.  This branch is an upstream v4.7-rc1 kernel
+`perf-opencsd-4.7-rc4` needs to be downloaded to the target system where
+traces are to be collected.  This branch is an upstream v4.7-rc4 kernel
 supplemented with modifications to the CoreSight framework and drivers to be
 usable by the Perf core.  The remaining out of tree patches are being
 upstreamed incrementally.
@@ -135,42 +135,42 @@ Off Target OpenCSD Compilation
 As of this writing the openCSD library is not part of the perf tools source.
 It is available on [github][1] and needs to be compiled before perf.
-    linaro@t430:~/linaro/coresight$ git clone -b opencsd-0v002 https://github.com/Linaro/OpenCSD.git opencsd-0v002
+    linaro@t430:~/linaro/coresight$ git clone -b opencsd-0v003 https://github.com/Linaro/OpenCSD.git opencsd-0v003
     Cloning into 'OpenCSD'...
     remote: Counting objects: 2063, done.
     remote: Total 2063 (delta 0), reused 0 (delta 0), pack-reused 2063
     Receiving objects: 100% (2063/2063), 2.51 MiB | 1.24 MiB/s, done.
     Resolving deltas: 100% (1399/1399), done.
     Checking connectivity... done.
-    linaro@t430:~/linaro/coresight$ ls opencsd-0v002
+    linaro@t430:~/linaro/coresight$ ls opencsd-0v003
     decoder LICENSE  README.md
Once the source code has been acquired compilation of the openCSD library can
 take place.  For Linux two options are available, LINUX and LINUX64, based on
 the host's (which has nothing to do with the target) architecture:
-    linaro@t430:~/linaro/coresight/$ cd opencsd-0v002/decoder/build/linux/
-    linaro@t430:~/linaro/coresight/opencsd-0v002/decoder/build/linux$ ls
+    linaro@t430:~/linaro/coresight/$ cd opencsd-0v003/decoder/build/linux/
+    linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ ls
     makefile  rctdl_c_api_lib  ref_trace_decode_lib
-    linaro@t430:~/linaro/coresight/opencsd-0v002/decoder/build/linux$ make LINUX64=1 DEBUG=1
+    linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ make LINUX64=1 DEBUG=1
     ...
     ...
-    linaro@t430:~/linaro/coresight/opencsd-0v002/decoder/build/linux$ ls ../../lib/linux64/dbg/
+    linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ ls ../../lib/linux64/dbg/
     libcstraced.a  libcstraced_c_api.a  libcstraced_c_api.so  libcstraced.so
Off Target Perf Tools Compilation
 ---------------------------------
 As stated above not all the pieces of the solution have been upstreamed.  To
-get all the components branch `perf-opencsd-4.7-rc1` needs to be
+get all the components branch `perf-opencsd-4.7-rc4` needs to be
 obtained:
-    linaro@t430:~/linaro/coresight$ git clone -b perf-opencsd-4.7-rc1 https://github.com/Linaro/OpenCSD.git perf-opencsd-4.7-rc1
+    linaro@t430:~/linaro/coresight$ git clone -b perf-opencsd-4.7-rc4 https://github.com/Linaro/OpenCSD.git perf-opencsd-4.7-rc4
     ...
     ...
-    linaro@t430:~/linaro/coresight$ ls perf-opencsd-4.7-rc1/
+    linaro@t430:~/linaro/coresight$ ls perf-opencsd-4.7-rc4/
     arch   certs    CREDITS  Documentation  firmware  include  ipc     Kconfig  lib          Makefile  net     REPORTING-BUGS  scripts   sound  usr
     block  COPYING  crypto   drivers        fs        init     Kbuild  kernel   MAINTAINERS  mm        README  samples         security  tools  virt
@@ -179,12 +179,12 @@ variable telling the build scripts where to find the library is needed.  If
 the `CSTRACE_PATH` variable is not defined the compilation will still be
 successful, but handling of CoreSight trace data won't be supported.
-    linaro@t430:~/linaro/coresight$ cd perf-opencsd-4.7-rc1
-    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc1$ export CSTRACE_PATH=~/linaro/coresight/opencsd-0v002/decoder
-    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc1$ make -C tools/perf
+    linaro@t430:~/linaro/coresight$ cd perf-opencsd-4.7-rc4
+    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc4$ export CSTRACE_PATH=~/linaro/coresight/opencsd-0v003/decoder
+    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc4$ make -C tools/perf
     ...
     ...
-    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc1$ ls -l tools/perf/perf
+    linaro@t430:~/linaro/coresight/perf-opencsd-4.7-rc4$ ls -l tools/perf/perf
     -rwxrwxr-x 1 linaro linaro 6276360 Mar  3 10:05 tools/perf/perf
@@ -223,8 +223,8 @@ to be sure everything is clean.
linaro@t430:~/linaro/coresight/feb24$ rm -rf ~/.debug
     linaro@t430:~/linaro/coresight/feb24$ cp -dpR .debug ~/
-    linaro@t430:~/linaro/coresight/feb24$ export LD_LIBRARY_PATH=~/linaro/coresight/opencsd-0v002/decoder/lib/linux64/dbg/
-    linaro@t430:~/linaro/coresight/feb24$ ../perf-opencsd-4.7-rc1/tools/perf/perf report --stdio
+    linaro@t430:~/linaro/coresight/feb24$ export LD_LIBRARY_PATH=~/linaro/coresight/opencsd-0v003/decoder/lib/linux64/dbg/
+    linaro@t430:~/linaro/coresight/feb24$ ../perf-opencsd-4.7-rc4/tools/perf/perf report --stdio
# To display the perf.data header info, please use --header/--header-only options.
     #
@@ -266,15 +266,61 @@ to be sure everything is clean.
          1.24%     1.24%  uname    libc-2.21.so      [.] 0x00000000000fcab8
     ...
+Additional data can be obtained, which contains a dump of the trace packets received using the command 
+
+    mjl@ubuntu-vbox:./perf-opencsd-4.7-rc4/coresight/tools/perf/perf report --stdio --dump 
+
+resulting a large amount of data, trace looking like:-
+
+    0x618 [0x30]: PERF_RECORD_AUXTRACE size: 0x11ef0  offset: 0  ref: 0x4d881c1f13216016  idx: 0  tid: 15244  cpu: -1
+
+    . ... CoreSight ETM Trace data: size 73456 bytes
+
+      0: I_ASYNC : Alignment Synchronisation.
+      12: I_TRACE_INFO : Trace Info.
+      17: I_TRACE_ON : Trace On.
+      18: I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0x0000007F89F24D80; Ctxt: AArch64,EL0, NS; 
+      28: I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
+      29: I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
+      30: I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
+      32: I_ATOM_F6 : Atom format 6.; EEEEN
+      33: I_ATOM_F1 : Atom format 1.; E
+      34: I_EXCEPT : Exception.;  Data Fault; Ret Addr Follows;
+      36: I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0x0000007F89F2832C; 
+      45: I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0xFFFFFFC000083400; Ctxt: AArch64,EL1, NS; 
+      56: I_TRACE_ON : Trace On.
+      57: I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0x0000007F89F2832C; Ctxt: AArch64,EL0, NS; 
+      68: I_ATOM_F3 : Atom format 3.; NEE
+      69: I_ATOM_F3 : Atom format 3.; NEN
+      70: I_ATOM_F3 : Atom format 3.; NNE
+      71: I_ATOM_F5 : Atom format 5.; ENENE
+      72: I_ATOM_F5 : Atom format 5.; NENEN
+      73: I_ATOM_F5 : Atom format 5.; ENENE
+      74: I_ATOM_F5 : Atom format 5.; NENEN
+      75: I_ATOM_F5 : Atom format 5.; ENENE
+      76: I_ATOM_F3 : Atom format 3.; NNE
+      77: I_ATOM_F3 : Atom format 3.; NNE
+      78: I_ATOM_F3 : Atom format 3.; NNE
+      80: I_ATOM_F3 : Atom format 3.; NNE
+      81: I_ATOM_F3 : Atom format 3.; ENN
+      82: I_EXCEPT : Exception.;  Data Fault; Ret Addr Follows;
+      84: I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0x0000007F89F283F0; 
+      93: I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0xFFFFFFC000083400; Ctxt: AArch64,EL1, NS; 
+      104: I_TRACE_ON : Trace On.
+      105: I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0x0000007F89F283F0; Ctxt: AArch64,EL0, NS; 
+      116: I_ATOM_F5 : Atom format 5.; NNNNN
+      117: I_ATOM_F5 : Atom format 5.; NNNNN
+
+
 Trace Decoding with Perf Script 
 -------------------------------
 Working with perf scripts needs more command line options but yields
 interesting results.
-    linaro@t430:~/linaro/coresight/feb24$ export EXEC_PATH=/home/linaro/coresight/perf-opencsd-4.7-rc1/tools/perf/
+    linaro@t430:~/linaro/coresight/feb24$ export EXEC_PATH=/home/linaro/coresight/perf-opencsd-4.7-rc4/tools/perf/
     linaro@t430:~/linaro/coresight/feb24$ export SCRIPT_PATH=$EXEC_PATH/scripts/python/
     linaro@t430:~/linaro/coresight/feb24$ export XTOOL_PATH=/your/aarch64/toolchain/path/bin/
-    linaro@t430:~/linaro/coresight/feb24$ ../perf-opencsd-4.7-rc1/tools/perf/perf --exec-path=${EXEC_PATH} script --script=python:${SCRIPT_PATH}/cs-trace-disasm.py -- -d ${XTOOL_PATH}/aarch64-linux-gnu-objdump
+    linaro@t430:~/linaro/coresight/feb24$ ../perf-opencsd-4.7-rc4/tools/perf/perf --exec-path=${EXEC_PATH} script --script=python:${SCRIPT_PATH}/cs-trace-disasm.py -- -d ${XTOOL_PATH}/aarch64-linux-gnu-objdump
7f89f24d80:   910003e0        mov     x0, sp
               7f89f24d84:   94000d53        bl      7f89f282d0 <free@plt+0x3790>
diff --git a/README.md b/README.md
index b1e6c73..d422b4a 100644
--- a/README.md
+++ b/README.md
@@ -26,10 +26,15 @@ _Current Version 0.004_
### Support to be added:
-- ITM software trace - packet processing.
+- STM software trace - packet decode.
+- ITM software trace - packet processing and decode.
 - ETMv3 data trace - packet decode.
 - ETMv4 data trace - packet processing and decode.
+Note: for ITM and STM, packet decode is combining Master+Channel+Marker+Payload packets into a single generic
+output packet.
+
+
 Note on the Git Repository.
 ---------------------------
diff --git a/decoder/tests/source/trc_pkt_lister.cpp b/decoder/tests/source/trc_pkt_lister.cpp
index c96d09b..893bc36 100644
--- a/decoder/tests/source/trc_pkt_lister.cpp
+++ b/decoder/tests/source/trc_pkt_lister.cpp
@@ -181,10 +181,10 @@ void print_help()
 {
     std::ostringstream oss;
     oss << "Trace Packet Lister - commands\n\n";
-    oss << "Snapshot:\n";
+    oss << "Snapshot:\n\n";
     oss << "-ss_dir <dir>       Set the directory path to a trace snapshot\n";
     oss << "-ss_verbose         Verbose output when reading the snapshot\n";
-    oss << "Decode:\n";
+    oss << "\nDecode:\n\n";
     oss << "-id <n>             Set an ID to list (may be used mutiple times) - default if no id set is for all IDs to be printed\n";
     oss << "-src_name <name>    List packets from a given snapshot source name (defaults to first source found)\n";
     oss << "-decode             Full decode of the packets from the trace snapshot (default is to list undecoded packets only\n";
@@ -192,6 +192,14 @@ void print_help()
     oss << "-o_raw_packed       Output raw packed trace frames\n";
     oss << "-o_raw_unpacked     Output raw unpacked trace data per ID\n";
     oss << "-test_waits <N>     Force wait from packet printer for N packets - test the wait/flush mechanisms for the decoder\n";
+    oss << "\nOutput:\n";
+    oss << "   Setting any of these options cancels the default output to file & stdout,\n   using _only_ the options supplied.\n\n";
+    oss << "-logstdout          Output to stdout -> console.\n";
+    oss << "-logstderr          Output to stderr.\n";
+    oss << "-logfile            Output to default file - " << logfileName << "\n";
+    oss << "-logfilename <name> Output to file <name> \n";
+
+
     logger.LogMsg(oss.str());
 }
@@ -381,7 +389,7 @@ bool process_cmd_line_opts(int argc, char* argv[])
                 no_undecoded_packets = true;
                 decode = true; 
             }
-            else if(strcmp(argv[optIdx], "-help") == 0)
+            else if((strcmp(argv[optIdx], "-help") == 0) || (strcmp(argv[optIdx], "--help") == 0) || (strcmp(argv[optIdx], "-h") == 0))
             {
                 print_help();
                 bOptsOK = false;
-- 
2.7.4


    

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

[PATCH 02/19] opencsd: Updated docs and help