[lttv.git] / trunk / masters-pmf / 3rd_gen_viewer / 3rd_gen_viewer_arch.lyx

#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize default
\spacing single
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Title
A Set of APIs for a Third-Generation Trace Viewer
\end_layout

\begin_layout Author
\noindent
Pierre-Marc Fournier, Michel Dagenais, Mathieu Desnoyers
\newline

\family typewriter
\size footnotesize
<pierre-marc.fournier _at_ polymtl.ca>
\family default
\size default

\newline

\newline
CASI Lab
\newline
École Polytechnique de Montréal
\newline

\newline
WORK IN PROGRESS
\end_layout

\begin_layout Section
Introduction
\end_layout

\begin_layout Standard
This document proposes some APIs for a trace viewing and analysis infrastructure.
\end_layout

\begin_layout Standard
Design choices were made based on the experience acquired by the design,
 development and use of two previous generations of trace viewers, respectively
 the Trace Visualizer from the Linux Trace Toolkit and its successor, the
 LTTV from the LTTng tracing toolkit.
\end_layout

\begin_layout Section
Goals
\end_layout

\begin_layout Itemize
Provide an infrastructure for fast, interactive visualization and analysis
 of huge traces (>10 GB) on standard workstations
\begin_inset Foot
status open

\begin_layout Standard
Efficiency is of great importance.
 It is tempting to think that as computers get faster, it will be possible
 to run more complex analyses on traces in a shorter time.
 In fact, the size of the traces grows as computers get more powerful, because
 they do more operations than before in the same amount of time and therefore
 generate more events.
 The current tendency to parallelize systems is another factor that results
 in bigger traces.
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Allow efficient manipulation of traces that are larger than the system memory
\end_layout

\begin_layout Itemize
Support processing of live traces
\end_layout

\begin_layout Itemize
Allow merging of traces of different formats
\end_layout

\begin_layout Itemize
Design with both command line utilities (C language) and graphical interfaces
 (Java and others) in mind, sharing code and standardizing interfaces as
 much as possible
\end_layout

\begin_deeper
\begin_layout Standard
Both command-line interfaces and graphical interfaces have an important
 role to play in trace analysis.
 While graphical interfaces allow for complex views, command-line utilities
 can be used quickly in more environments; they can also be more convenient
 in some circumstances.
 A good design should be such that they can share code and APIs.
\end_layout

\end_deeper
\begin_layout Section
General aspects
\end_layout

\begin_layout Itemize
All data structures must be accessed through API methods, in order to allow
 for internal change without breaking compatibility.
\end_layout

\begin_layout Itemize
The APIs in this document are described as C functions and datatypes.
 When an operation applies to an abstraction that could be an object in
 an object-oriented language, it is specified as the first argument of the
 function.
\end_layout

\begin_layout Subsection
Time
\end_layout

\begin_layout Standard
The framework needs to represent points in the time line and time ranges.
 This is done by two data structures, respectively:
\end_layout

\begin_layout Itemize
struct trace_time
\end_layout

\begin_layout Itemize
struct trace_time_range
\end_layout

\begin_layout Standard
The preferred representation for times is seconds.
\end_layout

\begin_layout Standard
Ranges are a span between two points in time.
 They are represented as these two points.
 One or both of them can have the special value 
\emph on
infinity
\emph default
.
\end_layout

\begin_layout Standard
Each time is accompanied by an uncertainty value.
\end_layout

\begin_layout Section
Low level reading of traces
\end_layout

\begin_layout Subsection
Overview
\end_layout

\begin_layout Standard
This API presents a uniform way of accessing traces at a low level, that
 is to access randomly the events of the trace in an physical-encoding-independa
nt way.
\end_layout

\begin_layout Standard
\begin_inset Note Note
status open

\begin_layout Subsubsection
Timestamps
\end_layout

\begin_layout Standard
Timestamps, at the framework level, should be in an architecture-independent
 format.
 One possibility would be to have them stored in seconds (with decimals).
 Offsetting, if necessary, could be handled by the traceset (trace merging)
 level.
 An uncertainty value should accompany the timestamp.
 Timestamps in cycles should be available if they are provided by the tracer.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Note Note
status open

\begin_layout Subsubsection
Factory methods
\end_layout

\begin_layout Itemize
void get_supported_formats(void)
\end_layout

\begin_deeper
\begin_layout Standard
Arguments: none
\end_layout

\begin_layout Standard
Return:
\end_layout

\begin_layout Itemize
a list of supported formats
\end_layout

\end_deeper
\begin_layout Itemize
open_trace()
\end_layout

\begin_deeper
\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
trace URL
\end_layout

\begin_deeper
\begin_layout Itemize
local file name
\end_layout

\begin_layout Itemize
other special url to establish a network connection
\end_layout

\begin_layout Itemize
etc...
\end_layout

\end_deeper
\begin_layout Itemize
trace format (optional, for cases where auto detection would not work or
 be ambiguous)
\end_layout

\begin_layout Standard
Return:
\end_layout

\begin_layout Itemize
a trace handle
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Methods of the Low Level Trace Reading API
\end_layout

\begin_layout Itemize
void close(struct trace *tr)
\end_layout

\begin_deeper
\begin_layout Standard
Close the trace and unallocate all resources associated to this struct trace
 including the handle.
 After this call, tr is invalid and its memory is freed.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace
\end_layout

\begin_layout Standard
Return value: none
\end_layout

\end_deeper
\begin_layout Itemize
struct event *current_event(struct trace *tr, struct cursor *cur)
\end_layout

\begin_deeper
\begin_layout Standard
Return the event pointed by the cursor cur.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace
\end_layout

\begin_layout Itemize
cur: the cursor indicating the position of the wanted event
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
the event currently pointed by the position pointer
\end_layout

\begin_layout Itemize
NULL, if current_event is called on a new cursor that is positioned before
 the beginning of the trace
\end_layout

\end_deeper
\begin_layout Itemize
int advance(struct trace *tr, struct trace_cursor *cur)
\end_layout

\begin_deeper
\begin_layout Standard
Advance the cursor to the next event in the trace.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace
\end_layout

\begin_layout Itemize
cur: the cursor that should be advanced
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
The result:
\end_layout

\begin_deeper
\begin_layout Itemize
Success (TRACE_ADVANCE_OK)
\end_layout

\begin_layout Itemize
The cursor was not advanced because the end of trace is reached (end of
 a non-live trace or of a completed live trace) (TRACE_ADVANCE_END)
\end_layout

\begin_layout Itemize
The cursor was not advanced because no new events are available at this
 time (with a live trace that is still running) (TRACE_ADVANCE_TRY_AGAIN)
\end_layout

\end_deeper
\end_deeper
\begin_layout Itemize
int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
 time)
\end_layout

\begin_deeper
\begin_layout Standard
Place a cursor at a particular time index in a trace.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace that should be seeked
\end_layout

\begin_layout Itemize
cur: the cursor to seek
\end_layout

\begin_layout Itemize
time: the time to seek to
\end_layout

\begin_layout Standard
Return:
\end_layout

\begin_layout Itemize
0: success
\end_layout

\begin_layout Itemize
!= 0: time out of range
\end_layout

\end_deeper
\begin_layout Itemize
struct trace_cursor *trace_new_cursor(struct trace *tr)
\end_layout

\begin_deeper
\begin_layout Standard
Return a new cursor associated to the trace.
 The position of this new cursor is just before the first event, therefore
 advance() must be called before reading the first event.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
the new cursor
\end_layout

\end_deeper
\begin_layout Itemize
struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
\end_layout

\begin_deeper
\begin_layout Standard
Copy a cursor.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
cur: the cursor to copy
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
a new cursor that is at the same location as cur
\end_layout

\end_deeper
\begin_layout Itemize
void trace_cursor_destroy(struct trace_cursor *cur)
\end_layout

\begin_deeper
\begin_layout Standard
Free all resources associated to a cursor.
 After this call, cur is invalid.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
cur: the cursor to destroy
\end_layout

\begin_layout Standard
Return value: none
\end_layout

\end_deeper
\begin_layout Itemize
struct trace_time get_time_start(struct trace *tr)
\end_layout

\begin_deeper
\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the trace
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
the timestamp of the first event in the trace
\end_layout

\end_deeper
\begin_layout Itemize
struct trace_time get_time_end(struct trace *tr)
\end_layout

\begin_deeper
\begin_layout Standard
Arguments: none
\end_layout

\begin_layout Standard
Return:
\end_layout

\begin_layout Itemize
the timestamp of the last event in the trace
\end_layout

\end_deeper
\begin_layout Itemize
register_callback_new_event(struct trace *tr, struct trace_time after, void
 (*cb)(struct trace *, void *priv), void *private)
\end_layout

\begin_deeper
\begin_layout Standard
Register a callback that is called when a new event becomes available in
 a live trace.
 It is also called when the live trace ends.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
after (timestamp) : call only if the timestamp of the event is later than
 
\emph on
after
\end_layout

\begin_layout Itemize
cb: the callback function
\begin_inset Note Note
status open

\begin_layout Standard
specify its args and return val
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Return:
\end_layout

\begin_layout Itemize
Result (success or failure)
\end_layout

\end_deeper
\begin_layout Section
High level reading of traces
\end_layout

\begin_layout Standard
When reading/analyzing/viewing several traces of heterogenous types, these
 traces are read by translator modules, which export the Low Level Trace
 Reading API.
 The traceset service then uses this API to read each of these traces individual
ly, merging them along the way.
 It may apply timestamp offsetting or other synchronization techniques.
 To allow views and analyses to access events, it in turn exports the High
 Level Trace Reading API.
\end_layout

\begin_layout Standard
The goal of this API is to provide a uniform way for analyses and views
 to obtain large sets of trace events from a traceset (merge of many traces
 or a single trace).
\end_layout

\begin_layout Subsection
Methods of the high-level trace reading API
\end_layout

\begin_layout Itemize
struct request_handle *traceset_new_event_request(struct traceset *tr, struct
 trace_time t1, struct trace_time t2, struct event_filter *filter, void
 (*cb)(void *priv, ), void *private)
\end_layout

\begin_deeper
\begin_layout Standard
Request a range of events from a traceset
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
tr: the traceset
\end_layout

\begin_layout Itemize
t1: start timestamp
\end_layout

\begin_layout Itemize
t2: stop timestamp (special value for infinity, for live traces)
\end_layout

\begin_layout Itemize
filter: filter with complex expressions
\end_layout

\begin_layout Itemize
private: private pointer to be passed to the callback
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
handle to the request for cancelling it
\end_layout

\end_deeper
\begin_layout Itemize
void event_request_cancel(struct request_handle *req)
\end_layout

\begin_deeper
\begin_layout Standard
Cancel a request.
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
req: the handle to the request
\end_layout

\end_deeper
\begin_layout Subsection
State management
\end_layout

\begin_layout Standard
States are key/value pairs associated with a time range.
 Keys can be (and generally are) duplicated as long as they do not apply
 to overlapping ranges.
\end_layout

\begin_layout Standard
Keys are character strings.
\end_layout

\begin_layout Standard
Values may be of various types:
\end_layout

\begin_layout Itemize
string
\end_layout

\begin_layout Itemize
uint32
\end_layout

\begin_layout Itemize
int32
\end_layout

\begin_layout Itemize
blob (binary block of arbitrary length)
\end_layout

\begin_layout Itemize
float32
\end_layout

\begin_layout Itemize
float64
\end_layout

\begin_layout Standard
The state information must be persistent between executions of the framework.
\end_layout

\begin_layout Standard
It is possible to assign a state to the range -infinity..infinity to indicate
 that it is global to the trace.
\end_layout

\begin_layout Standard
The key names should be hierarchical.
\end_layout

\begin_layout Subsubsection
State accessing API
\end_layout

\begin_layout Itemize
struct state_value *state_get_value_at_time(char *key, struct trace_time
 time)
\end_layout

\begin_deeper
\begin_layout Standard
Request the value of a given key at a point in time
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
var: the state variables (string)
\end_layout

\begin_layout Itemize
time: the timestamp
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
The state value
\end_layout

\end_deeper
\begin_layout Itemize
struct state_value_range **state_get_values_in_range(char *key, struct state_val
ue *val, struct trace_time_range range)
\end_layout

\begin_deeper
\begin_layout Standard
Request all the states changes of a given set of state variables between
 two time indexes
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
key: the key
\end_layout

\begin_layout Itemize
range: the time range
\end_layout

\end_deeper
\begin_layout Itemize
Other functions for getting values for a set of keys at once?
\end_layout

\begin_layout Subsubsection
State setting API
\end_layout

\begin_layout Itemize
set a particular state
\end_layout

\begin_layout Itemize
delete some states
\end_layout

\begin_layout Section
Describing event types
\end_layout

\begin_layout Subsection
Overview
\end_layout

\begin_layout Standard
Because tracepoints may be created dynamically, information about the descriptio
n of events is just as dynamic.
 In this context, one simple way to communicate the event description informatio
n to upper layers would be to send them as events, as it is done in recent
 versions of LTTV.
 The core events used to describe other events are the only ones whose descripti
on is hardcoded in the framework.
\end_layout

\begin_layout Standard
These event-type-describing events could then be received and interpreted
 by the Event Description Service, which would be a client to the high-level
 tracing API at the same level as normal views and analyses.
 It would store the information and allow the other views and analyses to
 access it via this API.
\end_layout

\begin_layout Standard
Each event has a timestamp, a name and arguments of various types.
 The framework should support the following types:
\end_layout

\begin_layout Itemize
uint32
\end_layout

\begin_layout Itemize
uint64
\end_layout

\begin_layout Itemize
int32
\end_layout

\begin_layout Itemize
int64
\end_layout

\begin_layout Itemize
string
\end_layout

\begin_layout Subsection
Events-describing events
\end_layout

\begin_layout Itemize
Event type declaration event
\end_layout

\begin_deeper
\begin_layout Standard
Announce the existence of an event type
\end_layout

\begin_layout Itemize
event type name
\end_layout

\end_deeper
\begin_layout Itemize
Argument declaration event
\end_layout

\begin_deeper
\begin_layout Standard
Announce the existence of an event argument
\end_layout

\begin_layout Itemize
event type name
\end_layout

\begin_layout Itemize
name
\end_layout

\begin_layout Itemize
type
\end_layout

\end_deeper
\begin_layout Itemize
Event destruction
\end_layout

\begin_deeper
\begin_layout Standard
Announce that an event type ceased to exist
\end_layout

\begin_layout Itemize
event type name
\end_layout

\end_deeper
\begin_layout Subsection
Event type description API
\end_layout

\begin_layout Standard
The event type description service provides the following functions.
\end_layout

\begin_layout Itemize
GArray<struct event_type *> *traceset_get_all_event_types(struct traceset
 *ts)
\end_layout

\begin_deeper
\begin_layout Standard
Get the list of all the event types
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
ts: the traceset of which we want the event types
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
A GArray of of struct event_type.
 The GArray must be gfree()'d by the caller when it is done reading it.
\end_layout

\end_deeper
\begin_layout Itemize
struct event_type *traceset_get_event_type_by_name(struct traceset *ts,
 char *name)
\end_layout

\begin_deeper
\begin_layout Standard
Find an event type by name
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
ts: the traceset of which we want the event type
\end_layout

\begin_layout Itemize
name: the name of the of the event type we are looking for
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
A pointer to the event type (must not be free'd) or NULL if not found
\end_layout

\end_deeper
\begin_layout Itemize
GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype)
\end_layout

\begin_deeper
\begin_layout Standard
Get the list of arguments of an event
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
eventype: the event type of which we want the arguments
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
A GArray of struct event_args.
 The GArray must be gfree()'d by the caller when it is done reading it.
\end_layout

\end_deeper
\begin_layout Itemize
struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
\end_layout

\begin_deeper
\begin_layout Standard
Find an argument by name
\end_layout

\end_deeper
\begin_layout Itemize
Functions for accessing struct event_arg fields
\end_layout

\begin_layout Section
Inspecting events
\end_layout

\begin_layout Subsection
Overview
\end_layout

\begin_layout Standard
Events contain the following information.
\end_layout

\begin_layout Itemize
Timestamp
\end_layout

\begin_layout Itemize
Event type identifier - an event id (integer) - hidden to the API users,
 manipulated as pointers/references to struct event_type
\end_layout

\begin_layout Itemize
A reference to the trace it was in
\end_layout

\begin_layout Subsection
Event inspecting API
\end_layout

\begin_layout Itemize
struct event_type *event_get_type(struct traceset *ts, struct event *ev)
\end_layout

\begin_deeper
\begin_layout Standard
get the event type corresponding to an event
\end_layout

\begin_layout Standard
Arguments:
\end_layout

\begin_layout Itemize
ts:
\end_layout

\begin_layout Itemize
ev:
\end_layout

\begin_layout Standard
Return value:
\end_layout

\begin_layout Itemize
The event type or NULL if no information
\end_layout

\end_deeper
\begin_layout Itemize
struct trace_time event_get_time(struct event *ev)
\end_layout

\begin_deeper
\begin_layout Standard
get the event time
\end_layout

\end_deeper
\begin_layout Itemize
struct trace *event_get_trace(struct event *ev)
\end_layout

\begin_layout Itemize
get the name of the machine on which the event occured or other location
 information
\end_layout

\begin_layout Itemize
get information on the type of tracing technology that was used
\end_layout

\begin_layout Itemize
get the corresponding tracepoint (machine/tracing technology/name/location
 in code(if available))
\end_layout

\begin_layout Itemize
uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Itemize
int32 event_read_arg_int32(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Itemize
uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Itemize
int64 event_read_arg_int64(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Itemize
float32 event_read_arg_float32(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Itemize
float64 event_read_arg_float64(struct event *ev, struct event_arg *arg)
\end_layout

\begin_layout Section
Filtering events
\end_layout

\begin_layout Standard
A filtering API is proposed.
\end_layout

\begin_layout Section
Controlling the tracing of a system
\end_layout

\begin_layout Subsection
Overview
\end_layout

\begin_layout Standard
The goal of this API is to provide a portable way of controlling tracing
 of heterogenous systems.
\end_layout

\begin_layout Standard
It should enable to do the following actions.
\end_layout

\begin_layout Itemize
Set the parameters of a trace (channels, buffering, destination of data
 (file, network, process)...) 
\end_layout

\begin_layout Itemize
Control the recording of events (start, stop, pause the trace)
\end_layout

\begin_layout Itemize
Create tracepoints (on dynamic tracers) and control which tracepoints are
 activated (some may be at trace level, others might only permit system
 level)
\end_layout

\begin_layout Subsection
Trace control API
\end_layout

\begin_layout Itemize
List the static tracepoints available on a system
\end_layout

\begin_deeper
\begin_layout Standard
These may be static tracepoints (active or inactive) or dynamic tracepoints
 (active or proposed).
\end_layout

\end_deeper
\begin_layout Itemize
Add a new dynamic tracepoint
\end_layout

\begin_layout Itemize
Activate a tracepoint
\end_layout

\begin_layout Itemize
Deactivate a tracepoint
\end_layout

\begin_layout Itemize
List available probes
\end_layout

\begin_layout Itemize
Connect a probe to a tracepoint
\end_layout

\begin_layout Itemize
Start tracing
\end_layout

\begin_layout Itemize
Stop tracing
\end_layout

\begin_layout Itemize
\begin_inset Note Greyedout
status open

\begin_layout Standard
others missing...
\end_layout

\end_inset


\end_layout

\end_body
\end_document