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
-Allow merging of traces of different formats
+Support processing of live traces
\end_layout
-\begin_layout Standard
-\begin_inset Note Note
-status open
-
\begin_layout Itemize
-Design the viewer in such a way that it can run in parallel on multi-core
- systems
-\begin_inset Note Greyedout
-status open
-
-\begin_layout Standard
-(Is it worth it? Beware of complex locking issues)
-\end_layout
-
-\end_inset
-
-; No, we don't.
-\end_layout
-
-\end_inset
-
-
+Allow merging of traces of different formats
\end_layout
\begin_layout Itemize
for internal change without breaking compatibility.
\end_layout
-\begin_layout Section
-Controlling the tracing of a system
+\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
-Overview
-\end_layout
-
-\begin_layout Standard
-The goal of this API is to provide a portable way of controlling tracing
- of heterogenous systems.
+Time
\end_layout
\begin_layout Standard
-It should enable to do the following actions.
+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
-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)
+struct trace_time
\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
+struct trace_time_range
\end_layout
-\begin_layout Itemize
-List the static tracepoints available on a system
+\begin_layout Standard
+The preferred representation for times is seconds.
\end_layout
-\begin_deeper
\begin_layout Standard
-These may be static tracepoints (active or inactive) or dynamic tracepoints
- (active or proposed).
+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
-\end_deeper
-\begin_layout Itemize
-Add a new dynamic tracepoint
+\begin_layout Standard
+Each time is accompanied by an uncertainty value.
\end_layout
-\begin_layout Itemize
-Activate a tracepoint
+\begin_layout Subsection
+Modules
\end_layout
-\begin_layout Itemize
-Deactivate a tracepoint
+\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 Itemize
-List available probes
+\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 Itemize
-Connect a probe to a tracepoint
+\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 Itemize
-Start tracing
+\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 Itemize
-Stop tracing
+\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 Itemize
-\begin_inset Note Greyedout
-status open
-
-\begin_layout Standard
-others missing...
+\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
-\end_inset
-
-
+\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
\end_layout
\begin_layout Itemize
-get_supported_formats()
+void get_supported_formats(void)
\end_layout
\begin_deeper
a trace handle
\end_layout
-\end_deeper
-\begin_layout Subsubsection
-Trace methods
+\end_inset
+
+
\end_layout
-\begin_layout Itemize
-close()
+\begin_layout Subsection
+Methods of the Low Level Trace Reading API
\end_layout
\begin_layout Itemize
-current_event()
+void close(struct trace *tr)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments: none
+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
-Return:
+Arguments:
\end_layout
\begin_layout Itemize
-the event currently pointed by the position pointer
+tr: the trace
+\end_layout
+
+\begin_layout Standard
+Return value: none
\end_layout
\end_deeper
\begin_layout Itemize
-advance()
+struct event *current_event(struct trace *tr, struct cursor *cur)
\end_layout
\begin_deeper
\begin_layout Standard
-Advance the position pointer to the next event in the trace.
+Return the event pointed by the cursor cur.
\end_layout
\begin_layout Standard
-Arguments: none
+Arguments:
\end_layout
-\begin_layout Standard
-Return values:
+\begin_layout Itemize
+tr: the trace
\end_layout
\begin_layout Itemize
-The result:
+cur: the cursor indicating the position of the wanted event
\end_layout
-\begin_deeper
-\begin_layout Itemize
-Success
+\begin_layout Standard
+Return value:
\end_layout
\begin_layout Itemize
-Final end of trace (end of a non-live trace or of a completed live trace)
+the event currently pointed by the position pointer
\end_layout
\begin_layout Itemize
-No more events for now (end of a still running live trace)
+NULL, if current_event is called on a new cursor that is positioned before
+ the beginning of the trace
\end_layout
-\end_deeper
\end_deeper
\begin_layout Itemize
-seek_time()
+int advance(struct trace *tr, struct trace_cursor *cur)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments:
-\end_layout
-
-\begin_layout Itemize
-The time to seek to
+Advance the cursor to the next event in the trace.
\end_layout
\begin_layout Standard
-Return: none
+Arguments:
\end_layout
-\end_deeper
\begin_layout Itemize
-get_position_handle()
+tr: the trace
\end_layout
\begin_layout Itemize
-seek_to_position_handle()
+cur: the cursor that should be advanced
\end_layout
-\begin_layout Itemize
-destroy_position_handle()
+\begin_layout Standard
+Return value:
\end_layout
\begin_layout Itemize
-get_time_start()
+The result:
\end_layout
\begin_deeper
-\begin_layout Standard
-Arguments: none
+\begin_layout Itemize
+Success (TRACE_ADVANCE_OK)
\end_layout
-\begin_layout Standard
-Return:
+\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 timestamp of the first event in the 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
-get_time_end()
+int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
+ time)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments: none
+Place a cursor at a particular time index in a trace.
\end_layout
\begin_layout Standard
-Return:
+Arguments:
\end_layout
\begin_layout Itemize
-the timestamp of the last event in the trace
+tr: the trace that should be seeked
\end_layout
-\end_deeper
\begin_layout Itemize
-register_callback_new_event()
+cur: the cursor to seek
\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.
+\begin_layout Itemize
+time: the time to seek to
\end_layout
\begin_layout Standard
-Arguments:
+Return:
\end_layout
\begin_layout Itemize
-after (timestamp) : call only if the event occurent later than
-\emph on
-after
+0: success
\end_layout
\begin_layout Itemize
-the callback function
-\begin_inset Note Note
-status open
-
-\begin_layout Standard
-specify its args and return val
+!= 0: time out of range
\end_layout
-\end_inset
-
+\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
-Return:
+Arguments:
\end_layout
\begin_layout Itemize
-Result (success or failure)
+tr: the trace
\end_layout
-\end_deeper
-\begin_layout Subsection
-High-level trace reading API
+\begin_layout Standard
+Return value:
\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.
+\begin_layout Itemize
+the new cursor
\end_layout
+\end_deeper
\begin_layout Itemize
-Request a range of events
+struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments:
+Copy a cursor.
\end_layout
-\begin_layout Itemize
-(implicitly) the traceset
+\begin_layout Standard
+Arguments:
\end_layout
\begin_layout Itemize
-start timestamp
+cur: the cursor to copy
\end_layout
-\begin_layout Itemize
-stop timestamp (special value for infinity, for live traces)
+\begin_layout Standard
+Return value:
\end_layout
\begin_layout Itemize
-list of event types and callbacks
+a new cursor that is at the same location as cur
\end_layout
+\end_deeper
\begin_layout Itemize
-filter with complex expressions
+void trace_cursor_destroy(struct trace_cursor *cur)
\end_layout
-\begin_layout Itemize
-private pointer to be passed to the callbacks
+\begin_deeper
+\begin_layout Standard
+Free all resources associated to a cursor.
+ After this call, cur is invalid.
\end_layout
\begin_layout Standard
-Return:
+Arguments:
\end_layout
\begin_layout Itemize
-handle to the request for cancelling it
+cur: the cursor to destroy
+\end_layout
+
+\begin_layout Standard
+Return value: none
\end_layout
\end_deeper
\begin_layout Itemize
-Cancel a request
+struct trace_time get_time_start(struct trace *tr)
\end_layout
\begin_deeper
\end_layout
\begin_layout Itemize
-the handle to the request
+tr: the trace
\end_layout
-\end_deeper
-\begin_layout Subsection
-State management
+\begin_layout Standard
+Return value:
\end_layout
-\begin_layout Subsubsection
-State accessing API
+\begin_layout Itemize
+the timestamp of the first event in the trace
\end_layout
+\end_deeper
\begin_layout Itemize
-Request the values of a given set of state variables at a point in time
+struct trace_time get_time_end(struct trace *tr)
\end_layout
\begin_deeper
\begin_layout Standard
-Arguments:
+Arguments: none
\end_layout
-\begin_layout Itemize
-the list of state variables
+\begin_layout Standard
+Return:
\end_layout
\begin_layout Itemize
-the timestamp
+the timestamp of the last event in the trace
\end_layout
\end_deeper
\begin_layout Itemize
-Request all the states changes of a given set of state variables between
- two time indexes
+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
-the list of state variables
+after (timestamp) : call only if the timestamp of the event is later than
+
+\emph on
+after
\end_layout
\begin_layout Itemize
-timestamp 1
+cb: the callback function
+\begin_inset Note Note
+status open
+
+\begin_layout Standard
+specify its args and return val
\end_layout
-\begin_layout Itemize
-timestamp 2
+\end_inset
+
+
\end_layout
-\end_deeper
-\begin_layout Subsubsection
-State setting API
+\begin_layout Standard
+Return:
+\end_layout
+
+\begin_layout Itemize
+Result (success or failure)
\end_layout
+\end_deeper
\begin_layout Section
-Describing event types
+High level reading of traces
\end_layout
\begin_layout Subsection
\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.
+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
-These event-type-describing events could then be received and interpreted
- by a module, 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.
+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
-Events-describing events
+Methods of the high-level trace reading API
\end_layout
\begin_layout Itemize
-Event type declaration event
+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
-Announce the existence of an event type
+Request a range of events from a traceset
\end_layout
-\begin_layout Itemize
-event type name
+\begin_layout Standard
+Arguments:
\end_layout
-\end_deeper
\begin_layout Itemize
-Argument declaration event
+tr: the traceset
\end_layout
-\begin_deeper
-\begin_layout Standard
-Announce the existence of an event argument
+\begin_layout Itemize
+t1: start timestamp
\end_layout
\begin_layout Itemize
-event type name
+t2: stop timestamp (special value for infinity, for live traces)
\end_layout
\begin_layout Itemize
-name
+filter: filter with complex expressions
\end_layout
\begin_layout Itemize
-type
+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
-\end_deeper
+\begin_layout Itemize
+name
+\end_layout
+
+\begin_layout Itemize
+type
+\end_layout
+
+\end_deeper
\begin_layout Itemize
Event destruction
\end_layout
\end_deeper
\begin_layout Subsection
-Event type description API
+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
-Get the number of arguments of an event
+ts: the traceset of which we want the event type
\end_layout
\begin_layout Itemize
-Get the list of arguments of an event
+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
-Find an argument by name
+A pointer to the event type (must not be free'd) or NULL if not found
\end_layout
+\end_deeper
\begin_layout Itemize
-Get the type of an argument of an event type
+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
-Get a string representation of an argument of any type, given an event that
- contains it an instance of it
+eventype: the event type of which we want the arguments
+\end_layout
+
+\begin_layout Standard
+Return value:
\end_layout
\begin_layout Itemize
-Get an integer representation of an integer argument, a floating-point represent
-ation of a floating-point argument
+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
-Functions for accessing other types
+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
\end_layout
\begin_layout Itemize
-Event type identifier
+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
-Two possibilities:
+get the event type corresponding to an event
\end_layout
-\begin_layout Itemize
-an event id (integer)
+\begin_layout Standard
+Arguments:
\end_layout
\begin_layout Itemize
-an event name (string)
+ts:
\end_layout
-\end_deeper
\begin_layout Itemize
-The name of the machine it occured on
+ev:
\end_layout
-\begin_layout Subsection
-Event inspecting API
+\begin_layout Standard
+Return value:
\end_layout
\begin_layout Itemize
-get the event type identifier
+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
-get timestamp
+struct trace *event_get_trace(struct event *ev)
\end_layout
\begin_layout Itemize
-get the name of the machine on which the event occured
+get the name of the machine on which the event occured or other location
+ information
\end_layout
\begin_layout Itemize
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