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
\end_layout
\begin_layout Itemize
-Support live trace processing
+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
\begin_layout Itemize
The APIs in this document are described as C functions and datatypes.
- When an operation applies to an abstraction that should be an object in
+ 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.
- In such languages, this first argument should be removed, as it will be
- passed implicitly.
\end_layout
\begin_layout Subsection
.
\end_layout
+\begin_layout Standard
+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
-Reading traces
+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
Timestamps in cycles should be available if they are provided by the tracer.
\end_layout
-\begin_layout Subsection
-Low-level trace reading API
+\end_inset
+
+
\end_layout
\begin_layout Standard
-The goal of this API is to provide a uniform way for the framework to access
- the events recorded in a trace, in an encoding-independant way.
-\end_layout
+\begin_inset Note Note
+status open
\begin_layout Subsubsection
Factory methods
a trace handle
\end_layout
-\end_deeper
-\begin_layout Subsubsection
-Trace methods
+\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
-bool close(struct trace *tr)
+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 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
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
-bool advance(struct trace *tr)
+int advance(struct trace *tr, struct trace_cursor *cur)
\end_layout
\begin_deeper
\begin_layout Standard
-Advance the position pointer to the next event in the trace.
+Advance the cursor to the next event in the trace.
\end_layout
\begin_layout Standard
-Arguments: none
+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 values:
+Return value:
\end_layout
\begin_layout Itemize
\begin_deeper
\begin_layout Itemize
-Success
+Success (TRACE_ADVANCE_OK)
\end_layout
\begin_layout Itemize
-Final end of trace (end of a non-live trace or of a completed live trace)
+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
-No more events for now (end of a still running live trace)
+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
-bool seek_time(struct trace *tr, struct trace_cursor *cur)
+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
-The time to seek to
+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: none
+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_beginning(struct trace *tr)
+struct trace_cursor *trace_new_cursor(struct trace *tr)
\end_layout
\begin_deeper
\begin_layout Standard
-Return a new cursor associated to the trace, positioned at its beginning
+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
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
-void trace_cursor_destroy(struct trace_cursor_destroy *)
+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: none
+Arguments:
+\end_layout
+
+\begin_layout Itemize
+tr: the trace
\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)(void))
+ (*cb)(struct trace *, void *priv), void *private)
\end_layout
\begin_deeper
\end_layout
\begin_layout Itemize
-after (timestamp) : call only if the event occurent later than
+after (timestamp) : call only if the timestamp of the event is later than
+
\emph on
after
\end_layout
\end_layout
\end_deeper
+\begin_layout Section
+High level reading of traces
+\end_layout
+
\begin_layout Subsection
-High-level trace reading API
+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, 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 trace events from a traceset (merge of many traces or a single
- trace), regardless of the system they were recorded on and of the tracer
- used.
+ 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 *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
\begin_deeper
+\begin_layout Standard
+Cancel a request.
+\end_layout
+
\begin_layout Standard
Arguments:
\end_layout
\end_layout
\end_deeper
-\begin_layout Subsection
+\begin_layout Itemize
+void traceset_process(struct traceset *tr, struct timeval *tv)
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Process requests for the time specified by tv, then return to the caller.
+ The time is a wall time and has no relationship with the timestamps of
+ the trace.
+ It is used to process a part of the trace while allowing a GUI to remain
+ responsive.
+\end_layout
+
+\begin_layout Standard
+Arguments:
+\end_layout
+
+\begin_layout Itemize
+tr: the traceset
+\end_layout
+
+\begin_layout Itemize
+tv: the duration for which to process the trace
+\end_layout
+
+\end_deeper
+\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, regardless of .
+\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
\end_inset
+\end_layout
+
+\begin_layout Standard
+\begin_inset Note Note
+status open
+
+\begin_layout Section*
+TODO
+\end_layout
+
+\begin_layout Itemize
+extend APIs for monitoring (case where the flow of events is constant and
+ we cannot keep the whole trace forever)
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+views must be able to register the fact that they need the whole trace if
+ they do
+\end_layout
+
+\begin_layout Itemize
+there must be an elegant way to destroy old events
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+add API or infos about interaction with gui? ex: how traceset_process should
+ be called
+\end_layout
+
+\end_inset
+
+
\end_layout
\end_body
projects / lttv.git / blobdiff