Merge pull request #2 from MIPI-Alliance/INITIAL_IMPORT_SYS_T_1.0

Adding MIPI System Software Trace Example Code

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "external/pugixml"]
+	path = external/pugixml
+	url = https://github.com/zeux/pugixml.git
+[submodule "external/googletest"]
+	path = external/googletest
+	url = https://github.com/google/googletest.git

LICENSE

@@ -1,29 +1,31 @@
-BSD 3-Clause License
-
-Copyright (c) 2017, MIPI-Alliance
+Copyright (c) 2018, MIPI Alliance, Inc. 
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+modification, are permitted provided that the following conditions
+are met:
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in
+  the documentation and/or other materials provided with the
+  distribution.
 
 * Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
+  contributors may be used to endorse or promote products derived
+  from this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

collateral/example_collateral.xml

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="utf-8"?>
+<syst:Collateral xmlns:syst="http://www.mipi.org/1.0/sys-t"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.mipi.org/1.0/sys-t
+                        https://www.mipi.org/schema/sys-t/sys-t_1-0.xsd">
+
+  <!--
+  A SyS-T collateral file starts with one syst:Collateral element
+  and contains at least one syst:Client child node.
+ -->
+  <syst:Client Name="example">
+
+    <!--
+    List of message GUIDs for this client:
+    A GUID is a 128bit numeric UUID following RFC 4122.
+    Clients that are identified by transport layer properties
+    can use pseudo GUID values to identify their messages. A
+    pseudo GUID is defined as a GUID with bit 71 set to zero.
+    The following encoding might be used for clients identified
+    by MIPI System Trace Protocol (STP) master/channel pairs:
+
+     {00000000-<MasterID>-<ChannelID>-<Origin>00-000000000000}
+
+    A Mask attribute can be added to define which bits of the GUID are
+    used for comparison. Without a mask, all bits need to match.
+    The example below makes the catalog valid for all channels from the
+    STP master value 0x644, or messages with the "494E..." GUID in their
+    payload.
+    -->
+    <syst:Guids>
+      <syst:Guid ID=  "{00000000-0644-0000-0000-000000000000}"
+                 Mask="{00000000-FFFF-0000-8000-000000000000}"><![CDATA[kernel]]></syst:Guid>
+      <syst:Guid ID="{494E5443-6F64-43D1-93F0-F3D49D92670C}"><![CDATA[user]]></syst:Guid>
+    </syst:Guids>
+
+    <!--
+    Define for which client build versions this collateral is valid.
+    Builds are expressed as values up to 64 bits in size, and can include a
+    mask that defines which bits need to match with a client build version
+    message.
+    -->
+    <syst:Builds>
+      <syst:Build ID="0x00010000" Mask="0xFFFF0000" ><![CDATA[SW Build 1.x]]></syst:Build>
+      <syst:Build ID="0x00020000" Mask="0xFFFF0000" ><![CDATA[SW Build 2.x]]></syst:Build>
+    </syst:Builds>
+
+     <!--
+     Settings to guide decoding tools what to do in cases
+     where several options are possible. The example below tells
+     a decoder to interprete SyS-T message timstamps only as an
+     informal field, but not the message creation time.
+     -->
+    <syst:Options>
+      <syst:Option Name="syst:timestamp">displayAsField</syst:Option>
+    </syst:Options>
+
+    <!--
+    Provide ID to name mapping for Origin header field values.
+    -->
+    <syst:Modules>
+      <syst:Module ID="0x1"><![CDATA[kernel]]></syst:Module>
+      <syst:Module ID="0x2"><![CDATA[user]]></syst:Module>
+  </syst:Modules>
+
+    <!--
+    Define the mapping of the numeric File-ID to source files.
+    This table is optional and only needed if source references are used
+    by the Catalog32 or Catalog64 elements.
+    -->
+    <syst:SourceFiles>
+      <syst:File ID="0x00000001"><![CDATA[example/src/main.c]]></syst:File>
+      <syst:File ID="0x00000002"><![CDATA[example/h/example.h]]></syst:File>
+    </syst:SourceFiles>
+
+    <!--
+    Define the mapping of catalog message ID to human-readable strings.
+    This table is optional and only needed if catalog messages are used.
+    A message can have optional "File" and "Line" attributes to specify the
+    source position of the instrumentation call. A decoder uses the
+    information from these attributes if the message payload doesn't provide
+    explicit location information.
+    -->
+    <syst:Catalog32>
+      <syst:Format ID="0x00000001" File="0x00000001" Line="23"><![CDATA[This is example %d.%d]]></syst:Format>
+      <syst:Format ID="0x00000002" File="0x00000002" Line="72"><![CDATA[task switch %x->%x]]></syst:Format>
+    </syst:Catalog32>
+
+    <syst:Catalog64>
+      <syst:Format ID="0x0000000000000001"><![CDATA[error %d]]></syst:Format>
+    </syst:Catalog64>
+
+    <!--
+    Define short message mapping from 28-Bit ID to user visible string.
+    -->
+    <syst:Short32>
+      <syst:Format ID="0x0000000" Mask="0xFFFFFF0"><![CDATA[Fatal Error code]]></syst:Format>
+      <syst:Format ID="0x0000013"><![CDATA[state ready]]></syst:Format>
+      <syst:Format ID="0x000001A"><![CDATA[state halt]]></syst:Format>
+    </syst:Short32>
+
+    <!--
+    Define short message mapping from 60-Bit ID to user visible string.
+    -->
+    <syst:Short64>
+      <syst:Format ID="0x123456700000000" Mask="0xFFFFFFF00000000"><![CDATA[warning state]]></syst:Format>
+
+    </syst:Short64>
+
+    <!--
+    Specify raw message protocol id assignment
+    -->
+    <syst:Write>
+      <syst:Protocol ID="0x01"><![CDATA[console]]></syst:Protocol>
+      <syst:Protocol ID="0x02"><![CDATA[console]]></syst:Protocol>
+      <syst:Protocol ID="0x03"><![CDATA[ftrace]]></syst:Protocol>
+      <syst:Protocol ID="0x20" Mask="0x30"><![CDATA[reserved]]></syst:Protocol>
+    </syst:Write>
+
+</syst:Client>
+
+</syst:Collateral>

collateral/generator/readme.txt

@@ -0,0 +1,8 @@
+syst_cgen.pl - a SYS-T message collateral generator
+
+Usage:
+perl ./syst_cgen.pl --help
+
+Example:
+An example project using the collateral generator
+is located in <SDK-ROOT>/library/examples/client.