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:

Frame Deformatting : Removal CoreSight frame formatting from individual trace streams.
Packet Processing : Separate individual trace streams into discrete packets.
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.5.4

Current support:

ETMv4 instruction trace - packet processing and packet decode.
PTM instruction trace - packet processing and packet decode.
ETMv3 instruction trace - packet processing and packet decode.
ETMv3 data trace - packet processing.
STM 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.

At present, the git repository for OpenCSD contains both branches/tags for the OpenCSD library itself, and branches that have the perf updates that are not yet upstream in the main linux tree for using perf to record and decode trace.

These perf branches are snapshots of the kernel tree and are thus quite large. It is advised if only the OpenCSD library is required, clone only selected branches. Otherwise, downloading may take some time.

e.g.

git clone -b opencsd-0v003 --single-branch https://github.com/Linaro/OpenCSD

(From version 0.4, releases appear as versioned tags on the master branch.)

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.

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.

Licence Information

This library is licensed under the BSD three clause licence.

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

HenryFeng2016/OpenCSD