1OpenCSD - An open source CoreSight(tm) Trace Decode library {#mainpage} 2=========================================================== 3 4This library provides an API suitable for the decode of ARM(r) CoreSight(tm) trace streams. 5 6The library will decode formatted trace in three stages: 7 81. *Frame Deformatting* : Removal CoreSight frame formatting from individual trace streams. 92. *Packet Processing* : Separate individual trace streams into discrete packets. 103. *Packet Decode* : Convert the packets into fully decoded trace describing the program flow on a core. 11 12The library is implemented in C++ with an optional "C" API. 13 14Library Versioning 15------------------ 16 17From version 0.4, library versioning will use a semantic versioning format 18(per http://semver.org) of the form _Major.minor.patch_ (M.m.p). 19 20Internal library version calls, documentation and git repository will use this format moving forwards. 21Where a patch version is not quoted, or quoted as .x then comments will apply to the entire release. 22 23Releases will be at M.m.0, with patch version incremented for bugfixes or documentation updates. 24 25Releases will appear on the master branch in the git repository with an appropriate version tag. 26 27CoreSight Trace Component Support. 28---------------------------------- 29 30_Current Version 0.14.0_ 31 32### Current support: 33 34- ETMv4 (v4.5 [A/R profile] v4.4 [M profile]) instruction trace - packet processing and packet decode. 35- PTM (v1.1) instruction trace - packet processing and packet decode. 36- ETMv3 (v3.5) instruction trace - packet processing and packet decode. 37- ETMv3 (v3.5) data trace - packet processing. 38- STM (v1.1) software trace - packet processing and packet decode. 39 40- External Decoders - support for addition of external / custom decoders into the library. 41 42### Support to be added: 43 44- ITM software trace - packet processing and decode. 45- ETMv3 data trace - packet decode. 46- ETMv4 data trace - packet processing and decode. 47 48Note: for ITM and STM, packet decode is combining Master+Channel+Marker+Payload packets into a single generic 49output packet. 50 51 52Note on the Git Repository. 53--------------------------- 54 55This git repository for OpenCSD contains only source for the OpenCSD decoder library. 56From version 0.4, releases appear as versioned tags on the master branch. 57 58CoreSight kernel drivers and perf suport for CoreSight trace is maintained in the latest 59upstream kernel versions. 60 61One exception is a minor patch required for autoFDO support. 62See [autofdo.md](@ref AutoFDO). 63 64Documentation 65------------- 66 67API Documentation is provided inline in the source header files, which use the __doxygen__ standard mark-up. 68Run `doxygen` on the `./doxygen_config.dox` file located in the `./docs` directory.. 69 70 doxygen ./doxygen_config.dox 71 72This will produce the documentation in the `./docs/html` directory. The doxygen configuration also includes 73the `*.md` files as part of the documentation. 74 75Application Programming using the Library 76----------------------------------------- 77 78See the [programmers guide](@ref prog_guide) for details on usage of the library in custom applications. 79(`./docs/prog_guide/prog_guide_main.md`). 80 81 82Building and Installing the Library 83----------------------------------- 84 85See [build_libs.md](@ref build_lib) in the `./docs` directory for build details. 86 87The linux build makefile now contains options to install the library for a linux environment. 88 89 90How the Library is used in Linux `perf` 91--------------------------------------- 92The library and additional infrastructure for programming CoreSight components has been integrated 93with the standard linux perfomance analysis tool `perf`. 94 95 96See [HOWTO.md](@ref howto_perf) for details. 97 98How to use the Library, perf and Trace for AutoFDO 99-------------------------------------------------- 100Capturing trace using perf and decoding using the library can 101generate profiles for AutoFDO. 102 103See [autofdo.md](@ref AutoFDO) for details and scripts. 104 105(`./tests/auto-fdo/autofdo.md`). 106 107 108Version and Modification Information 109==================================== 110 111- _Version 0.001_: Library development - tested with `perf` tools integration - BKK16, 8th March 2016 112- _Version 0.002_: Library development - added in PTM decoder support. Restructure header dir, replaced ARM rctdl prefix with opencsd/ocsd. 113- _Version 0.003_: Library development - added in ETMv3 instruction decoder support. 114- _Version 0.4_ : Library development - updated decode tree and C-API for generic decoder handling. Switch to semantic versioning. 115- _Version 0.4.1_: Minor Update & Bugfixes - fix to PTM decoder, ID checking on test program, adds NULL_TS support in STM packet processor. 116- _Version 0.4.2_: Minor Update - Update to documentation for perf usage in 4.8 kernel branch. 117- _Version 0.5.0_: Library Development - external decoder support. STM full decode. 118- _Version 0.5.1_: Minor Update & Bugfixes - Update HOWTO for kernel 4.9. Build fixes for parallel builds 119- _Version 0.5.2_: Minor Update & Bugfixes - Update trace info packet string o/p + Cycle count packet bugfixes. 120- _Version 0.5.3_: Doc update for using AutoFDO with ETM and additional timestamp and cycle count options. 121- _Version 0.5.4_: Updates: X-compile for arm/arm64. Remove deprecated VS2010 builds. Bugfix: GCC inline semantics in debug build. 122- _Version 0.6.0_: Packet printers moved from tests into the main library. C++ and C APIs updated to allow clients to use them. 123 Update to allow perf to insert barrier packets (4xFSYNC) which the decoder can be made to use to reset the decode state. 124- _Version 0.6.1_: Bugfix: instruction follower bug on A32 branch to T32. 125- _Version 0.7.0_: Add handling for trace return stack feature to ETMv4 and PTM trace. 126- _Version 0.7.1_: Bugfix: ETMv3 packet processor. 127- _Version 0.7.2_: Bugfix: ETMv4 decoder - fix exact match packet address follower. 128- _Version 0.7.3_: Bugfix: PTM decoder - issues with initialisation and ASYNC detection. 129- _Version 0.7.4_: Notification of change of repository for perf extensions. gcc 6.x build fixes. 130- _Version 0.7.5_: Bugfix: ETMv4 decoder memory leak. Linux build update - header dependencies force rebuild. 131- _Version 0.8.0_: Header restructure and build update to enable linux version to install library and C-API headers in standard locations. 132 Library output naming changed from 'cstraced' to 'opencsd'. 133- _Version 0.8.1_: Minor updates: Use install tool to copy headers. Changes to HOWTO for perf usage. 134- _Version 0.8.2_: Bugfix: C++ init errors fixed for CLANG build process. 135- _Version 0.8.3_: Bugfix: ETMv4 decoder issues fixed. 136- _Version 0.8.4_: build: makefile updates and improvements to get build process compatible with Debian packaging. 137- _Version 0.9.0_: Performance improvements for perf: Additional info in instruction range output packet. Caching memory accesses. 138 Added Programmers guide to documentation. 139- _Version 0.9.1_: Bugfix: Crash during decode when first memory access is to address where no image provided. 140- _Version 0.9.2_: Bugfix: ETMv4: Incorrect Exception number output for Genric exception packets. 141 AutoFDO: update documentation for AutoFDO usage and add in "record.sh" script 142- _Version 0.9.3_: Bugfix: Test snapshot library not handling 'offset' parameters in dump file sections. 143 Install: ocsd_if_version.h moved to opencsd/include to allow installation on OS & use in compiling client apps. 144- _Version 0.10.0_: __Updates__: Add additional information about the last instruction to the generic output packet. 145 __Docs__: update docs for updated output packet. 146 __Bugfix__: typecast removed from OCSD_VER_NUM in ocsd_if_version.h to allow use in C pre-processor. 147 __Bugfix__: ETMV4: Interworking ISA change between A32-T32 occasionally missed during instruction decode. 148- _Version 0.10.1_: __Updates__: Build update - allow multi-thread make (make -j<N>). 149 __Docs__: Minor update to AutoFDO documentation. 150- _Version 0.11.0_: __Update__: ETM v4 decoder updated to support ETM version up to v4.4 151 __Update__: Memory access callback function - added new callback signature to provide TraceID to client when requesting memory. 152 __Update__: Created new example program to demonstrate using memory buffer in APIs. 153 __Bugfix__: Typos in docs and source. 154 __Bugfix__: Memory accessor - validate callback return values. 155- _Version 0.11.1_: __Update__: build:- change -fpic to -fPIC to allow Debian build on sparc. 156 __Bugfix__: build:- remove unused variable 157- _Version 0.11.2_: __Update__: docs:- HOWTO.md update to match new perf build requirements. 158 __Bugfix__: Minor spelling typos fixed. 159- _Version 0.12.0_: __Update__: Frame deformatter - TPIU FSYNC and HSYNC support added. 160 __Update__: ETM v4: Bugfix & clarification on Exception trace handling. Where exception occurs at a branch target before any instructions 161 have been executed, the preferred return address is also the target address of the branch instruction. This case now includes as specific flag in 162 the packet. Additionally any context change associated with this target address was being applied incorrectly. 163 __Update__: Core / Architecture mapping to core names as used by test programs / snapshots updated to include additional recent ARM cores. 164 __Update__: Docs: Update to reflect new exception flag. Update test program example to reflect latest output. 165 __Bugfix__: ETM v4: Valid trace info packet was not handled correctly (0x01, 0x00). 166 __Bugfix__: ETM v4: Error messaging on commit stack overflow. 167- _Version 0.12.1_: __Update__: build: remove -g option from release build. 168 __Update__: tests: Snapshots can now use generic arch+profile names rather than core names, e.g. ARMv8-A 169 __Bugfix__: Instruction decode - v8.3 B[L]A{A|B}[Z] instructions mis-identified. 170 __Bugfix__: Transition from A64 to A32 can be mis-decoded if the trace implementation represents the transition 171 as an individual address packet followed by a context packet. 172- _Version 0.12.2_: __Bugfix__: Clean up memory leaks. 173 __Bugfix__: ETMv4: Ensure addressing history zeroed after TINFO. 174 __Update__: Allow GCC version to be included in build output path. 175 __Bugfix__: Packet printing update when WFI/WFE is P0 element. 176 177- _Version 0.13.x_ : Intermediate development version. 178 179- _Version 0.14.0_: __Update__: ETMv4 - decoder update & simplification to handle advanced trace features. 180 __Update__: ETMv4 - decoder support for speculative trace. 181 __Update__: Generic Elements: Additional information in EOT, UNSYNC, ON packets to give reason. 182 __Update__: Memaccess: Add EL2 secure memory space flag. 183 __Update__: Documentation: Updated for release changes and to reflect latest kernel version support for CoreSight. 184 __Update__: Perf helper scripts updated to reflect latest build flow. 185 __Bugfix__: Fix for component operational flag inputs. 186 187 188 189 190 191Licence Information 192=================== 193 194This library is licensed under the [BSD three clause licence.](http://directory.fsf.org/wiki/License:BSD_3Clause) 195 196A copy of this license is in the `LICENCE` file included with the source code. 197 198Contact 199======= 200 201Using the github site: https://github.com/Linaro/OpenCSD 202 203Mailing list: coresight@lists.linaro.org 204