Adding upstream version 1.3.3.upstream/1.3.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 302 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..85fa4d4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,302 @@
+OpenCSD - An open source CoreSight(tm) Trace Decode library        {#mainpage}
+===========================================================
+
+This library provides an API suitable for the decode of ARM(r) CoreSight(tm) trace streams.
+
+The library will decode formatted trace in three stages:
+
+1. *Frame Deformatting* : Removal CoreSight frame formatting from individual trace streams.
+2. *Packet Processing*  : Separate individual trace streams into discrete packets.
+3. *Packet Decode*      : Convert the packets into fully decoded trace describing the program flow on a core.
+
+The library is implemented in C++ with an optional "C" API.
+
+Library Versioning
+------------------
+
+From version 0.4, library versioning will use a semantic versioning format
+(per http://semver.org) of the form _Major.minor.patch_ (M.m.p).
+
+Internal library version calls, documentation and git repository will use this format moving forwards.
+Where a patch version is not quoted, or quoted as .x then comments will apply to the entire release.
+
+Releases will be at M.m.0, with patch version incremented for bugfixes or documentation updates.
+
+Releases will appear on the master branch in the git repository with an appropriate version tag.
+
+CoreSight Trace Component Support.
+----------------------------------
+
+_Current Version 1.3.3_
+
+### Current support:
+
+- ETE   (v1.2) instruction trace - packet processing and packet decode.
+- ETMv4 (v4.6 [A/R profile] v4.4 [M profile]) instruction trace - packet processing and packet decode.
+- PTM   (v1.1) instruction trace - packet processing and packet decode.
+- ETMv3 (v3.5) instruction trace - packet processing and packet decode.
+- ETMv3 (v3.5) data trace - packet processing.
+- STM   (v1.1) software trace - packet processing and packet decode.
+
+- External Decoders - support for addition of external / custom decoders into the library.
+
+### Support to be added:
+
+- 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.
+---------------------------
+
+This git repository for OpenCSD contains only source for the OpenCSD decoder library.
+From version 0.4, releases appear as versioned tags on the master branch.
+
+CoreSight kernel drivers and perf suport for CoreSight trace is maintained in the latest
+upstream kernel versions.
+
+One exception is a minor patch required for autoFDO support. 
+See [autofdo.md](@ref AutoFDO).
+
+Documentation
+-------------
+
+API Documentation is provided inline in the source header files, which use the __doxygen__ standard mark-up.
+Run `doxygen` on the `./doxygen_config.dox` file located in the `./docs` directory..
+
+    doxygen ./doxygen_config.dox
+
+This will produce the documentation in the `./docs/html` directory. The doxygen configuration also includes
+the `*.md` files as part of the documentation.
+
+Application Programming using the Library
+-----------------------------------------
+
+See the [programmers guide](@ref prog_guide) for details on usage of the library in custom applications.
+(`./docs/prog_guide/prog_guide_main.md`).
+
+
+Building and Installing the Library
+-----------------------------------
+
+See [build_libs.md](@ref build_lib) in the `./docs` directory for build details.
+
+The linux build makefile now contains options to install the library for a linux environment.
+
+
+How the Library is used in Linux `perf`
+---------------------------------------
+The library and additional infrastructure for programming CoreSight components has been integrated 
+with the standard linux perfomance analysis tool `perf`.
+
+
+See [HOWTO.md](@ref howto_perf) for details.
+
+How to use the Library, perf and Trace for AutoFDO
+--------------------------------------------------
+Capturing trace using perf and decoding using the library can 
+generate profiles for AutoFDO.
+
+See [autofdo.md](@ref AutoFDO) for details and scripts.
+
+(`./tests/auto-fdo/autofdo.md`).
+
+
+Version and Modification Information
+====================================
+
+- _Version 0.001_:  Library development - tested with `perf` tools integration - BKK16, 8th March 2016
+- _Version 0.002_:  Library development - added in PTM decoder support. Restructure header dir, replaced ARM rctdl prefix with opencsd/ocsd.
+- _Version 0.003_:  Library development - added in ETMv3 instruction decoder support.
+- _Version 0.4_  :  Library development - updated decode tree and C-API for generic decoder handling. Switch to semantic versioning.
+- _Version 0.4.1_:  Minor Update & Bugfixes - fix to PTM decoder, ID checking on test program, adds NULL_TS support in STM packet processor.
+- _Version 0.4.2_:  Minor Update - Update to documentation for perf usage in 4.8 kernel branch.
+- _Version 0.5.0_:  Library Development - external decoder support. STM full decode.
+- _Version 0.5.1_:  Minor Update & Bugfixes - Update HOWTO for kernel 4.9. Build fixes for parallel builds
+- _Version 0.5.2_:  Minor Update & Bugfixes - Update trace info packet string o/p + Cycle count packet bugfixes.
+- _Version 0.5.3_:  Doc update for using AutoFDO with ETM and additional timestamp and cycle count options.
+- _Version 0.5.4_:  Updates: X-compile for arm/arm64.  Remove deprecated VS2010 builds. Bugfix: GCC inline semantics in debug build. 
+- _Version 0.6.0_:  Packet printers moved from tests into the main library. C++ and C APIs updated to allow clients to use them. 
+                    Update to allow perf to insert barrier packets (4xFSYNC) which the decoder can be made to use to reset the decode state.
+- _Version 0.6.1_:  Bugfix: instruction follower bug on A32 branch to T32.
+- _Version 0.7.0_:  Add handling for trace return stack feature to ETMv4 and PTM trace.
+- _Version 0.7.1_:  Bugfix: ETMv3 packet processor.
+- _Version 0.7.2_:  Bugfix: ETMv4 decoder - fix exact match packet address follower.
+- _Version 0.7.3_:  Bugfix: PTM decoder - issues with initialisation and ASYNC detection.
+- _Version 0.7.4_:  Notification of change of repository for perf extensions. gcc 6.x build fixes.
+- _Version 0.7.5_:  Bugfix: ETMv4 decoder memory leak. Linux build update - header dependencies force rebuild.
+- _Version 0.8.0_:  Header restructure and build update to enable linux version to install library and C-API headers in standard locations.
+                    Library output naming changed from 'cstraced' to 'opencsd'.
+- _Version 0.8.1_:  Minor updates: Use install tool to copy headers. Changes to HOWTO for perf usage.                    
+- _Version 0.8.2_:  Bugfix: C++ init errors fixed for CLANG build process.
+- _Version 0.8.3_:  Bugfix: ETMv4 decoder issues fixed.
+- _Version 0.8.4_:  build: makefile updates and improvements to get build process compatible with Debian packaging.
+- _Version 0.9.0_:  Performance improvements for perf: Additional info in instruction range output packet. Caching memory accesses. 
+				    Added Programmers guide to documentation.
+- _Version 0.9.1_:  Bugfix: Crash during decode when first memory access is to address where no image provided.
+- _Version 0.9.2_:  Bugfix: ETMv4: Incorrect Exception number output for Genric exception packets.
+                    AutoFDO: update documentation for AutoFDO usage and add in "record.sh" script
+- _Version 0.9.3_:  Bugfix: Test snapshot library not handling 'offset' parameters in dump file sections.
+                    Install: ocsd_if_version.h moved to opencsd/include to allow installation on OS & use in compiling client apps.
+- _Version 0.10.0_: 
+    - __Updates__: Add additional information about the last instruction to the generic output packet.
+    - __Docs__: update docs for updated output packet.
+    - __Bugfix__: typecast removed from OCSD_VER_NUM in ocsd_if_version.h to allow use in C pre-processor.
+    - __Bugfix__: ETMV4: Interworking ISA change between A32-T32 occasionally missed during instruction decode.
+
+- _Version 0.10.1_: 
+    - __Updates__: Build update - allow multi-thread make (make -j<N>).
+    - __Docs__: Minor update to AutoFDO documentation.
+
+- _Version 0.11.0_: 
+    - __Update__: ETM v4 decoder updated to support ETM version up to v4.4
+    - __Update__: Memory access callback function - added new callback signature to provide TraceID to client when requesting memory.
+    - __Update__: Created new example program to demonstrate using memory buffer in APIs.
+    - __Bugfix__: Typos in docs and source.
+    - __Bugfix__: Memory accessor - validate callback return values.
+
+- _Version 0.11.1_: 
+    - __Update__: build:- change -fpic to -fPIC to allow Debian build on sparc.
+    - __Bugfix__: build:- remove unused variable
+
+- _Version 0.11.2_: 
+    - __Update__: docs:- HOWTO.md update to match new perf build requirements.
+    - __Bugfix__: Minor spelling typos fixed.
+
+- _Version 0.12.0_: 
+    - __Update__: Frame deformatter - TPIU FSYNC and HSYNC support added.
+    - __Update__: ETM v4: Bugfix & clarification on Exception trace handling. Where exception occurs at a branch target before any instructions
+                  have been executed, the preferred return address is also the target address of the branch instruction. This case now includes as specific flag in
+                  the packet. Additionally any context change associated with this target address was being applied incorrectly.
+    - _Update__: Core / Architecture mapping to core names as used by test programs / snapshots updated to include additional recent ARM cores.
+    - __Update__: Docs: Update to reflect new exception flag. Update test program example to reflect latest output.
+    - __Bugfix__: ETM v4: Valid trace info packet was not handled correctly (0x01, 0x00).
+    - __Bugfix__: ETM v4: Error messaging on commit stack overflow.
+
+- _Version 0.12.1_: 
+    - __Update__: build: remove -g option from release build.
+    - __Update__: tests: Snapshots can now use generic arch+profile names rather than core names, e.g. ARMv8-A
+    - __Bugfix__: Instruction decode - v8.3 B[L]A{A|B}[Z] instructions mis-identified.
+     -__Bugfix__: Transition from A64 to A32 can be mis-decoded if the trace implementation represents the transition 
+                  as an individual address packet followed by a context packet. 
+
+- _Version 0.12.2_:
+    - __Bugfix__: Clean up memory leaks.
+    - __Bugfix__: ETMv4: Ensure addressing history zeroed after TINFO.
+    - __Update__: Allow GCC version to be included in build output path.
+    - __Bugfix__: Packet printing update when WFI/WFE is P0 element.
+
+- _Version 0.13.x_ : Intermediate development version.
+
+- _Version 0.14.0_: 
+    - __Update__: ETMv4 - decoder update & simplification to handle advanced trace features.
+    - __Update__: ETMv4 - decoder support for speculative trace.
+    - __Update__: Generic Elements: Additional information in EOT, UNSYNC, ON packets to give reason.
+    - __Update__: Memaccess: Add EL2 secure memory space flag.
+    - __Update__: Documentation: Updated for release changes and to reflect latest kernel version support for CoreSight.
+    - __Update__: Perf helper scripts updated to reflect latest build flow.
+    - __Bugfix__: Fix for component operational flag inputs.
+
+- _Version 0.14.1_: 
+    - __Update__: ETMv4 - Add support for Q elements.
+    - __Bugfix__: build: fix logic issue for && operator. (github issue #23, sumitted by yabinc)
+
+- _Version 0.14.2_: 
+    - __Update__: Architecture versioning. Set enum tag values to make conversion to numeric version easier.
+    - __Update__: I-decode: remove global temporary decode state data and replace with local instance data
+                  to make library more easily usable in multi-threaded programs.
+    - __Bugfix__: I-decode: Some Thumb instructions not correctly reported as implied returns.
+                  (github issue #24, submitted by kongy).
+
+- _Version 0.14.3_:
+    - __Update__: Fix makefile to be compliant with RPM base distros. (github issue #26, submitted by jlinton)
+    - __Update__: Add section to autofdo document.
+    - __Bugfix__: STM: fix bug that was missing ASYNC packets. (github issue #27, reported by subhasish Karmakar)
+
+- _Version 0.14.4_:
+    - __Update__: makefile: Add DESTDIR to install targets. (github issue #30)
+    - __Update__: tests: add script to run single test only.
+    - __Update__: docs: update to location of ARM coresight driver backports directory.
+    - __Bugfix__: ETMv3: Fix missing comma in string list. (github issue #31)
+    - __Bugfix__: makefile: tests: Fix build race problem (github issue #32)
+    - __Bugfix__: tests: fix ignore tpiu command line options (github issue #28)
+
+- _Version 1.0.0_:
+    - __New Decode Protocol__: Support added for the ETE protocol, used by ARM PEs that implement the FEAT_ETE 
+                               feature. Supports new architectural features in this trace, including FEAT_TME. 
+    - __Update__: Output Elememts: New protocol defines two new output elements. 
+    - __Update__: Add support for WFIT / WFET instructions traced as P0 elements.
+    - __Update__: Architecture versioning. Arch v8 + PEs may add features in a flexible manner, and ARM also
+                  declares future features ahead of architecture versions to allow support to be added. 
+                  APIs requiring an architecture version can now use ARCH_AA64 to declare a version of v8.3 +
+                  additional features. This relaxes the strict versionnig rules that the decoder uses when
+                  looking for Opcodes as trace waypoints.
+    - __Update__: docs: Add linux 'man' file and installation.				  
+    - __Bugfix__: build: Fix clean install, and remove static lib build test from main makefile to 
+                  dev makefile only. (github issue #33)
+
+- _Version 1.1.0_:
+    - __Update__: ETM v4.6 support.
+    - __Update__: C-API - add API functions to get last error and convert error code to string.
+    - __Bugfix__: ETMv4/ETE - fix loop problem in commit elements.
+    - __Bugfix__: ETMv4/ETE - make error handling consistent.
+    - __Bugfix__: Add Pull request #36 from github (Ross Burton)
+    - __Bugfix__: Add Pull request #37 from github (Ian Rogers)
+
+- _Version 1.1.1_:
+    - __Bugfix__: Fix include and install for ETE decoder headers.
+
+- _Version 1.2.0_:
+    - __Update__: Add API for counting packet decode statistics, and Frame debmux statistics.
+    - __Update__: Update test scripts to allow additional command line options to be passed.
+    - __Bugfix__: Fix various build warnings.
+    - __Bugfix__: Remove unused variable (github issue #38 from Yi Kong)
+    - __Bugfix__: Remove noisy printf (James Clark)
+    - __Bugfix__: Fix documentation issues (github issues #39 & #40 from rbresalier)
+
+- _Version 1.2.1_:
+   - __Bugfix__: ETM4x / ETE - output of context elements to client can in some circumstances
+                 be delayed until after subsequent atoms have been processed leading to incorrect
+                 memory decode access via the client callbacks.
+                 Fixed to flush context elements immediately they are committed.
+
+- _Version 1.3.0_:
+    - __Admin__: Dev versions now have patch versions at least +100 from root public version
+    - __Update__: Add support for conditional branch (BC.cond) introduced for v8.8 / v9.3 architecture.
+    - __Update__: ETE: Add support for NSE bit - security state bit defining Root / Realm states in FEAT_RME.
+
+- _Version 1.3.1_:
+    - __Bugfix__: Add header file in snapshot parser - fix build for certain libc++ libs (github issue #43 from manojgupta)
+    - __Bugfix__: Fix typo in comment (github issue #42 from nothatDinger)
+
+- _Version 1.3.2_:
+    - __Bugfix__: ETM4x / ETE - 64 bit timestamp value - MS bit incorrectly masked to 1b0 during extraction from packet.
+
+- _Version 1.3.3_:
+    - __Update__: Add build directory for VS2022 build.
+    - __Update__: Add test program for Coresight Frame Demux code
+    - __Bugfix__: PTM: Fix incorrect extraction of Waypoint Address packet (github issue #48)
+    - __Bugfix__: Frame Demux: Fix HSYNC, FSYNC and 4xFSYNC handling that was causing out-of-bounds reads
+                  on invalid data input. (issues #49, #50 and #51). Fixed error handling for incorrect 
+                  number of FSYNC packets in 4xFSYNC frame reset code that was not triggering an error
+                  and allowing fun with mis-aligned input data.
+    - __Bugfix__: Fix silent failure if incorrect config flags set when setting up frame demux modes.
+
+
+Licence Information
+===================
+
+This library is licensed under the [BSD three clause licence.](http://directory.fsf.org/wiki/License:BSD_3Clause)
+
+A copy of this license is in the `LICENCE` file included with the source code.
+
+Contact
+=======
+
+Using the github site: https://github.com/Linaro/OpenCSD
+
+Mailing list: coresight@lists.linaro.org