path: root/README.md
diff options
authorRuslan Bukin <br@FreeBSD.org>2018-04-04 12:33:46 +0000
committerRuslan Bukin <br@FreeBSD.org>2018-04-04 12:33:46 +0000
commita6157d81121ac9559d806dafa346039199598442 (patch)
tree74bb8dac03bea2e41b98a242951cee587339288a /README.md
Import OpenCSD -- an ARM CoreSight Trace Decode library.vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4
Git ID 900407e9d6400f6541138d6c2e483a9fc2d699a4 Sponsored by: DARPA, AFRL
Notes: svn path=/vendor/opencsd/dist/; revision=332012 svn path=/vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4/; revision=332013; tag=vendor/opencsd/900407e9d6400f6541138d6c2e483a9fc2d699a4
Diffstat (limited to 'README.md')
1 files changed, 132 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..44b7c6807c35
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+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 0.8.2_
+### Current support:
+- ETMv4 (v4.1) 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.
+From version 0.7.4, the required updates to CoreSight drivers and perf, that are not
+currently upstream in the linux kernel tree, are now contained in a separate
+repository to be found at:
+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.
+Building the Library
+See [build_libs.md](@ref build_lib) in the `./docs` directory for build details.
+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.
+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.
+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.
+Using the github site: https://github.com/Linaro/OpenCSD
+Mailing list: coresight@lists.linaro.org