Update README and HOWTO to explain the change to semantic versioning.
Ensure references in HOWTO explaining use of perf have correct refs.
Signed-off-by: Mike Leach mike.leach@linaro.org --- HOWTO.md | 26 ++++++++++++++++---------- README.md | 20 +++++++++++++++++--- TODO | 6 ++---- decoder/docs/doxygen_config.dox | 2 +- 4 files changed, 36 insertions(+), 18 deletions(-)
diff --git a/HOWTO.md b/HOWTO.md index 6d3cde3..5a9b0c2 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -11,6 +11,11 @@ using library branches `opencsd-0v002` and `opencsd-0v003` (decode library only) and the latest perf branch `perf-opencsd-4.7` (decode library + perf tools) on the [OpenCSD github repository][1].
+From v0.4 of the library releases appear as master branch tags. v0.4 requires +a patched version of the `perf-opencsd-4.7` perf tools to use the updated C API. +The unpatched `perf-opencsd-4.7` may be used with v0.4 if the build makefile +for the tools is altered to #define OPENCSD_INC_DEPRECATED_API which will +include the decprecated function call wrappers for the new generic API.
On Target Trace Acquisition - Perf Record ----------------------------------------- @@ -133,31 +138,32 @@ have also been collected. Off Target OpenCSD Compilation ------------------------------ As of this writing the openCSD library is not part of the perf tools source. -It is available on [github][1] and needs to be compiled before perf. +It is available on [github][1] and needs to be compiled before perf. Checkout the +required branch/tag version into a local directory.
- linaro@t430:~/linaro/coresight$ git clone -b opencsd-0v003 https://github.com/Linaro/OpenCSD.git opencsd-0v003 + linaro@t430:~/linaro/coresight$ git clone -b opencsd-0v003 https://github.com/Linaro/OpenCSD.git my-opencsd Cloning into 'OpenCSD'... remote: Counting objects: 2063, done. remote: Total 2063 (delta 0), reused 0 (delta 0), pack-reused 2063 Receiving objects: 100% (2063/2063), 2.51 MiB | 1.24 MiB/s, done. Resolving deltas: 100% (1399/1399), done. Checking connectivity... done. - linaro@t430:~/linaro/coresight$ ls opencsd-0v003 - decoder LICENSE README.md + linaro@t430:~/linaro/coresight$ ls my-opencsd + decoder LICENSE README.md HOWTO.md TODO
Once the source code has been acquired compilation of the openCSD library can take place. For Linux two options are available, LINUX and LINUX64, based on the host's (which has nothing to do with the target) architecture:
- linaro@t430:~/linaro/coresight/$ cd opencsd-0v003/decoder/build/linux/ - linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ ls + linaro@t430:~/linaro/coresight/$ cd my-opencsd/decoder/build/linux/ + linaro@t430:~/linaro/coresight/my-opencsd/decoder/build/linux$ ls makefile rctdl_c_api_lib ref_trace_decode_lib
- linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ make LINUX64=1 DEBUG=1 + linaro@t430:~/linaro/coresight/my-opencsd/decoder/build/linux$ make LINUX64=1 DEBUG=1 ... ...
- linaro@t430:~/linaro/coresight/opencsd-0v003/decoder/build/linux$ ls ../../lib/linux64/dbg/ + linaro@t430:~/linaro/coresight/my-opencsd/decoder/build/linux$ ls ../../lib/linux64/dbg/ libcstraced.a libcstraced_c_api.a libcstraced_c_api.so libcstraced.so
Off Target Perf Tools Compilation @@ -182,7 +188,7 @@ successful, but handling of CoreSight trace data won't be supported. **See perf-test-scripts below for assistance in creating a build and test enviroment.**
linaro@t430:~/linaro/coresight$ cd perf-opencsd-4.7 - linaro@t430:~/linaro/coresight/perf-opencsd-4.7$ export CSTRACE_PATH=~/linaro/coresight/opencsd-0v003/decoder + linaro@t430:~/linaro/coresight/perf-opencsd-4.7$ export CSTRACE_PATH=~/linaro/coresight/my-opencsd/decoder linaro@t430:~/linaro/coresight/perf-opencsd-4.7$ make -C tools/perf ... ... @@ -225,7 +231,7 @@ to be sure everything is clean.
linaro@t430:~/linaro/coresight/feb24$ rm -rf ~/.debug linaro@t430:~/linaro/coresight/feb24$ cp -dpR .debug ~/ - linaro@t430:~/linaro/coresight/feb24$ export LD_LIBRARY_PATH=~/linaro/coresight/opencsd-0v003/decoder/lib/linux64/dbg/ + linaro@t430:~/linaro/coresight/feb24$ export LD_LIBRARY_PATH=~/linaro/coresight/my-opencsd/decoder/lib/linux64/dbg/ linaro@t430:~/linaro/coresight/feb24$ ../perf-opencsd-4.7/tools/perf/perf report --stdio
# To display the perf.data header info, please use --header/--header-only options. diff --git a/README.md b/README.md index d422b4a..2ca2de1 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,23 @@ The library will decode formatted trace in three stages:-
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. + +Releases will appear on the master branch in the git repository with an appropriate version tag.
CoreSight Trace Component Support. ----------------------------------
-_Current Version 0.004_ +_Current Version 0.4_
### Current support:
@@ -38,7 +50,7 @@ output packet. Note on the Git Repository. ---------------------------
-At present, the git repository for OpenCSD contains both branches for the OpenCSD library itself, and branches that +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. @@ -49,6 +61,8 @@ 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 ------------- @@ -83,7 +97,7 @@ 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.004_: In development - decode tree api updates. +- _Version 0.4_ : Library development - updated decode tree and C-API for generic decoder handling. Switch to semantic versioning.
Licence Information =================== diff --git a/TODO b/TODO index 6bce346..e705a82 100644 --- a/TODO +++ b/TODO @@ -1,10 +1,8 @@ * Decode Tree API updates. -> Re-factor the decode tree API to: - 1) remove the per decoder type creation functions - CreateETMv4Decoder(...), - replacing with a single CreateDecoder("Type"). - 2) Use new structure to enable custom decoders - may be proprietary / binaries to + 1) Use new structure to enable custom decoders - may be proprietary / binaries to be used in the decoder structure. - 3) Make it easier to add a new decoder to the library source, without the overhead of + 2) Make it easier to add a new decoder to the library source, without the overhead of doing all the creation fns.
* STM "full decode". diff --git a/decoder/docs/doxygen_config.dox b/decoder/docs/doxygen_config.dox index d6b1666..72eeaa9 100644 --- a/decoder/docs/doxygen_config.dox +++ b/decoder/docs/doxygen_config.dox @@ -38,7 +38,7 @@ PROJECT_NAME = "OpenCSD - CoreSight Trace Decode Library" # could be handy for archiving the generated documentation or if some version # control system is used.
-PROJECT_NUMBER = 0.004 +PROJECT_NUMBER = 0.4
# Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a