1 /* This file is part of the Linux Trace Toolkit Graphic User Interface
2 * Copyright (C) 2003-2004 Xiangxiu Yang, Mathieu Desnoyers
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License Version 2 as
6 * published by the Free Software Foundation;
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
20 This file is what every viewer plugin writer should refer to.
25 A viewer plugin is, before anything, a plugin. As a dynamically loadable
26 module, it thus has an init and a destroy function called whenever it is
27 loaded/initialized and unloaded/destroyed. A graphical module depends on
28 lttvwindow for construction of its viewer instances. In order to achieve this,
29 it must register its constructor function to the main window along with
30 button description or text menu entry description. A module keeps a list of
31 every viewer that currently sits in memory so it can destroy them before the
32 module gets unloaded/destroyed.
34 The contructor registration to the main window adds button and menu entry
35 to each main window, thus allowing instanciation of viewers.
40 The main window is a container that offers menus, buttons and a notebook. Some
41 of those menus and buttons are part of the core of the main window, others
42 are dynamically added and removed when modules are loaded/unloaded.
44 The notebook contains as much tabs as wanted. Each tab is linked with a
45 set of traces (traceset). Each trace contains many tracefiles (one per cpu).
46 A trace corresponds to a kernel being traced. A traceset corresponds to
47 many traces read together. The time span of a traceset goes from the
48 earliest start of all the traces to the latest end of all the traces.
50 Inside each tab are added the viewers. When they interact with the main
51 window through the lttvwindow API, they affect the other viewers located
52 in the same tab as they are.
54 The insertion of many viewers in a tab permits a quick look at all the
55 information wanted in a glance. The main window does merge the read requests
56 from all the viewers in the same tab in a way that every viewer will get exactly
57 the events it asked for, while the event reading loop and state update are
58 shared. It improves performance of events delivery to the viewers.
62 Viewer Instance Related API
64 The lifetime of a viewer is as follows. The viewer constructor function is
65 called each time an instance view is created (one subwindow of this viewer
66 type is created by the user either by clicking on the menu item or the button
67 corresponding to the viewer). Thereafter, the viewer gets hooks called for
68 different purposes by the window containing it. These hooks are detailed
69 below. It also has to deal with GTK Events. Finally, it can be destructed by
70 having its top level widget unreferenced by the main window or by any
71 GTK Event causing a "destroy-event" signal on the its top widget. Another
72 possible way for it do be destroyed is if the module gets unloaded. The module
73 unload function will have to emit a "destroy" signal on each top level widget
74 of all instances of its viewers.
77 Notices from Main Window
79 time_window : This is the time interval visible on the viewer's tab. Every
80 viewer that cares about being synchronised by respect to the
81 time with other viewers should register to this notification.
82 They should redraw all or part of their display when this occurs.
84 traceset : This notification is called whenever a trace is added/removed
85 from the traceset. As it affects all the data displayed by the
86 viewer, it sould redraw itself totally.
88 filter : FIXME : describe..
90 current_time: Being able to zoom nearer a specific time or highlight a specific
91 time on every viewer in synchronicity implies that the viewer
92 has to shown a visual sign over the drawing or select an event
93 when it receives this notice. It should also inform the main
94 window with the appropriate report API function when a user
95 selects a specific time as being the current time.
97 dividor : This notice links the positions of the horizontal dividors
98 between the graphic display zone of every viewer and their Y axis,
99 typically showing processes, cpus, ...
102 FIXME : Add background computation explanation here
103 background_init: prepare for background computation (comes after show_end).
104 process_trace for background: done in small chunks in gtk_idle, hooks called.
105 background_end: remove the hooks and perhaps update the window.
108 Reporting Changes to the Main Window
110 In most cases, the enclosing window knows about updates such as described in the
111 Notification section higher. There are a few cases, however, where updates are
112 caused by actions known by a view instance. For example, clicking in a view may
113 update the current time; all viewers within the same window must be told about
114 the new current time to change the currently highlighted time point. A viewer
115 reports such events by calling lttvwindow_report_current_time on its lttvwindow.
116 The lttvwindow will consequently call current_time_notify for each of its
120 Available report methods are :
122 lttvwindow_report_status : reports the text of the status bar.
123 lttvwindow_report_time_window : reports the new time window.
124 lttvwindow_report_current_time : reports the new current time.
125 lttvwindow_report_dividor : reports the new horizontal dividor's position.
126 lttvwindow_report_focus : One on the widgets in the viewer has the keyboard's
131 Requesting Events to Main Window
133 Events can be requested by passing a EventsRequest structure to the main window.
134 They will be delivered later when the next g_idle functions will be called.
135 Event delivery is done by calling the event hook for this event ID, or the
136 main event hooks. A pointer to the EventsRequest structure is passed as
137 hook_data to the event hooks of the viewers.
139 EventsRequest consists in
140 - a pointer to the viewer specific data structure
141 - a start timestamp or position
142 - a stop_flag, ending the read process when set to TRUE
143 - a end timestamp and/or position and/or number of events to read
144 - hook lists to call for traceset/trace/tracefile begin and end, and for each
145 event (event hooks and event_by_id hooks).
147 The main window will deliver events for every EventRequests it has pending
148 through an algorithm that guarantee that all events requested, and only them,
149 will be delivered to the viewer between the call of the tracefile_begin hooks
150 and the call of the tracefile_end hooks.
152 If a viewer wants to stop the event request at a certain point inside the event
153 hooks, it has to set the stop_flag to TRUE and return TRUE from the hook
154 function. Then return value will stop the process traceset. Then, the main
155 window will look for the stop_flag and remove the EventRequests from its lists,
156 calling the process_traceset_end for this request (it removes hooks from the
157 context and calls the after hooks).
159 It no stop_flag is rose, the end timestamp, end position or number of events to
160 read has to be reached to determine the end of the request. Otherwise,
161 the end of traceset does determine it.
168 GTK is quite different from the other graphical toolkits around there. The main
169 difference resides in that there are many X Windows inside one GtkWindow,
170 instead of just one. That means that X events are delivered by the glib main
171 loop directly to the widget corresponding to the GdkWindow affected by the X
174 Event delivery to a widget emits a signal on that widget. Then, if a handler
175 is connected to this widget's signal, it will be executed. There are default
176 handlers for signals, connected at class instantiation time. There is also
177 the possibility to connect other handlers to these signals, which is what
178 should be done in most cases when a viewer needs to interact with X in any
183 Signal emission and propagation is described there :
185 http://www.gtk.org/tutorial/sec-signalemissionandpropagation.html
187 For further information on the GTK main loop (now a wrapper over glib main loop)
190 http://developer.gnome.org/doc/API/2.0/gtk/gtk-General.html
191 http://developer.gnome.org/doc/API/2.0/glib/glib-The-Main-Event-Loop.html
194 For documentation on event handling in GTK/GDK, see :
196 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Events.html
197 http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html
200 Signals can be connected to handlers, emitted, propagated, blocked,
203 http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html
210 Provides the exposed region in the GdkEventExpose structure.
212 There are two ways of dealing with exposures. The first one is to directly draw
213 on the screen and the second one is to draw in a pixmap buffer, and then to
214 update the screen when necessary.
216 In the first case, the expose event will be responsible for registering hooks to
217 process_traceset and require time intervals to the main window. So, in this
218 scenario, if a part of the screen is damaged, the trace has to be read to
221 In the second case, with a pixmap buffer, the expose handler is only responsible
222 of showing the pixmap buffer on the screen. If the pixmap buffer has never
223 been filled with a drawing, the expose handler may ask for it to be filled.
225 The interest of using events request to the main window instead of reading the
226 events directly from the trace comes from the fact that the main window
227 does merge requests from the different viewers in the same tab so that the
228 read loop and the state update is shared. As viewers will, in the common
229 scenario, request the same events, only one pass through the trace that will
230 call the right hooks for the right intervals will be done.
232 When the traceset read is over for a events request, the traceset_end hook is
233 called. It has the responsibility of finishing the drawing if some parts
234 still need to be drawn and to show it on the screen (if the viewer uses a pixmap
237 It can add dotted lines and such visual effects to enhance the user's
241 FIXME : explain other important events
249 * \brief API used by the graphical viewers to interact with their top window.
251 * Main window (lttvwindow module) is the place to contain and display viewers.
252 * Viewers (lttv plugins) interact with main window through this API.
253 * This header file should be included in each graphic module.
259 #include <ltt/time.h>
260 #include <lttv/hook.h>
261 #include <lttv/tracecontext.h>
262 #include <lttv/stats.h>
263 #include <lttvwindow/common.h>
264 //FIXME (not ready yet) #include <lttv/filter.h>
267 /* Module Related API */
270 /* constructor a the viewer */
271 //FIXME explain LttvTracesetSelector and key
272 typedef GtkWidget
* (*lttvwindow_viewer_constructor
)
273 (MainWindow
* main_window
, LttvTracesetSelector
* s
, char *key
);
277 * Function to register a view constructor so that main window can generate
278 * a menu item and a toolbar item for the viewer in order to generate a new
279 * instance easily. A menu entry and toolbar item will be added to each main
282 * It should be called by init function of the module.
284 * @param menu_path path of the menu item. NULL : no menu entry.
285 * @param menu_text text of the menu item.
286 * @param pixmap Image shown on the toolbar item. NULL : no button.
287 * @param tooltip tooltip of the toolbar item.
288 * @param view_constructor constructor of the viewer.
291 void lttvwindow_register_constructor
296 lttvwindow_viewer_constructor view_constructor
);
300 * Function to unregister the viewer's constructor, release the space
301 * occupied by menu_path, menu_text, pixmap, tooltip and constructor of the
304 * It will be called when a module is unloaded.
306 * @param view_constructor constructor of the viewer.
309 void lttvwindow_unregister_constructor
310 (lttvwindow_viewer_constructor view_constructor
);
315 /* Viewer Instance Related API */
318 * Structure used as hook_data for the time_window_notify hook.
320 typedef struct _TimeWindowNotifyData
{
321 TimeWindow
*new_time_window
;
322 TimeWindow
*old_time_window
;
323 } TimeWindowNotifyData
;
327 * Function to register a hook function that will be called by the main window
328 * when the time interval needs to be updated.
330 * This register function is typically called by the constructor of the viewer.
332 * @param main_win the main window the viewer belongs to.
333 * @param hook hook that sould be called by the main window when the time
334 * interval changes. This hook function takes a
335 * TimeWindowNotifyData* as call_data.
336 * @param hook_data hook data associated with the hook function. It will
337 * be typically a pointer to the viewer's data structure.
340 void lttvwindow_register_time_window_notify(MainWindow
*main_win
,
346 * Function to unregister the time_window notification hook.
348 * This unregister function is typically called by the destructor of the viewer.
350 * @param main_win the main window the viewer belongs to.
351 * @param hook hook that sould be called by the main window when the time
352 * interval changes. This hook function takes a
353 * TimeWindowNotifyData* as call_data.
354 * @param hook_data hook data associated with the hook function. It will
355 * be typically a pointer to the viewer's data structure.
358 void lttvwindow_unregister_time_window_notify(MainWindow
*main_win
,
364 * Function to register a hook function that will be called by the main window
365 * when the traceset is changed. That means that the viewer must redraw
366 * itself completely or check if it's affected by the particular change to the
369 * This register function is typically called by the constructor of the viewer.
371 * @param main_win the main window the viewer belongs to.
372 * @param hook hook that should be called whenever a change to the traceset
373 * occurs. The call_data of this hook is a NULL pointer.
374 * @param hook_data hook data associated with the hook function. It will
375 * be typically a pointer to the viewer's data structure.
378 void lttvwindow_register_traceset_notify(MainWindow
*main_win
,
384 * Function to unregister the traceset_notify hook.
386 * @param main_win the main window the viewer belongs to.
387 * @param hook hook that should be called whenever a change to the traceset
388 * occurs. The call_data of this hook is a NULL pointer.
389 * @param hook_data hook data associated with the hook function. It will
390 * be typically a pointer to the viewer's data structure.
393 void lttvwindow_unregister_traceset_notify(MainWindow
*main_win
,
399 * Function to register a hook function for a viewer to set/update its
402 * FIXME : Add information about what a filter is as seen from a viewer and how
405 * This register function is typically called by the constructor of the viewer.
407 * @param main_win the main window the viewer belongs to.
408 * @param hook hook function called by the main window when a filter change
410 * @param hook_data hook data associated with the hook function. It will
411 * be typically a pointer to the viewer's data structure.
414 void lttvwindow_register_filter_notify(MainWindow
*main_win
,
420 * Function to unregister a viewer's hook function which is used to
421 * set/update the filter of the viewer.
423 * This unregistration is called by the destructor of the viewer.
425 * @param main_win the main window the viewer belongs to.
426 * @param hook hook function called by the main window when a filter change
428 * @param hook_data hook data associated with the hook function. It will
429 * be typically a pointer to the viewer's data structure.
432 void lttvwindow_unregister_filter_notify(MainWindow
* main_win
,
438 * Function to register a hook function for a viewer to set/update its
441 * @param main_win the main window the viewer belongs to.
442 * @param hook hook function of the viewer that updates the current time. The
443 * call_data is a LttTime* representing the new current time.
444 * @param hook_data hook data associated with the hook function. It will
445 * be typically a pointer to the viewer's data structure.
448 void lttvwindow_register_current_time_notify(MainWindow
*main_win
,
454 * Function to unregister a viewer's hook function which is used to
455 * set/update the current time of the viewer.
456 * @param main_win the main window the viewer belongs to.
457 * @param hook hook function of the viewer that updates the current time. The
458 * call_data is a LttTime* representing the new current time.
459 * @param hook_data hook data associated with the hook function. It will
460 * be typically a pointer to the viewer's data structure.
463 void lttvwindow_unregister_current_time_notify(MainWindow
*main_win
,
469 * Function to register a hook function for a viewer to set/update the
470 * dividor of the hpane. It provides a way to make the horizontal
471 * dividors of all the viewers linked together.
473 * @param main_win the main window the viewer belongs to.
474 * @param hook hook function of the viewer that will be called whenever a
475 * dividor changes in another viewer. The call_data of this hook
476 * is a gint*. The value of the integer is the new position of the
478 * @param hook_data hook data associated with the hook function. It will
479 * be typically a pointer to the viewer's data structure.
482 void lttvwindow_register_dividor(MainWindow
*main_win
,
488 * Function to unregister a viewer's hook function which is used to
489 * set/update hpane's dividor of the viewer.
491 * @param main_win the main window the viewer belongs to.
492 * @param hook hook function of the viewer that will be called whenever a
493 * dividor changes in another viewer. The call_data of this hook
494 * is a gint*. The value of the integer is the new position of the
496 * @param hook_data hook data associated with the hook function. It will
497 * be typically a pointer to the viewer's data structure.
500 void lttvwindow_unregister_dividor(MainWindow
*main_win
,
507 * This method reports the information to show on the status bar in the
510 * @param main_win the main window the viewer belongs to.
511 * @param info the message which will be shown in the status bar.
514 void lttvwindow_report_status(MainWindow
*main_win
, const char *info
);
518 * Function to set the time interval of the current tab.a
520 * @param main_win the main window the viewer belongs to.
521 * @param time_interval pointer to the time interval value.
524 void lttvwindow_report_time_window(MainWindow
*main_win
,
525 const TimeWindow
*time_window
);
528 * Function to set the current time/event of the current tab.
529 * It will be called by a viewer's signal handle associated with
530 * the button-release-event signal
531 * @param main_win the main window the viewer belongs to.
532 * @param time a pointer where time is stored.
535 void lttvwindow_report_current_time(MainWindow
*main_win
,
536 const LttTime
*time
);
540 * Function to set the position of the hpane's dividor (viewer).
541 * It will typically be called by a viewer's signal handle associated
542 * with the motion_notify_event event/signal.
544 * @param main_win the main window the viewer belongs to.
545 * @param position position of the hpane's dividor.
548 void lttvwindow_report_dividor(MainWindow
*main_win
, gint position
);
551 * Function to set the focused viewer of the tab.
552 * It will be called by a viewer's signal handle associated with
553 * the grab_focus signal of all widgets in the viewer.
555 * @param main_win the main window the viewer belongs to.
556 * @param top_widget the top widget containing all the other widgets of the
559 void lttvwindow_report_focus(MainWindow
*main_win
,
560 GtkWidget
*top_widget
);
562 /* Structure sent to the time request hook */
563 /* Value considered as empty */
564 typedef struct _EventsRequest
{
565 LttTime start_time
; /* Unset : { 0, 0 } */
566 LttvTracesetContextPosition
*start_position
; /* Unset : num_traces = 0 */
567 gboolean stop_flag
; /* Continue:TRUE Stop:FALSE */
568 LttTime end_time
; /* Unset : { 0, 0 } */
569 guint num_events
; /* Unset : G_MAXUINT */
570 LttvTracesetContextPosition
*end_position
; /* Unset : num_traces = 0 */
571 LttvHooks
*before_traceset
; /* Unset : NULL */
572 LttvHooks
*before_trace
; /* Unset : NULL */
573 LttvHooks
*before_tracefile
; /* Unset : NULL */
574 LttvHooks
*event
; /* Unset : NULL */
575 LttvHooksById
*event_by_id
; /* Unset : NULL */
576 LttvHooks
*after_tracefile
; /* Unset : NULL */
577 LttvHooks
*after_trace
; /* Unset : NULL */
578 LttvHooks
*after_traceset
; /* Unset : NULL */
583 * Function to request data in a specific time interval to the main window. The
584 * time request servicing is differed until the glib idle functions are
587 * The viewer has to provide hooks that should be associated with the event
590 * Either start time or start position must be defined in a EventRequest
591 * structure for it to be valid.
593 * end_time, end_position and num_events can all be defined. The first one
594 * to occur will be used as end criterion.
596 * @param main_win the main window the viewer belongs to.
597 * @param events_requested the structure of request from.
600 void lttvwindow_events_request(MainWindow
*main_win
,
601 EventsRequest events_request
);
604 * Function to get the current time window of the current tab.
606 * @param main_win the main window the viewer belongs to.
607 * @return a pointer to the current tab's time interval.
610 const TimeWindow
*lttvwindow_get_time_window(MainWindow
*main_win
);
614 * Function to get the current time of the current tab.
616 * @param main_win the main window the viewer belongs to.
617 * @return a pointer to the current tab's current time.
620 const LttTime
*lttvwindow_get_current_time(MainWindow
*main_win
);
624 * Function to get the filter of the current tab.
625 * @param main_win, the main window the viewer belongs to.
626 * @param filter, a pointer to a filter.
630 typedef void lttv_filter
;
632 const lttv_filter
*lttvwindow_get_filter(MainWindow
*main_win
);
636 * Function to get the stats of the traceset
637 * It must be non const so the viewer can modify it.
638 * FIXME : a set/get pair of functions would be more appropriate here.
639 * @param main_win the main window the viewer belongs to.
640 * @return A pointer to Traceset statistics.
643 LttvTracesetStats
* lttvwindow_get_traceset_stats(MainWindow
*main_win
);
646 * Function to get the context of the traceset
647 * It must be non const so the viewer can add and remove hooks from it.
648 * @param main_win the main window the viewer belongs to.
649 * @return Context of the current tab.
653 LttvTracesetContext
* lttvwindow_get_traceset_context(MainWindow
*main_win
);