{"id":20841371,"url":"https://github.com/zephyrproject-rtos/mipi-sys-t","last_synced_at":"2025-10-15T04:45:05.685Z","repository":{"id":42656443,"uuid":"217042311","full_name":"zephyrproject-rtos/mipi-sys-t","owner":"zephyrproject-rtos","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-08T16:06:34.000Z","size":443,"stargazers_count":7,"open_issues_count":1,"forks_count":10,"subscribers_count":3,"default_branch":"zephyr","last_synced_at":"2025-05-08T22:09:51.281Z","etag":null,"topics":["logging","module"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zephyrproject-rtos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-23T11:37:29.000Z","updated_at":"2025-04-21T02:56:09.000Z","dependencies_parsed_at":"2022-08-12T10:03:06.299Z","dependency_job_id":"6d182882-d718-432e-b291-e44bc82d0749","html_url":"https://github.com/zephyrproject-rtos/mipi-sys-t","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zephyrproject-rtos/mipi-sys-t","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephyrproject-rtos%2Fmipi-sys-t","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephyrproject-rtos%2Fmipi-sys-t/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephyrproject-rtos%2Fmipi-sys-t/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephyrproject-rtos%2Fmipi-sys-t/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephyrproject-rtos","download_url":"https://codeload.github.com/zephyrproject-rtos/mipi-sys-t/tar.gz/refs/heads/zephyr","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephyrproject-rtos%2Fmipi-sys-t/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279049972,"owners_count":26093391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logging","module"],"created_at":"2024-11-18T01:19:48.357Z","updated_at":"2025-10-15T04:45:05.667Z","avatar_url":"https://github.com/zephyrproject-rtos.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MIPI System Software Trace (MIPI SyS-T) - Example Code #\n\nThe **MIPI Alliance Specification for System Software-Trace (MIPI SyS-T\u0026#8480;**)\ndefines a platform-independent, low bandwidth trace data protocol and software\nAPI for generating trace debug information from mobile or mobile influenced\ndevices.\n\nThis project provides an example implementation of a MIPI SyS-T\ninstrumentation library as its main component. The library exposes the\nMIPI SyS-T API which generates the MIPI SyS-T data protocol.\n\nThe project includes the following additional components to provide a\nworking trace cross debug solution:\n\n  * An example implementation for a MIPI SyS-T data protocol printer for\n    converting the binary protocol into comma separated value (CSV)\n    text format.\n  * A PERL based collateral generator that automates the creation and\n    updating of MIPI SyS-T decode collateral in XML format. The generator\n    parses the catalog instrumentation calls inside the client source.\n    It can be embedded into the software build process to keep builds\n    and decode collateral updated at the same time.\n  * Doxygen based documentation for the instrumentation library.\n  * A unit test suite for the instrumentation library\n\n## SyS-T Trace Debug Environment ##\nSyS-T is intended for, but not limited to, cross-development environments\nwhere two machines, named target system (TS) and debug test system (DTS),\nexchange data over a transport layer. The TS uses the SyS-T library to generate\na trace data protocol that is sent via a transport to the DTS. The tool\nstack on the DTS reads the data and decodes it into a format suitable for human\nor automated analysis. The decode step utilizes collateral that\ncontains static trace data information like string to numeric key mappings. The\ncollateral is used to reduce both trace transport bandwidth and compiled\nsoftware space needs.\n\n![MIPI SyS-T Overview](library/doxygen/mipi_sys_t_overview.png)\n\nThe  MIPI specification for SyS-T is available from the\n[MIPI Alliance Website](https://mipi.org/specifications/sys-t).\n\n\n## Supported Platforms ##\n\n   * Windows\n   * Mac OS X\n   * Linux\n\n## Requirements ##\n\nThe instrumentation library is designed to have minimal dependencies for\nbuilding. The library core is written using self-contained C-language code.\nOnly the platform dependent adaptation software layer relies on C-runtime\nheaders and libraries.\n\nThe protocol printer is written in C++11 and requires a C++11 compliant\ncompiler and runtime environment.\n\nThe following third party components are used for building the project:\n\n  * [CMake](https://cmake.org/) for generating the platform dependent build system (required).\n  * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) for building the library documentation (optional).\n  * [Google Test](https://github.com/google/googletest) for building the library unit tests (optional).\n  * [PugiXML](https://github.com/zeux/pugixml) for building the printer project (required).\n\nThe Google Test and PugiXML components are configured as git modules\nin the external folder of this project. If the folders are not populated,\nrun the following command to pull the required components from GitHub.\n```\ngit submodule update --init --recursive\n```\n## Building ##\nThe project is split into the following sub projects.\n\n| Project                          | Location    |\n| ---------------------------------|-------------|\n| SyS-T instrumentation library    | library     |\n| Instrumented code examples       | examples    |\n| SyS-T protocol printer tool      | printer     |\n| Collateral generator tool        | collateral  |\n\nThe following chapters describe how to build the individual projects.\n\n### Building the SyS-T Instrumentation Library ###\nThe instrumentation library uses the CMake build system. Building\nthe project follows the normal CMake flow. It requires an initial CMake run\nto generate the platform dependent build system, for example Makefiles on\nLinux or Visual Studio Projects on Windows. The native build tools are then\nused to do the actual build. Note that CMake follows the \"out of source\"\nbuild concept. That means that you create a build folder for CMake\nprojects outside of the source sandbox. All build artifacts are\ncreated inside this build folder.\n\nThe CMake script for the instrumentation library uses the following\nconfiguration switches:\n\n| Option                           | Description |   Default Value |\n| ---------------------------------|-------------|-----------------|\n| CMAKE_INSTALL_PREFIX| Path prefix for the compiled library binaries and include files install location| (defined by CMake) |\n| SYST_BUILD_PLATFORM_NAME|Name of the platform adaption code folder| example |\n| SYST_BUILD_DOC|Enable build of Doxygen documentation| True if Doxygen installation was found, False otherwise |\n| SYST_BUILD_GTEST_DIR|Installation location of Google Test sources. Set this for building the unit tests| (unset) |\n\nThe following transcript shows an example for configuring and building the\nlibrary on a Linux console. Replace \"../sys-t/library\" with the location of\nyour SyS-T project sandbox.\n\n```\n$ mkdir build\n$ cd build\n$ cmake ../sys-t/library -DCMAKE_INSTALL_PREFIX=../deploy -DSYST_BUILD_PLATFORM_NAME=example -DCMAKE_BUILD_TYPE=Release\n(...)\n-- Configuring done\n-- Generating done\n-- Build files have been written to: /users/mipi/prj/build\n\n $ make install\n (...)\n -- Installing: /users/mipi/prj/deploy/lib/libmipi_syst.so\n -- Installing: /users/mipi/prj/deploy/lib/libmipi_syst_static.a\n -- Installing: /users/mipi/prj/deploy/include\n $\n```\nThe install target builds the projects and copies the libraries\nand SyS-T header files to the deploy location. This location was defined\nby the CMake variable ``CMAKE_INSTALL_PREFIX``. It forms a SyS-T SDK\nthat applications compile and link against.\n\nIf the unit tests are built as well, they can be run using one of the\nfollowing commands:\n\n```bash\n$ ctest -verbose\n$ make RUN_TEST_VERBOSE\n$ ./test/unit/syst_unittest\n```\n\n### Building the Example Applications ###\nThe project ships with example applications that show how to instrument\nsource code with the SyS-T API. The examples use the CMake build\nsystem and require that the instrumentation library project was built and\ninstalled first. The building depends on the SyS-T libraries and header\nfiles in the install location. The location of the install folder needs\nto be specified by setting the CMake variable ``SYST_SDK`` when configuring\nthe example project.\n\nThe following transcript shows the configuring and building of the examples\nin a Linux console. Replace \"../sys-t/examples\" with the location of\nyour SyS-T sandbox examples folder and replace the value for SYST_SDK\nwith the location of the install location from a previously built\ninstrumentation library.\n\n\n```\n$ mkdir build_examples\n$ cd build_examples\n$ cmake ../sys-t/examples -DSYST_SDK=../deploy -DCMAKE_BUILD_TYPE=Release\n\n-- Found SYST: /users/mipi/prj/deploy/include\n-- Configuring done\n-- Generating done\n-- Build files have been written to: /users/mipi/prj/build_examples\n\n$ make\nScanning dependencies of target hello\n[ 20%] Building C object hello/CMakeFiles/hello.dir/hello.c.o\n[ 40%] Linking C executable hello\n[ 40%] Built target hello\nScanning dependencies of target systclient\n[ 60%] Building C object client/CMakeFiles/systclient.dir/systclient.c.o\n[ 80%] Building C object client/CMakeFiles/systclient.dir/othersource.c.o\n[100%] Linking C executable systclient\n[100%] Built target systclient\n```\n\nThe examples code builds into standalone applications that can be run\ndirectly from the console. To run the minimal hello example, enter the\nfollowing command:\n\n```\n$ hello/hello\n  in SyS-T platform init hook: \"mipi_syst_platform_state_init()\"\n                              systh = 0x6250c0, platform_data = (nil)\n  in SyS-T platform handle init hook: systh = 0x1edd420\n\nSTP Protocol Output:\n     0 \u003cD32TS\u003e  01801042\n     1 \u003cD64\u003e    704caea243544e49\n     2 \u003cD64\u003e    35ea9c9ea7d1b5ab\n     3 \u003cD64\u003e    7953206f6c6c6548\n     4 \u003cD32\u003e    21542d53\n     5 \u003cD8\u003e     00\n     6 \u003cFLAG\u003e\nSYS-T RAW DATA: 42108001494E5443A2AE4C70ABB5D1A79E9CEA3548656C6C6F205379532D542100\n\n  in SyS-T platform handle release hook:systh = 0x1edd420\n$\n```\n\nThe transcript shows the output from the example platform code in\nthe instrumentation library. The example platform code only prints\noutput actions to the console. It does not interface to any real\ntrace transport. The output shows the raw messages as hex dumps.\nThis output can be fed into the protocol printer tool to convert\nit into human readable CSV textual data.\n\n### Building the Data Protocol Printer ###\nThe project includes a SyS-T data protocol pretty printer tool\nin the printer subdirectory. The printer is a standalone application\nwritten in C++11. It supports reading the output from instrumented\napplications using the example platform from the SyS-T\ninstrumentation library.\nIt scans the output for lines starting with ``SYS-T RAW DATA:`` and\nconverts the hex dumps into binary data for decoding. The printer can\nbe easily adapted to real trace data transports by replacing the code\nin ``printer/src/mipi_syst_main.cpp`` with an appropriate data reader.\n\nThe following transcript shows how to build the printer on a Linux console.\nThe printer is a standalone application and independent from the\ninstrumentation or example projects.\n\n```\n$ cmake ../../sys-t/printer\n-- The C compiler identification is GNU 5.4.0\n-- The CXX compiler identification is GNU 5.4.0\n-- Check for working C compiler: /usr/bin/cc\n-- Check for working C compiler: /usr/bin/cc -- works\n-- Detecting C compiler ABI info\n-- Detecting C compiler ABI info - done\n-- Detecting C compile features\n-- Detecting C compile features - done\n-- Check for working CXX compiler: /usr/bin/c++\n-- Check for working CXX compiler: /usr/bin/c++ -- works\n-- Detecting CXX compiler ABI info\n-- Detecting CXX compiler ABI info - done\n-- Detecting CXX compile features\n-- Detecting CXX compile features - done\n-- Configuring done\n-- Generating done\n-- Build files have been written to: /users/mipi/prj/syst_build/printer\n\n$ make\nScanning dependencies of target systprint\n[ 14%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_main.cpp.o\n[ 28%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_collateral.cpp.o\n[ 42%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_printf.cpp.o\n[ 57%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_decode.cpp.o\n[ 71%] Building CXX object CMakeFiles/systprint.dir/src/mipi_syst_message.cpp.o\n[100%] Linking CXX executable systprint\n[100%] Built target systprint\n```\n\nThe printer project comes with a self test feature. The ``printer/test``\nfolder contains reference input and output files collected using the\n``example/client`` example application. To run the printer test use the\nfollowing command (or the cmake test driver command ``ctest``) in the\nprinter build folder:\n\n```\n$ make test\nRunning tests...\nTest project /users/mipi/prj/syst_build/printer\n    Start 1: print_client_example\n1/3 Test #1: print_client_example ...............   Passed    0.01 sec\n    Start 2: diff_output_with_32bit_reference\n2/3 Test #2: diff_output_with_32bit_reference ...   Passed    0.04 sec\n    Start 3: diff_output_with_64bit_reference\n3/3 Test #3: diff_output_with_64bit_reference ...   Passed    0.03 sec\n\n100% tests passed, 0 tests failed out of 3\n\nTotal Test time (real) =   0.11 sec\n```\n\nTo actually see the printer output, run the printer directly using command\nline arguments, or indirectly through the test driver in verbose mode\n(```ctest --verbose```). The following transcript shows how to call the\nprinter directly:\n\n```\n$systprint --short_guid {494E5443-8A9C-4014-A65A-2F36A36D96E4} --collateral ../../sys-t/printer/test/collateral.xml ../../sys-t/printer/test/input_client64.txt\n\nDecode Status,Payload,Type,Severity,Origin,Unit,Message TimeStamp,Context TimeStamp,Location,Raw Length,Checksum,Collateral\nOK,\"0x0000000000010000 version banner string\",BUILD:LONG,MAX,example,1,0x00054A4B376A70E9,0x0000000000000000,,62,0x4DDEF5B9,../../sys-t/printer/test/collateral.xml\nOK,\"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\nOK,\"+-------------------------------------------------------+\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000002,./othersource.c:40,36,0x7CBB44B6,../../sys-t/printer/test/collateral.xml\nOK,\"|               ____         _____   _______            |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000003,./othersource.c:41,36,0x2761EBF4,../../sys-t/printer/test/collateral.xml\nOK,\"|              / ___|       / ____| |__   __|           |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000004,./othersource.c:42,36,0x55C63EAB,../../sys-t/printer/test/collateral.xml\nOK,\"|             | |___  __  _| |___ _____| |              |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000005,./othersource.c:43,36,0xE3885FB4,../../sys-t/printer/test/collateral.xml\nOK,\"|              \\___ \\| | | |\\___ \\_____| |              |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000006,./othersource.c:44,36,0x4C13A7F5,../../sys-t/printer/test/collateral.xml\nOK,\"|              ____| | |_| |____| |    | |              |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000007,./othersource.c:45,36,0xE2C8BDC2,../../sys-t/printer/test/collateral.xml\nOK,\"|             |_____/ \\__| |_____/     |_|              |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000008,./othersource.c:46,36,0xD0734297,../../sys-t/printer/test/collateral.xml\nOK,\"|                      _/ /                             |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x0000000000000009,./othersource.c:47,36,0x6D704426,../../sys-t/printer/test/collateral.xml\nOK,\"|                     |__/                              |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000A,./othersource.c:48,36,0x0A8FD609,../../sys-t/printer/test/collateral.xml\nOK,\"+-------------------------------------------------------+\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000B,./othersource.c:49,36,0x1E99CD8F,../../sys-t/printer/test/collateral.xml\nOK,\"|    catalog Format  |         Printed Result           |\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A70E9,0x000000000000000C,./othersource.c:231,36,0xA17B5C1C,../../sys-t/printer/test/collateral.xml\nOK,\"|---------------------------------strings---------------|\",CATALOG:ID32P64,INFO,example,1,0x00054A4B376A74D1,0x000000000000000D,./othersource.c:232,36,0x11A215E6,../../sys-t/printer/test\n(...)\n$\n```\n## Decode Collateral Creation Tool ##\nThe project includes a PERL based collateral generator that automates the\ncreation and updating of SyS-T decode collateral in XML format. This\ngenerator parses the catalog instrumentation points by scanning the\nclient source code. The tool can be embedded into a software build process to\nkeep software builds and decode collateral updated at the same time. The tool\nis stored in the ```collateral\\generator``` folder of the project with the\nname ```syst_cgen.pl```.\n\n### Dependencies ###\nThe generator is written in PERL and requires a PERL installation with the\nfollowing optional modules installed.\n * String::Escape\n * Xml::Simple\n\nRefer to the documentation for your PERL installation on module installation.\nOn Linux, the following commands can be used:\n\n```\n$ perl -MCPAN -e 'install XML::Simple'\n$ perl -MCPAN -e 'install String::Escape'\n```\n\n### Collateral Generation Process ###\nThe collateral generator takes a SyS-T collateral template and\na configuration file as input. The configuration file defines the locations\nand file extensions of the source files to be scanned and how the catalog\nmessage calls\ninside the source code are named. The tool can then detect the catalog\ncalls, and extracts the format strings, source locations, and\ncatalog IDs to update the collateral template file. The result is a\nnew collateral file that matches the actual state of the source code.\n\n### Catalog Generation Example ###\nThe client application in ```example/client``` uses various catalog calls.\nIt therefore provides a configuration file for```syst_cgen.pl``` to detect\nthe SyS-T catalog message calls, and a collateral template file that is\nupdated by the generator. It is executed in the following way:\n\n```\n$ perl ../../collateral/generator/syst_cgen.pl -config collateral_config.xml\nsyst_catgen.pl: Parsing: ./othersource.c\nsyst_catgen.pl: Add ./othersource.c with file id 1 to file catalog\nsyst_catgen.pl: Parsing finished: ./othersource.c, found 127 call(s)\nsyst_catgen.pl: Parsing: ./systclient.c\nsyst_catgen.pl: Add ./systclient.c with file id 2 to file catalog\nsyst_catgen.pl: Parsing finished: ./systclient.c, found 4 call(s)\nsyst_catgen.pl: Generating XML structure\nsyst_catgen.pl: Loaded template collateral file template.xml\nsyst_catgen.pl: Generating XML structure finished\nsyst_catgen.pl: Writing XML file: generated_catalog.xml\nsyst_catgen.pl: Writing XML file finished\n```\n\nThis call creates the file ``generated_catalog.xml``. It is used by\nSyS-T data protocol processing tools to decode the catalog messages\nfrom this application. For an example of such an application, see the\nearlier section about the protocol printer. The printer tool uses the\n``--collateral \u003cfile\u003e`` argument to load collateral files.\n\n## Integration Build Test ##\nThe bash script in ``examples/scripts/bldall.sh`` can be used to run an\nintegration test for the different projects. The script builds all projects\nsequentially using the example library platform. It then runs components\ntests and finally calls the printer tool to format the output of\nthe ``hello`` example application. The following transcript shows how to\nrun execute the script. The BLD_ROOT variable sets the location of the build\nfolder. If unset, the script creates a local build folder in the scripts\nfolder.\n\n```\n$ cd sys-t/examples/scripts\n$ BLD_ROOT=/tmp/sys_t_test_bld ./bldall.sh\n```\n\n## License\n\nSee [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephyrproject-rtos%2Fmipi-sys-t","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephyrproject-rtos%2Fmipi-sys-t","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephyrproject-rtos%2Fmipi-sys-t/lists"}