callstack: Add the doc.user files from Incubator's

Preserve the original Incubator files, and supporting files as they are elsewhere in the code base. Simply main-line the incubated callstack documentation as is, for this initial scope. Use 8.3.0.qualifier as Bundle-Version to pass the Maven build locally. Change-Id: Ic96253819a3489fb1952f91040e5fe6105c03877 Signed-off-by: Marco Miller <marco.miller@ericsson.com> Reviewed-on: https://git.eclipse.org/r/c/tracecompass/org.eclipse.tracecompass/+/200145 Tested-by: Trace Compass Bot <tracecompass-bot@eclipse.org> Tested-by: Bernd Hufmann <bernd.hufmann@ericsson.com> Reviewed-by: Bernd Hufmann <bernd.hufmann@ericsson.com>
eclipse-tracecompass · Mar 31, 2023 · 8c78d20 · 8c78d20
1 parent 97d76b1
commit 8c78d20
Show file tree

Hide file tree

Showing 18 changed files with 391 additions and 0 deletions.
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/.project b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/.project
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.eclipse.tracecompass.analysis.callstack.doc.user</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<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>
+	</natures>
+</projectDescription>
diff --git a/...lipse.tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.core.resources.prefs b/...lipse.tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.core.resources.prefs
@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
diff --git a/...eclipse.tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.core.runtime.prefs b/...eclipse.tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.core.runtime.prefs
@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+line.separator=\n
diff --git a/...tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.ltk.core.refactoring.prefs b/...tracecompass.analysis.callstack.doc.user/.settings/org.eclipse.ltk.core.refactoring.prefs
@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/META-INF/MANIFEST.MF b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/META-INF/MANIFEST.MF
@@ -0,0 +1,8 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 8.3.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.analysis.callstack.doc.user;singleton:=true
+Require-Bundle: org.eclipse.help
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/about.html b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/about.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<title>About</title>
+</head>
+<body lang="EN-US">
+	<h2>About This Content</h2>
+	<p>November 30, 2017</p>
+	<h3>License</h3>
+	<p>
+		The Eclipse Foundation makes available all content in this plug-in
+		(&quot;Content&quot;). Unless otherwise indicated below, the Content
+		is provided to you under the terms and conditions of the Eclipse
+		Public License Version 2.0 (&quot;EPL&quot;). A copy of the EPL is
+		available at <a href="http://www.eclipse.org/legal/epl-2.0">http://www.eclipse.org/legal/epl-2.0</a>.
+		For purposes of the EPL, &quot;Program&quot; will mean the Content.
+	</p>
+	<p>
+		If you did not receive this Content directly from the Eclipse
+		Foundation, the Content is being redistributed by another party
+		(&quot;Redistributor&quot;) and different terms and conditions may
+		apply to your use of any object code in the Content. Check the
+		Redistributor's license that was provided with the Content. If no such
+		license exists, contact the Redistributor. Unless otherwise indicated
+		below, the terms and conditions of the EPL still apply to any source
+		code in the Content and such source code may be obtained at <a
+			href="http://www.eclipse.org/">http://www.eclipse.org</a>.
+	</p>
+</body>
+</html>
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/book.css b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/book.css
@@ -0,0 +1,59 @@
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre				{ font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre				{ font-size: 12pt}
+
+/* end font size declarations */
+
+body	     { background: #FFFFFF}
+h1           { font-size: 18pt; margin-top: 5; margin-bottom: 1 }	
+h2           { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3           { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4           { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5           { font size: 13.5pt; }
+p 	     { font-size: 12pt; }
+pre	     { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover  { color: #006699 }
+
+ul	     { margin-top: 0; margin-bottom: 10 }
+li	     { margin-top: 0; margin-bottom: 0 } 
+li p	     { margin-top: 0; margin-bottom: 0 } 
+ol	     { margin-top: 0; margin-bottom: 10 }
+dl	     { margin-top: 0; margin-bottom: 10 }
+dt	     { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd	     { margin-top: 0; margin-bottom: 0 }
+strong	     { font-weight: bold}
+em	     { font-style: italic}
+var	     { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin; 
+				   border-left-color: #7B68EE; padding-left:5 }
+th	     { font-weight: bold }
+.hidden {
+	display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel, 
+.notetitle  {
+     color: #000000;
+     font-family: helvetica, arial, sans-serif;
+     font-weight: bold;
+     }
+div.linux  {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/build.properties b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/build.properties
@@ -0,0 +1,19 @@
+###############################################################################
+# Copyright (c) 2017 École Polytechnique de Montréal
+#
+# 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
+###############################################################################
+
+bin.includes = plugin.xml,\
+               META-INF/,\
+               about.html,\
+               plugin.properties,\
+               book.css,\
+               doc/,\
+               index/
+src.includes = about.html
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/build.xml b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/build.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="org.eclipse.tracecompass.analysis.callstack.doc.user" default="build" basedir=".">
+    <description>
+        Generate Eclipse help content for the (new) callstack User Guide
+    </description>
+
+    <property name="document.title" value="Trace Compass (new-) Callstack User Guide" />
+
+    <taskdef resource="org/eclipse/mylyn/wikitext/ant/tasks.properties"/>
+
+    <target name="build" description="Generate Eclipse help content for the Trace Compass (new-) Callstack User Guide">
+        <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+            validate="true"
+            failonvalidationerror="true"
+            overwrite="true"
+            multipleOutputFiles="true"
+            navigationimages="true"
+            title="${document.title}"
+            formatoutput="true"
+            helpPrefix="doc">
+            <fileset dir="doc">
+                <include name="User-Guide.mediawiki" />
+            </fileset>
+            <stylesheet url="book.css" />
+        </wikitext-to-eclipse-help>
+        <antcall target="test" />
+    </target>
+
+    <target name="test" description="Verify that all of the HTML files are well-formed XML">
+        <!--
+        Don't bother with DTD validation: we only care if the files are well-formed.
+        We therefore provide an empty DTD
+        -->
+        <xmlvalidate lenient="true">
+            <fileset dir="doc">
+                <include name="**/*.html" />
+            </fileset>
+            <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location="../.empty.dtd" />
+        </xmlvalidate>
+    </target>
+
+    <target name ="clean" description="Delete all generated files">
+        <delete failonerror="false">
+            <fileset dir="doc" includes="**/*.html" />
+            <fileset dir="doc" includes="**/*.xml" />
+        </delete>
+    </target>
+    <target name="build.index" description="Builds search index for the plug-in" if="eclipse.running">
+        <help.buildHelpIndex manifest="${basedir}/plugin.xml" destination="${basedir}" />
+    </target>
+</project>
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/.gitignore b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.xml
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/User-Guide.mediawiki b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/User-Guide.mediawiki
@@ -0,0 +1,40 @@
+
+= Table of Contents =
+
+__TOC__
+
+= Overview =
+
+The Generic Callstack plugin provides the possibility to describe and analyze call stacks, i.e., the subroutines and function calls a program is in. But it can be generalized to any concept in the application that can be stacked.
+
+For example, if an application uses a thread pool to send jobs that are instrumented, the data can be analyzed in such a way that it is grouped not per thread or process, but by what the ongoing job does.
+
+= Terminology =
+
+Here are the definitions of the terms used in this plugin.
+
+* Callstack: According to [https://en.wikipedia.org/wiki/Call_stack Wikipedia (as of July 2017)], the call stack ''is a stack data structure that stores information about the active subroutines of a computer program. It is also known as an execution stack, program stack, control stack, run-time stack or machine stack.'' In our case, it refers to all the analyses that can be done on a trace that contains call stack data.
+
+* Instrumented callstack: It is a callstack created by instrumenting entry and exits of methods, functions, logical operation, etc. The real time spent in each level of the stack is accurate and with some kernel data, it is possible to know the CPU time as well. Instrumenting a whole application can be costly and have large overhead for the application but one can accurately know the path the code went through and when.
+
+* Sampled callstack: The sampled callstack is obtained by profiling the application. The trace events usually contain an array of frame pointers that were being executed at the moment of the sampling. With this kind of data, only statistical analyses of the callstack can be done, like the number of sampling that were at a given frame, but no information on timing is available.
+
+* Call graph: According to [https://en.wikipedia.org/wiki/Call_graph Wikipedia (as of July 2017)] a call graph ''represents calling relationships between subroutines'', i.e., the relationship between the callers and callees and how often one is called.
+
+* Calling context tree: It is the most precise form of callgraph, that shows the hierarchy of calls from the very first level of the graph, i.e., it keeps the context of the calls when building a callgraph, unlike the less precise callgraphs, where an edge is just added from the caller to the callee, no matter who called the caller (there can be cycles).
+
+* Symbol: A symbol is a way to identify a given call site. In the callstack analysis, it represents either the address of the function or routine in the code. In this case, it usually is gibberish, but it can be resolved as a function name using some symbol providers. In other cases, it may already be a readable string.
+
+* Call site: A call site is a location in the executable, that could eventually be located in some source code. The call site is identified by a symbol.
+
+* Flame chart: The flame chart is a way to organize data in instrumented call stack analysis to show the exact state of the callstack at different moment of the trace.
+
+* Flame graph: The flame graph is an visualization of the calling context tree, which shows the length (with instrumented data) or frequency (with sampling data) of the different code paths.
+
+= Analyses and views =
+
+Depending on whether the callstack is sampled or instrumented, all the analyses may not be available. The views that contain timed data are not available for sampled traces.
+
+= Additional documentation for developers =
+
+Developers wishing to extend this plugin and its analyses can read this section for additional information on the class hierarchy and structures.
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/home.gif b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/home.gif
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/next.gif b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/next.gif
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/prev.gif b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/doc/images/prev.gif
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/plugin.properties b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/plugin.properties
@@ -0,0 +1,13 @@
+###############################################################################
+# Copyright (c) 2017 Ecole Polytechnique de Montreal
+#
+# 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
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass (new-) Callstack User Guide
diff --git a/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/plugin.xml b/doc/org.eclipse.tracecompass.analysis.callstack.doc.user/plugin.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+   <extension point="org.eclipse.help.toc">
+      <toc
+            file="doc/User-Guide-toc.xml"
+            primary="true" />
+      <index
+            path="index/">
+      </index>
+   </extension>
+</plugin>