3rd_gen_viewer: add Modules section
[lttv.git] / trunk / masters-pmf / 3rd_gen_viewer / 3rd_gen_viewer_arch.lyx
CommitLineData
1fde1b39 1#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
2\lyxformat 276
3\begin_document
4\begin_header
5\textclass article
6\language english
7\inputencoding auto
8\font_roman default
9\font_sans default
10\font_typewriter default
11\font_default_family default
12\font_sc false
13\font_osf false
14\font_sf_scale 100
15\font_tt_scale 100
16\graphics default
17\paperfontsize default
18\spacing single
19\papersize default
20\use_geometry false
21\use_amsmath 1
22\use_esint 1
23\cite_engine basic
24\use_bibtopic false
25\paperorientation portrait
26\secnumdepth 3
27\tocdepth 3
28\paragraph_separation skip
29\defskip medskip
30\quotes_language english
31\papercolumns 1
32\papersides 1
33\paperpagestyle default
34\tracking_changes false
35\output_changes false
36\author ""
37\author ""
38\end_header
39
40\begin_body
41
42\begin_layout Title
43A Set of APIs for a Third-Generation Trace Viewer
44\end_layout
45
46\begin_layout Author
47\noindent
48Pierre-Marc Fournier, Michel Dagenais, Mathieu Desnoyers
49\newline
50
51\family typewriter
52\size footnotesize
53<pierre-marc.fournier _at_ polymtl.ca>
54\family default
55\size default
56
57\newline
58
59\newline
60CASI Lab
61\newline
62École Polytechnique de Montréal
63\newline
64
65\newline
66WORK IN PROGRESS
67\end_layout
68
1fde1b39 69\begin_layout Standard
70This document proposes some APIs for a trace viewing and analysis infrastructure.
71\end_layout
72
73\begin_layout Standard
74Design choices were made based on the experience acquired by the design,
75 development and use of two previous generations of trace viewers, respectively
76 the Trace Visualizer from the Linux Trace Toolkit and its successor, the
77 LTTV from the LTTng tracing toolkit.
78\end_layout
79
80\begin_layout Section
81Goals
82\end_layout
83
84\begin_layout Itemize
85Provide an infrastructure for fast, interactive visualization and analysis
86 of huge traces (>10 GB) on standard workstations
87\begin_inset Foot
88status open
89
90\begin_layout Standard
91Efficiency is of great importance.
92 It is tempting to think that as computers get faster, it will be possible
93 to run more complex analyses on traces in a shorter time.
94 In fact, the size of the traces grows as computers get more powerful, because
95 they do more operations than before in the same amount of time and therefore
96 generate more events.
97 The current tendency to parallelize systems is another factor that results
98 in bigger traces.
99\end_layout
100
101\end_inset
102
103
104\end_layout
105
106\begin_layout Itemize
b71d449a 107Allow efficient manipulation of traces that are larger than the system memory
108\end_layout
109
110\begin_layout Itemize
111Support processing of live traces
1fde1b39 112\end_layout
113
114\begin_layout Itemize
115Allow merging of traces of different formats
116\end_layout
117
1fde1b39 118\begin_layout Itemize
119Design with both command line utilities (C language) and graphical interfaces
120 (Java and others) in mind, sharing code and standardizing interfaces as
121 much as possible
122\end_layout
123
124\begin_deeper
125\begin_layout Standard
126Both command-line interfaces and graphical interfaces have an important
127 role to play in trace analysis.
128 While graphical interfaces allow for complex views, command-line utilities
129 can be used quickly in more environments; they can also be more convenient
130 in some circumstances.
131 A good design should be such that they can share code and APIs.
132\end_layout
133
134\end_deeper
135\begin_layout Section
136General aspects
137\end_layout
138
139\begin_layout Itemize
140All data structures must be accessed through API methods, in order to allow
141 for internal change without breaking compatibility.
142\end_layout
143
1fde1b39 144\begin_layout Itemize
4414440b 145The APIs in this document are described as C functions and datatypes.
b71d449a 146 When an operation applies to an abstraction that could be an object in
4414440b 147 an object-oriented language, it is specified as the first argument of the
148 function.
1fde1b39 149\end_layout
150
151\begin_layout Subsection
4414440b 152Time
1fde1b39 153\end_layout
154
1fde1b39 155\begin_layout Standard
4414440b 156The framework needs to represent points in the time line and time ranges.
157 This is done by two data structures, respectively:
1fde1b39 158\end_layout
159
160\begin_layout Itemize
4414440b 161struct trace_time
1fde1b39 162\end_layout
163
164\begin_layout Itemize
4414440b 165struct trace_time_range
1fde1b39 166\end_layout
167
1fde1b39 168\begin_layout Standard
4414440b 169The preferred representation for times is seconds.
1fde1b39 170\end_layout
171
4414440b 172\begin_layout Standard
173Ranges are a span between two points in time.
174 They are represented as these two points.
175 One or both of them can have the special value
176\emph on
177infinity
178\emph default
179.
1fde1b39 180\end_layout
181
b71d449a 182\begin_layout Standard
183Each time is accompanied by an uncertainty value.
184\end_layout
185
aed623d7 186\begin_layout Subsection
187Modules
188\end_layout
189
190\begin_layout Standard
191The following modules should be part of the framework.
192 This list does not include modules related to the GUI, the controlling
193 of traces and the transfer of traces.
194\end_layout
195
196\begin_layout Description
197Trace Has one instance per open trace.
198 Allows the access to a trace by exporting the Low-level Trace Reading API.
199 The underlying implementation may change from one trace to another to adapt
200 to the specific format of each trace.
201\end_layout
202
203\begin_layout Description
204Traceset Receives data from several Traces using their Low-Level Trace Reading
205 API and merge them in a single stream.
206 May also receive data from other instances of Traceset.
207 Exports the High-level Trace Reading API and the Low-level Trace Reading
208 API.
209 Handles time offsetting if necessary to align traces.
210 Handles filtering.
211\end_layout
212
213\begin_layout Description
214State\InsetSpace ~
215providers They receive the stream of events from the Traceset, using
216 the High-level Trace Reading API.
217 They detect state changes.
218 Each one is designed to detect states of a particular level (kernel, applicatio
219n-level, UML states).
220 It pushes the detected states to the State module using the State Setting
221 API.
222\end_layout
223
224\begin_layout Description
225State Records changes in the system state received from State providers
226 by the State Setting API.
227 It implements an efficient state searching engine.
228 Exports the State Accessing API to allow plugins to access the information.
229\end_layout
230
231\begin_layout Description
232Event\InsetSpace ~
233description Receives the stream of events from the Traceset using the
234 High-level Trace Reading API.
235 It reads the events that describe other events and stores the information
236 they contain.
237 Other components can access this information through an API it exports.
238\end_layout
239
240\begin_layout Description
241Plugins...
242 These are the graphical views, analyses and other components that need
243 access to the events.
244 They receive data from a traceset using the High-level Trace Reading API.
245 They use the services they need (State, Event Description, and/or others).
246 They may export a special API if other components need to access their
247 data.
248\end_layout
249
1fde1b39 250\begin_layout Section
b71d449a 251Low level reading of traces
1fde1b39 252\end_layout
253
254\begin_layout Subsection
255Overview
256\end_layout
257
b71d449a 258\begin_layout Standard
259This API presents a uniform way of accessing traces at a low level, that
260 is to access randomly the events of the trace in an physical-encoding-independa
261nt way.
262\end_layout
263
264\begin_layout Standard
265\begin_inset Note Note
266status open
267
1fde1b39 268\begin_layout Subsubsection
269Timestamps
270\end_layout
271
272\begin_layout Standard
273Timestamps, at the framework level, should be in an architecture-independent
274 format.
275 One possibility would be to have them stored in seconds (with decimals).
276 Offsetting, if necessary, could be handled by the traceset (trace merging)
277 level.
278 An uncertainty value should accompany the timestamp.
279 Timestamps in cycles should be available if they are provided by the tracer.
280\end_layout
281
b71d449a 282\end_inset
283
284
1fde1b39 285\end_layout
286
287\begin_layout Standard
b71d449a 288\begin_inset Note Note
289status open
1fde1b39 290
291\begin_layout Subsubsection
292Factory methods
293\end_layout
294
295\begin_layout Itemize
6e3755ba 296void get_supported_formats(void)
1fde1b39 297\end_layout
298
299\begin_deeper
300\begin_layout Standard
301Arguments: none
302\end_layout
303
304\begin_layout Standard
305Return:
306\end_layout
307
308\begin_layout Itemize
309a list of supported formats
310\end_layout
311
312\end_deeper
313\begin_layout Itemize
314open_trace()
315\end_layout
316
317\begin_deeper
318\begin_layout Standard
319Arguments:
320\end_layout
321
322\begin_layout Itemize
323trace URL
324\end_layout
325
326\begin_deeper
327\begin_layout Itemize
328local file name
329\end_layout
330
331\begin_layout Itemize
332other special url to establish a network connection
333\end_layout
334
335\begin_layout Itemize
336etc...
337\end_layout
338
339\end_deeper
340\begin_layout Itemize
341trace format (optional, for cases where auto detection would not work or
342 be ambiguous)
343\end_layout
344
345\begin_layout Standard
346Return:
347\end_layout
348
349\begin_layout Itemize
350a trace handle
351\end_layout
352
b71d449a 353\end_inset
354
355
356\end_layout
357
358\begin_layout Subsection
359Methods of the Low Level Trace Reading API
1fde1b39 360\end_layout
361
362\begin_layout Itemize
b71d449a 363void close(struct trace *tr)
1fde1b39 364\end_layout
365
b71d449a 366\begin_deeper
367\begin_layout Standard
368Close the trace and unallocate all resources associated to this struct trace
369 including the handle.
370 After this call, tr is invalid and its memory is freed.
371\end_layout
372
9e22a509 373\begin_layout Standard
374Arguments:
375\end_layout
376
377\begin_layout Itemize
378tr: the trace
379\end_layout
380
381\begin_layout Standard
382Return value: none
383\end_layout
384
b71d449a 385\end_deeper
1fde1b39 386\begin_layout Itemize
9e22a509 387struct event *current_event(struct trace *tr, struct cursor *cur)
1fde1b39 388\end_layout
389
390\begin_deeper
391\begin_layout Standard
9e22a509 392Return the event pointed by the cursor cur.
1fde1b39 393\end_layout
394
395\begin_layout Standard
9e22a509 396Arguments:
397\end_layout
398
399\begin_layout Itemize
400tr: the trace
401\end_layout
402
403\begin_layout Itemize
404cur: the cursor indicating the position of the wanted event
405\end_layout
406
407\begin_layout Standard
408Return value:
1fde1b39 409\end_layout
410
411\begin_layout Itemize
412the event currently pointed by the position pointer
413\end_layout
414
b71d449a 415\begin_layout Itemize
416NULL, if current_event is called on a new cursor that is positioned before
417 the beginning of the trace
418\end_layout
419
1fde1b39 420\end_deeper
421\begin_layout Itemize
b71d449a 422int advance(struct trace *tr, struct trace_cursor *cur)
1fde1b39 423\end_layout
424
425\begin_deeper
426\begin_layout Standard
b71d449a 427Advance the cursor to the next event in the trace.
1fde1b39 428\end_layout
429
430\begin_layout Standard
b71d449a 431Arguments:
432\end_layout
433
434\begin_layout Itemize
435tr: the trace
436\end_layout
437
438\begin_layout Itemize
439cur: the cursor that should be advanced
1fde1b39 440\end_layout
441
442\begin_layout Standard
b71d449a 443Return value:
1fde1b39 444\end_layout
445
446\begin_layout Itemize
447The result:
448\end_layout
449
450\begin_deeper
451\begin_layout Itemize
b71d449a 452Success (TRACE_ADVANCE_OK)
1fde1b39 453\end_layout
454
455\begin_layout Itemize
b71d449a 456The cursor was not advanced because the end of trace is reached (end of
457 a non-live trace or of a completed live trace) (TRACE_ADVANCE_END)
1fde1b39 458\end_layout
459
460\begin_layout Itemize
b71d449a 461The cursor was not advanced because no new events are available at this
462 time (with a live trace that is still running) (TRACE_ADVANCE_TRY_AGAIN)
1fde1b39 463\end_layout
464
465\end_deeper
466\end_deeper
467\begin_layout Itemize
b71d449a 468int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
469 time)
1fde1b39 470\end_layout
471
472\begin_deeper
9e22a509 473\begin_layout Standard
474Place a cursor at a particular time index in a trace.
475\end_layout
476
1fde1b39 477\begin_layout Standard
478Arguments:
479\end_layout
480
481\begin_layout Itemize
b71d449a 482tr: the trace that should be seeked
483\end_layout
484
485\begin_layout Itemize
486cur: the cursor to seek
487\end_layout
488
489\begin_layout Itemize
490time: the time to seek to
1fde1b39 491\end_layout
492
493\begin_layout Standard
b71d449a 494Return:
495\end_layout
496
497\begin_layout Itemize
4980: success
499\end_layout
500
501\begin_layout Itemize
502!= 0: time out of range
1fde1b39 503\end_layout
504
505\end_deeper
506\begin_layout Itemize
b71d449a 507struct trace_cursor *trace_new_cursor(struct trace *tr)
1fde1b39 508\end_layout
509
6e3755ba 510\begin_deeper
511\begin_layout Standard
b71d449a 512Return a new cursor associated to the trace.
513 The position of this new cursor is just before the first event, therefore
514 advance() must be called before reading the first event.
6e3755ba 515\end_layout
516
9e22a509 517\begin_layout Standard
518Arguments:
519\end_layout
520
521\begin_layout Itemize
522tr: the trace
523\end_layout
524
525\begin_layout Standard
526Return value:
527\end_layout
528
529\begin_layout Itemize
530the new cursor
531\end_layout
532
6e3755ba 533\end_deeper
1fde1b39 534\begin_layout Itemize
6e3755ba 535struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
1fde1b39 536\end_layout
537
b71d449a 538\begin_deeper
539\begin_layout Standard
540Copy a cursor.
541\end_layout
542
543\begin_layout Standard
544Arguments:
545\end_layout
546
547\begin_layout Itemize
548cur: the cursor to copy
549\end_layout
550
551\begin_layout Standard
552Return value:
553\end_layout
554
555\begin_layout Itemize
556a new cursor that is at the same location as cur
557\end_layout
558
559\end_deeper
560\begin_layout Itemize
561void trace_cursor_destroy(struct trace_cursor *cur)
562\end_layout
563
564\begin_deeper
565\begin_layout Standard
566Free all resources associated to a cursor.
567 After this call, cur is invalid.
568\end_layout
569
570\begin_layout Standard
571Arguments:
572\end_layout
573
1fde1b39 574\begin_layout Itemize
b71d449a 575cur: the cursor to destroy
1fde1b39 576\end_layout
577
9e22a509 578\begin_layout Standard
579Return value: none
580\end_layout
581
b71d449a 582\end_deeper
1fde1b39 583\begin_layout Itemize
6e3755ba 584struct trace_time get_time_start(struct trace *tr)
1fde1b39 585\end_layout
586
587\begin_deeper
588\begin_layout Standard
b71d449a 589Arguments:
590\end_layout
591
592\begin_layout Itemize
593tr: the trace
1fde1b39 594\end_layout
595
596\begin_layout Standard
9e22a509 597Return value:
1fde1b39 598\end_layout
599
600\begin_layout Itemize
601the timestamp of the first event in the trace
602\end_layout
603
604\end_deeper
605\begin_layout Itemize
6e3755ba 606struct trace_time get_time_end(struct trace *tr)
1fde1b39 607\end_layout
608
609\begin_deeper
610\begin_layout Standard
611Arguments: none
612\end_layout
613
614\begin_layout Standard
615Return:
616\end_layout
617
618\begin_layout Itemize
619the timestamp of the last event in the trace
620\end_layout
621
622\end_deeper
623\begin_layout Itemize
6e3755ba 624register_callback_new_event(struct trace *tr, struct trace_time after, void
9e22a509 625 (*cb)(struct trace *, void *priv), void *private)
1fde1b39 626\end_layout
627
628\begin_deeper
629\begin_layout Standard
630Register a callback that is called when a new event becomes available in
631 a live trace.
632 It is also called when the live trace ends.
633\end_layout
634
635\begin_layout Standard
636Arguments:
637\end_layout
638
639\begin_layout Itemize
b71d449a 640after (timestamp) : call only if the timestamp of the event is later than
641
1fde1b39 642\emph on
643after
644\end_layout
645
646\begin_layout Itemize
6e3755ba 647cb: the callback function
1fde1b39 648\begin_inset Note Note
649status open
650
651\begin_layout Standard
652specify its args and return val
653\end_layout
654
655\end_inset
656
657
658\end_layout
659
660\begin_layout Standard
661Return:
662\end_layout
663
664\begin_layout Itemize
665Result (success or failure)
666\end_layout
667
668\end_deeper
b71d449a 669\begin_layout Section
670High level reading of traces
671\end_layout
672
673\begin_layout Standard
674When reading/analyzing/viewing several traces of heterogenous types, these
675 traces are read by translator modules, which export the Low Level Trace
676 Reading API.
677 The traceset service then uses this API to read each of these traces individual
9e22a509 678ly, merging them along the way.
b71d449a 679 It may apply timestamp offsetting or other synchronization techniques.
680 To allow views and analyses to access events, it in turn exports the High
681 Level Trace Reading API.
1fde1b39 682\end_layout
683
684\begin_layout Standard
685The goal of this API is to provide a uniform way for analyses and views
b71d449a 686 to obtain large sets of trace events from a traceset (merge of many traces
687 or a single trace).
688\end_layout
689
690\begin_layout Subsection
691Methods of the high-level trace reading API
1fde1b39 692\end_layout
693
694\begin_layout Itemize
4414440b 695struct request_handle *traceset_new_event_request(struct traceset *tr, struct
696 trace_time t1, struct trace_time t2, struct event_filter *filter, void
9e22a509 697 (*cb)(void *priv, ), void *private)
1fde1b39 698\end_layout
699
700\begin_deeper
701\begin_layout Standard
9e22a509 702Request a range of events from a traceset
1fde1b39 703\end_layout
704
4414440b 705\begin_layout Standard
706Arguments:
1fde1b39 707\end_layout
708
709\begin_layout Itemize
4414440b 710tr: the traceset
1fde1b39 711\end_layout
712
713\begin_layout Itemize
4414440b 714t1: start timestamp
1fde1b39 715\end_layout
716
717\begin_layout Itemize
4414440b 718t2: stop timestamp (special value for infinity, for live traces)
1fde1b39 719\end_layout
720
721\begin_layout Itemize
4414440b 722filter: filter with complex expressions
1fde1b39 723\end_layout
724
725\begin_layout Itemize
9e22a509 726private: private pointer to be passed to the callback
1fde1b39 727\end_layout
728
729\begin_layout Standard
9e22a509 730Return value:
1fde1b39 731\end_layout
732
733\begin_layout Itemize
734handle to the request for cancelling it
735\end_layout
736
737\end_deeper
738\begin_layout Itemize
4414440b 739void event_request_cancel(struct request_handle *req)
1fde1b39 740\end_layout
741
742\begin_deeper
b71d449a 743\begin_layout Standard
744Cancel a request.
745\end_layout
746
1fde1b39 747\begin_layout Standard
748Arguments:
749\end_layout
750
751\begin_layout Itemize
4414440b 752req: the handle to the request
1fde1b39 753\end_layout
754
755\end_deeper
756\begin_layout Subsection
757State management
758\end_layout
759
4414440b 760\begin_layout Standard
761States are key/value pairs associated with a time range.
762 Keys can be (and generally are) duplicated as long as they do not apply
763 to overlapping ranges.
764\end_layout
765
766\begin_layout Standard
767Keys are character strings.
768\end_layout
769
770\begin_layout Standard
771Values may be of various types:
772\end_layout
773
774\begin_layout Itemize
775string
776\end_layout
777
778\begin_layout Itemize
779uint32
780\end_layout
781
782\begin_layout Itemize
783int32
784\end_layout
785
786\begin_layout Itemize
787blob (binary block of arbitrary length)
788\end_layout
789
790\begin_layout Itemize
791float32
792\end_layout
793
794\begin_layout Itemize
795float64
796\end_layout
797
798\begin_layout Standard
799The state information must be persistent between executions of the framework.
800\end_layout
801
802\begin_layout Standard
803It is possible to assign a state to the range -infinity..infinity to indicate
b71d449a 804 that it is global to the trace.
4414440b 805\end_layout
806
807\begin_layout Standard
808The key names should be hierarchical.
809\end_layout
810
1fde1b39 811\begin_layout Subsubsection
aed623d7 812Methods of the State Accessing API
1fde1b39 813\end_layout
814
815\begin_layout Itemize
4414440b 816struct state_value *state_get_value_at_time(char *key, struct trace_time
817 time)
1fde1b39 818\end_layout
819
820\begin_deeper
4414440b 821\begin_layout Standard
822Request the value of a given key at a point in time
823\end_layout
824
1fde1b39 825\begin_layout Standard
826Arguments:
827\end_layout
828
829\begin_layout Itemize
4414440b 830var: the state variables (string)
831\end_layout
832
833\begin_layout Itemize
834time: the timestamp
835\end_layout
836
837\begin_layout Standard
838Return value:
1fde1b39 839\end_layout
840
841\begin_layout Itemize
4414440b 842The state value
1fde1b39 843\end_layout
844
845\end_deeper
846\begin_layout Itemize
4414440b 847struct state_value_range **state_get_values_in_range(char *key, struct state_val
848ue *val, struct trace_time_range range)
849\end_layout
850
851\begin_deeper
852\begin_layout Standard
1fde1b39 853Request all the states changes of a given set of state variables between
854 two time indexes
855\end_layout
856
1fde1b39 857\begin_layout Standard
858Arguments:
859\end_layout
860
861\begin_layout Itemize
4414440b 862key: the key
1fde1b39 863\end_layout
864
865\begin_layout Itemize
4414440b 866range: the time range
1fde1b39 867\end_layout
868
4414440b 869\end_deeper
1fde1b39 870\begin_layout Itemize
4414440b 871Other functions for getting values for a set of keys at once?
1fde1b39 872\end_layout
873
1fde1b39 874\begin_layout Subsubsection
aed623d7 875Methods of the State Setting API
1fde1b39 876\end_layout
877
4414440b 878\begin_layout Itemize
879set a particular state
880\end_layout
881
882\begin_layout Itemize
883delete some states
884\end_layout
885
1fde1b39 886\begin_layout Section
887Describing event types
888\end_layout
889
890\begin_layout Subsection
891Overview
892\end_layout
893
894\begin_layout Standard
895Because tracepoints may be created dynamically, information about the descriptio
896n of events is just as dynamic.
897 In this context, one simple way to communicate the event description informatio
898n to upper layers would be to send them as events, as it is done in recent
899 versions of LTTV.
900 The core events used to describe other events are the only ones whose descripti
901on is hardcoded in the framework.
902\end_layout
903
904\begin_layout Standard
905These event-type-describing events could then be received and interpreted
4414440b 906 by the Event Description Service, which would be a client to the high-level
907 tracing API at the same level as normal views and analyses.
1fde1b39 908 It would store the information and allow the other views and analyses to
909 access it via this API.
910\end_layout
911
4414440b 912\begin_layout Standard
913Each event has a timestamp, a name and arguments of various types.
914 The framework should support the following types:
915\end_layout
916
917\begin_layout Itemize
918uint32
919\end_layout
920
921\begin_layout Itemize
922uint64
923\end_layout
924
925\begin_layout Itemize
926int32
927\end_layout
928
929\begin_layout Itemize
930int64
931\end_layout
932
933\begin_layout Itemize
934string
935\end_layout
936
1fde1b39 937\begin_layout Subsection
938Events-describing events
939\end_layout
940
941\begin_layout Itemize
942Event type declaration event
943\end_layout
944
945\begin_deeper
946\begin_layout Standard
947Announce the existence of an event type
948\end_layout
949
950\begin_layout Itemize
951event type name
952\end_layout
953
954\end_deeper
955\begin_layout Itemize
956Argument declaration event
957\end_layout
958
959\begin_deeper
960\begin_layout Standard
961Announce the existence of an event argument
962\end_layout
963
964\begin_layout Itemize
965event type name
966\end_layout
967
968\begin_layout Itemize
969name
970\end_layout
971
972\begin_layout Itemize
973type
974\end_layout
975
976\end_deeper
977\begin_layout Itemize
978Event destruction
979\end_layout
980
981\begin_deeper
982\begin_layout Standard
983Announce that an event type ceased to exist
984\end_layout
985
986\begin_layout Itemize
987event type name
988\end_layout
989
990\end_deeper
991\begin_layout Subsection
aed623d7 992Methods of the Event Type Description API
1fde1b39 993\end_layout
994
4414440b 995\begin_layout Standard
996The event type description service provides the following functions.
997\end_layout
998
1fde1b39 999\begin_layout Itemize
4414440b 1000GArray<struct event_type *> *traceset_get_all_event_types(struct traceset
1001 *ts)
1002\end_layout
1003
1004\begin_deeper
1005\begin_layout Standard
1fde1b39 1006Get the list of all the event types
1007\end_layout
1008
4414440b 1009\begin_layout Standard
1010Arguments:
1011\end_layout
1012
1fde1b39 1013\begin_layout Itemize
4414440b 1014ts: the traceset of which we want the event types
1015\end_layout
1016
1017\begin_layout Standard
1018Return value:
1019\end_layout
1020
1021\begin_layout Itemize
1022A GArray of of struct event_type.
1023 The GArray must be gfree()'d by the caller when it is done reading it.
1024\end_layout
1025
1026\end_deeper
1027\begin_layout Itemize
1028struct event_type *traceset_get_event_type_by_name(struct traceset *ts,
1029 char *name)
1030\end_layout
1031
1032\begin_deeper
1033\begin_layout Standard
1fde1b39 1034Find an event type by name
1035\end_layout
1036
4414440b 1037\begin_layout Standard
1038Arguments:
1039\end_layout
1040
1fde1b39 1041\begin_layout Itemize
4414440b 1042ts: the traceset of which we want the event type
1fde1b39 1043\end_layout
1044
1045\begin_layout Itemize
4414440b 1046name: the name of the of the event type we are looking for
1047\end_layout
1048
1049\begin_layout Standard
1050Return value:
1fde1b39 1051\end_layout
1052
1053\begin_layout Itemize
4414440b 1054A pointer to the event type (must not be free'd) or NULL if not found
1055\end_layout
1056
1057\end_deeper
1058\begin_layout Itemize
1059GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype)
1060\end_layout
1061
1062\begin_deeper
1063\begin_layout Standard
1064Get the list of arguments of an event
1065\end_layout
1066
1067\begin_layout Standard
1068Arguments:
1fde1b39 1069\end_layout
1070
1071\begin_layout Itemize
4414440b 1072eventype: the event type of which we want the arguments
1073\end_layout
1074
1075\begin_layout Standard
1076Return value:
1fde1b39 1077\end_layout
1078
1079\begin_layout Itemize
4414440b 1080A GArray of struct event_args.
1081 The GArray must be gfree()'d by the caller when it is done reading it.
1fde1b39 1082\end_layout
1083
4414440b 1084\end_deeper
1fde1b39 1085\begin_layout Itemize
4414440b 1086struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
1fde1b39 1087\end_layout
1088
4414440b 1089\begin_deeper
1090\begin_layout Standard
1091Find an argument by name
1092\end_layout
1093
1094\end_deeper
1fde1b39 1095\begin_layout Itemize
4414440b 1096Functions for accessing struct event_arg fields
1fde1b39 1097\end_layout
1098
1099\begin_layout Section
1100Inspecting events
1101\end_layout
1102
1103\begin_layout Subsection
1104Overview
1105\end_layout
1106
1107\begin_layout Standard
1108Events contain the following information.
1109\end_layout
1110
1111\begin_layout Itemize
1112Timestamp
1113\end_layout
1114
1115\begin_layout Itemize
4414440b 1116Event type identifier - an event id (integer) - hidden to the API users,
1117 manipulated as pointers/references to struct event_type
1118\end_layout
1119
1120\begin_layout Itemize
1121A reference to the trace it was in
1122\end_layout
1123
1124\begin_layout Subsection
aed623d7 1125Methods of the Event inspecting API
4414440b 1126\end_layout
1127
1128\begin_layout Itemize
1129struct event_type *event_get_type(struct traceset *ts, struct event *ev)
1fde1b39 1130\end_layout
1131
1132\begin_deeper
1133\begin_layout Standard
4414440b 1134get the event type corresponding to an event
1fde1b39 1135\end_layout
1136
4414440b 1137\begin_layout Standard
1138Arguments:
1fde1b39 1139\end_layout
1140
1141\begin_layout Itemize
4414440b 1142ts:
1fde1b39 1143\end_layout
1144
1fde1b39 1145\begin_layout Itemize
4414440b 1146ev:
1fde1b39 1147\end_layout
1148
4414440b 1149\begin_layout Standard
1150Return value:
1fde1b39 1151\end_layout
1152
1153\begin_layout Itemize
4414440b 1154The event type or NULL if no information
1155\end_layout
1156
1157\end_deeper
1158\begin_layout Itemize
1159struct trace_time event_get_time(struct event *ev)
1160\end_layout
1161
1162\begin_deeper
1163\begin_layout Standard
1164get the event time
1fde1b39 1165\end_layout
1166
4414440b 1167\end_deeper
1fde1b39 1168\begin_layout Itemize
4414440b 1169struct trace *event_get_trace(struct event *ev)
1fde1b39 1170\end_layout
1171
1172\begin_layout Itemize
4414440b 1173get the name of the machine on which the event occured or other location
1174 information
1fde1b39 1175\end_layout
1176
1177\begin_layout Itemize
1178get information on the type of tracing technology that was used
1179\end_layout
1180
1181\begin_layout Itemize
1182get the corresponding tracepoint (machine/tracing technology/name/location
1183 in code(if available))
1184\end_layout
1185
4414440b 1186\begin_layout Itemize
1187uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg)
1188\end_layout
1189
1190\begin_layout Itemize
1191int32 event_read_arg_int32(struct event *ev, struct event_arg *arg)
1192\end_layout
1193
1194\begin_layout Itemize
1195uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg)
1196\end_layout
1197
1198\begin_layout Itemize
1199int64 event_read_arg_int64(struct event *ev, struct event_arg *arg)
1200\end_layout
1201
1202\begin_layout Itemize
1203float32 event_read_arg_float32(struct event *ev, struct event_arg *arg)
1204\end_layout
1205
1206\begin_layout Itemize
1207float64 event_read_arg_float64(struct event *ev, struct event_arg *arg)
1208\end_layout
1209
1210\begin_layout Section
1211Filtering events
1212\end_layout
1213
1214\begin_layout Standard
1215A filtering API is proposed.
1216\end_layout
1217
1218\begin_layout Section
1219Controlling the tracing of a system
1220\end_layout
1221
1222\begin_layout Subsection
1223Overview
1224\end_layout
1225
1226\begin_layout Standard
1227The goal of this API is to provide a portable way of controlling tracing
1228 of heterogenous systems.
1229\end_layout
1230
1231\begin_layout Standard
1232It should enable to do the following actions.
1233\end_layout
1234
1235\begin_layout Itemize
1236Set the parameters of a trace (channels, buffering, destination of data
1237 (file, network, process)...)
1238\end_layout
1239
1240\begin_layout Itemize
1241Control the recording of events (start, stop, pause the trace)
1242\end_layout
1243
1244\begin_layout Itemize
1245Create tracepoints (on dynamic tracers) and control which tracepoints are
1246 activated (some may be at trace level, others might only permit system
1247 level)
1248\end_layout
1249
1250\begin_layout Subsection
aed623d7 1251Methods of the Trace Control API
4414440b 1252\end_layout
1253
1254\begin_layout Itemize
1255List the static tracepoints available on a system
1256\end_layout
1257
1258\begin_deeper
1259\begin_layout Standard
1260These may be static tracepoints (active or inactive) or dynamic tracepoints
1261 (active or proposed).
1262\end_layout
1263
1264\end_deeper
1265\begin_layout Itemize
1266Add a new dynamic tracepoint
1267\end_layout
1268
1269\begin_layout Itemize
1270Activate a tracepoint
1271\end_layout
1272
1273\begin_layout Itemize
1274Deactivate a tracepoint
1275\end_layout
1276
1277\begin_layout Itemize
1278List available probes
1279\end_layout
1280
1281\begin_layout Itemize
1282Connect a probe to a tracepoint
1283\end_layout
1284
1285\begin_layout Itemize
1286Start tracing
1287\end_layout
1288
1289\begin_layout Itemize
1290Stop tracing
1291\end_layout
1292
1293\begin_layout Itemize
1294\begin_inset Note Greyedout
1295status open
1296
1297\begin_layout Standard
1298others missing...
1299\end_layout
1300
1301\end_inset
1302
1303
1304\end_layout
1305
1fde1b39 1306\end_body
1307\end_document
This page took 0.074629 seconds and 4 git commands to generate.