update compat

[lttv.git] / tags / lttv-0.11.3-23102008 / doc / developer / developer_guide / docbook / developer_guide.docbook

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                      "/usr/share/sgml/docbook/dtd/4.3/xdocbook.dtd">
<!--<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" >-->

<book>

<bookinfo>
<title>Linux Trace Toolkit Viewer Developer Guide</title>
<authorgroup>
<author>
<firstname>Mathieu</firstname>
<surname>Desnoyers</surname>
</author>
</authorgroup>

<date>01/12/2004</date>
<releaseinfo>1.00.00</releaseinfo>

<abstract>
<para>
This document describes the basic steps necessary to develop within the 
<application>Linux Trace Toolkit Viewer</application> project.

</para>
</abstract>

<keywordset>
<keyword>Linux Trace Toolkit Viewer</keyword>
<keyword>text</keyword>
<keyword>module</keyword>
<keyword>context</keyword>
</keywordset>

</bookinfo>
<chapter>
<title>Linux Trace Toolkit Viewer Text Module Tutorial</title>

<sect1>
<title>Introduction</title>
<para>
This chapter explains all the steps that are necessary to create a text module
in LTTV.
</para>
</sect1>

<sect1>
<title>A typical module</title>
<para>
A typical module must have a init() and destroy() function. Please refer to
lttv/modules/text/textDump.c for the detail of these functions.
</para>
<para>
The init() function is called when the library is loaded and destroy()
inversely. It adds options to the command line by calling "lttv_option_add" from
option.h
</para>
<para>
The module communicates with the main lttv program through the use of global
attributes. Use lttv/attribute.h, lttv/iattribute.h and lttv/lttv.h, and then
LTTV_IATTRIBUTE(lttv_global_attributes()) to get the pointer to these
global attributes.
</para>
<para>
You can then add your hooks (functions that follows the prototype of a hook, as
defined in lttv/hook.h) in the different hook lists defined in lttv/lttv.h. Note
that hooks have an assigned priority. This is necessary to inform the trace
reader that a specific hook needs to be called, for example, before or after the
state update done for an event by the state module. For that specific example, a
hook could use the LTTV_PRIO_STATE-5 to get called before the state update and a
second hook could use the LTTV_PRIO_STATE+5 to get called after the state
update. This is especially important for graphical module, which is the subject
of a the chapter named "Linux Trace Toolkit Viewer Graphical Module Tutorial".
</para>
<para>
You should also take a look at lttv/state.c, where by_id hooks are used. When
you only need some specific events, you should use this interface. It makes the
event filtering sooner in the dispatch chain : you hook doesn't have to be
called for each event, only the ones selected. That improves the performances a
lot!
</para>
<para>
Note that you should use the lttv_trace_find_hook method from
lttv/tracecontext.h to connect the hook to the right facility/event type. See
state.c for an example. A problem that may arise is that the LttvTraceHook
structure must be passed as hook_data when registering the hook. In fact, it is
not necessary for it to be directly passed as the hook_data parameter. As long
as the hook function can access the LttvTraceHook fields necessary to parse the
LttEvent, there is no problem. In a complex viewer where you need a pointer to
your own data structure, just keep a pointer to the LttvTraceHook structure
inside your own data structure, and give to pointer to your data structure in
parameter as the hook_data.
</para>
<para>
Then, you should use the macro LTTV_MODULE, defined in lttv/module.h. It allows
you to specify the module name, a short and a long description, the init and
destroy functions and the module dependencies. That permits to the module
backend to load the right dependencies when needed.
</para>
<para>
A typical text module will depend on batchAnalysis for the batch computation of a
trace, and simply register before and after trace hooks, as weel as the most
important one : a event hook.
</para>
</sect1>

<sect1>
<title>The hooks</title>
<para>
The before and after trace hooks only exists to be able to generate a report at
the end of a trace computation. The effective computation is done by the event
hooks.
</para>
<para>
These hooks does particular computation on data arriving as argument, a
call_data. The type of the call_data, when a hook is called during the trace
read, is a traceset context. It contains all the necessary information about the
read in progress. This is the base class from which inherits trace set
state, and trace set/trace/tracefile state is the base classe of trace
set/trace/tracefile statistics. All these types can be casted to another without
problem (a TracesetState, for example, can be casted to a TracesetContext, but
it's not true for the casting between a TraceContext and a TracesetContext, see
the chapter "How to use the trace reading context" for details). They offer the
input data and they give a container (the attributes of the trace set/trace/tracefile
statistics) to write the output of this hook.
</para>
<para>
The idea behind writing in the attributes container is to provide an extensible
way of storing any type of information. For example, a specific module that adds
statistics to a trace can store them there, and the statistic printout will
automatically include the results produced by the specific module.
</para>
<para>
Output data does not necessarily need to be stored in such a global container
though. If we think of data of which we need to keed track during the execution,
an event counter for example, we should create our own data structure that
contains this counter, and pass the address of the allocated structure as the
hook_data parameter of the hook list creation function. That way, the hook will
be called with its hook_data as first parameter, which it can read and write. We
can think of this structure as the data related to the function that persists
between each call to the hook. You must make sure that you cast the hook_data to
the type of the structure before you use it in the hook function.
</para>
<para>
The detail about how to access the different fields of the reading context (the
hook's call_data) will be discussed in the chapter  "How to use the trace
reading context".
</para>
</sect1>


</chapter>


<chapter>
<title>How to use the Linux Trace Toolkit Viewer's Reading Context</title>

<sect1>
<title>Introduction</title>
<para>
This chapter describes how to use the Linux Trace Toolkit reading context, a
data structure that is given as call data parameter of the modules'callbacks.
</para>
<para>
Linux Trace Toolkit Viewer provides a backend that reads the traces. In combines
them in tracesets. A trace is an abstaction over many tracefiles, one per CPU.
LTTV reads the whole trace together, providing the events to modules by calling
their pre-registered hook lists in a chronological order.
</para>
</sect1>

<sect1>
<title>Why an event driven trace reader ?</title>
<para>
The complexity of synchronizing the tracesets is then hidden to the viewer. Some
future plans involve to be able to put many traces together in a trace set.
Before this becomes possible, the time of each trace must be synchronized in
some way. Some work is actually done to create a module that uses the network
traffic shared by different computers to synchronize the time of different
traces.
</para>
<para>
In order to make each module integrate well with each other, we made the trace
reader a simple hook caller. For each event it reads, it just calls the hook
lists for this event. For each event, it calls the by_id specific hooks
registered for this event and also the "main" hooks, registered for all events.
Note that the two hook lists are merged when called so the priority of the
hooks of each list is respected. For example, a hook of higher priority (20) in
the main list will be called before a hook of lower priority (40) from the
by_id specific list.
</para>
</sect1>

<sect1>
<title>Using the reading context</title>
<para>
If you have read the tutorials about writing a text and a graphic module, you
should be fairly ready to use the information provided to your hook by the
reading API.
</para>
<para>
The data structures of the reading context are based on the gobject, a
object-oriented library from the glib. Some evolved types that are found in the
context also comes from the "glib" (GArray, GHashTable and so on). For detailed
information about "gobjects" and the "glib", see the <ulink
url="http://www.gtk.org">www.gtk.org</ulink> website. They provide a complete
API reference about the data types they provide.
</para>
<para>
The reading context is object oriented. It is described by the lttv/tracecontext.h
header. Is can be illustrated with this UML class diagram :
</para>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-context.png"
format="PNG" align="center"/>
</imageobject>
<imageobject>
<imagedata srccredit="Mathieu Desnoyers, 2004"
fileref="lttv-context.eps"
format="EPS" align="center"/>
</imageobject>
<!--<imagedata srccredit="Mathieu Desnoyers, 2004" fileref="lttv-numbered-6.svg"
format="SVG" align="center" scalefit="1"/>
</imageobject>-->
<caption><para>Linux Trace Toolkit Viewer Reading Context Class Diagram</para></caption>
</mediaobject>
</screenshot>
</para>
<para>
Though, for performance's sake, navigating through it is not as encapsulated as
it could. Consider the class attributes to be all public (no get/set functions).
Sometimes, iteration upon a specific element can be uneasy. For example, you may
have to get the number of tracefiles in a trace from the "vt" field of the trace
context to be able to iterate over all the tracefiles contained by the trace.
</para>
<para>
To facilitate the common operations on the reading context, LTTV now provides a
header that consists of simple macros : lttv/contextmacros.h. It gives an object
look-and-feel to the context classes. Simple "GET" macros can be used to easily
access the different fields are iterate over the elements (and get the total
number of elements too).
</para>
</sect1>
</chapter>

<chapter>
<title>Linux Trace Toolkit Viewer Graphical Module Tutorial</title>
<sect1>
<title>Introduction</title>
<para>
As a matter of fact, most of the things said for the text modules still hold for
the graphical modules. However, the fact that every module must instanciate
objects (called viewers) more than once changes a little bit the scenario. It is
then impossible to use static structures : everything must be instanciated at
run-time, except the structures related to the module itself.
</para>
</sect1>
<sect1>
<title>The static part of a module</title>
<para>
A module must have a static part to be able to get loaded just like a text
module. Now, let's see the differences. The graphical module depends on the
"lttvwindow" module. See module.c from the control flow viewer for an example.
</para>
<para>
The init() and destroy() functions must register functions that can be called by
user interaction to instanciate the viewers. That's the goal of
lttvwindow_register_constructor() and lttvwindow_unregister_constructor() :
they register a function with a menu entry and an icon. The main window will
shown them in its interface and call the function when the button or menu item
is selected. This hook function must receive a pointer to a "Tab" object in
parameter.
</para>
<para>
Also note the presence of the destroy_walk() method. It is called when the
module is unloaded : it must destroy all the instances of the viewers from the
module.
</para>
</sect1>
<sect1>
<title>The dynamic part of a module : the viewer</title>
<para>
The dynamic part starts with the constructor of the viewer. It is called by the
main window when the corresponding button or menu item is selected. See
h_guicontrolflow() from control flow viewer eventhooks.c for an example. It does
basic connexion to the tab's events available : time window change notification,
current time notification, redraw notification, continue notification. All these
function should be implemented in your viewer if you want the data you shown to
be synchronised with the main window and the other viewers. It also calls the
background computation, which will be discussed in the next section.
</para>
<para>
This is also at this point that the viewer does create it's own memory footprint
: its inner structure. This structure will have to be passed as hook_data to
each function registered by the viewer : this is what makes the functions
"belong" to this instance of the viewer.
</para>
</sect1>
<sect1>
<title>How to request background computation</title>
<para>
You will also notice the presence of a request_background_data() called in the
constructor. This function, in eventhooks.c, does verify for the presence of the
state information that could be precomputed by the main window background
computation. If it has not been precomputed, we ask for a computation and show
partial data. We also register a hook that will be called (notified) by the main
window when the requested data will become ready, so the viewer can update
itself with the new data. If no partial information would have made sense in a
particular viewer, one could choose to shown a "waiting for computation" message
while waiting for the notification. See lttvwindow/lttvwindowtraces.h for the API
of the background requests.
</para>
</sect1>

<sect1>
<title>How to handle events and use the graphical trace reading service</title>
<para>
The events that are delivered by the main window are defined in
lttvwindow/lttvwindow.h. Let's describe them and their use in details. Remember
that you can refer to the control flow viewer module as an example.
</para>

<sect2>
<title>Module Related API</title>
<para>
A viewer plugin is, before anything, a plugin. As a dynamically loadable
module, it thus has an init and a destroy function called whenever it is
loaded/initialized and unloaded/destroyed. A graphical module depends on
lttvwindow for construction of its viewer instances. In order to achieve
this, it must register its constructor function to the main window along
with button description or text menu entry description. A module keeps
a list of every viewer that currently sits in memory so it can destroy
them before the module gets unloaded/destroyed.
</para>
<para>
The contructor registration to the main windows adds button and menu
entry to each main window, thus allowing instanciation of viewers.
</para>
</sect2>
<sect2>
<title>Main Window</title>
<para>
The main window is a container that offers menus, buttons and a
notebook. Some of those menus and buttons are part of the core of the
main window, others are dynamically added and removed when modules are
loaded/unloaded.
</para>
<para>
The notebook contains as much tabs as wanted. Each tab is linked with
a set of traces (traceset). Each trace contains many tracefiles (one
per cpu).  A trace corresponds to a kernel being traced. A traceset
corresponds to many traces read together. The time span of a traceset
goes from the earliest start of all the traces to the latest end of all
the traces.
</para>
<para>
Inside each tab are added the viewers. When they interact with the main
window through the lttvwindow API, they affect the other viewers located
in the same tab as they are.
</para>
<para>
The insertion of many viewers in a tab permits a quick look at all the
information wanted in a glance. The main window does merge the read
requests from all the viewers in the same tab in a way that every viewer
will get exactly the events it asked for, while the event reading loop
and state update are shared. It improves performance of events delivery
to the viewers.
</para>
</sect2>

<sect2>
<title>Viewer Instance Related API</title>
<para>
The lifetime of a viewer is as follows. The viewer constructor function
is called each time an instance view is created (one subwindow of this
viewer type is created by the user either by clicking on the menu item
or the button corresponding to the viewer). Thereafter, the viewer gets
hooks called for different purposes by the window containing it. These
hooks are detailed below. It also has to deal with GTK Events. Finally,
it can be destructed by having its top level widget unreferenced by the
main window or by any GTK Event causing a "destroy-event" signal on the
its top widget. Another possible way for it do be destroyed is if the
module gets unloaded. The module unload function will have to emit a
"destroy" signal on each top level widget of all instances of its viewers.
</para>
</sect2>
<sect2>
<title>Notices from Main Window</title>
<variablelist>
<varlistentry>
<term>time_window</term>
<listitem>
<simpara>This is the time interval visible on the viewer's tab. Every
              viewer that cares about being synchronised by respect to the
              time with other viewers should register to this notification.
              They should redraw all or part of their display when this
              occurs.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>traceset</term>
<listitem>
<simpara>This notification is called whenever a trace is added/removed
              from the traceset. As it affects all the data displayed by the
              viewer, it sould redraw itself totally.</simpara>
</listitem>
</varlistentry>

<varlistentry>
<term>filter</term>
<listitem>
<simpara>This feature has not been implemented yet.</simpara>
</listitem>
</varlistentry>

<varlistentry>
<term>current_time</term>
<listitem>
<simpara>Being able to zoom nearer a specific time or highlight a specific
              time on every viewer in synchronicity implies that the viewer
              has to shown a visual sign over the drawing or select an event
              when it receives this notice. It should also inform the main
              window with the appropriate report API function when a user
              selects a specific time as being the current time.</simpara>
</listitem>
</varlistentry>

<varlistentry>
<term>dividor</term>
<listitem>
<simpara>This notice links the positions of the horizontal dividors
              between the graphic display zone of every viewer and their Y axis,
              typically showing processes, cpus, ...</simpara>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Reporting Changes to the Main Window</title>
<para>
In most cases, the enclosing window knows about updates such as described
in the Notification section higher. There are a few cases, however, where
updates are caused by actions known by a view instance. For example,
clicking in a view may update the current time; all viewers within
the same window must be told about the new current time to change the
currently highlighted time point. A viewer reports such events by calling
lttvwindow_report_current_time on its lttvwindow.  The lttvwindow will
consequently call current_time_notify for each of its contained viewers.
</para>
<para>
Available report methods are :
<itemizedlist>
<listitem>
<simpara>
lttvwindow_report_time_window : reports the new time window.
</simpara>
</listitem>
<listitem>
<simpara>
lttvwindow_report_current_time : reports the new current time.
</simpara>
</listitem>
<listitem>
<simpara>
lttvwindow_report_dividor : reports the new horizontal dividor's position.
</simpara>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title>Requesting Events to Main Window</title>
<para>
Events can be requested by passing a EventsRequest structure to the main
window.  They will be delivered later when the next g_idle functions
will be called.  Event delivery is done by calling the event hook for
this event ID, or the main event hooks. A pointer to the EventsRequest
structure is passed as hook_data to the event hooks of the viewers.
</para>
<para>
EventsRequest consists in 
<itemizedlist>
<listitem>
<simpara>
a pointer to the viewer specific data structure
</simpara>
</listitem>
<listitem>
<simpara>
a start timestamp or position
</simpara>
</listitem>
<listitem>
<simpara>
a stop_flag, ending the read process when set to TRUE
</simpara>
</listitem>
<listitem>
<simpara>
a end timestamp and/or position and/or number of events to read
</simpara>
</listitem>
<listitem>
<simpara>
hook lists to call for traceset/trace/tracefile begin and end, and for each
  event (event hooks and event_by_id hooks).
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
The main window will deliver events for every EventRequests it has
pending through an algorithm that guarantee that all events requested,
and only them, will be delivered to the viewer between the call of the
tracefile_begin hooks and the call of the tracefile_end hooks.
</para>
<para>
If a viewer wants to stop the event request at a certain point inside the
event hooks, it has to set the stop_flag to TRUE and return TRUE from the
hook function. Then return value will stop the process traceset. Then,
the main window will look for the stop_flag and remove the EventRequests
from its lists, calling the process_traceset_end for this request (it
removes hooks from the context and calls the after hooks).
</para>
<para>
It no stop_flag is risen, the end timestamp, end position or number
of events to read has to be reached to determine the end of the
request. Otherwise, the end of traceset does determine it.
</para>
</sect2>
<sect2>
<title>GTK Events</title>
<sect3>
<title>Events and Signals</title>
<para>
GTK is quite different from the other graphical toolkits around
there. The main difference resides in that there are many X Windows
inside one GtkWindow, instead of just one. That means that X events are
delivered by the glib main loop directly to the widget corresponding to
the GdkWindow affected by the X event.
</para>
<para>
Event delivery to a widget emits a signal on that widget. Then, if a
handler is connected to this widget's signal, it will be executed. There
are default handlers for signals, connected at class instantiation
time. There is also the possibility to connect other handlers to these
signals, which is what should be done in most cases when a viewer needs
to interact with X in any way.
</para>

<para>
Signal emission and propagation is described there : 

<itemizedlist>
<listitem>
<simpara>
http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
</simpara>
</listitem>
</itemizedlist>
</para>

<para>
For further information on the GTK main loop (now a wrapper over glib main loop)
see :

<itemizedlist>
<listitem>
<simpara>
http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
</simpara>
</listitem>
<listitem>
<simpara>
http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
</simpara>
</listitem>
</itemizedlist>
</para>


<para>
For documentation on event handling in GTK/GDK, see :

<itemizedlist>
<listitem>
<simpara>
http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
</simpara>
</listitem>
<listitem>
<simpara>
http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
</simpara>
</listitem>
</itemizedlist>
</para>


<para>
Signals can be connected to handlers, emitted, propagated, blocked, 
stopped. See :

<itemizedlist>
<listitem>
<simpara>
http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
</simpara>
</listitem>
</itemizedlist>
</para>

</sect3>


<sect3>
<title>The "expose_event"</title>
<para>
Provides the exposed region in the GdkEventExpose structure. 
</para>
<para>
There are two ways of dealing with exposures. The first one is to directly
draw on the screen and the second one is to draw in a pixmap buffer,
and then to update the screen when necessary.
</para>
<para>
In the first case, the expose event will be responsible for registering
hooks to process_traceset and require time intervals to the main
window. So, in this scenario, if a part of the screen is damaged, the
trace has to be read to redraw the screen.
</para>
<para>
In the second case, with a pixmap buffer, the expose handler is only
responsible of showing the pixmap buffer on the screen. If the pixmap
buffer has never been filled with a drawing, the expose handler may ask
for it to be filled.
</para>
<para>
The interest of using events request to the main window instead of reading
the events directly from the trace comes from the fact that the main
window does merge requests from the different viewers in the same tab so
that the read loop and the state update is shared. As viewers will, in
the common scenario, request the same events, only one pass through the
trace that will call the right hooks for the right intervals will be done.
</para>
<para>
When the traceset read is over for a events request, the traceset_end
hook is called. It has the responsibility of finishing the drawing if
some parts still need to be drawn and to show it on the screen (if the
viewer uses a pixmap buffer).
</para>
<para>
It can add dotted lines and such visual effects to enhance the user's
experience.
</para>
</sect3>
</sect2>
</sect1>

</chapter>



</book>