The MIPI Alliance Specification for System Software-Trace (MIPI SyS-T℠) defines a platform-independent, low bandwidth trace data protocol and software API for generating trace debug information from mobile or mobile influenced devices.
This project provides an example implementation of a MIPI SyS-T instrumentation library as its main component. The library exposes the MIPI SyS-T API which generates the MIPI SyS-T data protocol.
The project includes the following additional components to provide a working trace cross debug solution:
- An example implementation for a MIPI SyS-T data protocol printer for converting the binary protocol into comma separated value (CSV) text format.
- A PERL based collateral generator that automates the creation and updating of MIPI SyS-T decode collateral in XML format. The generator parses the catalog instrumentation calls inside the client source. It can be embedded into the software build process to keep builds and decode collateral updated at the same time.
- Doxygen based documentation for the instrumentation library.
- A unit test suite for the instrumentation library
SyS-T is intended for, but not limited to, cross-development environments where two machines, named target system (TS) and debug test system (DTS), exchange data over a transport layer. The TS uses the SyS-T library to generate a trace data protocol that is sent via a transport to the DTS. The tool stack on the DTS reads the data and decodes it into a format suitable for human or automated analysis. The decode step utilizes collateral that contains static trace data information like string to numeric key mappings. The collateral is used to reduce both trace transport bandwidth and compiled software space needs.
The MIPI specification for SyS-T is available from the MIPI Alliance Website.
- Windows
- Mac OS X
- Linux
The instrumentation library is designed to have minimal dependencies for building. The library core is written using self-contained C-language code. Only the platform dependent adaptation software layer relies on C-runtime headers and libraries.
The protocol printer is written in C++11 and requires a C++11 compliant compiler and runtime environment.
The following third party components are used for building the project:
- CMake for generating the platform dependent build system (required).
- Doxygen for building the library documentation (optional).
- Google Test for building the library unit tests (optional).
- PugiXML for building the printer project (required).
The Google Test and PugiXML components are configured as git modules in the external folder of this project. If the folders are not populated, run the following command to pull the required components from GitHub.
git submodule update --init --recursive
The project is split into the following sub projects.
| Project | Location |
|---|---|
| SyS-T instrumentation library | library |
| Instrumented code examples | examples |
| SyS-T protocol printer tool | printer |
| Collateral generator tool | collateral |
The following chapters describe how to build the individual projects.
The instrumentation library uses the CMake build system. Building the project follows the normal CMake flow. It requires an initial CMake run to generate the platform dependent build system, for example Makefiles on Linux or Visual Studio Projects on Windows. The native build tools are then used to do the actual build. Note that CMake follows the "out of source" build concept. That means that you create a build folder for CMake projects outside of the source sandbox. All build artifacts are created inside this build folder.
The CMake script for the instrumentation library uses the following configuration switches:
| Option | Description | Default Value |
|---|---|---|
| CMAKE_INSTALL_PREFIX | Path prefix for the compiled library binaries and include files install location | (defined by CMake) |
| SYST_BUILD_PLATFORM_NAME | Name of the platform adaption code folder | example |
| SYST_BUILD_DOC | Enable build of Doxygen documentation | True if Doxygen installation was found, False otherwise |
| SYST_BUILD_GTEST_DIR | Installation location of Google Test sources. Set this for building the unit tests | (unset) |
The following transcript shows an example for configuring and building the library on a Linux console. Replace "../sys-t/library" with the location of your SyS-T project sandbox.
$ mkdir build
$ cd build
$ cmake ../sys-t/library -DCMAKE_INSTALL_PREFIX=../deploy -DSYST_BUILD_PLATFORM_NAME=example -DCMAKE_BUILD_TYPE=Release
(...)
-- Configuring done
-- Generating done
-- Build files have been written to: /users/mipi/prj/build
$ make install
(...)
-- Installing: /users/mipi/prj/deploy/lib/libmipi_syst.so
-- Installing: /users/mipi/prj/deploy/lib/libmipi_syst_static.a
-- Installing: /users/mipi/prj/deploy/include
$
The install target builds the projects and copies the libraries
and SyS-T header files to the deploy location. This location was defined
by the CMake variable CMAKE_INSTALL_PREFIX. It forms a SyS-T SDK
that applications compile and link against.
If the unit tests are built as well, they can be run using one of the following commands:
$ ctest -verbose
$ make RUN_TEST_VERBOSE
$ ./test/unit/syst_unittestThe project ships with example applications that show how to instrument
source code with the SyS-T API. The examples use the CMake build
system and require that the instrumentation library project was built and
installed first. The building depends on the SyS-T libraries and header
files in the install location. The location of the install folder needs
to be specified by setting the CMake variable SYST_SDK when configuring
the example project.
The following transcript shows the configuring and building of the examples in a Linux console. Replace "../sys-t/examples" with the location of your SyS-T sandbox examples folder and replace the value for SYST_SDK with the location of the install location from a previously built instrumentation library.
$ mkdir build_examples
$ cd build_examples
$ cmake ../sys-t/examples -DSYST_SDK=../deploy -DCMAKE_BUILD_TYPE=Release
-- Found SYST: /users/mipi/prj/deploy/include
-- Configuring done
-- Generating done
-- Build files have been written to: /users/mipi/prj/build_examples
$ make
Scanning dependencies of target hello
[ 20%] Building C object hello/CMakeFiles/hello.dir/hello.c.o
[ 40%] Linking C executable hello
[ 40%] Built target hello
Scanning dependencies of target systclient
[ 60%] Building C object client/CMakeFiles/systclient.dir/systclient.c.o
[ 80%] Building C object client/CMakeFiles/systclient.dir/othersource.c.o
[100%] Linking C executable systclient
[100%] Built target systclient
The examples code builds into standalone applications that can be run directly from the console. To run the minimal hello example, enter the following command:
$ hello/hello
in SyS-T platform init hook: "mipi_syst_platform_state_init()"
systh = 0x6250c0, platform_data = (nil)
in SyS-T platform handle init hook: systh = 0x1edd420
STP Protocol Output:
0 <D32TS> 01801042
1 <D64> 704caea243544e49
2 <D64> 35ea9c9ea7d1b5ab
3 <D64> 7953206f6c6c6548
4 <D32> 21542d53
5 <D8> 00
6 <FLAG>
SYS-T RAW DATA: 42108001494E5443A2AE4C70ABB5D1A79E9CEA3548656C6C6F205379532D542100
in SyS-T platform handle release hook:systh = 0x1edd420
$
The transcript shows the output from the example platform code in the instrumentation library. The example platform code only prints output actions to the console. It does not interface to any real trace transport. The output shows the raw messages as hex dumps. This output can be fed into the protocol printer tool to convert it into human readable CSV textual data.
The project includes a SyS-T data protocol pretty printer tool
in the printer subdirectory. The printer is a standalone application
written in C++11. It supports reading the output from instrumented
applications using the example platform from the SyS-T
instrumentation library.
It scans the output for lines starting with SYS-T RAW DATA: and
converts the hex dumps into binary data for decoding. The printer can
be easily adapted to real trace data transports by replacing the code
in printer/src/mipi_syst_main.cpp with an appropriate data reader.
The following transcript shows how to build the printer on a Linux console. The printer is a standalone application and independent from the instrumentation or example projects.
$ cmake ../../sys-t/printer
-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /users/mipi/prj/syst_build/printer
$ make
Scanning dependencies of target systprint
[ 14%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_main.cpp.o
[ 28%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_collateral.cpp.o
[ 42%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_printf.cpp.o
[ 57%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_decode.cpp.o
[ 71%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_message.cpp.o
[100%] Linking CXX executable systprint
[100%] Built target systprint
The printer project comes with a self test feature. The printer/test
folder contains reference input and output files collected using the
example/client example application. To run the printer test use the
following command (or the cmake test driver command ctest) in the
printer build folder:
$ make test
Running tests...
Test project /users/mipi/prj/syst_build/printer
Start 1: print_client_example
1/3 Test #1: print_client_example ............... Passed 0.01 sec
Start 2: diff_output_with_32bit_reference
2/3 Test #2: diff_output_with_32bit_reference ... Passed 0.04 sec
Start 3: diff_output_with_64bit_reference
3/3 Test #3: diff_output_with_64bit_reference ... Passed 0.03 sec
100% tests passed, 0 tests failed out of 3
Total Test time (real) = 0.11 sec
To actually see the printer output, run the printer directly using command
line arguments, or indirectly through the test driver in verbose mode
(ctest --verbose). The following transcript shows how to call the
printer directly:
$systprint --short_guid {494E5443-8A9C-4014-A65A-2F36A36D96E4} --collateral ../../sys-t/printer/test/collateral.xml ../../sys-t/printer/test/input_client64.txt
Decode Status,Payload,Type,Severity,Origin,Unit,Message TimeStamp,Context TimeStamp,Location,Raw Length,Checksum,Collateral
OK,"0x0000000000010000 version banner string",BUILD:LONG,MAX,example,1,0x00054A4B376A70E9,0x0000000000000000,,62,0x4DDEF5B9,../../sys-t/printer/test/collateral.xml
OK,"SyS-T Library version 1.0.0",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000001,./systclient.c:64,48,0x7A34B527,../../sys-t/printer/test/collateral.xml
OK,"+-------------------------------------------------------+",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000002,./othersource.c:40,36,0x7CBB44B6,../../sys-t/printer/test/collateral.xml
OK,"| ____ _____ _______ |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000003,./othersource.c:41,36,0x2761EBF4,../../sys-t/printer/test/collateral.xml
OK,"| / ___| / ____| |__ __| |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000004,./othersource.c:42,36,0x55C63EAB,../../sys-t/printer/test/collateral.xml
OK,"| | |___ __ _| |___ _____| | |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000005,./othersource.c:43,36,0xE3885FB4,../../sys-t/printer/test/collateral.xml
OK,"| \___ \| | | |\___ \_____| | |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000006,./othersource.c:44,36,0x4C13A7F5,../../sys-t/printer/test/collateral.xml
OK,"| ____| | |_| |____| | | | |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000007,./othersource.c:45,36,0xE2C8BDC2,../../sys-t/printer/test/collateral.xml
OK,"| |_____/ \__| |_____/ |_| |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000008,./othersource.c:46,36,0xD0734297,../../sys-t/printer/test/collateral.xml
OK,"| _/ / |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000009,./othersource.c:47,36,0x6D704426,../../sys-t/printer/test/collateral.xml
OK,"| |__/ |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000A,./othersource.c:48,36,0x0A8FD609,../../sys-t/printer/test/collateral.xml
OK,"+-------------------------------------------------------+",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000B,./othersource.c:49,36,0x1E99CD8F,../../sys-t/printer/test/collateral.xml
OK,"| catalog Format | Printed Result |",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000C,./othersource.c:231,36,0xA17B5C1C,../../sys-t/printer/test/collateral.xml
OK,"|---------------------------------strings---------------|",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A74D1,0x000000000000000D,./othersource.c:232,36,0x11A215E6,../../sys-t/printer/test
(...)
$
The project includes a PERL based collateral generator that automates the
creation and updating of SyS-T decode collateral in XML format. This
generator parses the catalog instrumentation points by scanning the
client source code. The tool can be embedded into a software build process to
keep software builds and decode collateral updated at the same time. The tool
is stored in the collateral\generator folder of the project with the
name syst_cgen.pl.
The generator is written in PERL and requires a PERL installation with the following optional modules installed.
- String::Escape
- Xml::Simple
Refer to the documentation for your PERL installation on module installation. On Linux, the following commands can be used:
$ perl -MCPAN -e 'install XML::Simple'
$ perl -MCPAN -e 'install String::Escape'
The collateral generator takes a SyS-T collateral template and a configuration file as input. The configuration file defines the locations and file extensions of the source files to be scanned and how the catalog message calls inside the source code are named. The tool can then detect the catalog calls, and extracts the format strings, source locations, and catalog IDs to update the collateral template file. The result is a new collateral file that matches the actual state of the source code.
The client application in example/client uses various catalog calls.
It therefore provides a configuration file forsyst_cgen.pl to detect
the SyS-T catalog message calls, and a collateral template file that is
updated by the generator. It is executed in the following way:
$ perl ../../collateral/generator/syst_cgen.pl -config collateral_config.xml
syst_catgen.pl: Parsing: ./othersource.c
syst_catgen.pl: Add ./othersource.c with file id 1 to file catalog
syst_catgen.pl: Parsing finished: ./othersource.c, found 127 call(s)
syst_catgen.pl: Parsing: ./systclient.c
syst_catgen.pl: Add ./systclient.c with file id 2 to file catalog
syst_catgen.pl: Parsing finished: ./systclient.c, found 4 call(s)
syst_catgen.pl: Generating XML structure
syst_catgen.pl: Loaded template collateral file template.xml
syst_catgen.pl: Generating XML structure finished
syst_catgen.pl: Writing XML file: generated_catalog.xml
syst_catgen.pl: Writing XML file finished
This call creates the file generated_catalog.xml. It is used by
SyS-T data protocol processing tools to decode the catalog messages
from this application. For an example of such an application, see the
earlier section about the protocol printer. The printer tool uses the
--collateral <file> argument to load collateral files.
The bash script in examples/scripts/bldall.sh can be used to run an
integration test for the different projects. The script builds all projects
sequentially using the example library platform. It then runs components
tests and finally calls the printer tool to format the output of
the hello example application. The following transcript shows how to
run execute the script. The BLD_ROOT variable sets the location of the build
folder. If unset, the script creates a local build folder in the scripts
folder.
$ cd sys-t/examples/scripts
$ BLD_ROOT=/tmp/sys_t_test_bld ./bldall.sh
See LICENSE