1\page mipi_syst_adapting_page Adapting the SyS-T Library
2
3[TOC]
4
5SyS-T Platform Code {#mipi_syst_adapting_platform}
6==============================================================================
7The SyS-T library uses a platform concept for integrating it into a system.
8A platform is responsible for the following:
9
10   * Providing the low level trace output code that interfaces with the
11    underlying trace transport system. This is typically trace aggregating
12    hardware or a protocol driver. The ``example`` platform code
13    simply prints the SyS-T protocol output to stdout.
14
15   * Providing platform hook functions for SyS-T global and handle state
16     manipulations. This is platform specific code that allows efficient
17     processing of SyS-T.
18
19SyS-T ships with the following example platforms:
20
21Platform Directory|  Description
22------------|--------------------------------------------
23example     | Simple trace output driver that prints all IOs as hexadecimal data strings to ``stdout``. The [printer](@ref mipi_syst_printer_page) project can consume this output and decode it into human readable text using comma separated value format (CSV).
24mipi_stp_sim| [MIPI System Trace Protocol](https://mipi.org/specifications/stp) format file writer. It shows how to connect the library with an STP generator. In this example code, a software encoder is used to produce the STP data.
25nop         | A minimal boilerplate platform implementation that allows the library to compile but doesn't produce any output.
26
27Adapting SyS-T means providing your own platform code. The recommended procedure
28is to clone an existing platform folder and adapt it as needed. The following
29chapter shows an example of how this can be done.
30
31Copy an Existing Platform {#mipi_syst_adapting_copy}
32==============================================================================
33
34Example:
35
36     $ cd platform
37     $ cp -rv example myplatform
38
39Adapting the Platform {#mipi_syst_adapting_adapt}
40==============================================================================
41
42Modify the copied platfrom code to interface with the system by performing
43the following changes
44
45 * Implement the hook functions for state and handle initialisation and
46   destruction.
47 * Interface the data output writer code with the trace transport.
48   The writer routine in the library assumes a MIPI STP protocol style
49   output processor and calls a set of STP tailored macros named
50   ```MIPI_SYST_OUTPUT_*``` for the actual write operations. These macros
51   are defined in ```platform.h```. See #MIPI_SYST_OUTPUT_D32TS for an example
52   macro definition to emit a SyS-T message header which will turn into a MIPI
53   STP D32TS packet when using STP output. Alternatively replace the entire
54   writer code in a case where the MIPI STP writer cannot be efficently
55   interfaced with the transport.
56
57Edit the Build Configuration {#mipi_syst_adapting_build}
58==============================================================================
59Define the CMake symbol ```SYST_BUILD_PLATFORM_NAME``` to point to the new
60platform directory name. See the page @ref mipi_syst_building_page
61for further information on building SyS-T.
62
63Specify  the API conformance level by setting the CMAKE symbol
64```SYST_CFG_CONFORMANCE_LEVEL``` to one of the following:
65
66| Conformance level | Data Size                                              |
67| ------------------|--------------------------------------------------------|
68|  10               | Minimal - only Short and Compact Messages              |
69|  20               | Low overhead - excluding  printf and crc32             |
70|  30               | complete - All messages and options                    |
71
72