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 |
43 | A Set of APIs for a Third-Generation Trace Viewer |
44 | \end_layout |
45 | |
46 | \begin_layout Author |
47 | \noindent |
48 | Pierre-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 |
60 | CASI Lab |
61 | \newline |
62 | École Polytechnique de Montréal |
63 | \newline |
64 | |
65 | \newline |
66 | WORK IN PROGRESS |
67 | \end_layout |
68 | |
69 | \begin_layout Section |
70 | Introduction |
71 | \end_layout |
72 | |
73 | \begin_layout Standard |
74 | This document proposes some APIs for a trace viewing and analysis infrastructure. |
75 | \end_layout |
76 | |
77 | \begin_layout Standard |
78 | Design choices were made based on the experience acquired by the design, |
79 | development and use of two previous generations of trace viewers, respectively |
80 | the Trace Visualizer from the Linux Trace Toolkit and its successor, the |
81 | LTTV from the LTTng tracing toolkit. |
82 | \end_layout |
83 | |
84 | \begin_layout Section |
85 | Goals |
86 | \end_layout |
87 | |
88 | \begin_layout Itemize |
89 | Provide an infrastructure for fast, interactive visualization and analysis |
90 | of huge traces (>10 GB) on standard workstations |
91 | \begin_inset Foot |
92 | status open |
93 | |
94 | \begin_layout Standard |
95 | Efficiency is of great importance. |
96 | It is tempting to think that as computers get faster, it will be possible |
97 | to run more complex analyses on traces in a shorter time. |
98 | In fact, the size of the traces grows as computers get more powerful, because |
99 | they do more operations than before in the same amount of time and therefore |
100 | generate more events. |
101 | The current tendency to parallelize systems is another factor that results |
102 | in bigger traces. |
103 | \end_layout |
104 | |
105 | \end_inset |
106 | |
107 | |
108 | \end_layout |
109 | |
110 | \begin_layout Itemize |
111 | Support live trace processing |
112 | \end_layout |
113 | |
114 | \begin_layout Itemize |
115 | Allow merging of traces of different formats |
116 | \end_layout |
117 | |
1fde1b39 |
118 | \begin_layout Itemize |
119 | Design 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 |
126 | Both 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 |
136 | General aspects |
137 | \end_layout |
138 | |
139 | \begin_layout Itemize |
140 | All 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 |
145 | The APIs in this document are described as C functions and datatypes. |
146 | When an operation applies to an abstraction that should be an object in |
147 | an object-oriented language, it is specified as the first argument of the |
148 | function. |
149 | In such languages, this first argument should be removed, as it will be |
150 | passed implicitly. |
1fde1b39 |
151 | \end_layout |
152 | |
153 | \begin_layout Subsection |
4414440b |
154 | Time |
1fde1b39 |
155 | \end_layout |
156 | |
1fde1b39 |
157 | \begin_layout Standard |
4414440b |
158 | The framework needs to represent points in the time line and time ranges. |
159 | This is done by two data structures, respectively: |
1fde1b39 |
160 | \end_layout |
161 | |
162 | \begin_layout Itemize |
4414440b |
163 | struct trace_time |
1fde1b39 |
164 | \end_layout |
165 | |
166 | \begin_layout Itemize |
4414440b |
167 | struct trace_time_range |
1fde1b39 |
168 | \end_layout |
169 | |
1fde1b39 |
170 | \begin_layout Standard |
4414440b |
171 | The preferred representation for times is seconds. |
1fde1b39 |
172 | \end_layout |
173 | |
4414440b |
174 | \begin_layout Standard |
175 | Ranges are a span between two points in time. |
176 | They are represented as these two points. |
177 | One or both of them can have the special value |
178 | \emph on |
179 | infinity |
180 | \emph default |
181 | . |
1fde1b39 |
182 | \end_layout |
183 | |
184 | \begin_layout Section |
185 | Reading traces |
186 | \end_layout |
187 | |
188 | \begin_layout Subsection |
189 | Overview |
190 | \end_layout |
191 | |
192 | \begin_layout Subsubsection |
193 | Timestamps |
194 | \end_layout |
195 | |
196 | \begin_layout Standard |
197 | Timestamps, at the framework level, should be in an architecture-independent |
198 | format. |
199 | One possibility would be to have them stored in seconds (with decimals). |
200 | Offsetting, if necessary, could be handled by the traceset (trace merging) |
201 | level. |
202 | An uncertainty value should accompany the timestamp. |
203 | Timestamps in cycles should be available if they are provided by the tracer. |
204 | \end_layout |
205 | |
206 | \begin_layout Subsection |
207 | Low-level trace reading API |
208 | \end_layout |
209 | |
210 | \begin_layout Standard |
211 | The goal of this API is to provide a uniform way for the framework to access |
212 | the events recorded in a trace, in an encoding-independant way. |
213 | \end_layout |
214 | |
215 | \begin_layout Subsubsection |
216 | Factory methods |
217 | \end_layout |
218 | |
219 | \begin_layout Itemize |
6e3755ba |
220 | void get_supported_formats(void) |
1fde1b39 |
221 | \end_layout |
222 | |
223 | \begin_deeper |
224 | \begin_layout Standard |
225 | Arguments: none |
226 | \end_layout |
227 | |
228 | \begin_layout Standard |
229 | Return: |
230 | \end_layout |
231 | |
232 | \begin_layout Itemize |
233 | a list of supported formats |
234 | \end_layout |
235 | |
236 | \end_deeper |
237 | \begin_layout Itemize |
238 | open_trace() |
239 | \end_layout |
240 | |
241 | \begin_deeper |
242 | \begin_layout Standard |
243 | Arguments: |
244 | \end_layout |
245 | |
246 | \begin_layout Itemize |
247 | trace URL |
248 | \end_layout |
249 | |
250 | \begin_deeper |
251 | \begin_layout Itemize |
252 | local file name |
253 | \end_layout |
254 | |
255 | \begin_layout Itemize |
256 | other special url to establish a network connection |
257 | \end_layout |
258 | |
259 | \begin_layout Itemize |
260 | etc... |
261 | \end_layout |
262 | |
263 | \end_deeper |
264 | \begin_layout Itemize |
265 | trace format (optional, for cases where auto detection would not work or |
266 | be ambiguous) |
267 | \end_layout |
268 | |
269 | \begin_layout Standard |
270 | Return: |
271 | \end_layout |
272 | |
273 | \begin_layout Itemize |
274 | a trace handle |
275 | \end_layout |
276 | |
277 | \end_deeper |
278 | \begin_layout Subsubsection |
279 | Trace methods |
280 | \end_layout |
281 | |
282 | \begin_layout Itemize |
6e3755ba |
283 | bool close(struct trace *tr) |
1fde1b39 |
284 | \end_layout |
285 | |
286 | \begin_layout Itemize |
6e3755ba |
287 | struct event *current_event(struct trace *) |
1fde1b39 |
288 | \end_layout |
289 | |
290 | \begin_deeper |
291 | \begin_layout Standard |
292 | Arguments: none |
293 | \end_layout |
294 | |
295 | \begin_layout Standard |
296 | Return: |
297 | \end_layout |
298 | |
299 | \begin_layout Itemize |
300 | the event currently pointed by the position pointer |
301 | \end_layout |
302 | |
303 | \end_deeper |
304 | \begin_layout Itemize |
6e3755ba |
305 | bool advance(struct trace *tr) |
1fde1b39 |
306 | \end_layout |
307 | |
308 | \begin_deeper |
309 | \begin_layout Standard |
310 | Advance the position pointer to the next event in the trace. |
311 | \end_layout |
312 | |
313 | \begin_layout Standard |
314 | Arguments: none |
315 | \end_layout |
316 | |
317 | \begin_layout Standard |
318 | Return values: |
319 | \end_layout |
320 | |
321 | \begin_layout Itemize |
322 | The result: |
323 | \end_layout |
324 | |
325 | \begin_deeper |
326 | \begin_layout Itemize |
327 | Success |
328 | \end_layout |
329 | |
330 | \begin_layout Itemize |
331 | Final end of trace (end of a non-live trace or of a completed live trace) |
332 | \end_layout |
333 | |
334 | \begin_layout Itemize |
335 | No more events for now (end of a still running live trace) |
336 | \end_layout |
337 | |
338 | \end_deeper |
339 | \end_deeper |
340 | \begin_layout Itemize |
6e3755ba |
341 | bool seek_time(struct trace *tr, struct trace_cursor *cur) |
1fde1b39 |
342 | \end_layout |
343 | |
344 | \begin_deeper |
345 | \begin_layout Standard |
346 | Arguments: |
347 | \end_layout |
348 | |
349 | \begin_layout Itemize |
350 | The time to seek to |
351 | \end_layout |
352 | |
353 | \begin_layout Standard |
354 | Return: none |
355 | \end_layout |
356 | |
357 | \end_deeper |
358 | \begin_layout Itemize |
6e3755ba |
359 | struct trace_cursor *trace_new_cursor_beginning(struct trace *tr) |
1fde1b39 |
360 | \end_layout |
361 | |
6e3755ba |
362 | \begin_deeper |
363 | \begin_layout Standard |
364 | Return a new cursor associated to the trace, positioned at its beginning |
365 | \end_layout |
366 | |
367 | \end_deeper |
1fde1b39 |
368 | \begin_layout Itemize |
6e3755ba |
369 | struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur) |
1fde1b39 |
370 | \end_layout |
371 | |
372 | \begin_layout Itemize |
6e3755ba |
373 | void trace_cursor_destroy(struct trace_cursor_destroy *) |
1fde1b39 |
374 | \end_layout |
375 | |
376 | \begin_layout Itemize |
6e3755ba |
377 | struct trace_time get_time_start(struct trace *tr) |
1fde1b39 |
378 | \end_layout |
379 | |
380 | \begin_deeper |
381 | \begin_layout Standard |
382 | Arguments: none |
383 | \end_layout |
384 | |
385 | \begin_layout Standard |
386 | Return: |
387 | \end_layout |
388 | |
389 | \begin_layout Itemize |
390 | the timestamp of the first event in the trace |
391 | \end_layout |
392 | |
393 | \end_deeper |
394 | \begin_layout Itemize |
6e3755ba |
395 | struct trace_time get_time_end(struct trace *tr) |
1fde1b39 |
396 | \end_layout |
397 | |
398 | \begin_deeper |
399 | \begin_layout Standard |
400 | Arguments: none |
401 | \end_layout |
402 | |
403 | \begin_layout Standard |
404 | Return: |
405 | \end_layout |
406 | |
407 | \begin_layout Itemize |
408 | the timestamp of the last event in the trace |
409 | \end_layout |
410 | |
411 | \end_deeper |
412 | \begin_layout Itemize |
6e3755ba |
413 | register_callback_new_event(struct trace *tr, struct trace_time after, void |
414 | (*cb)(void)) |
1fde1b39 |
415 | \end_layout |
416 | |
417 | \begin_deeper |
418 | \begin_layout Standard |
419 | Register a callback that is called when a new event becomes available in |
420 | a live trace. |
421 | It is also called when the live trace ends. |
422 | \end_layout |
423 | |
424 | \begin_layout Standard |
425 | Arguments: |
426 | \end_layout |
427 | |
428 | \begin_layout Itemize |
429 | after (timestamp) : call only if the event occurent later than |
430 | \emph on |
431 | after |
432 | \end_layout |
433 | |
434 | \begin_layout Itemize |
6e3755ba |
435 | cb: the callback function |
1fde1b39 |
436 | \begin_inset Note Note |
437 | status open |
438 | |
439 | \begin_layout Standard |
440 | specify its args and return val |
441 | \end_layout |
442 | |
443 | \end_inset |
444 | |
445 | |
446 | \end_layout |
447 | |
448 | \begin_layout Standard |
449 | Return: |
450 | \end_layout |
451 | |
452 | \begin_layout Itemize |
453 | Result (success or failure) |
454 | \end_layout |
455 | |
456 | \end_deeper |
457 | \begin_layout Subsection |
458 | High-level trace reading API |
459 | \end_layout |
460 | |
461 | \begin_layout Standard |
462 | The goal of this API is to provide a uniform way for analyses and views |
463 | to obtain trace events from a traceset (merge of many traces or a single |
464 | trace), regardless of the system they were recorded on and of the tracer |
465 | used. |
466 | \end_layout |
467 | |
468 | \begin_layout Itemize |
4414440b |
469 | struct request_handle *traceset_new_event_request(struct traceset *tr, struct |
470 | trace_time t1, struct trace_time t2, struct event_filter *filter, void |
471 | (*cb)(void *data, ), void *data) |
1fde1b39 |
472 | \end_layout |
473 | |
474 | \begin_deeper |
475 | \begin_layout Standard |
4414440b |
476 | Request a range of events |
1fde1b39 |
477 | \end_layout |
478 | |
4414440b |
479 | \begin_layout Standard |
480 | Arguments: |
1fde1b39 |
481 | \end_layout |
482 | |
483 | \begin_layout Itemize |
4414440b |
484 | tr: the traceset |
1fde1b39 |
485 | \end_layout |
486 | |
487 | \begin_layout Itemize |
4414440b |
488 | t1: start timestamp |
1fde1b39 |
489 | \end_layout |
490 | |
491 | \begin_layout Itemize |
4414440b |
492 | t2: stop timestamp (special value for infinity, for live traces) |
1fde1b39 |
493 | \end_layout |
494 | |
495 | \begin_layout Itemize |
4414440b |
496 | filter: filter with complex expressions |
1fde1b39 |
497 | \end_layout |
498 | |
499 | \begin_layout Itemize |
4414440b |
500 | data: private pointer to be passed to the callback |
1fde1b39 |
501 | \end_layout |
502 | |
503 | \begin_layout Standard |
504 | Return: |
505 | \end_layout |
506 | |
507 | \begin_layout Itemize |
508 | handle to the request for cancelling it |
509 | \end_layout |
510 | |
511 | \end_deeper |
512 | \begin_layout Itemize |
4414440b |
513 | void event_request_cancel(struct request_handle *req) |
1fde1b39 |
514 | \end_layout |
515 | |
516 | \begin_deeper |
517 | \begin_layout Standard |
518 | Arguments: |
519 | \end_layout |
520 | |
521 | \begin_layout Itemize |
4414440b |
522 | req: the handle to the request |
1fde1b39 |
523 | \end_layout |
524 | |
525 | \end_deeper |
526 | \begin_layout Subsection |
527 | State management |
528 | \end_layout |
529 | |
4414440b |
530 | \begin_layout Standard |
531 | States are key/value pairs associated with a time range. |
532 | Keys can be (and generally are) duplicated as long as they do not apply |
533 | to overlapping ranges. |
534 | \end_layout |
535 | |
536 | \begin_layout Standard |
537 | Keys are character strings. |
538 | \end_layout |
539 | |
540 | \begin_layout Standard |
541 | Values may be of various types: |
542 | \end_layout |
543 | |
544 | \begin_layout Itemize |
545 | string |
546 | \end_layout |
547 | |
548 | \begin_layout Itemize |
549 | uint32 |
550 | \end_layout |
551 | |
552 | \begin_layout Itemize |
553 | int32 |
554 | \end_layout |
555 | |
556 | \begin_layout Itemize |
557 | blob (binary block of arbitrary length) |
558 | \end_layout |
559 | |
560 | \begin_layout Itemize |
561 | float32 |
562 | \end_layout |
563 | |
564 | \begin_layout Itemize |
565 | float64 |
566 | \end_layout |
567 | |
568 | \begin_layout Standard |
569 | The state information must be persistent between executions of the framework. |
570 | \end_layout |
571 | |
572 | \begin_layout Standard |
573 | It is possible to assign a state to the range -infinity..infinity to indicate |
574 | that it is global to the trace, regardless of . |
575 | \end_layout |
576 | |
577 | \begin_layout Standard |
578 | The key names should be hierarchical. |
579 | \end_layout |
580 | |
1fde1b39 |
581 | \begin_layout Subsubsection |
582 | State accessing API |
583 | \end_layout |
584 | |
585 | \begin_layout Itemize |
4414440b |
586 | struct state_value *state_get_value_at_time(char *key, struct trace_time |
587 | time) |
1fde1b39 |
588 | \end_layout |
589 | |
590 | \begin_deeper |
4414440b |
591 | \begin_layout Standard |
592 | Request the value of a given key at a point in time |
593 | \end_layout |
594 | |
1fde1b39 |
595 | \begin_layout Standard |
596 | Arguments: |
597 | \end_layout |
598 | |
599 | \begin_layout Itemize |
4414440b |
600 | var: the state variables (string) |
601 | \end_layout |
602 | |
603 | \begin_layout Itemize |
604 | time: the timestamp |
605 | \end_layout |
606 | |
607 | \begin_layout Standard |
608 | Return value: |
1fde1b39 |
609 | \end_layout |
610 | |
611 | \begin_layout Itemize |
4414440b |
612 | The state value |
1fde1b39 |
613 | \end_layout |
614 | |
615 | \end_deeper |
616 | \begin_layout Itemize |
4414440b |
617 | struct state_value_range **state_get_values_in_range(char *key, struct state_val |
618 | ue *val, struct trace_time_range range) |
619 | \end_layout |
620 | |
621 | \begin_deeper |
622 | \begin_layout Standard |
1fde1b39 |
623 | Request all the states changes of a given set of state variables between |
624 | two time indexes |
625 | \end_layout |
626 | |
1fde1b39 |
627 | \begin_layout Standard |
628 | Arguments: |
629 | \end_layout |
630 | |
631 | \begin_layout Itemize |
4414440b |
632 | key: the key |
1fde1b39 |
633 | \end_layout |
634 | |
635 | \begin_layout Itemize |
4414440b |
636 | range: the time range |
1fde1b39 |
637 | \end_layout |
638 | |
4414440b |
639 | \end_deeper |
1fde1b39 |
640 | \begin_layout Itemize |
4414440b |
641 | Other functions for getting values for a set of keys at once? |
1fde1b39 |
642 | \end_layout |
643 | |
1fde1b39 |
644 | \begin_layout Subsubsection |
645 | State setting API |
646 | \end_layout |
647 | |
4414440b |
648 | \begin_layout Itemize |
649 | set a particular state |
650 | \end_layout |
651 | |
652 | \begin_layout Itemize |
653 | delete some states |
654 | \end_layout |
655 | |
1fde1b39 |
656 | \begin_layout Section |
657 | Describing event types |
658 | \end_layout |
659 | |
660 | \begin_layout Subsection |
661 | Overview |
662 | \end_layout |
663 | |
664 | \begin_layout Standard |
665 | Because tracepoints may be created dynamically, information about the descriptio |
666 | n of events is just as dynamic. |
667 | In this context, one simple way to communicate the event description informatio |
668 | n to upper layers would be to send them as events, as it is done in recent |
669 | versions of LTTV. |
670 | The core events used to describe other events are the only ones whose descripti |
671 | on is hardcoded in the framework. |
672 | \end_layout |
673 | |
674 | \begin_layout Standard |
675 | These event-type-describing events could then be received and interpreted |
4414440b |
676 | by the Event Description Service, which would be a client to the high-level |
677 | tracing API at the same level as normal views and analyses. |
1fde1b39 |
678 | It would store the information and allow the other views and analyses to |
679 | access it via this API. |
680 | \end_layout |
681 | |
4414440b |
682 | \begin_layout Standard |
683 | Each event has a timestamp, a name and arguments of various types. |
684 | The framework should support the following types: |
685 | \end_layout |
686 | |
687 | \begin_layout Itemize |
688 | uint32 |
689 | \end_layout |
690 | |
691 | \begin_layout Itemize |
692 | uint64 |
693 | \end_layout |
694 | |
695 | \begin_layout Itemize |
696 | int32 |
697 | \end_layout |
698 | |
699 | \begin_layout Itemize |
700 | int64 |
701 | \end_layout |
702 | |
703 | \begin_layout Itemize |
704 | string |
705 | \end_layout |
706 | |
1fde1b39 |
707 | \begin_layout Subsection |
708 | Events-describing events |
709 | \end_layout |
710 | |
711 | \begin_layout Itemize |
712 | Event type declaration event |
713 | \end_layout |
714 | |
715 | \begin_deeper |
716 | \begin_layout Standard |
717 | Announce the existence of an event type |
718 | \end_layout |
719 | |
720 | \begin_layout Itemize |
721 | event type name |
722 | \end_layout |
723 | |
724 | \end_deeper |
725 | \begin_layout Itemize |
726 | Argument declaration event |
727 | \end_layout |
728 | |
729 | \begin_deeper |
730 | \begin_layout Standard |
731 | Announce the existence of an event argument |
732 | \end_layout |
733 | |
734 | \begin_layout Itemize |
735 | event type name |
736 | \end_layout |
737 | |
738 | \begin_layout Itemize |
739 | name |
740 | \end_layout |
741 | |
742 | \begin_layout Itemize |
743 | type |
744 | \end_layout |
745 | |
746 | \end_deeper |
747 | \begin_layout Itemize |
748 | Event destruction |
749 | \end_layout |
750 | |
751 | \begin_deeper |
752 | \begin_layout Standard |
753 | Announce that an event type ceased to exist |
754 | \end_layout |
755 | |
756 | \begin_layout Itemize |
757 | event type name |
758 | \end_layout |
759 | |
760 | \end_deeper |
761 | \begin_layout Subsection |
762 | Event type description API |
763 | \end_layout |
764 | |
4414440b |
765 | \begin_layout Standard |
766 | The event type description service provides the following functions. |
767 | \end_layout |
768 | |
1fde1b39 |
769 | \begin_layout Itemize |
4414440b |
770 | GArray<struct event_type *> *traceset_get_all_event_types(struct traceset |
771 | *ts) |
772 | \end_layout |
773 | |
774 | \begin_deeper |
775 | \begin_layout Standard |
1fde1b39 |
776 | Get the list of all the event types |
777 | \end_layout |
778 | |
4414440b |
779 | \begin_layout Standard |
780 | Arguments: |
781 | \end_layout |
782 | |
1fde1b39 |
783 | \begin_layout Itemize |
4414440b |
784 | ts: the traceset of which we want the event types |
785 | \end_layout |
786 | |
787 | \begin_layout Standard |
788 | Return value: |
789 | \end_layout |
790 | |
791 | \begin_layout Itemize |
792 | A GArray of of struct event_type. |
793 | The GArray must be gfree()'d by the caller when it is done reading it. |
794 | \end_layout |
795 | |
796 | \end_deeper |
797 | \begin_layout Itemize |
798 | struct event_type *traceset_get_event_type_by_name(struct traceset *ts, |
799 | char *name) |
800 | \end_layout |
801 | |
802 | \begin_deeper |
803 | \begin_layout Standard |
1fde1b39 |
804 | Find an event type by name |
805 | \end_layout |
806 | |
4414440b |
807 | \begin_layout Standard |
808 | Arguments: |
809 | \end_layout |
810 | |
1fde1b39 |
811 | \begin_layout Itemize |
4414440b |
812 | ts: the traceset of which we want the event type |
1fde1b39 |
813 | \end_layout |
814 | |
815 | \begin_layout Itemize |
4414440b |
816 | name: the name of the of the event type we are looking for |
817 | \end_layout |
818 | |
819 | \begin_layout Standard |
820 | Return value: |
1fde1b39 |
821 | \end_layout |
822 | |
823 | \begin_layout Itemize |
4414440b |
824 | A pointer to the event type (must not be free'd) or NULL if not found |
825 | \end_layout |
826 | |
827 | \end_deeper |
828 | \begin_layout Itemize |
829 | GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype) |
830 | \end_layout |
831 | |
832 | \begin_deeper |
833 | \begin_layout Standard |
834 | Get the list of arguments of an event |
835 | \end_layout |
836 | |
837 | \begin_layout Standard |
838 | Arguments: |
1fde1b39 |
839 | \end_layout |
840 | |
841 | \begin_layout Itemize |
4414440b |
842 | eventype: the event type of which we want the arguments |
843 | \end_layout |
844 | |
845 | \begin_layout Standard |
846 | Return value: |
1fde1b39 |
847 | \end_layout |
848 | |
849 | \begin_layout Itemize |
4414440b |
850 | A GArray of struct event_args. |
851 | The GArray must be gfree()'d by the caller when it is done reading it. |
1fde1b39 |
852 | \end_layout |
853 | |
4414440b |
854 | \end_deeper |
1fde1b39 |
855 | \begin_layout Itemize |
4414440b |
856 | struct event_arg *event_type_get_arg_by_name(struct event_type *evtype) |
1fde1b39 |
857 | \end_layout |
858 | |
4414440b |
859 | \begin_deeper |
860 | \begin_layout Standard |
861 | Find an argument by name |
862 | \end_layout |
863 | |
864 | \end_deeper |
1fde1b39 |
865 | \begin_layout Itemize |
4414440b |
866 | Functions for accessing struct event_arg fields |
1fde1b39 |
867 | \end_layout |
868 | |
869 | \begin_layout Section |
870 | Inspecting events |
871 | \end_layout |
872 | |
873 | \begin_layout Subsection |
874 | Overview |
875 | \end_layout |
876 | |
877 | \begin_layout Standard |
878 | Events contain the following information. |
879 | \end_layout |
880 | |
881 | \begin_layout Itemize |
882 | Timestamp |
883 | \end_layout |
884 | |
885 | \begin_layout Itemize |
4414440b |
886 | Event type identifier - an event id (integer) - hidden to the API users, |
887 | manipulated as pointers/references to struct event_type |
888 | \end_layout |
889 | |
890 | \begin_layout Itemize |
891 | A reference to the trace it was in |
892 | \end_layout |
893 | |
894 | \begin_layout Subsection |
895 | Event inspecting API |
896 | \end_layout |
897 | |
898 | \begin_layout Itemize |
899 | struct event_type *event_get_type(struct traceset *ts, struct event *ev) |
1fde1b39 |
900 | \end_layout |
901 | |
902 | \begin_deeper |
903 | \begin_layout Standard |
4414440b |
904 | get the event type corresponding to an event |
1fde1b39 |
905 | \end_layout |
906 | |
4414440b |
907 | \begin_layout Standard |
908 | Arguments: |
1fde1b39 |
909 | \end_layout |
910 | |
911 | \begin_layout Itemize |
4414440b |
912 | ts: |
1fde1b39 |
913 | \end_layout |
914 | |
1fde1b39 |
915 | \begin_layout Itemize |
4414440b |
916 | ev: |
1fde1b39 |
917 | \end_layout |
918 | |
4414440b |
919 | \begin_layout Standard |
920 | Return value: |
1fde1b39 |
921 | \end_layout |
922 | |
923 | \begin_layout Itemize |
4414440b |
924 | The event type or NULL if no information |
925 | \end_layout |
926 | |
927 | \end_deeper |
928 | \begin_layout Itemize |
929 | struct trace_time event_get_time(struct event *ev) |
930 | \end_layout |
931 | |
932 | \begin_deeper |
933 | \begin_layout Standard |
934 | get the event time |
1fde1b39 |
935 | \end_layout |
936 | |
4414440b |
937 | \end_deeper |
1fde1b39 |
938 | \begin_layout Itemize |
4414440b |
939 | struct trace *event_get_trace(struct event *ev) |
1fde1b39 |
940 | \end_layout |
941 | |
942 | \begin_layout Itemize |
4414440b |
943 | get the name of the machine on which the event occured or other location |
944 | information |
1fde1b39 |
945 | \end_layout |
946 | |
947 | \begin_layout Itemize |
948 | get information on the type of tracing technology that was used |
949 | \end_layout |
950 | |
951 | \begin_layout Itemize |
952 | get the corresponding tracepoint (machine/tracing technology/name/location |
953 | in code(if available)) |
954 | \end_layout |
955 | |
4414440b |
956 | \begin_layout Itemize |
957 | uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg) |
958 | \end_layout |
959 | |
960 | \begin_layout Itemize |
961 | int32 event_read_arg_int32(struct event *ev, struct event_arg *arg) |
962 | \end_layout |
963 | |
964 | \begin_layout Itemize |
965 | uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg) |
966 | \end_layout |
967 | |
968 | \begin_layout Itemize |
969 | int64 event_read_arg_int64(struct event *ev, struct event_arg *arg) |
970 | \end_layout |
971 | |
972 | \begin_layout Itemize |
973 | float32 event_read_arg_float32(struct event *ev, struct event_arg *arg) |
974 | \end_layout |
975 | |
976 | \begin_layout Itemize |
977 | float64 event_read_arg_float64(struct event *ev, struct event_arg *arg) |
978 | \end_layout |
979 | |
980 | \begin_layout Section |
981 | Filtering events |
982 | \end_layout |
983 | |
984 | \begin_layout Standard |
985 | A filtering API is proposed. |
986 | \end_layout |
987 | |
988 | \begin_layout Section |
989 | Controlling the tracing of a system |
990 | \end_layout |
991 | |
992 | \begin_layout Subsection |
993 | Overview |
994 | \end_layout |
995 | |
996 | \begin_layout Standard |
997 | The goal of this API is to provide a portable way of controlling tracing |
998 | of heterogenous systems. |
999 | \end_layout |
1000 | |
1001 | \begin_layout Standard |
1002 | It should enable to do the following actions. |
1003 | \end_layout |
1004 | |
1005 | \begin_layout Itemize |
1006 | Set the parameters of a trace (channels, buffering, destination of data |
1007 | (file, network, process)...) |
1008 | \end_layout |
1009 | |
1010 | \begin_layout Itemize |
1011 | Control the recording of events (start, stop, pause the trace) |
1012 | \end_layout |
1013 | |
1014 | \begin_layout Itemize |
1015 | Create tracepoints (on dynamic tracers) and control which tracepoints are |
1016 | activated (some may be at trace level, others might only permit system |
1017 | level) |
1018 | \end_layout |
1019 | |
1020 | \begin_layout Subsection |
1021 | Trace control API |
1022 | \end_layout |
1023 | |
1024 | \begin_layout Itemize |
1025 | List the static tracepoints available on a system |
1026 | \end_layout |
1027 | |
1028 | \begin_deeper |
1029 | \begin_layout Standard |
1030 | These may be static tracepoints (active or inactive) or dynamic tracepoints |
1031 | (active or proposed). |
1032 | \end_layout |
1033 | |
1034 | \end_deeper |
1035 | \begin_layout Itemize |
1036 | Add a new dynamic tracepoint |
1037 | \end_layout |
1038 | |
1039 | \begin_layout Itemize |
1040 | Activate a tracepoint |
1041 | \end_layout |
1042 | |
1043 | \begin_layout Itemize |
1044 | Deactivate a tracepoint |
1045 | \end_layout |
1046 | |
1047 | \begin_layout Itemize |
1048 | List available probes |
1049 | \end_layout |
1050 | |
1051 | \begin_layout Itemize |
1052 | Connect a probe to a tracepoint |
1053 | \end_layout |
1054 | |
1055 | \begin_layout Itemize |
1056 | Start tracing |
1057 | \end_layout |
1058 | |
1059 | \begin_layout Itemize |
1060 | Stop tracing |
1061 | \end_layout |
1062 | |
1063 | \begin_layout Itemize |
1064 | \begin_inset Note Greyedout |
1065 | status open |
1066 | |
1067 | \begin_layout Standard |
1068 | others missing... |
1069 | \end_layout |
1070 | |
1071 | \end_inset |
1072 | |
1073 | |
1074 | \end_layout |
1075 | |
1fde1b39 |
1076 | \end_body |
1077 | \end_document |