From 4414440b5fcb058b2b0faa8f4804d594a2a26ca4 Mon Sep 17 00:00:00 2001 From: pmf Date: Wed, 6 Aug 2008 17:44:25 +0000 Subject: [PATCH] further work on the API document git-svn-id: http://ltt.polymtl.ca/svn@2985 04897980-b3bd-0310-b5e0-8ef037075253 --- .../3rd_gen_viewer/3rd_gen_viewer_arch.lyx | 510 +++++++++++++----- 1 file changed, 376 insertions(+), 134 deletions(-) diff --git a/trunk/masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx b/trunk/masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx index ebc96bf6..5f248896 100644 --- a/trunk/masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx +++ b/trunk/masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx @@ -115,30 +115,6 @@ Support live trace processing Allow merging of traces of different formats \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 - - -\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 @@ -165,92 +141,44 @@ All data structures must be accessed through API methods, in order to allow for internal change without breaking compatibility. \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) +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 + 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 -Trace control API -\end_layout - -\begin_layout Itemize -List the static tracepoints available on a system +Time \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 +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 -Start tracing +struct trace_time \end_layout \begin_layout Itemize -Stop tracing +struct trace_time_range \end_layout -\begin_layout Itemize -\begin_inset Note Greyedout -status open - \begin_layout Standard -others missing... +The preferred representation for times is seconds. \end_layout -\end_inset - - +\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 Section @@ -538,36 +466,38 @@ The goal of this API is to provide a uniform way for analyses and views \end_layout \begin_layout Itemize -Request a range of events +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) \end_layout \begin_deeper \begin_layout Standard -Arguments: +Request a range of events \end_layout -\begin_layout Itemize -(implicitly) the traceset +\begin_layout Standard +Arguments: \end_layout \begin_layout Itemize -start timestamp +tr: the traceset \end_layout \begin_layout Itemize -stop timestamp (special value for infinity, for live traces) +t1: start timestamp \end_layout \begin_layout Itemize -list of event types and callbacks +t2: stop timestamp (special value for infinity, for live traces) \end_layout \begin_layout Itemize -filter with complex expressions +filter: filter with complex expressions \end_layout \begin_layout Itemize -private pointer to be passed to the callbacks +data: private pointer to be passed to the callback \end_layout \begin_layout Standard @@ -580,7 +510,7 @@ handle to the request for cancelling it \end_deeper \begin_layout Itemize -Cancel a request +void event_request_cancel(struct request_handle *req) \end_layout \begin_deeper @@ -589,7 +519,7 @@ Arguments: \end_layout \begin_layout Itemize -the handle to the request +req: the handle to the request \end_layout \end_deeper @@ -597,55 +527,132 @@ the handle to the request 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, regardless of . +\end_layout + +\begin_layout Standard +The key names should be hierarchical. +\end_layout + \begin_layout Subsubsection State accessing API \end_layout \begin_layout Itemize -Request the values of a given set of state variables at a point in time +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 -the list of state variables +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 timestamp +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_deeper \begin_layout Standard Arguments: \end_layout \begin_layout Itemize -the list of state variables +key: the key \end_layout \begin_layout Itemize -timestamp 1 +range: the time range \end_layout +\end_deeper \begin_layout Itemize -timestamp 2 +Other functions for getting values for a set of keys at once? \end_layout -\end_deeper \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 @@ -666,12 +673,37 @@ on is hardcoded in the framework. \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. + 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 @@ -730,42 +762,108 @@ event type name Event type description API \end_layout +\begin_layout Standard +The event type description service provides the following functions. +\end_layout + \begin_layout Itemize +GArray *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 +GArray *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 the type of an argument of an event type +eventype: the event type of which we want the arguments +\end_layout + +\begin_layout Standard +Return value: \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 +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 -Get an integer representation of an integer argument, a floating-point represent -ation of a floating-point argument +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 other types +Functions for accessing struct event_arg fields \end_layout \begin_layout Section @@ -785,41 +883,65 @@ Timestamp \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 +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 @@ -831,5 +953,125 @@ 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 -- 2.34.1