From c0f11b833d3fc9f9720a9cb5ff92133bba3ea290 Mon Sep 17 00:00:00 2001 From: Alexandre Montplaisir Date: Mon, 9 Feb 2015 16:28:02 -0500 Subject: [PATCH] doc: Updates to the first section of the Dev Guide * Move the Nexus-lite example at the end of the section. Typically you exlain things first, then show an example, not the other way around. * Apparantly the Nexus code itself was never merged in the tree. Remove the references to this code (hopefully the contents of the doc is still useful by itself). * Wrap non-list text to 80 columns. Makes the text files and git diffs easier to read. Change-Id: I790f8087a792ed66fae8f2d9511bf76d448ffbed Signed-off-by: Alexandre Montplaisir Reviewed-on: https://git.eclipse.org/r/41470 Reviewed-by: Hudson CI Reviewed-by: Marc-Andre Laperle Tested-by: Marc-Andre Laperle --- .../doc/Developer-Guide.mediawiki | 196 +++++++++++------- 1 file changed, 121 insertions(+), 75 deletions(-) diff --git a/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki b/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki index 10850ae1c8..7be5d07f2f 100644 --- a/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki +++ b/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki @@ -5,11 +5,20 @@ __TOC__ = Introduction = -The purpose of the '''Tracing Monitoring Framework (TMF)''' is to facilitate the integration of tracing and monitoring tools into Eclipse, to provide out-of-the-box generic functionalities/views and provide extension mechanisms of the base functionalities for application specific purposes. +The purpose of '''Trace Compass''' is to facilitate the integration of tracing +and monitoring tools into Eclipse, to provide out-of-the-box generic +functionalities/views and provide extension mechanisms of the base +functionalities for application specific purposes. + +This guide goes over the internal components of the Trace Compass framework. It +should help developers trying to add new capabilities (support for new trace +type, new analysis or views, etc.) to the framework. End-users, using the RCP +for example, should not have to worry about the concepts explained here. = Implementing a New Trace Type = -The framework can easily be extended to support more trace types. To make a new trace type, one must define the following items: +The framework can easily be extended to support more trace types. To make a new +trace type, one must define the following items: * The event type * The trace reader @@ -18,15 +27,99 @@ The framework can easily be extended to support more trace types. To make a new * The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point * (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point -The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI. +The '''event type''' must implement an ''ITmfEvent'' or extend a class that +implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event +type must contain all the data of an event. + +The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class +will supply many background operations so that the reader only needs to +implement certain functions. + +The '''trace context''' can be seen as the internals of an iterator. It is +required by the trace reader to parse events as it iterates the trace and to +keep track of its rank and location. It can have a timestamp, a rank, a file +position, or any other element, it should be considered to be ephemeral. + +The '''trace location''' is an element that is cloned often to store +checkpoints, it is generally persistent. It is used to rebuild a context, +therefore, it needs to contain enough information to unambiguously point to one +and only one event. Finally the ''tracetype'' plug-in extension associates a +given trace, non-programmatically to a trace type for use in the UI. + +== Optional Trace Type Attributes == + +After defining the trace type as described in the previous chapters it is +possible to define optional attributes for the trace type. + +=== Default Editor === + +The '''defaultEditor''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' +extension point allows for configuring the editor to use for displaying the +events. If omitted, the ''TmfEventsEditor'' is used as default. + +To configure an editor, first add the '''defaultEditor''' attribute to the trace +type in the extension definition. This can be done by selecting the trace type +in the plug-in manifest editor. Then click the right mouse button and select +'''New -> defaultEditor''' in the context sensitive menu. Then select the newly +added attribute. Now you can specify the editor id to use on the right side of +the manifest editor. For example, this attribute could be used to implement an +extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page +could use the ''TmfEventsEditor''' to display the events in a table as usual and +other pages can display other aspects of the trace. + +=== Events Table Type === + +The '''eventsTableType''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' +extension point allows for configuring the events table class to use in the +default events editor. If omitted, the default events table will be used. + +To configure a trace type specific events table, first add the +'''eventsTableType''' attribute to the trace type in the extension definition. +This can be done by selecting the trace type in the plug-in manifest editor. +Then click the right mouse button and select '''New -> eventsTableType''' in the +context sensitive menu. Then select the newly added attribute and click on +''class'' on the right side of the manifest editor. The new class wizard will +open. The ''superclass'' field will be already filled with the class ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable''. + +By using this attribute, a table with different columns than the default columns +can be defined. See the class +''org.eclipse.tracecompass.internal.gdbtrace.ui.views.events.GdbEventsTable'' +for an example implementation. + +== Other Considerations == + +Other views and components may provide additional features that are active only +when the event or trace type class implements certain additional interfaces. + +=== Collapsing of repetitive events === + +By implementing the interface +''org.eclipse.tracecompass.tmf.core.event.collapse.ITmfCollapsibleEvent'' the +event table will allow to collapse repetitive events by selecting the menu item +'''Collapse Events''' after pressing the right mouse button in the table. + +== Best Practices == + +* Do not load the whole trace in RAM, it will limit the size of the trace that can be read. +* Reuse as much code as possible, it makes the trace format much easier to maintain. +* Use Eclipse's editor instead of editing the XML directly. +* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data. +* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix. +** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable. == An Example: Nexus-lite parser == === Description of the file === -This is a very small subset of the nexus trace format, with some changes to make it easier to read. There is one file. This file starts with 64 Strings containing the event names, then an arbitrarily large number of events. The events are each 64 bits long. the first 32 are the timestamp in microseconds, the second 32 are split into 6 bits for the event type, and 26 for the data payload. +This is a very small subset of the nexus trace format, with some changes to make +it easier to read. There is one file. This file starts with 64 Strings +containing the event names, then an arbitrarily large number of events. The +events are each 64 bits long. the first 32 are the timestamp in microseconds, +the second 32 are split into 6 bits for the event type, and 26 for the data +payload. -The trace type will be made of two parts, part 1 is the event description, it is just 64 strings, comma seperated and then a line feed. +The trace type will be made of two parts, part 1 is the event description, it is +just 64 strings, comma separated and then a line feed. 
 Startup,Stop,Load,Add, ... ,reserved\n
@@ -46,11 +139,14 @@ all events will be the same size (64 bits).
 
 === NexusLite Plug-in ===
 
-Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
+Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to
+'''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
 
 Now the structure for the Nexus trace Plug-in is set up.
 
-Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...''' '''org.eclipse.tracecompass.tmf.core''' and '''org.eclipse.tracecompass.tmf.ui'''.
+Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in
+'''META-INF''', selecting the '''Dependencies''' tab and '''Add ...'''
+'''org.eclipse.tracecompass.tmf.core''' and '''org.eclipse.tracecompass.tmf.ui'''.
 
 [[Image:images/NTTAddDepend.png]]

 [[Image:images/NTTSelectProjects.png]]

@@ -95,13 +191,21 @@ confidence. If confidence 0 is returned the auto-detection won't pick this type.
 Here we used a confidence of 20, to leave "room" for more specific trace types
 in the Nexus format that could be defined in TMF.
 
-The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
+The '''initTrace''' function will read the event names, and find where the data
+starts. After this, the number of events is known, and since each event is 8
+bytes long according to the specs, the seek is then trivial.
 
 The '''seek''' here will just reset the reader to the right location.
 
-The '''parseEvent''' method needs to parse and return the current event and store the current location.
+The '''parseEvent''' method needs to parse and return the current event and
+store the current location.
 
-The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
+The '''getNext''' method (in base class) will read the next event and update the
+context. It calls the '''parseEvent''' method to read the event and update the
+location. It does not need to be overridden and in this example it is not. The
+sequence of actions necessary are parse the next event from the trace, create an
+'''ITmfEvent''' with that data, update the current location, call
+'''updateAttributes''', update the context then return the event.
 
 Traces will typically implement an index, to make seeking faster. The index can
 be rebuilt every time the trace is opened. Alternatively, it can be saved to
@@ -114,14 +218,17 @@ The trace context will be a '''TmfContext'''
 
 === Trace Location ===
 
-The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
+The trace location will be a long, representing the rank in the file. The
+'''TmfLongLocation''' will be the used, once again, no code is required.
 
-=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point ===
+=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension points ===
 
 One should use the ''tmf.core.tracetype'' extension point in their own plug-in.
 In this example, the Nexus trace plug-in will be modified.
 
-The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
+The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants
+users to access the given event type. It can be updated in the Eclipse plug-in
+editor.
 
 # In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
 [[Image:images/NTTExtension.png]]

@@ -142,9 +249,7 @@ The '''event type''' is the canonical path refering to the class of the events o
 
 The  '''category''' (optional) is the container in which this trace type will be stored.
 
-# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that,
-'''right click''' on the extension then in the context menu, go to
-'''New >''', '''type'''.
+# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that, '''right click''' on the extension then in the context menu, go to '''New >''', '''type'''.
 
 The '''tracetype''' here is the '''id''' of the
 ''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
@@ -155,65 +260,6 @@ In the end, the extension menu should look like this.
 
 [[Image:images/NTTPluginxmlComplete.png]]

 
-== Other Considerations ==
-The ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable'' provides additional features that are active when the event class (defined in '''event type''') implements certain additional interfaces.
-
-=== Collapsing of repetitive events ===
-By implementing the interface ''org.eclipse.tracecompass.tmf.core.event.collapse.ITmfCollapsibleEvent'' the events table will allow to collapse repetitive events by selecting the menu item '''Collapse Events''' after pressing the right mouse button in the table.
-
-== Best Practices ==
-
-* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
-* Reuse as much code as possible, it makes the trace format much easier to maintain.
-* Use Eclipse's editor instead of editing the XML directly.
-* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
-* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
-** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
-
-== Download the Code ==
-
-The described example is available in the
-org.eclipse.tracecompass.tracing.examples.(tests.)trace.nexus packages with a
-trace generator and a quick test case.
-
-== Optional Trace Type Attributes ==
-
-After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
-
-=== Default Editor ===
-
-The '''defaultEditor''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
-extension point allows for configuring the editor to use for displaying the
-events. If omitted, the ''TmfEventsEditor'' is used as default.
-
-To configure an editor, first add the '''defaultEditor''' attribute to the trace
-type in the extension definition. This can be done by selecting the trace type
-in the plug-in manifest editor. Then click the right mouse button and select
-'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
-added attribute. Now you can specify the editor id to use on the right side of
-the manifest editor. For example, this attribute could be used to implement an
-extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
-could use the ''TmfEventsEditor''' to display the events in a table as usual and
-other pages can display other aspects of the trace.
-
-=== Events Table Type ===
-
-The  '''eventsTableType''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
-extension point allows for configuring the events table class to use in the
-default events editor. If omitted, the default events table will be used.
-
-To configure a trace type specific events table, first add the
-'''eventsTableType''' attribute to the trace type in the extension definition.
-This can be done by selecting the trace type in the plug-in manifest editor.
-Then click the right mouse button and select '''New -> eventsTableType''' in the
-context sensitive menu. Then select the newly added attribute and click on
-''class'' on the right side of the manifest editor. The new class wizard will
-open. The ''superclass'' field will be already filled with the class ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable''.
-
-By using this attribute, a table with different columns than the default columns
-can be defined. See the class org.eclipse.tracecompass.internal.gdbtrace.ui.views.events.GdbEventsTable
-for an example implementation.
-
 = View Tutorial =
 
 This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
-- 
2.34.1