Skip to content

MIPI-Alliance/public-mipi-sys-t

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MIPI System Software Trace (MIPI SyS-T) - Example Code

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 Trace Debug Environment

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.

MIPI SyS-T Overview

The MIPI specification for SyS-T is available from the MIPI Alliance Website.

Supported Platforms

  • Windows
  • Mac OS X
  • Linux

Requirements

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

Building

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.

Building the SyS-T Instrumentation Library

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_unittest

Building the Example Applications

The 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.

Building the Data Protocol Printer

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
(...)
$

Decode Collateral Creation Tool

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.

Dependencies

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'

Collateral Generation Process

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.

Catalog Generation Example

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.

Integration Build Test

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

License

See LICENSE