+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 type''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class
+will supply many background operations so that the reader only needs to
+implement certain functions. This includes the ''event aspects'' for events of
+this trace type. See the section below.
+
+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.
+
+== Event Aspects ==
+
+In Trace Compass, an ''event aspect'' represents any type of information that
+can be extracted from a trace event. The simple case is information that is
+present directly in the event. For example, the timestamp of an event, a field
+of an LTTng event, or the "payload" that is on the same line of a text trace
+entry. But it could also be the result of an indirect operation, for example a
+state system query at the timestamp of the given event (see the section
+[[#Generic State System]]).
+
+All aspects should implement the '''ITmfEventAspect''' interface. The important
+method in there is ''resolve(ITmfEvent)'', which tells this aspect what to
+output for a given event. The singleton pattern fits well for pre-defined aspect
+classes, in general.
+
+The aspects defined for a trace type determine the initial columns in the Event
+Table, as well as the elements on which the trace can be filtered, among other
+things.
+
+=== Base and custom aspects ===
+
+Some base aspects are defined in '''TmfTrace#BASE_ASPECTS'''. They use generic
+methods found in '''ITmfEvent''', so they should be applicable for any event
+type defined in the framework. If one does not override
+'''TmfTrace#getEventAspects''', then only the base aspects will be used with
+this trace.
+
+Overriding the method does not append to this list, it replaces it. So if you
+wish to define additional aspects for a new trace type, do not forget to include
+the BASE_ASPECTS you want to use, if any, within the list.
+
+The order of the elements in the returned ''Iterable'' may matter to other
+components. For instance, the initial ordering of the columns in the Events
+Table will match it.
+
+Defining additional aspects allows to expose more data from the trace events
+without having to update all the views using the aspects API.
+
+=== Creating event aspects programmatically ===
+
+Another advantage of event aspects is that they can be created programmatically,
+without having to modify the base trace or event classes. A new analysis
+applying to a pre-existing trace type may wish to define additional aspects to
+make its job easier.
+
+While the notion of event aspects should not be exposed to users directly, it is
+possible to create new aspects based on user input. For example, an "event
+field" dialog could ask the user to enter a field name, which would then create
+an aspect that would look for the value of a field with this name in every
+event. The user could then be able to display or filter on this aspect.
+
+== 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.