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
Each time is accompanied by an uncertainty value.
\end_layout
+\begin_layout Subsection
+Modules
+\end_layout
+
+\begin_layout Standard
+The following modules should be part of the framework.
+ This list does not include modules related to the GUI, the controlling
+ of traces and the transfer of traces.
+\end_layout
+
+\begin_layout Description
+Trace Has one instance per open trace.
+ Allows the access to a trace by exporting the Low-level Trace Reading API.
+ The underlying implementation may change from one trace to another to adapt
+ to the specific format of each trace.
+\end_layout
+
+\begin_layout Description
+Traceset Receives data from several Traces using their Low-Level Trace Reading
+ API and merge them in a single stream.
+ May also receive data from other instances of Traceset.
+ Exports the High-level Trace Reading API and the Low-level Trace Reading
+ API.
+ Handles time offsetting if necessary to align traces.
+ Handles filtering.
+\end_layout
+
+\begin_layout Description
+State\InsetSpace ~
+providers They receive the stream of events from the Traceset, using
+ the High-level Trace Reading API.
+ They detect state changes.
+ Each one is designed to detect states of a particular level (kernel, applicatio
+n-level, UML states).
+ It pushes the detected states to the State module using the State Setting
+ API.
+\end_layout
+
+\begin_layout Description
+State Records changes in the system state received from State providers
+ by the State Setting API.
+ It implements an efficient state searching engine.
+ Exports the State Accessing API to allow plugins to access the information.
+\end_layout
+
+\begin_layout Description
+Event\InsetSpace ~
+description Receives the stream of events from the Traceset using the
+ High-level Trace Reading API.
+ It reads the events that describe other events and stores the information
+ they contain, possibly using the State module.
+ Other components can access this information through an exported API.
+\end_layout
+
+\begin_layout Description
+Plugins...
+ These are the graphical views, analyses and other components that need
+ access to the events.
+ They receive data from a traceset using the High-level Trace Reading API.
+ They use the services they need (State, Event Description, and/or others).
+ They may export a special API if other components need to access their
+ data.
+\end_layout
+
\begin_layout Section
Low level reading of traces
\end_layout
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 *, struct cursor *cur)
+struct event *current_event(struct trace *tr, struct cursor *cur)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments: none
+Return the event pointed by the cursor cur.
\end_layout
\begin_layout Standard
-Return:
+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
\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
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)
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_layout Standard
-Return:
+Return value:
\end_layout
\begin_layout Itemize
\end_deeper
\begin_layout Itemize
register_callback_new_event(struct trace *tr, struct trace_time after, void
- (*cb)(struct trace *))
+ (*cb)(struct trace *, void *priv), void *private)
\end_layout
\begin_deeper
High level reading of traces
\end_layout
+\begin_layout Subsection
+Overview
+\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, then merge them.
+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.
\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 *data, ), void *data)
+ (*cb)(void *priv, ), void *private)
\end_layout
\begin_deeper
\begin_layout Standard
-Request a range of events
+Request a range of events from a traceset
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Itemize
-data: private pointer to be passed to the callback
+private: private pointer to be passed to the callback
\end_layout
\begin_layout Standard
-Return:
+Return value:
\end_layout
\begin_layout Itemize
\end_layout
\end_deeper
-\begin_layout Subsection
+\begin_layout Section
State management
\end_layout
\begin_layout Standard
Keys are character strings.
+ They are organized in a filesystem-like hierarchy.
+\end_layout
+
+\begin_layout Standard
+Each key/value pair is associated either to a specific trace or to the traceset.
+\end_layout
+
+\begin_layout Standard
+State can persist between runs of the program.
+ This is useful both to reduce pre-calculation times when re-opening a trace,
+ and also to keep general parameters like bookmarks.
+\end_layout
+
+\begin_layout Standard
+It is possible to assign a state to the time range -infinity..infinity to
+ indicate that it is global to the trace.
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Itemize
-blob (binary block of arbitrary length)
+uint64
\end_layout
\begin_layout Itemize
-float32
+int64
\end_layout
\begin_layout Itemize
-float64
+blob (binary block of arbitrary length)
\end_layout
-\begin_layout Standard
-The state information must be persistent between executions of the framework.
+\begin_layout Itemize
+float32
\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.
+\begin_layout Itemize
+float64
\end_layout
-\begin_layout Standard
-The key names should be hierarchical.
+\begin_layout Itemize
+others?
\end_layout
-\begin_layout Subsubsection
-State accessing API
+\begin_layout Subsection
+Methods of the State Accessing API
\end_layout
\begin_layout Itemize
\end_layout
\begin_layout Itemize
-The state value
+The state value.
+ A struct state_value contains the value and the time interval that applies
+ to it.
\end_layout
\end_deeper
\begin_deeper
\begin_layout Standard
-Request all the states changes of a given set of state variables between
+Request all the state changes of a given set of state variables between
two time indexes
\end_layout
range: the time range
\end_layout
+\begin_layout Standard
+Return value:
+\end_layout
+
+\begin_layout Itemize
+The values
+\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
+\begin_layout Subsection
+Methods of the State Setting API
\end_layout
\begin_layout Itemize
\end_deeper
\begin_layout Subsection
-Event type description API
+Methods of the Event Type Description API
\end_layout
\begin_layout Standard
\end_layout
\begin_layout Subsection
-Event inspecting API
+Methods of the Event inspecting API
\end_layout
\begin_layout Itemize
\end_layout
\begin_layout Subsection
-Trace control API
+Methods of the Trace Control API
\end_layout
\begin_layout Itemize
projects / lttv.git / blobdiff