masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx

   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 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
 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
 112 \end_layout
 113
 114 \begin_layout Itemize
 115 Allow merging of traces of different formats
 116 \end_layout
 117
 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
 144 \begin_layout Itemize
 145 The APIs in this document are described as C functions and datatypes.
 146  When an operation applies to an abstraction that could be an object in
 147  an object-oriented language, it is specified as the first argument of the
 148  function.
 149 \end_layout
 150
 151 \begin_layout Subsection
 152 Time
 153 \end_layout
 154
 155 \begin_layout Standard
 156 The framework needs to represent points in the time line and time ranges.
 157  This is done by two data structures, respectively:
 158 \end_layout
 159
 160 \begin_layout Itemize
 161 struct trace_time
 162 \end_layout
 163
 164 \begin_layout Itemize
 165 struct trace_time_range
 166 \end_layout
 167
 168 \begin_layout Standard
 169 The preferred representation for times is seconds.
 170 \end_layout
 171
 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 .
 180 \end_layout
 181
 182 \begin_layout Standard
 183 Each time is accompanied by an uncertainty value.
 184 \end_layout
 185
 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
 236  they contain, possibly using the State module.
 237  Other components can access this information through an exported API.
 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
 250 \begin_layout Section
 251 Low level reading of traces
 252 \end_layout
 253
 254 \begin_layout Subsection
 255 Overview
 256 \end_layout
 257
 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
 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
 282 \end_inset
 283
 284
 285 \end_layout
 286
 287 \begin_layout Standard
 288 \begin_inset Note Note
 289 status open
 290
 291 \begin_layout Subsubsection
 292 Factory methods
 293 \end_layout
 294
 295 \begin_layout Itemize
 296 void get_supported_formats(void)
 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
 353 \end_inset
 354
 355
 356 \end_layout
 357
 358 \begin_layout Subsection
 359 Methods of the Low Level Trace Reading API
 360 \end_layout
 361
 362 \begin_layout Itemize
 363 void close(struct trace *tr)
 364 \end_layout
 365
 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
 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
 385 \end_deeper
 386 \begin_layout Itemize
 387 struct event *current_event(struct trace *tr, struct cursor *cur)
 388 \end_layout
 389
 390 \begin_deeper
 391 \begin_layout Standard
 392 Return the event pointed by the cursor cur.
 393 \end_layout
 394
 395 \begin_layout Standard
 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:
 409 \end_layout
 410
 411 \begin_layout Itemize
 412 the event currently pointed by the position pointer
 413 \end_layout
 414
 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
 420 \end_deeper
 421 \begin_layout Itemize
 422 int advance(struct trace *tr, struct trace_cursor *cur)
 423 \end_layout
 424
 425 \begin_deeper
 426 \begin_layout Standard
 427 Advance the cursor to the next event in the trace.
 428 \end_layout
 429
 430 \begin_layout Standard
 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
 440 \end_layout
 441
 442 \begin_layout Standard
 443 Return value:
 444 \end_layout
 445
 446 \begin_layout Itemize
 447 The result:
 448 \end_layout
 449
 450 \begin_deeper
 451 \begin_layout Itemize
 452 Success (TRACE_ADVANCE_OK)
 453 \end_layout
 454
 455 \begin_layout Itemize
 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)
 458 \end_layout
 459
 460 \begin_layout Itemize
 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)
 463 \end_layout
 464
 465 \end_deeper
 466 \end_deeper
 467 \begin_layout Itemize
 468 int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
 469  time)
 470 \end_layout
 471
 472 \begin_deeper
 473 \begin_layout Standard
 474 Place a cursor at a particular time index in a trace.
 475 \end_layout
 476
 477 \begin_layout Standard
 478 Arguments:
 479 \end_layout
 480
 481 \begin_layout Itemize
 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
 491 \end_layout
 492
 493 \begin_layout Standard
 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
 503 \end_layout
 504
 505 \end_deeper
 506 \begin_layout Itemize
 507 struct trace_cursor *trace_new_cursor(struct trace *tr)
 508 \end_layout
 509
 510 \begin_deeper
 511 \begin_layout Standard
 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.
 515 \end_layout
 516
 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
 533 \end_deeper
 534 \begin_layout Itemize
 535 struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
 536 \end_layout
 537
 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
 574 \begin_layout Itemize
 575 cur: the cursor to destroy
 576 \end_layout
 577
 578 \begin_layout Standard
 579 Return value: none
 580 \end_layout
 581
 582 \end_deeper
 583 \begin_layout Itemize
 584 struct trace_time get_time_start(struct trace *tr)
 585 \end_layout
 586
 587 \begin_deeper
 588 \begin_layout Standard
 589 Arguments:
 590 \end_layout
 591
 592 \begin_layout Itemize
 593 tr: the trace
 594 \end_layout
 595
 596 \begin_layout Standard
 597 Return value:
 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
 606 struct trace_time get_time_end(struct trace *tr)
 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
 624 register_callback_new_event(struct trace *tr, struct trace_time after, void
 625  (*cb)(struct trace *, void *priv), void *private)
 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
 640 after (timestamp) : call only if the timestamp of the event is later than
 641
 642 \emph on
 643 after
 644 \end_layout
 645
 646 \begin_layout Itemize
 647 cb: the callback function
 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
 669 \begin_layout Section
 670 High level reading of traces
 671 \end_layout
 672
 673 \begin_layout Subsection
 674 Overview
 675 \end_layout
 676
 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
 682 ly, merging them along the way.
 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.
 686 \end_layout
 687
 688 \begin_layout Standard
 689 The goal of this API is to provide a uniform way for analyses and views
 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
 696 \end_layout
 697
 698 \begin_layout Itemize
 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
 701  (*cb)(void *priv, ), void *private)
 702 \end_layout
 703
 704 \begin_deeper
 705 \begin_layout Standard
 706 Request a range of events from a traceset
 707 \end_layout
 708
 709 \begin_layout Standard
 710 Arguments:
 711 \end_layout
 712
 713 \begin_layout Itemize
 714 tr: the traceset
 715 \end_layout
 716
 717 \begin_layout Itemize
 718 t1: start timestamp
 719 \end_layout
 720
 721 \begin_layout Itemize
 722 t2: stop timestamp (special value for infinity, for live traces)
 723 \end_layout
 724
 725 \begin_layout Itemize
 726 filter: filter with complex expressions
 727 \end_layout
 728
 729 \begin_layout Itemize
 730 private: private pointer to be passed to the callback
 731 \end_layout
 732
 733 \begin_layout Standard
 734 Return value:
 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
 743 void event_request_cancel(struct request_handle *req)
 744 \end_layout
 745
 746 \begin_deeper
 747 \begin_layout Standard
 748 Cancel a request.
 749 \end_layout
 750
 751 \begin_layout Standard
 752 Arguments:
 753 \end_layout
 754
 755 \begin_layout Itemize
 756 req: the handle to the request
 757 \end_layout
 758
 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
 785 \end_deeper
 786 \begin_layout Section
 787 State management
 788 \end_layout
 789
 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.
 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.
 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
 833 uint64
 834 \end_layout
 835
 836 \begin_layout Itemize
 837 int64
 838 \end_layout
 839
 840 \begin_layout Itemize
 841 blob (binary block of arbitrary length)
 842 \end_layout
 843
 844 \begin_layout Itemize
 845 float32
 846 \end_layout
 847
 848 \begin_layout Itemize
 849 float64
 850 \end_layout
 851
 852 \begin_layout Itemize
 853 others?
 854 \end_layout
 855
 856 \begin_layout Subsection
 857 Methods of the State Accessing API
 858 \end_layout
 859
 860 \begin_layout Itemize
 861 struct state_value *state_get_value_at_time(char *key, struct trace_time
 862  time)
 863 \end_layout
 864
 865 \begin_deeper
 866 \begin_layout Standard
 867 Request the value of a given key at a point in time
 868 \end_layout
 869
 870 \begin_layout Standard
 871 Arguments:
 872 \end_layout
 873
 874 \begin_layout Itemize
 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:
 884 \end_layout
 885
 886 \begin_layout Itemize
 887 The state value.
 888  A struct state_value contains the value and the time interval that applies
 889  to it.
 890 \end_layout
 891
 892 \end_deeper
 893 \begin_layout Itemize
 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
 900 Request all the state changes of a given set of state variables between
 901  two time indexes
 902 \end_layout
 903
 904 \begin_layout Standard
 905 Arguments:
 906 \end_layout
 907
 908 \begin_layout Itemize
 909 key: the key
 910 \end_layout
 911
 912 \begin_layout Itemize
 913 range: the time range
 914 \end_layout
 915
 916 \begin_layout Standard
 917 Return value:
 918 \end_layout
 919
 920 \begin_layout Itemize
 921 The values
 922 \end_layout
 923
 924 \end_deeper
 925 \begin_layout Itemize
 926 Other functions for getting values for a set of keys at once?
 927 \end_layout
 928
 929 \begin_layout Subsection
 930 Methods of the State Setting API
 931 \end_layout
 932
 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
 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
 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.
 963  It would store the information and allow the other views and analyses to
 964  access it via this API.
 965 \end_layout
 966
 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
 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
1047 Methods of the Event Type Description API
1048 \end_layout
1049
1050 \begin_layout Standard
1051 The event type description service provides the following functions.
1052 \end_layout
1053
1054 \begin_layout Itemize
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
1061 Get the list of all the event types
1062 \end_layout
1063
1064 \begin_layout Standard
1065 Arguments:
1066 \end_layout
1067
1068 \begin_layout Itemize
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
1089 Find an event type by name
1090 \end_layout
1091
1092 \begin_layout Standard
1093 Arguments:
1094 \end_layout
1095
1096 \begin_layout Itemize
1097 ts: the traceset of which we want the event type
1098 \end_layout
1099
1100 \begin_layout Itemize
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:
1106 \end_layout
1107
1108 \begin_layout Itemize
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:
1124 \end_layout
1125
1126 \begin_layout Itemize
1127 eventype: the event type of which we want the arguments
1128 \end_layout
1129
1130 \begin_layout Standard
1131 Return value:
1132 \end_layout
1133
1134 \begin_layout Itemize
1135 A GArray of struct event_args.
1136  The GArray must be gfree()'d by the caller when it is done reading it.
1137 \end_layout
1138
1139 \end_deeper
1140 \begin_layout Itemize
1141 struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
1142 \end_layout
1143
1144 \begin_deeper
1145 \begin_layout Standard
1146 Find an argument by name
1147 \end_layout
1148
1149 \end_deeper
1150 \begin_layout Itemize
1151 Functions for accessing struct event_arg fields
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
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
1180 Methods of the Event inspecting API
1181 \end_layout
1182
1183 \begin_layout Itemize
1184 struct event_type *event_get_type(struct traceset *ts, struct event *ev)
1185 \end_layout
1186
1187 \begin_deeper
1188 \begin_layout Standard
1189 get the event type corresponding to an event
1190 \end_layout
1191
1192 \begin_layout Standard
1193 Arguments:
1194 \end_layout
1195
1196 \begin_layout Itemize
1197 ts:
1198 \end_layout
1199
1200 \begin_layout Itemize
1201 ev:
1202 \end_layout
1203
1204 \begin_layout Standard
1205 Return value:
1206 \end_layout
1207
1208 \begin_layout Itemize
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
1220 \end_layout
1221
1222 \end_deeper
1223 \begin_layout Itemize
1224 struct trace *event_get_trace(struct event *ev)
1225 \end_layout
1226
1227 \begin_layout Itemize
1228 get the name of the machine on which the event occured or other location
1229  information
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
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
1306 Methods of the Trace Control API
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
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
1393 \end_layout
1394
1395 \end_body
1396 \end_document