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 | |
1fde1b39 |
69 | \begin_layout Standard |
70 | This document proposes some APIs for a trace viewing and analysis infrastructure. |
71 | \end_layout |
72 | |
73 | \begin_layout Standard |
74 | Design 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 |
81 | Goals |
82 | \end_layout |
83 | |
84 | \begin_layout Itemize |
85 | Provide an infrastructure for fast, interactive visualization and analysis |
86 | of huge traces (>10 GB) on standard workstations |
87 | \begin_inset Foot |
88 | status open |
89 | |
90 | \begin_layout Standard |
91 | Efficiency 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 |
107 | Allow efficient manipulation of traces that are larger than the system memory |
108 | \end_layout |
109 | |
110 | \begin_layout Itemize |
111 | Support processing of live traces |
1fde1b39 |
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. |
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 |
152 | Time |
1fde1b39 |
153 | \end_layout |
154 | |
1fde1b39 |
155 | \begin_layout Standard |
4414440b |
156 | The 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 |
161 | struct trace_time |
1fde1b39 |
162 | \end_layout |
163 | |
164 | \begin_layout Itemize |
4414440b |
165 | struct trace_time_range |
1fde1b39 |
166 | \end_layout |
167 | |
1fde1b39 |
168 | \begin_layout Standard |
4414440b |
169 | The preferred representation for times is seconds. |
1fde1b39 |
170 | \end_layout |
171 | |
4414440b |
172 | \begin_layout Standard |
173 | Ranges 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 |
177 | infinity |
178 | \emph default |
179 | . |
1fde1b39 |
180 | \end_layout |
181 | |
b71d449a |
182 | \begin_layout Standard |
183 | Each time is accompanied by an uncertainty value. |
184 | \end_layout |
185 | |
aed623d7 |
186 | \begin_layout Subsection |
187 | Modules |
188 | \end_layout |
189 | |
190 | \begin_layout Standard |
191 | The 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 |
197 | Trace 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 |
204 | Traceset 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 |
214 | State\InsetSpace ~ |
215 | providers 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 |
219 | n-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 |
225 | State 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 |
232 | Event\InsetSpace ~ |
233 | description 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 |
3f188151 |
236 | they contain, possibly using the State module. |
237 | Other components can access this information through an exported API. |
aed623d7 |
238 | \end_layout |
239 | |
240 | \begin_layout Description |
241 | Plugins... |
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 |
251 | Low level reading of traces |
1fde1b39 |
252 | \end_layout |
253 | |
254 | \begin_layout Subsection |
255 | Overview |
256 | \end_layout |
257 | |
b71d449a |
258 | \begin_layout Standard |
259 | This 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 |
261 | nt way. |
262 | \end_layout |
263 | |
264 | \begin_layout Standard |
265 | \begin_inset Note Note |
266 | status open |
267 | |
1fde1b39 |
268 | \begin_layout Subsubsection |
269 | Timestamps |
270 | \end_layout |
271 | |
272 | \begin_layout Standard |
273 | Timestamps, 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 |
289 | status open |
1fde1b39 |
290 | |
291 | \begin_layout Subsubsection |
292 | Factory methods |
293 | \end_layout |
294 | |
295 | \begin_layout Itemize |
6e3755ba |
296 | void get_supported_formats(void) |
1fde1b39 |
297 | \end_layout |
298 | |
299 | \begin_deeper |
300 | \begin_layout Standard |
301 | Arguments: none |
302 | \end_layout |
303 | |
304 | \begin_layout Standard |
305 | Return: |
306 | \end_layout |
307 | |
308 | \begin_layout Itemize |
309 | a list of supported formats |
310 | \end_layout |
311 | |
312 | \end_deeper |
313 | \begin_layout Itemize |
314 | open_trace() |
315 | \end_layout |
316 | |
317 | \begin_deeper |
318 | \begin_layout Standard |
319 | Arguments: |
320 | \end_layout |
321 | |
322 | \begin_layout Itemize |
323 | trace URL |
324 | \end_layout |
325 | |
326 | \begin_deeper |
327 | \begin_layout Itemize |
328 | local file name |
329 | \end_layout |
330 | |
331 | \begin_layout Itemize |
332 | other special url to establish a network connection |
333 | \end_layout |
334 | |
335 | \begin_layout Itemize |
336 | etc... |
337 | \end_layout |
338 | |
339 | \end_deeper |
340 | \begin_layout Itemize |
341 | trace format (optional, for cases where auto detection would not work or |
342 | be ambiguous) |
343 | \end_layout |
344 | |
345 | \begin_layout Standard |
346 | Return: |
347 | \end_layout |
348 | |
349 | \begin_layout Itemize |
350 | a trace handle |
351 | \end_layout |
352 | |
b71d449a |
353 | \end_inset |
354 | |
355 | |
356 | \end_layout |
357 | |
358 | \begin_layout Subsection |
359 | Methods of the Low Level Trace Reading API |
1fde1b39 |
360 | \end_layout |
361 | |
362 | \begin_layout Itemize |
b71d449a |
363 | void close(struct trace *tr) |
1fde1b39 |
364 | \end_layout |
365 | |
b71d449a |
366 | \begin_deeper |
367 | \begin_layout Standard |
368 | Close 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 |
374 | Arguments: |
375 | \end_layout |
376 | |
377 | \begin_layout Itemize |
378 | tr: the trace |
379 | \end_layout |
380 | |
381 | \begin_layout Standard |
382 | Return value: none |
383 | \end_layout |
384 | |
b71d449a |
385 | \end_deeper |
1fde1b39 |
386 | \begin_layout Itemize |
9e22a509 |
387 | struct event *current_event(struct trace *tr, struct cursor *cur) |
1fde1b39 |
388 | \end_layout |
389 | |
390 | \begin_deeper |
391 | \begin_layout Standard |
9e22a509 |
392 | Return the event pointed by the cursor cur. |
1fde1b39 |
393 | \end_layout |
394 | |
395 | \begin_layout Standard |
9e22a509 |
396 | Arguments: |
397 | \end_layout |
398 | |
399 | \begin_layout Itemize |
400 | tr: the trace |
401 | \end_layout |
402 | |
403 | \begin_layout Itemize |
404 | cur: the cursor indicating the position of the wanted event |
405 | \end_layout |
406 | |
407 | \begin_layout Standard |
408 | Return value: |
1fde1b39 |
409 | \end_layout |
410 | |
411 | \begin_layout Itemize |
412 | the event currently pointed by the position pointer |
413 | \end_layout |
414 | |
b71d449a |
415 | \begin_layout Itemize |
416 | NULL, 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 |
422 | int advance(struct trace *tr, struct trace_cursor *cur) |
1fde1b39 |
423 | \end_layout |
424 | |
425 | \begin_deeper |
426 | \begin_layout Standard |
b71d449a |
427 | Advance the cursor to the next event in the trace. |
1fde1b39 |
428 | \end_layout |
429 | |
430 | \begin_layout Standard |
b71d449a |
431 | Arguments: |
432 | \end_layout |
433 | |
434 | \begin_layout Itemize |
435 | tr: the trace |
436 | \end_layout |
437 | |
438 | \begin_layout Itemize |
439 | cur: the cursor that should be advanced |
1fde1b39 |
440 | \end_layout |
441 | |
442 | \begin_layout Standard |
b71d449a |
443 | Return value: |
1fde1b39 |
444 | \end_layout |
445 | |
446 | \begin_layout Itemize |
447 | The result: |
448 | \end_layout |
449 | |
450 | \begin_deeper |
451 | \begin_layout Itemize |
b71d449a |
452 | Success (TRACE_ADVANCE_OK) |
1fde1b39 |
453 | \end_layout |
454 | |
455 | \begin_layout Itemize |
b71d449a |
456 | The 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 |
461 | The 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 |
468 | int 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 |
474 | Place a cursor at a particular time index in a trace. |
475 | \end_layout |
476 | |
1fde1b39 |
477 | \begin_layout Standard |
478 | Arguments: |
479 | \end_layout |
480 | |
481 | \begin_layout Itemize |
b71d449a |
482 | tr: the trace that should be seeked |
483 | \end_layout |
484 | |
485 | \begin_layout Itemize |
486 | cur: the cursor to seek |
487 | \end_layout |
488 | |
489 | \begin_layout Itemize |
490 | time: the time to seek to |
1fde1b39 |
491 | \end_layout |
492 | |
493 | \begin_layout Standard |
b71d449a |
494 | Return: |
495 | \end_layout |
496 | |
497 | \begin_layout Itemize |
498 | 0: 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 |
507 | struct trace_cursor *trace_new_cursor(struct trace *tr) |
1fde1b39 |
508 | \end_layout |
509 | |
6e3755ba |
510 | \begin_deeper |
511 | \begin_layout Standard |
b71d449a |
512 | Return 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 |
518 | Arguments: |
519 | \end_layout |
520 | |
521 | \begin_layout Itemize |
522 | tr: the trace |
523 | \end_layout |
524 | |
525 | \begin_layout Standard |
526 | Return value: |
527 | \end_layout |
528 | |
529 | \begin_layout Itemize |
530 | the new cursor |
531 | \end_layout |
532 | |
6e3755ba |
533 | \end_deeper |
1fde1b39 |
534 | \begin_layout Itemize |
6e3755ba |
535 | struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur) |
1fde1b39 |
536 | \end_layout |
537 | |
b71d449a |
538 | \begin_deeper |
539 | \begin_layout Standard |
540 | Copy a cursor. |
541 | \end_layout |
542 | |
543 | \begin_layout Standard |
544 | Arguments: |
545 | \end_layout |
546 | |
547 | \begin_layout Itemize |
548 | cur: the cursor to copy |
549 | \end_layout |
550 | |
551 | \begin_layout Standard |
552 | Return value: |
553 | \end_layout |
554 | |
555 | \begin_layout Itemize |
556 | a new cursor that is at the same location as cur |
557 | \end_layout |
558 | |
559 | \end_deeper |
560 | \begin_layout Itemize |
561 | void trace_cursor_destroy(struct trace_cursor *cur) |
562 | \end_layout |
563 | |
564 | \begin_deeper |
565 | \begin_layout Standard |
566 | Free all resources associated to a cursor. |
567 | After this call, cur is invalid. |
568 | \end_layout |
569 | |
570 | \begin_layout Standard |
571 | Arguments: |
572 | \end_layout |
573 | |
1fde1b39 |
574 | \begin_layout Itemize |
b71d449a |
575 | cur: the cursor to destroy |
1fde1b39 |
576 | \end_layout |
577 | |
9e22a509 |
578 | \begin_layout Standard |
579 | Return value: none |
580 | \end_layout |
581 | |
b71d449a |
582 | \end_deeper |
1fde1b39 |
583 | \begin_layout Itemize |
6e3755ba |
584 | struct trace_time get_time_start(struct trace *tr) |
1fde1b39 |
585 | \end_layout |
586 | |
587 | \begin_deeper |
588 | \begin_layout Standard |
b71d449a |
589 | Arguments: |
590 | \end_layout |
591 | |
592 | \begin_layout Itemize |
593 | tr: the trace |
1fde1b39 |
594 | \end_layout |
595 | |
596 | \begin_layout Standard |
9e22a509 |
597 | Return value: |
1fde1b39 |
598 | \end_layout |
599 | |
600 | \begin_layout Itemize |
601 | the timestamp of the first event in the trace |
602 | \end_layout |
603 | |
604 | \end_deeper |
605 | \begin_layout Itemize |
6e3755ba |
606 | struct trace_time get_time_end(struct trace *tr) |
1fde1b39 |
607 | \end_layout |
608 | |
609 | \begin_deeper |
610 | \begin_layout Standard |
611 | Arguments: none |
612 | \end_layout |
613 | |
614 | \begin_layout Standard |
615 | Return: |
616 | \end_layout |
617 | |
618 | \begin_layout Itemize |
619 | the timestamp of the last event in the trace |
620 | \end_layout |
621 | |
622 | \end_deeper |
623 | \begin_layout Itemize |
6e3755ba |
624 | register_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 |
630 | Register 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 |
636 | Arguments: |
637 | \end_layout |
638 | |
639 | \begin_layout Itemize |
b71d449a |
640 | after (timestamp) : call only if the timestamp of the event is later than |
641 | |
1fde1b39 |
642 | \emph on |
643 | after |
644 | \end_layout |
645 | |
646 | \begin_layout Itemize |
6e3755ba |
647 | cb: the callback function |
1fde1b39 |
648 | \begin_inset Note Note |
649 | status open |
650 | |
651 | \begin_layout Standard |
652 | specify its args and return val |
653 | \end_layout |
654 | |
655 | \end_inset |
656 | |
657 | |
658 | \end_layout |
659 | |
660 | \begin_layout Standard |
661 | Return: |
662 | \end_layout |
663 | |
664 | \begin_layout Itemize |
665 | Result (success or failure) |
666 | \end_layout |
667 | |
668 | \end_deeper |
b71d449a |
669 | \begin_layout Section |
670 | High level reading of traces |
671 | \end_layout |
672 | |
3f188151 |
673 | \begin_layout Subsection |
674 | Overview |
675 | \end_layout |
676 | |
b71d449a |
677 | \begin_layout Standard |
678 | When reading/analyzing/viewing several traces of heterogenous types, these |
679 | traces are read by translator modules, which export the Low Level Trace |
680 | Reading API. |
681 | The traceset service then uses this API to read each of these traces individual |
9e22a509 |
682 | ly, merging them along the way. |
b71d449a |
683 | It may apply timestamp offsetting or other synchronization techniques. |
684 | To allow views and analyses to access events, it in turn exports the High |
685 | Level Trace Reading API. |
1fde1b39 |
686 | \end_layout |
687 | |
688 | \begin_layout Standard |
689 | The goal of this API is to provide a uniform way for analyses and views |
b71d449a |
690 | to obtain large sets of trace events from a traceset (merge of many traces |
691 | or a single trace). |
692 | \end_layout |
693 | |
694 | \begin_layout Subsection |
695 | Methods of the high-level trace reading API |
1fde1b39 |
696 | \end_layout |
697 | |
698 | \begin_layout Itemize |
4414440b |
699 | struct request_handle *traceset_new_event_request(struct traceset *tr, struct |
700 | trace_time t1, struct trace_time t2, struct event_filter *filter, void |
9e22a509 |
701 | (*cb)(void *priv, ), void *private) |
1fde1b39 |
702 | \end_layout |
703 | |
704 | \begin_deeper |
705 | \begin_layout Standard |
9e22a509 |
706 | Request a range of events from a traceset |
1fde1b39 |
707 | \end_layout |
708 | |
4414440b |
709 | \begin_layout Standard |
710 | Arguments: |
1fde1b39 |
711 | \end_layout |
712 | |
713 | \begin_layout Itemize |
4414440b |
714 | tr: the traceset |
1fde1b39 |
715 | \end_layout |
716 | |
717 | \begin_layout Itemize |
4414440b |
718 | t1: start timestamp |
1fde1b39 |
719 | \end_layout |
720 | |
721 | \begin_layout Itemize |
4414440b |
722 | t2: stop timestamp (special value for infinity, for live traces) |
1fde1b39 |
723 | \end_layout |
724 | |
725 | \begin_layout Itemize |
4414440b |
726 | filter: filter with complex expressions |
1fde1b39 |
727 | \end_layout |
728 | |
729 | \begin_layout Itemize |
9e22a509 |
730 | private: private pointer to be passed to the callback |
1fde1b39 |
731 | \end_layout |
732 | |
733 | \begin_layout Standard |
9e22a509 |
734 | Return value: |
1fde1b39 |
735 | \end_layout |
736 | |
737 | \begin_layout Itemize |
738 | handle to the request for cancelling it |
739 | \end_layout |
740 | |
741 | \end_deeper |
742 | \begin_layout Itemize |
4414440b |
743 | void event_request_cancel(struct request_handle *req) |
1fde1b39 |
744 | \end_layout |
745 | |
746 | \begin_deeper |
b71d449a |
747 | \begin_layout Standard |
748 | Cancel a request. |
749 | \end_layout |
750 | |
1fde1b39 |
751 | \begin_layout Standard |
752 | Arguments: |
753 | \end_layout |
754 | |
755 | \begin_layout Itemize |
4414440b |
756 | req: the handle to the request |
1fde1b39 |
757 | \end_layout |
758 | |
4275fd69 |
759 | \end_deeper |
760 | \begin_layout Itemize |
761 | void traceset_process(struct traceset *tr, struct timeval *tv) |
762 | \end_layout |
763 | |
764 | \begin_deeper |
765 | \begin_layout Standard |
766 | Process requests for the time specified by tv, then return to the caller. |
767 | The time is a wall time and has no relationship with the timestamps of |
768 | the trace. |
769 | It is used to process a part of the trace while allowing a GUI to remain |
770 | responsive. |
771 | \end_layout |
772 | |
773 | \begin_layout Standard |
774 | Arguments: |
775 | \end_layout |
776 | |
777 | \begin_layout Itemize |
778 | tr: the traceset |
779 | \end_layout |
780 | |
781 | \begin_layout Itemize |
782 | tv: the duration for which to process the trace |
783 | \end_layout |
784 | |
1fde1b39 |
785 | \end_deeper |
3f188151 |
786 | \begin_layout Section |
1fde1b39 |
787 | State management |
788 | \end_layout |
789 | |
4414440b |
790 | \begin_layout Standard |
791 | States are key/value pairs associated with a time range. |
792 | Keys can be (and generally are) duplicated as long as they do not apply |
793 | to overlapping ranges. |
794 | \end_layout |
795 | |
796 | \begin_layout Standard |
797 | Keys are character strings. |
3f188151 |
798 | They are organized in a filesystem-like hierarchy. |
799 | \end_layout |
800 | |
801 | \begin_layout Standard |
802 | Each key/value pair is associated either to a specific trace or to the traceset. |
803 | \end_layout |
804 | |
805 | \begin_layout Standard |
806 | State can persist between runs of the program. |
807 | This is useful both to reduce pre-calculation times when re-opening a trace, |
808 | and also to keep general parameters like bookmarks. |
809 | \end_layout |
810 | |
811 | \begin_layout Standard |
812 | It is possible to assign a state to the time range -infinity..infinity to |
813 | indicate that it is global to the trace. |
4414440b |
814 | \end_layout |
815 | |
816 | \begin_layout Standard |
817 | Values may be of various types: |
818 | \end_layout |
819 | |
820 | \begin_layout Itemize |
821 | string |
822 | \end_layout |
823 | |
824 | \begin_layout Itemize |
825 | uint32 |
826 | \end_layout |
827 | |
828 | \begin_layout Itemize |
829 | int32 |
830 | \end_layout |
831 | |
832 | \begin_layout Itemize |
3f188151 |
833 | uint64 |
4414440b |
834 | \end_layout |
835 | |
836 | \begin_layout Itemize |
3f188151 |
837 | int64 |
4414440b |
838 | \end_layout |
839 | |
840 | \begin_layout Itemize |
3f188151 |
841 | blob (binary block of arbitrary length) |
4414440b |
842 | \end_layout |
843 | |
3f188151 |
844 | \begin_layout Itemize |
845 | float32 |
4414440b |
846 | \end_layout |
847 | |
3f188151 |
848 | \begin_layout Itemize |
849 | float64 |
4414440b |
850 | \end_layout |
851 | |
3f188151 |
852 | \begin_layout Itemize |
853 | others? |
4414440b |
854 | \end_layout |
855 | |
3f188151 |
856 | \begin_layout Subsection |
aed623d7 |
857 | Methods of the State Accessing API |
1fde1b39 |
858 | \end_layout |
859 | |
860 | \begin_layout Itemize |
4414440b |
861 | struct state_value *state_get_value_at_time(char *key, struct trace_time |
862 | time) |
1fde1b39 |
863 | \end_layout |
864 | |
865 | \begin_deeper |
4414440b |
866 | \begin_layout Standard |
867 | Request the value of a given key at a point in time |
868 | \end_layout |
869 | |
1fde1b39 |
870 | \begin_layout Standard |
871 | Arguments: |
872 | \end_layout |
873 | |
874 | \begin_layout Itemize |
4414440b |
875 | var: the state variables (string) |
876 | \end_layout |
877 | |
878 | \begin_layout Itemize |
879 | time: the timestamp |
880 | \end_layout |
881 | |
882 | \begin_layout Standard |
883 | Return value: |
1fde1b39 |
884 | \end_layout |
885 | |
886 | \begin_layout Itemize |
3f188151 |
887 | The state value. |
888 | A struct state_value contains the value and the time interval that applies |
889 | to it. |
1fde1b39 |
890 | \end_layout |
891 | |
892 | \end_deeper |
893 | \begin_layout Itemize |
4414440b |
894 | struct state_value_range **state_get_values_in_range(char *key, struct state_val |
895 | ue *val, struct trace_time_range range) |
896 | \end_layout |
897 | |
898 | \begin_deeper |
899 | \begin_layout Standard |
3f188151 |
900 | Request all the state changes of a given set of state variables between |
1fde1b39 |
901 | two time indexes |
902 | \end_layout |
903 | |
1fde1b39 |
904 | \begin_layout Standard |
905 | Arguments: |
906 | \end_layout |
907 | |
908 | \begin_layout Itemize |
4414440b |
909 | key: the key |
1fde1b39 |
910 | \end_layout |
911 | |
912 | \begin_layout Itemize |
4414440b |
913 | range: the time range |
1fde1b39 |
914 | \end_layout |
915 | |
3f188151 |
916 | \begin_layout Standard |
917 | Return value: |
918 | \end_layout |
919 | |
920 | \begin_layout Itemize |
921 | The values |
922 | \end_layout |
923 | |
4414440b |
924 | \end_deeper |
1fde1b39 |
925 | \begin_layout Itemize |
4414440b |
926 | Other functions for getting values for a set of keys at once? |
1fde1b39 |
927 | \end_layout |
928 | |
3f188151 |
929 | \begin_layout Subsection |
aed623d7 |
930 | Methods of the State Setting API |
1fde1b39 |
931 | \end_layout |
932 | |
4414440b |
933 | \begin_layout Itemize |
934 | set a particular state |
935 | \end_layout |
936 | |
937 | \begin_layout Itemize |
938 | delete some states |
939 | \end_layout |
940 | |
1fde1b39 |
941 | \begin_layout Section |
942 | Describing event types |
943 | \end_layout |
944 | |
945 | \begin_layout Subsection |
946 | Overview |
947 | \end_layout |
948 | |
949 | \begin_layout Standard |
950 | Because tracepoints may be created dynamically, information about the descriptio |
951 | n of events is just as dynamic. |
952 | In this context, one simple way to communicate the event description informatio |
953 | n to upper layers would be to send them as events, as it is done in recent |
954 | versions of LTTV. |
955 | The core events used to describe other events are the only ones whose descripti |
956 | on is hardcoded in the framework. |
957 | \end_layout |
958 | |
959 | \begin_layout Standard |
960 | These event-type-describing events could then be received and interpreted |
4414440b |
961 | by the Event Description Service, which would be a client to the high-level |
962 | tracing API at the same level as normal views and analyses. |
1fde1b39 |
963 | It would store the information and allow the other views and analyses to |
964 | access it via this API. |
965 | \end_layout |
966 | |
4414440b |
967 | \begin_layout Standard |
968 | Each event has a timestamp, a name and arguments of various types. |
969 | The framework should support the following types: |
970 | \end_layout |
971 | |
972 | \begin_layout Itemize |
973 | uint32 |
974 | \end_layout |
975 | |
976 | \begin_layout Itemize |
977 | uint64 |
978 | \end_layout |
979 | |
980 | \begin_layout Itemize |
981 | int32 |
982 | \end_layout |
983 | |
984 | \begin_layout Itemize |
985 | int64 |
986 | \end_layout |
987 | |
988 | \begin_layout Itemize |
989 | string |
990 | \end_layout |
991 | |
1fde1b39 |
992 | \begin_layout Subsection |
993 | Events-describing events |
994 | \end_layout |
995 | |
996 | \begin_layout Itemize |
997 | Event type declaration event |
998 | \end_layout |
999 | |
1000 | \begin_deeper |
1001 | \begin_layout Standard |
1002 | Announce the existence of an event type |
1003 | \end_layout |
1004 | |
1005 | \begin_layout Itemize |
1006 | event type name |
1007 | \end_layout |
1008 | |
1009 | \end_deeper |
1010 | \begin_layout Itemize |
1011 | Argument declaration event |
1012 | \end_layout |
1013 | |
1014 | \begin_deeper |
1015 | \begin_layout Standard |
1016 | Announce the existence of an event argument |
1017 | \end_layout |
1018 | |
1019 | \begin_layout Itemize |
1020 | event type name |
1021 | \end_layout |
1022 | |
1023 | \begin_layout Itemize |
1024 | name |
1025 | \end_layout |
1026 | |
1027 | \begin_layout Itemize |
1028 | type |
1029 | \end_layout |
1030 | |
1031 | \end_deeper |
1032 | \begin_layout Itemize |
1033 | Event destruction |
1034 | \end_layout |
1035 | |
1036 | \begin_deeper |
1037 | \begin_layout Standard |
1038 | Announce that an event type ceased to exist |
1039 | \end_layout |
1040 | |
1041 | \begin_layout Itemize |
1042 | event type name |
1043 | \end_layout |
1044 | |
1045 | \end_deeper |
1046 | \begin_layout Subsection |
aed623d7 |
1047 | Methods of the Event Type Description API |
1fde1b39 |
1048 | \end_layout |
1049 | |
4414440b |
1050 | \begin_layout Standard |
1051 | The event type description service provides the following functions. |
1052 | \end_layout |
1053 | |
1fde1b39 |
1054 | \begin_layout Itemize |
4414440b |
1055 | GArray<struct event_type *> *traceset_get_all_event_types(struct traceset |
1056 | *ts) |
1057 | \end_layout |
1058 | |
1059 | \begin_deeper |
1060 | \begin_layout Standard |
1fde1b39 |
1061 | Get the list of all the event types |
1062 | \end_layout |
1063 | |
4414440b |
1064 | \begin_layout Standard |
1065 | Arguments: |
1066 | \end_layout |
1067 | |
1fde1b39 |
1068 | \begin_layout Itemize |
4414440b |
1069 | ts: the traceset of which we want the event types |
1070 | \end_layout |
1071 | |
1072 | \begin_layout Standard |
1073 | Return value: |
1074 | \end_layout |
1075 | |
1076 | \begin_layout Itemize |
1077 | A GArray of of struct event_type. |
1078 | The GArray must be gfree()'d by the caller when it is done reading it. |
1079 | \end_layout |
1080 | |
1081 | \end_deeper |
1082 | \begin_layout Itemize |
1083 | struct event_type *traceset_get_event_type_by_name(struct traceset *ts, |
1084 | char *name) |
1085 | \end_layout |
1086 | |
1087 | \begin_deeper |
1088 | \begin_layout Standard |
1fde1b39 |
1089 | Find an event type by name |
1090 | \end_layout |
1091 | |
4414440b |
1092 | \begin_layout Standard |
1093 | Arguments: |
1094 | \end_layout |
1095 | |
1fde1b39 |
1096 | \begin_layout Itemize |
4414440b |
1097 | ts: the traceset of which we want the event type |
1fde1b39 |
1098 | \end_layout |
1099 | |
1100 | \begin_layout Itemize |
4414440b |
1101 | name: the name of the of the event type we are looking for |
1102 | \end_layout |
1103 | |
1104 | \begin_layout Standard |
1105 | Return value: |
1fde1b39 |
1106 | \end_layout |
1107 | |
1108 | \begin_layout Itemize |
4414440b |
1109 | A pointer to the event type (must not be free'd) or NULL if not found |
1110 | \end_layout |
1111 | |
1112 | \end_deeper |
1113 | \begin_layout Itemize |
1114 | GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype) |
1115 | \end_layout |
1116 | |
1117 | \begin_deeper |
1118 | \begin_layout Standard |
1119 | Get the list of arguments of an event |
1120 | \end_layout |
1121 | |
1122 | \begin_layout Standard |
1123 | Arguments: |
1fde1b39 |
1124 | \end_layout |
1125 | |
1126 | \begin_layout Itemize |
4414440b |
1127 | eventype: the event type of which we want the arguments |
1128 | \end_layout |
1129 | |
1130 | \begin_layout Standard |
1131 | Return value: |
1fde1b39 |
1132 | \end_layout |
1133 | |
1134 | \begin_layout Itemize |
4414440b |
1135 | A GArray of struct event_args. |
1136 | The GArray must be gfree()'d by the caller when it is done reading it. |
1fde1b39 |
1137 | \end_layout |
1138 | |
4414440b |
1139 | \end_deeper |
1fde1b39 |
1140 | \begin_layout Itemize |
4414440b |
1141 | struct event_arg *event_type_get_arg_by_name(struct event_type *evtype) |
1fde1b39 |
1142 | \end_layout |
1143 | |
4414440b |
1144 | \begin_deeper |
1145 | \begin_layout Standard |
1146 | Find an argument by name |
1147 | \end_layout |
1148 | |
1149 | \end_deeper |
1fde1b39 |
1150 | \begin_layout Itemize |
4414440b |
1151 | Functions for accessing struct event_arg fields |
1fde1b39 |
1152 | \end_layout |
1153 | |
1154 | \begin_layout Section |
1155 | Inspecting events |
1156 | \end_layout |
1157 | |
1158 | \begin_layout Subsection |
1159 | Overview |
1160 | \end_layout |
1161 | |
1162 | \begin_layout Standard |
1163 | Events contain the following information. |
1164 | \end_layout |
1165 | |
1166 | \begin_layout Itemize |
1167 | Timestamp |
1168 | \end_layout |
1169 | |
1170 | \begin_layout Itemize |
4414440b |
1171 | Event type identifier - an event id (integer) - hidden to the API users, |
1172 | manipulated as pointers/references to struct event_type |
1173 | \end_layout |
1174 | |
1175 | \begin_layout Itemize |
1176 | A reference to the trace it was in |
1177 | \end_layout |
1178 | |
1179 | \begin_layout Subsection |
aed623d7 |
1180 | Methods of the Event inspecting API |
4414440b |
1181 | \end_layout |
1182 | |
1183 | \begin_layout Itemize |
1184 | struct event_type *event_get_type(struct traceset *ts, struct event *ev) |
1fde1b39 |
1185 | \end_layout |
1186 | |
1187 | \begin_deeper |
1188 | \begin_layout Standard |
4414440b |
1189 | get the event type corresponding to an event |
1fde1b39 |
1190 | \end_layout |
1191 | |
4414440b |
1192 | \begin_layout Standard |
1193 | Arguments: |
1fde1b39 |
1194 | \end_layout |
1195 | |
1196 | \begin_layout Itemize |
4414440b |
1197 | ts: |
1fde1b39 |
1198 | \end_layout |
1199 | |
1fde1b39 |
1200 | \begin_layout Itemize |
4414440b |
1201 | ev: |
1fde1b39 |
1202 | \end_layout |
1203 | |
4414440b |
1204 | \begin_layout Standard |
1205 | Return value: |
1fde1b39 |
1206 | \end_layout |
1207 | |
1208 | \begin_layout Itemize |
4414440b |
1209 | The event type or NULL if no information |
1210 | \end_layout |
1211 | |
1212 | \end_deeper |
1213 | \begin_layout Itemize |
1214 | struct trace_time event_get_time(struct event *ev) |
1215 | \end_layout |
1216 | |
1217 | \begin_deeper |
1218 | \begin_layout Standard |
1219 | get the event time |
1fde1b39 |
1220 | \end_layout |
1221 | |
4414440b |
1222 | \end_deeper |
1fde1b39 |
1223 | \begin_layout Itemize |
4414440b |
1224 | struct trace *event_get_trace(struct event *ev) |
1fde1b39 |
1225 | \end_layout |
1226 | |
1227 | \begin_layout Itemize |
4414440b |
1228 | get the name of the machine on which the event occured or other location |
1229 | information |
1fde1b39 |
1230 | \end_layout |
1231 | |
1232 | \begin_layout Itemize |
1233 | get information on the type of tracing technology that was used |
1234 | \end_layout |
1235 | |
1236 | \begin_layout Itemize |
1237 | get the corresponding tracepoint (machine/tracing technology/name/location |
1238 | in code(if available)) |
1239 | \end_layout |
1240 | |
4414440b |
1241 | \begin_layout Itemize |
1242 | uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg) |
1243 | \end_layout |
1244 | |
1245 | \begin_layout Itemize |
1246 | int32 event_read_arg_int32(struct event *ev, struct event_arg *arg) |
1247 | \end_layout |
1248 | |
1249 | \begin_layout Itemize |
1250 | uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg) |
1251 | \end_layout |
1252 | |
1253 | \begin_layout Itemize |
1254 | int64 event_read_arg_int64(struct event *ev, struct event_arg *arg) |
1255 | \end_layout |
1256 | |
1257 | \begin_layout Itemize |
1258 | float32 event_read_arg_float32(struct event *ev, struct event_arg *arg) |
1259 | \end_layout |
1260 | |
1261 | \begin_layout Itemize |
1262 | float64 event_read_arg_float64(struct event *ev, struct event_arg *arg) |
1263 | \end_layout |
1264 | |
1265 | \begin_layout Section |
1266 | Filtering events |
1267 | \end_layout |
1268 | |
1269 | \begin_layout Standard |
1270 | A filtering API is proposed. |
1271 | \end_layout |
1272 | |
1273 | \begin_layout Section |
1274 | Controlling the tracing of a system |
1275 | \end_layout |
1276 | |
1277 | \begin_layout Subsection |
1278 | Overview |
1279 | \end_layout |
1280 | |
1281 | \begin_layout Standard |
1282 | The goal of this API is to provide a portable way of controlling tracing |
1283 | of heterogenous systems. |
1284 | \end_layout |
1285 | |
1286 | \begin_layout Standard |
1287 | It should enable to do the following actions. |
1288 | \end_layout |
1289 | |
1290 | \begin_layout Itemize |
1291 | Set the parameters of a trace (channels, buffering, destination of data |
1292 | (file, network, process)...) |
1293 | \end_layout |
1294 | |
1295 | \begin_layout Itemize |
1296 | Control the recording of events (start, stop, pause the trace) |
1297 | \end_layout |
1298 | |
1299 | \begin_layout Itemize |
1300 | Create tracepoints (on dynamic tracers) and control which tracepoints are |
1301 | activated (some may be at trace level, others might only permit system |
1302 | level) |
1303 | \end_layout |
1304 | |
1305 | \begin_layout Subsection |
aed623d7 |
1306 | Methods of the Trace Control API |
4414440b |
1307 | \end_layout |
1308 | |
1309 | \begin_layout Itemize |
1310 | List the static tracepoints available on a system |
1311 | \end_layout |
1312 | |
1313 | \begin_deeper |
1314 | \begin_layout Standard |
1315 | These may be static tracepoints (active or inactive) or dynamic tracepoints |
1316 | (active or proposed). |
1317 | \end_layout |
1318 | |
1319 | \end_deeper |
1320 | \begin_layout Itemize |
1321 | Add a new dynamic tracepoint |
1322 | \end_layout |
1323 | |
1324 | \begin_layout Itemize |
1325 | Activate a tracepoint |
1326 | \end_layout |
1327 | |
1328 | \begin_layout Itemize |
1329 | Deactivate a tracepoint |
1330 | \end_layout |
1331 | |
1332 | \begin_layout Itemize |
1333 | List available probes |
1334 | \end_layout |
1335 | |
1336 | \begin_layout Itemize |
1337 | Connect a probe to a tracepoint |
1338 | \end_layout |
1339 | |
1340 | \begin_layout Itemize |
1341 | Start tracing |
1342 | \end_layout |
1343 | |
1344 | \begin_layout Itemize |
1345 | Stop tracing |
1346 | \end_layout |
1347 | |
1348 | \begin_layout Itemize |
1349 | \begin_inset Note Greyedout |
1350 | status open |
1351 | |
1352 | \begin_layout Standard |
1353 | others missing... |
1354 | \end_layout |
1355 | |
1356 | \end_inset |
1357 | |
1358 | |
4275fd69 |
1359 | \end_layout |
1360 | |
1361 | \begin_layout Standard |
1362 | \begin_inset Note Note |
1363 | status open |
1364 | |
1365 | \begin_layout Section* |
1366 | TODO |
1367 | \end_layout |
1368 | |
1369 | \begin_layout Itemize |
1370 | extend APIs for monitoring (case where the flow of events is constant and |
1371 | we cannot keep the whole trace forever) |
1372 | \end_layout |
1373 | |
1374 | \begin_deeper |
1375 | \begin_layout Itemize |
1376 | views must be able to register the fact that they need the whole trace if |
1377 | they do |
1378 | \end_layout |
1379 | |
1380 | \begin_layout Itemize |
1381 | there must be an elegant way to destroy old events |
1382 | \end_layout |
1383 | |
1384 | \end_deeper |
1385 | \begin_layout Itemize |
1386 | add API or infos about interaction with gui? ex: how traceset_process should |
1387 | be called |
1388 | \end_layout |
1389 | |
1390 | \end_inset |
1391 | |
1392 | |
4414440b |
1393 | \end_layout |
1394 | |
1fde1b39 |
1395 | \end_body |
1396 | \end_document |