Dev guide

doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki

@@ -4786,17 +4786,17 @@ Data providers are queried with a filter object, which usually contains a time r
 
 == Data provider types ==
 
-The base data provider returns a tree, as a list of '''TmfTreeDataModel''', with a name, ID and parent ID. The ID is unique to a provider type and the parent ID indicates which element from the list is the entry's parent to rebuild the tree hierarchy from the list of models.
+The base data provider '''ITmfDataProvider''' interface is the interface each data provider type has to implement. The data provider factories create instances of such provider type. Tree data providers are of type '''ITmfTreeDataProvider''' extend the '''ITmfDataProvider''' interface and returns a tree, as a list of '''TmfTreeDataModel''', with a name, ID and parent ID. The ID is unique to a provider type and the parent ID indicates which element from the list is the entry's parent to rebuild the tree hierarchy from the list of models. Note such tree need to have limited size to not exceed the available memory.
 
-The base '''TimeGraphEntryModel''' class extends this with a start time and end time. Concrete classes are free to add other fields, as long as the model is serializable.
+The base '''TimeGraphEntryModel''' class extends this with a start time and end time. Concrete classes are free to add other fields, which can be used in the Eclipse Trace Context where the UI code can access the model type. However, in Trace Compass server context only fields defined in the Trace Server protocol will be serialized.
 
 === XY ===
 
 The XY data provider type is used to associate an XY series to an entry from the tree. The data provider is queried with a filter that also contains a Collection of the IDs of the entries for which we want XY series. The response contains a map of the series for the desired IDs.
 
 Each XY series can have its own x axis ('''ISeriesModel''' / '''SeriesModel''' - encapsulated in an '''ITmfXyModel''' / '''TmfXyModel''') or they can be shared by all models ('''IYModel''' / '''YModel''' encapsulated in an '''ITmfCommonXAxisModel''' / '''TmfCommonXAxisModel'''). The X axis is an array of longs, which makes it useful for a time axis or time buckets, but it can be used for any XY content.
 
-The interface to implement is '''ITmfTreeXYDataProvider'''.
+The interface to implement is '''ITmfTreeXYDataProvider'''. Abstract base classes exist for common use case, e.g. '''AbstractTreeDataProvider''' for tree data providers that are using a state system. Extend those classes if applicable.
 
 Here is a simple example of XY data provider, retrieving data from a simple state system displaying the child attributes of the root attributes.
 

doc/org.eclipse.tracecompass.examples.core/.project

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.eclipse.tracecompass.examples.core</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.pde.PluginNature</nature>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>

doc/org.eclipse.tracecompass.examples.core/META-INF/MANIFEST.MF

@@ -0,0 +1,25 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-SymbolicName: org.eclipse.tracecompass.examples.core;singleton:=true
+Bundle-Version: 1.0.12.qualifier
+Bundle-Localization: plugin
+Bundle-Activator: org.eclipse.tracecompass.examples.core.Activator
+Require-Bundle: org.eclipse.core.runtime,
+ org.eclipse.tracecompass.common.core,
+ org.eclipse.tracecompass.tmf.core,
+ org.eclipse.core.resources,
+ org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
+Bundle-ActivationPolicy: lazy
+Bundle-RequiredExecutionEnvironment: JavaSE-17
+Export-Package: org.eclipse.tracecompass.examples.core,
+ org.eclipse.tracecompass.examples.core.analysis,
+ org.eclipse.tracecompass.examples.core.analysis.config,
+ org.eclipse.tracecompass.examples.core.data.provider,
+ org.eclipse.tracecompass.examples.core.data.provider.config
+Bundle-Vendor: %Bundle-Vendor
+Import-Package: com.google.common.collect,
+ com.google.gson;version="2.8.2",
+ com.google.gson.annotations;version="2.8.2",
+ com.google.gson.reflect;version="2.8.2"
+Automatic-Module-Name: org.eclipse.tracecompass.examples.core

doc/org.eclipse.tracecompass.examples.core/plugin.properties

@@ -0,0 +1,16 @@
+###############################################################################
+# Copyright (c) 2014, 2025 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License 2.0
+# which accompanies this distribution, and is available at
+# https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#
+# Contributors:
+#    Ericsson - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass Examples Core Plug-in

doc/org.eclipse.tracecompass.examples.core/plugin.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?eclipse version="3.4"?>
+<plugin>
+   <extension
+         point="org.eclipse.linuxtools.tmf.core.analysis">
+      <module
+         id="org.eclipse.tracecompass.examples.state.system.module"
+         name="Example State System Module"
+         analysis_module="org.eclipse.tracecompass.examples.core.analysis.ExampleStateSystemAnalysisModule"
+         automatic="false">
+         <tracetype
+               class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
+         </tracetype>
+      </module>
+      <module
+         id="org.eclipse.tracecompass.examples.state.system.module.config"
+         name="Example State System Module"
+         analysis_module="org.eclipse.tracecompass.examples.core.analysis.config.ExampleConfigurableStateSystemAnalysisModule"
+         automatic="false">
+         <tracetype
+               class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
+         </tracetype>
+      </module>
+   </extension>
+   <extension point="org.eclipse.tracecompass.tmf.core.dataprovider">
+      <dataProviderFactory
+         class="org.eclipse.tracecompass.examples.core.data.provider.ExampleTimeGraphProviderFactory"
+         id="org.eclipse.tracecompass.examples.timegraph.dataprovider">
+      </dataProviderFactory>
+      <dataProviderFactory
+         class="org.eclipse.tracecompass.examples.core.data.provider.ExampleXYDataProviderFactory"
+         id="org.eclipse.tracecompass.examples.xy.dataprovider">
+      </dataProviderFactory>
+      <dataProviderFactory
+            class="org.eclipse.tracecompass.examples.core.data.provider.ExampleDataTreeDataProviderFactory"
+            id="org.eclipse.tracecompass.examples.nomodulestats">
+      </dataProviderFactory>
+      <dataProviderFactory
+            class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableDataTreeDataProviderFactory"
+            id="org.eclipse.tracecompass.examples.nomodulestats.config">
+      </dataProviderFactory>
+      <dataProviderFactory
+         class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableTimeGraphProviderFactory"
+         id="org.eclipse.tracecompass.examples.timegraph.dataprovider.config">
+      </dataProviderFactory>
+   </extension>
+</plugin>

doc/org.eclipse.tracecompass.examples.core/schema/example-schema-cpu.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://org.eclipse.tracecompass/example-schema.json",
+    "title": "Example Schema",
+    "description": "Example Schema for event statistics",
+    "type": "object",
+    "properties": {
+        "filter": {
+            "description": "filter regular expressions",
+            "type": "string"
+        }
+    },
+    "required": ["filter"]
+}

doc/org.eclipse.tracecompass.examples.core/schema/example-schema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://org.eclipse.tracecompass/example-schema.json",
+    "title": "Example Schema for cpu",
+    "description": "Example Schema for cpu",
+    "type": "object",
+    "properties": {
+        "filter": {
+            "description": "cpu number",
+            "type": "number"
+        }
+    },
+    "required": ["filter"]
+}

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/Activator.java

@@ -0,0 +1,78 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Ericsson
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.examples.core;
+
+
+import org.eclipse.core.runtime.Plugin;
+import org.osgi.framework.BundleContext;
+
+/**
+ */
+public class Activator extends Plugin {
+
+    /** The plug-in ID */
+    public static String PLUGIN_ID = "org.eclipse.tracecompass.examples.core"; //$NON-NLS-1$
+
+    // ------------------------------------------------------------------------
+    // Attributes
+    // ------------------------------------------------------------------------
+    /**
+     * The shared instance
+     */
+    private static Activator fPlugin;
+
+    // ------------------------------------------------------------------------
+    // Constructors
+    // ------------------------------------------------------------------------
+
+    /**
+     * Constructor
+     */
+    public Activator() {
+        setDefault(this);
+    }
+
+    // ------------------------------------------------------------------------
+    // Accessors
+    // ------------------------------------------------------------------------
+
+    /**
+     * Returns the plug-in instance.
+     *
+     * @return the plug-in instance.
+     */
+    public static Activator getDefault() {
+        return fPlugin;
+    }
+
+    // Sets plug-in instance
+    private static void setDefault(Activator plugin) {
+        fPlugin = plugin;
+    }
+
+    // ------------------------------------------------------------------------
+    // Plugin
+    // ------------------------------------------------------------------------
+
+    @Override
+    public void start(BundleContext context) throws Exception {
+        super.start(context);
+        setDefault(this);
+    }
+
+    @Override
+    public void stop(BundleContext context) throws Exception {
+        setDefault(null);
+        super.stop(context);
+    }
+}
+

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/analysis/config/ExampleConfigurableStateProvider.java

@@ -0,0 +1,131 @@
+/*******************************************************************************
+ * Copyright (c) 2020, 2025 École Polytechnique de Montréal and others
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License 2.0 which
+ * accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package org.eclipse.tracecompass.examples.core.analysis.config;
+
+import java.util.Map;
+import java.util.Objects;
+
+import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
+import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
+import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration;
+import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
+import org.eclipse.tracecompass.tmf.core.event.aspect.TmfCpuAspect;
+import org.eclipse.tracecompass.tmf.core.statesystem.AbstractTmfStateProvider;
+import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
+import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
+import org.eclipse.tracecompass.tmf.core.trace.TmfTraceUtils;
+
+import com.google.gson.Gson;
+import com.google.gson.JsonSyntaxException;
+import com.google.gson.annotations.Expose;
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * An example of a simple state provider for a simple state system analysis
+ *
+ * This module is also in the developer documentation of Trace Compass. If it is
+ * modified here, the doc should also be updated.
+ *
+ * @author Alexandre Montplaisir
+ * @author Geneviève Bastien
+ * @author Bernd Hufmann
+ */
+public class ExampleConfigurableStateProvider extends AbstractTmfStateProvider {
+
+    private static final @NonNull String PROVIDER_ID = "org.eclipse.tracecompass.examples.state.system.module.config"; //$NON-NLS-1$
+    private static final int VERSION = 0;
+    private int fCpu = -1;
+
+    /**
+     * Constructor
+     * 
+     * @param trace
+     *                     the trace
+     * @param configuration
+     *                     the configuration
+     */
+    public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace, @Nullable ITmfConfiguration configuration) {
+        super(trace, PROVIDER_ID + (configuration == null ? "" : ":" + configuration.getId())); //$NON-NLS-1$ //$NON-NLS-2$
+        if (configuration != null) {
+            try {
+                String jsonParameters = new Gson().toJson(configuration.getParameters(), Map.class);
+                @SuppressWarnings("null")
+                Integer cpu = new Gson().fromJson(jsonParameters, InternalConfiguration.class).getCpu();
+                if (cpu != null) {
+                    fCpu = cpu.intValue();
+                }
+            } catch (JsonSyntaxException e) {
+                fCpu = -1;
+            }
+        }
+    }
+
+    /**
+     * Constructor
+     *
+     * @param trace
+     *            The trace for this state provider
+     */
+    public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace) {
+        super(trace, PROVIDER_ID);
+    }
+
+    @Override
+    public int getVersion() {
+        return VERSION;
+    }
+
+    @Override
+    public @NonNull ITmfStateProvider getNewInstance() {
+        return new ExampleConfigurableStateProvider(getTrace());
+    }
+
+    @Override
+    protected void eventHandle(ITmfEvent event) {
+
+        /**
+         * Do what needs to be done with this event, here is an example that
+         * updates the CPU state and TID after a sched_switch
+         */
+        if (event.getName().equals("sched_switch")) { //$NON-NLS-1$
+
+            final long ts = event.getTimestamp().getValue();
+            Long nextTid = event.getContent().getFieldValue(Long.class, "next_tid"); //$NON-NLS-1$
+            Integer cpu = TmfTraceUtils.resolveIntEventAspectOfClassForEvent(event.getTrace(), TmfCpuAspect.class, event);
+            if (cpu == null || nextTid == null || (fCpu >= 0 && cpu != fCpu)) {
+                return;
+            }
+
+            ITmfStateSystemBuilder ss = Objects.requireNonNull(getStateSystemBuilder());
+            int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(cpu)); //$NON-NLS-1$
+            // The main quark contains the tid of the running thread
+            ss.modifyAttribute(ts, nextTid, quark);
+
+            // The status attribute has an integer value
+            int statusQuark = ss.getQuarkRelativeAndAdd(quark, "Status"); //$NON-NLS-1$
+            Integer value = (nextTid > 0 ? 1 : 0);
+            ss.modifyAttribute(ts, value, statusQuark);
+        }
+    }
+
+
+    private static class InternalConfiguration {
+        @Expose
+        @SerializedName(value = "cpu")
+        private @Nullable Integer fCpuValue = null;
+
+        public @Nullable Integer getCpu() {
+            return fCpuValue;
+        }
+    }
+}