256 lines
14 KiB
Markdown
256 lines
14 KiB
Markdown
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.0.0_
|
|
|
|
### Current support:
|
|
|
|
- ETE (v1.1) instruction trace - packet processing and packet decode.
|
|
- ETMv4 (v4.5 [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)
|
|
|
|
|
|
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
|