</head>
</pre>
-If pre-defined values will be used in the state provider, they must be defined before the state providers. They can then be referred to in the state changes by name, preceded by the '$' sign. It is not necessary to use pre-defined values, the state change can use values like (100, 101, 102) directly.
+If predefined values will be used in the state provider, they must be defined before the state providers. They can then be referred to in the state changes by name, preceded by the '$' sign. It is not necessary to use predefined values, the state change can use values like (100, 101, 102) directly.
<pre>
<definedValue name="RUNNING" value="100" />
If modifications are made to the XML state provider after it has been "published", the '''version''' attribute of the '''xmlStateProvider''' element should be updated. This avoids having to delete each trace's supplementary file manually. If the saved state system used a previous version, it will automatically be rebuilt from the XML file.
+== Defining an XML pattern provider ==
+It exists patterns within an execution trace that can provide high level details about the system execution. A '''pattern''' is a particular combination of events or states that are expected to occur within a trace. It may be composed of several state machines that inherit or communicate through a common state system.
+
+We may have multiple instances (scenarios) of a running state machine within a pattern. Each scenario which has its own path in the state system can generate segments to populate the data-driven views
+
+=== The state system structure ===
+
+The pattern analysis generates a predefined attribute tree described as follows :
+
+<pre>
+|- state machines
+| |- state machine 0
+| |- scenario 0
+| |- status
+| |- state
+| |- start
+| ...
+| |- storedFields
+| |- field 1
+| ...
+| |- startTime
+| ...
+| ...
+| |- scenarios 1
+| ...
+| |- state machine 1
+| ...
+</pre>
+
+The user can add custom data in this tree or determine its own attribute tree beside of this one.
+
+=== Writing the XML pattern provider ===
+Details about the XML structure are available in the XSD files.
+
+First define the pattern element. As the state provider element described in [[#Writing_the_XML_state_provider | Writing the XML state provider]], it has a "version" attribute and an "id" attribute.
+
+<pre>
+<pattern version="0" id="my.test.pattern">
+</pre>
+
+Optional header information as well as predefined values like described in [[#Writing_the_XML_state_provider | Writing the XML state provider]] can be added.
+
+Stored values can be added before the pattern handler. The predefined action '''saveStoredField''' triggers the updates of the stored fields and the predefined action '''clearStoredFields''' reset the values.
+
+<pre>
+<storedField id="offset" alias="offset"/>
+</pre>
+
+The behavior of the pattern and the models it needs are described in the pattern handler element.
+
+The structure of the state machine (FSM) is based on the SCXML structure. The following example describe an FSM that matches all the system call in an LTTng kernel trace.
+
+<pre>
+<fsm id="syscall" initial="start">
+ <state id="start">
+ <transition event="syscall_entry_*" target="syscall_entry_x" action="sys_x_founded" saveStoredFields="true"/>
+ </state>
+ <state id="in_progress" >
+ <transition event="syscall_exit_*" cond="thread_condition" target="syscall_exit_x" action="exit_syscall_found" saveStoredFields="true" clearStoredFields="true"/>
+ </state>
+ <final id="end"/>
+</fsm>
+</pre>
+
+The value of the target attribute corresponds to the 'id' of a test element described in the XML file and is a reference to it. Similarly, the value of the action attribute corresponds to the 'id' of an action element described in the XML file and is a reference to it.
+
+Conditions are used in the transitions to switch between the state of an FSM. They are defined under the '''test''' element. Two types of conditions are allowed : '''Data condition''' and '''Time condition'''. It is possible to combine several conditions using a logical operator (OR, AND, ...).
+
+Data conditions tests the ongoing event information against the data in the state system or constant values. The following condition tests whether the current thread running on the CPU is also the ongoing scenario thread.
+
+<pre>
+<test id="thread_condition">
+ <if>
+ <condition>
+ <stateValue type="query" >
+ <stateAttribute type="location" value="CurrentCPU" />
+ <stateAttribute type="constant" value="Current_thread" />
+ </stateValue>
+ <stateValue type="query">
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="thread" />
+ </stateValue>
+ </condition>
+ </if>
+</test>
+</pre>
+
+Two types of time conditions are available:
+* Time range conditions tests whether the ongoing event happens between a specific range of time. The following condition tests whether the ongoing event happens between 1 nanosecond and 3 nanoseconds.
+
+<pre>
+<test id="time_condition">
+ <if>
+ <condition>
+ <timerange unit="ns">
+ <in begin="1" end="3" />
+ </timerange>
+ </condition>
+ </if>
+</test>
+</pre>
+
+* Elapsed time conditions tests the value of the time spent since a specific state of an fsm. The following condition tests whether the ongoing event happens less than 3 nanoseconds after that the scenario reaches the state "syscall_entry_x".
+
+<pre>
+<test id="time_condition">
+ <if>
+ <condition>
+ <elapsedTime unit="ns">
+ <less since="syscall_entry_x" value="3" />
+ </elapsedTime>
+ </condition>
+ </if>
+</test>
+</pre>
+
+Two types of actions are allowed :
+* State changes update values of attributes into the state system. The following example set the value of the thread for the current scenario.
+
+<pre>
+ <action id="sys_x_found">
+ <stateChange>
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="thread" />
+ <stateValue type="query">
+ <stateAttribute type="location" value="CurrentCPU" />
+ <stateAttribute type="constant" value="Current_thread" />
+ </stateValue>
+ </stateChange>
+ </action>
+</pre>
+
+* Generate segments. The following example represents a system call segment.
+
+<pre>
+<action id="exit_syscall_founded">
+ <segment>
+ <segType>
+ <segName>
+ <stateValue type="query">
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="syscall" />
+ <stateAttribute type="constant" value="name" />
+ </stateValue>
+ </segName>
+ </segType>
+ </segment>
+</action>
+</pre>
+
+When existing, the stored fields will be added as fields for the generated segments.
+
+Here is the complete XML file by combining all the examples models above:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="xmlDefinition.xsd">
+
+<pattern version="1" id="my.test.pattern">
+ <head>
+ <traceType id="org.eclipse.linuxtools.lttng2.kernel.tracetype" />
+ <label value="xml syscall" />
+ </head>
+
+ <storedField id="filename"/>
+ <storedField id="fd"/>
+ <storedField id="ret" alias="ret"/>
+ <storedField id="flags" alias="flags"/>
+ <storedField id="offset" alias="offset"/>
+ <storedField id="fd_in" alias="fd_in"/>
+ <storedField id="fd_out" alias="fd_out"/>
+ <storedField id="uservaddr" alias="uservaddr"/>
+ <storedField id="upeer_sockaddr" alias="upeer_sockaddr"/>
+
+ <location id="CurrentThread">
+ <stateAttribute type="constant" value="Threads" />
+ <stateAttribute type="query">
+ <stateAttribute type="constant" value="CPUs" />
+ <stateAttribute type="eventField" value="cpu" />
+ <stateAttribute type="constant" value="Current_thread" />
+ </stateAttribute>
+ </location>
+
+ <location id="CurrentCPU">
+ <stateAttribute type="constant" value="CPUs" />
+ <stateAttribute type="eventField" value="cpu" />
+ </location>
+
+ <patternHandler>
+ <test id="time_condition">
+ <if>
+ <or>
+ <not>
+ <condition>
+ <timerange unit="ns">
+ <in begin="1" end="3" />
+ </timerange>
+ </condition>
+ </not>
+ <condition>
+ <elapsedTime unit="ns">
+ <less since="syscall_entry_x" value="3" />
+ </elapsedTime>
+ </condition>
+ </or>
+ </if>
+ </test>
+
+ <test id="thread_condition">
+ <if>
+ <condition>
+ <stateValue type="query" >
+ <stateAttribute type="location" value="CurrentCPU" />
+ <stateAttribute type="constant" value="Current_thread" />
+ </stateValue>
+ <stateValue type="query">
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="thread" />
+ </stateValue>
+ </condition>
+ </if>
+ </test>
+
+ <action id="sys_x_founded">
+ <stateChange>
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="syscall" />
+ <stateAttribute type="constant" value="name" />
+ <stateValue type="eventName"/>
+ </stateChange>
+
+ <stateChange>
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="cpu" />
+ <stateValue type="eventField" value="cpu"/>
+ </stateChange>
+
+ <stateChange>
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="thread" />
+ <stateValue type="query">
+ <stateAttribute type="location" value="CurrentCPU" />
+ <stateAttribute type="constant" value="Current_thread" />
+ </stateValue>
+ </stateChange>
+ </action>
+
+ <action id="exit_syscall_founded">
+ <segment>
+ <segType>
+ <segName>
+ <stateValue type="query">
+ <stateAttribute type="constant" value="#CurrentScenario" />
+ <stateAttribute type="constant" value="syscall" />
+ <stateAttribute type="constant" value="name" />
+ </stateValue>
+ </segName>
+ </segType>
+ </segment>
+ </action>
+
+ <fsm id="syscall" initial="start">
+ <state id="start">
+ <transition event="syscall_entry_*" target="syscall_entry_x" action="sys_x_founded" saveStoredFields="true"/>
+ </state>
+ <state id="in_progress" >
+ <transition event="syscall_exit_*" cond="thread_condition" target="syscall_exit_x" action="exit_syscall_found" saveStoredFields="true" clearStoredFields="true"/>
+ </state>
+ <final id="end"/>
+ </fsm>
+ </patternHandler>
+</pattern>
+</tmfxml>
+</pre>
+
+=== Representing the scenarios ===
+
+Segments generated by the pattern analysis are used to populate latency views. A description of these views can be found in [[#Latency_Analyses | Latency Analyses]].
+
+The full XML analysis example described above will generate the following views :
+
+* Latency Table
+
+[[Image:images/XMLPatternAnalysis/LatencyTable.png| Latency Table example - System Call pattern]]
+
+* Latency vs Time
+
+[[Image:images/XMLPatternAnalysis/LatencyVSTime.png| Latency vs Time example - System Call pattern]]
+
+* Latency Statistics
+
+[[Image:images/XMLPatternAnalysis/LatencyStatistics.png| Latency Statistics example - System Call pattern]]
+
+* Latency vs Count
+
+[[Image:images/XMLPatternAnalysis/LatencyVSCount.png| Latency vs Count example - System Call pattern]]
+
== Defining an XML time graph view ==
A time graph view is a view divided in two, with a tree viewer on the left showing information on the different entries to display and a Gantt-like viewer on the right, showing the state of the entries over time. The [[#Control_Flow_View | Control Flow View]] is an example of a time graph view.
-Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
+Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any predefined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
In the example above, suppose we want to display the status for each task. In the state system, it means the path of the entries to display is "Tasks/*". The attribute whose value should be shown in the Gantt chart is the entry attribute itself. So the XML to display these entries would be as such:
An XY chart displays series as a set of numerical values over time. The X-axis represents the time and is synchronized with the trace's current time range. The Y-axis can be any numerical value.
-Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
+Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any predefined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
We will use the Linux Kernel Analysis on LTTng kernel traces to show an example XY chart. In this state system, the status of each CPU is a numerical value. We will display this value as the Y axis of the series. There will be one series per CPU. The XML to display these entries would be as such:
projects / deliverable / tracecompass.git / commitdiff
