+++ /dev/null
-#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 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 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
-
-\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 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, 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 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
-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.
- 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
-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
-uint64
-\end_layout
-
-\begin_layout Itemize
-int64
-\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 Itemize
-others?
-\end_layout
-
-\begin_layout Subsection
-Methods of the 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.
- A struct state_value contains the value and the time interval that applies
- to it.
-\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 state 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
-
-\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 Subsection
-Methods of the 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
-Methods of the 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
-Methods of the 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
-Methods of the 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
-
-\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
-\end_document
projects / lttv.git / blobdiff