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